8000 feat: ROADMAP §3.1–3.5, §4.1–4.8, §4.10 — budget semantics, intent contract, ids, semantic targets, provenance, impact seam, metrics by adeelahmad · Pull Request #8 · adeelahmad/aloop · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
9a6a575
feat(budget): soft token limit is telemetry only (ROADMAP §3.1)
claude Oct 17, 2026
80d25f1
fix: quote ${CLAUDE_PLUGIN_ROOT} in hook commands (port of #6's fix)
claude Oct 17, 2026
3b1f07d
feat(budget): no post-kill narration (ROADMAP §3.5)
claude Oct 17, 2026
895af24
feat(budget): token meter counts classes separately (ROADMAP §3.2)
claude Oct 17, 2026
1a670d4
feat(budget): meter every model role (ROADMAP §3.3)
claude Oct 17, 2026
024c69c
feat(budget): classify hard breaches before re-plan (ROADMAP §3.4)
claude Oct 17, 2026
2c4f26a
feat(budget): sprint token envelope + admission control (ROADMAP §4.2)
claude Oct 17, 2026
bc8a36d
feat(planner): failure envelope, grace rule, calibration verdict (ROA…
claude Oct 17, 2026
5790eca
feat(provenance): aladdin.event/1 stream + events CLI (ROADMAP §4.7)
claude Oct 17, 2026
c45f460
feat(handoff): canonical sprint handoff + resume rule (ROADMAP §4.4)
claude Oct 17, 2026
888abb9
feat(stats): sprint Metrics table (ROADMAP §4.10)
claude Oct 17, 2026
a04e139
feat(provenance): authority record + structured decisions (ROADMAP §4.7)
claude Oct 17, 2026
c5ceff6
feat(intake): Intent Contract + clarification policy + explicit auton…
claude Oct 17, 2026
25c1e99
feat(memory): planner lesson candidates gated by the archivist recurr…
claude Oct 17, 2026
67146dd
feat(ids): canonical ids + referential integrity gate (ROADMAP §4.5)
claude Oct 17, 2026
4d2f1f1
feat(targets): semantic change targets, shadow workspace, narrow-cont…
claude Oct 17, 2026
ecd3787
feat(events): plan/commit emitters + events trace SHA (ROADMAP §4.7, …
claude Oct 17, 2026
69f5ec8
feat(stats): commits, tests added, time soft limits, semantic context…
claude Oct 17, 2026
ee5a02c
feat(impact): optional cross-project impact provider seam (ROADMAP §4.8)
claude Oct 17, 2026
ee3ef42
test(hosts): no background cargo build into the temp dir
claude Oct 17, 2026
fe72c5e
feat(events): commit-msg from rationale + graph export (ROADMAP §4.7)
claude Oct 17, 2026
95f9ac7
feat(budget): time budget auto mode via a recorded project timebox (R…
claude Oct 17, 2026
8940344
docs(planner): sync the pipeline persona with the timebox guidance
claude Oct 17, 2026
ce57973
feat(sweep): fact-decided inspect step + token-free wait (ROADMAP §4.2)
claude Oct 17, 2026
14efbd8
docs(tracking): requirement status table checked in make test-hosts (…
claude Oct 17, 2026
923da6b
feat(targets): LSP adapter seam for refs/callers/callees (ROADMAP §4.6)
claude Oct 17, 2026
46e6fdc
feat(usage): exact usage, unreported classes named (ROADMAP §4.9, con…
claude Oct 17, 2026
c37438d
feat(hosts): capability matrix + context-boundary rule (ROADMAP §4.4,…
claude Oct 17, 2026
59aab5e
feat(gates): derive GREEN's diff scope from change targets (ROADMAP §…
claude Oct 17, 2026
f5a2db3
Merge PR #7 (rename to aloop, live e2e, gate hardening) into the road…
claude Oct 17, 2026
32a2930
Merge master (#7)
claude Oct 17, 2026
fbbafcc
fix(gates): scope checks see committed work, not only the uncommitted…
claude Oct 17, 2026
72d3928
Merge master (#12) into the roadmap branch
claude Oct 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 127 additions & 0 deletions CHANGELOG.md
any overrides). `events decide` records one-line decisions with evidence refs, linked to
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,134 @@ tag in lockstep. Tag releases as `vMAJOR.MINOR.PATCH`.

## [Unreleased]

### Changed
- **The soft token limit is telemetry only** (ROADMAP §3.1). Crossing it no longer tells
the worker to wrap up; `budget` records `task.token_soft_limit` once per attempt in
`.agentic/logs/events.jsonl`, `stats.md` counts it, and `NEXT.md` lists those tasks as
planner input. The soft *time* limit still warns.
- **No post-kill narration** (ROADMAP §3.5). At the hard limit the worker is stopped on
the crossing call instead of being given a last call to write its report. The harness
appends the gate-valid `status: re-plan` block to output.md itself (limits, worktree
diff, transcript path) and records `task.token_hard_limit` / `task.time_hard_timeout`.
A verdict reached before the worker's worktree is known still gets one call to find it.
- **The token meter counts classes separately** (ROADMAP §3.2). The budget charge is now
fresh (uncached) input + output by default. Cache read and cache write are kept as
their own classes in each attempt's state (`usage`), and context size is the latest
call's, never cumulative cache traffic. `TOKEN_METER=context` in defaults.md (or
`BUDGET_TOKEN_METER=context` in a task.env) keeps the previous context + output charge;
`budget resolve` / `status` show the meter in force.
- **Budgets cover every model role** (ROADMAP §3.3). Intake, standards, planner,
archivist, structural-reviewer and final-gate are metered against per-role profiles
(overridable with `AGENTIC_BUDGET_<ROLE>` in defaults.md). They are observe-only:
crossings are recorded as events, and the agent is never told or stopped.
- **Hard breaches are classified, not always split** (ROADMAP §3.4). The hook makes a
deterministic first call (`TASK_TOO_LARGE`, `AGENT_LOOPING`, `EXTERNAL_SERVICE`,
`TEST_SUITE_SLOW`, `ENVIRONMENT_SLOW`, `CONTEXT_PATHOLOGY`, `HOST_FAILURE`, `UNKNOWN`)
from usage classes, tool calls and results, with its evidence in the output.md block,
the event, `budget watch` and the new `budget classify`. The planner confirms or
overrides it (`breach:` line) and acts per class (SKILL.md "Breach classes").

### Added
- **Sprint token envelope and admission control** (ROADMAP §4.2). `budget admit <task>`
runs before each dispatch. At `SPRINT_TOKENS_SOFT` it prints one rollover warning, and
at `SPRINT_TOKENS_HARD` admission closes (exit 3). Refused tasks are carried over in
`sprintN/rollover.md` with the reason, gate-final accepts unticked boxes only for those
tasks (`budget rollover-check`), and NEXT.md lists them for the next planning cycle.
Events: `sprint.token_soft_limit`, `sprint.admission_closed`, `sprint.rolled_over`.
- **Planning feedback lifecycle** (ROADMAP §4.3). `budget envelope <task>` prints the
minimal failure envelope: limit, observed value, breach class, last gate, changed files
and references, with nothing inlined. NEXT.md gains a "Planner feedback" section that
applies the grace rule (0–1 failed or hard-breached tasks → no nudge; 2+ → one "plan
smaller" nudge for the next cycle only) with a calibration verdict derived from the
breach classes (`plan-smaller`, `raise-time`, `raise-tokens`, `reduce-context`,
`fix-environment`).
- **The `aladdin.event/1` stream** (ROADMAP §4.7). `_events.py` and `bin/events` give
every harness event one envelope (ids, `parent_event_id` / `caused_by`, role, host,
model, authority, decision, refs, data) and refuse unknown event types. Budget events,
every real gate verdict (`gate.passed` / `gate.failed`) and the worktree lifecycle
(`worktree.created` / `merged` / `discarded`) are emitted into it. `events query` and
`events lineage <task>` answer from the stream, with references only and no transcripts.
`events authority` records the run's authority (who approved it, the mode, the scope and
that authority. A decision without an authority, with a multi-line reason or with an
unknown kind is refused.
- **The Intent Contract and the clarification policy** (ROADMAP §4.1). `bin/intent new`
issues a canonical, time-ordered `intent_id`, which is never model text, and the
contract skeleton with provenance. `intent check` validates every field. It requires a
class for each open question (`assume` / `default` / `spike` must record their
resolution) and stops BOTH modes on an unanswered `ask` (exit 3). `intent summary`
surfaces defaults and assumptions for approval. gate-intake runs the check. Autonomous
mode is explicit (`events authority --mode autonomous`) and skips approval unless an
escalation class is hit.
- **Host capability matrix and the context-boundary rule** (ROADMAP §4.4, §4.9).
`plugin/hosts/capabilities.json` + `bin/capabilities` state what each host advertises
(`unknown` counts as not advertised). At a sprint boundary the harness rotates (the host's
own `/clear` or `/new`, named in the sprint-close message) unless
`AGENTIC_CONTEXT_BOUNDARY=compact` and the host advertises compaction; keeping a session
needs a recorded reason. SessionStart records `context.rotated` / `context.compacted`,
and stats.md counts them.
- **Usage accuracy is explicit** (ROADMAP §4.9, conformance 12). Each attempt's usage
carries `accuracy: exact` and names any class the host never reports (Codex has no cache
write) instead of a silent zero; stats.md shows it in the Metrics table.
- **Diff scope derived from change targets** (ROADMAP §4.6). When the supervisor gives no
`SCOPE_GLOBS` and the story has `targets.json`, gate-green-verify enforces the task's
target paths (`targets scope`) instead of skipping the scope check.
- **LSP adapter seam** (ROADMAP §4.6). `targets refs|callers|callees` ask the language
server named by `AGENTIC_LSP_COMMAND` (`_lsp.py`: references and the call hierarchy only).
No server, or a server without the capability, is reported with exit 4; planned targets
answer "none yet" without touching any server.
- **The orchestrator's inspect step** (ROADMAP §4.2). `bin/sweep` prints one action per
planned task (DONE, ROLLOVER, WAIT, REPLAN, ACCEPT, RETRY, ESCALATE, SPAWN), decided from
the event stream, attempt states and rollover.md. `sweep wait` is a token-free sleep
that wakes on the next event or state change.
- **Time budget `auto` mode** (ROADMAP §4.2). With `AGENTIC_TIME_MODE=auto`, `bin/timebox
propose` records one stable task duration per project (with min/max) and `budget` uses
it (soft = 2/3). `timebox revise` changes it only within range and only with evidence
that exists; each change is a `decision.recorded`. Task overrides still win.
- **Cross-project impact provider seam** (ROADMAP §4.8). `bin/impact query` asks an optional
provider (`AGENTIC_IMPACT_PROVIDER`, any command speaking `aladdin.impact/1`) for downstream
consumers, rationale, migration order or standards. Results without a source ref are
dropped; answers are saved under `docs/agents/impact/` and recorded as planning
provenance. An unavailable provider is reported and planning continues.
- **More run metrics** (ROADMAP §4.10). The Metrics table adds commits produced and test
files added (from `commit.created`), time soft limits reached, and semantic context
served (`targets target|context` emit `semantic_target.resolved`).
- **Commit → intent trace** (ROADMAP §4.7, milestone 7). gate-stage2-complete emits
`plan.created` / `plan.revised`, caused by the intent; `events authority` emits
`plan.approved` for the latest plan; `task-worktree remove` emits `commit.created` per
merged commit. `events trace SHA` walks commit → task → gates → plan → intent → approver
from the event stream alone. `events commit-msg TASK` builds the commit message from the
task title, recorded decisions and ids; `events graph` exports the stream as a
rebuildable graph (JSON or DOT).
- **Semantic change targets, first slice** (ROADMAP §4.6). The planner may write
`<story>/targets.json` (`change_ref / operation / path / symbol | planned_symbol / reason /
evidence_refs / constraints`). `bin/targets check` proves each target against tasks.md and
the real tree, and gate-stage2-complete runs it. Workers start from `targets target` and
`targets context --budget N`, including for files that do not exist yet; planned files
form a shadow workspace and no stub is created. `refs/callers/callees` report the missing
LSP backend (exit 4) instead of guessing.
- **Canonical ids and referential integrity** (ROADMAP §4.5). `bin/ids freeze` checks the
structured references between planning artifacts, never prose, and issues each story and
task alias a frozen UUIDv7 in `sprintN/ids.json`. A split task's original is retired and
its number can never be reused. gate-stage2-complete runs it, and events for a frozen
task carry `story_uid` and `task_uid`.
- **Planner lesson candidates** (ROADMAP §4.3). `bin/lessons add` records a candidate with
`symptom / cause / change / applies_to / evidence_refs` and emits `memory.candidate`.
It refuses empty fields, missing evidence and any change that would weaken a gate.
`lessons recurring` hands the archivist the groups seen in two or more tasks, as
memory.md rows. gate-memory blocks a row that promotes a one-off without a human `keep`.
There is no second memory system.
- **Canonical sprint handoff and the resume rule** (ROADMAP §4.4). sprint-close writes
`sprintN/handoff.json` (`aladdin.handoff/1`) from accepted state: completed tasks with
their gate verdict and merge event, unverified, open and carried tasks, the nudge and
evidence refs. NEXT.md renders it. `stats resume-check` names every task that
plan-ready.md shows as done but that has no passing gate verdict, and SessionStart
appends that live check to the loaded handoff.
- **Sprint metrics** (ROADMAP §4.10). stats.md gains a Metrics table: p50/p90/p95 attempt
duration and tokens, hard breaches by role and class, hard-breach waste, tokens per
accepted task, first-pass rate by gate, re-plan rate, cache-hit and churn ratios,
context peak, and admission closures. All of it is derived from harness files, with no
model calls.
- **Second live e2e intent**: `make e2e-live YES=1 INTENT=wordfreq` runs two dependent stories
(word counting, then top-N ranking).
- **`gate-final` checks every planned test is on main**: each `path::fn` bullet in a story's
Expand Down
24 changes: 23 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -73,13 +73,35 @@ shellcheck: ## Lint gate scripts (skipped with a warning if shellcheck is absent
.PHONY: pycheck
pycheck: ## Byte-compile the Python hook scripts
@python3 -m py_compile plugin/bin/budget plugin/bin/stats plugin/bin/aloop-init plugin/bin/gate-commit-author plugin/bin/_paths.py \
plugin/bin/_usage.py plugin/bin/host-adapter plugin/bin/install \
plugin/bin/_usage.py plugin/bin/_events.py plugin/bin/events plugin/bin/intent plugin/bin/lessons plugin/bin/ids plugin/bin/targets plugin/bin/impact plugin/bin/timebox plugin/bin/sweep plugin/bin/capabilities plugin/bin/_lsp.py scripts/test/fixtures/fake-lsp.py plugin/bin/_timebox.py plugin/bin/host-adapter plugin/bin/install \
&& rm -rf plugin/bin/__pycache__ && echo "python ok"

.PHONY: test-hosts
test-hosts: ## Budget/worktree regression + Codex hooks emulation + OpenCode plugin end-to-end (no network, no tokens)
@command -v node >/dev/null && node --check plugin/hosts/opencode/aloop.js
python3 scripts/test/budget-worktree.test.py
python3 scripts/test/budget-soft-telemetry.test.py
python3 scripts/test/budget-hard-stop.test.py
python3 scripts/test/budget-meter.test.py
python3 scripts/test/budget-roles.test.py
python3 scripts/test/budget-classify.test.py
python3 scripts/test/sprint-admission.test.py
python3 scripts/test/planner-feedback.test.py
python3 scripts/test/events.test.py
python3 scripts/test/handoff-resume.test.py
python3 scripts/test/metrics.test.py
python3 scripts/test/intent-contract.test.py
python3 scripts/test/lesson-candidates.test.py
python3 scripts/test/ids-integrity.test.py
python3 scripts/test/semantic-targets.test.py
python3 scripts/test/commit-trace.test.py
python3 scripts/test/impact-provider.test.py
python3 scripts/test/timebox-auto.test.py
python3 scripts/test/orchestrator-sweep.test.py
python3 scripts/test/lsp-adapter.test.py
python3 scripts/test/context-boundary.test.py
python3 scripts/test/targets-scope.test.py
python3 scripts/check-tracking.py
python3 scripts/test/codex-hooks.test.py
python3 scripts/test/rename-compat.test.py
python3 scripts/test/supervisor-scope.test.py
Expand Down
Loading
Loading
0