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

adeelahmad · 2026-10-17T02:32:40Z

Requested by Adeel · project thread

Before: crossing the soft token limit told the worker to wrap up. The token meter folded cache traffic into context. Only the three workers were metered. Every hard stop was split, and the stopped worker spent one more model call narrating. The sprint had no aggregate budget, the planner got no structured feedback, intents were prose, aliases had no canonical identity, workers scanned the repo for what to change, and nothing linked a commit back to the intent that asked for it.

After: one commit per ROADMAP item, each with a test that fails on master:

§3.1: the soft token limit is telemetry only.
§3.2: the default charge is fresh input plus output; cache classes kept apart; TOKEN_METER=context keeps the old meter.
§3.3: every model role is metered against a per-role profile; non-workers are observe-only.
§3.4: each hard breach gets a deterministic class with evidence.
§3.5: no post-kill narration; the harness writes the status: re-plan block.
§4.1: the Intent Contract (bin/intent) with the assume/default/ask/spike policy; an unanswered ask stops both modes.
§4.2: a sprint token envelope with budget admit and rollover.md.
§4.3: failure envelope, grace rule, calibration verdict, and planner lesson candidates (bin/lessons) promoted only by the recurrence rule (gate-memory).
§4.4: sprintN/handoff.json and the resume rule.
§4.5: bin/ids freeze: structured cross-artifact references checked, UUIDv7 ids frozen per story/task, retired aliases never reused.
§4.6 (first slice): bin/targets: structured change targets, a shadow workspace for planned files, target / context --budget N for workers; refs/callers report the missing LSP backend instead of guessing.
§4.7: the aladdin.event/1 stream with plan/commit emitters; events trace SHA walks commit → task → gates → plan → intent → approver (milestone 7); events commit-msg and events graph.
§4.8: bin/impact, an optional provider seam; unsourced results dropped; an unavailable provider never blocks planning.
§4.10: the stats.md Metrics table, including commits, tests added, time soft limits and semantic context served.

Also ports #6's ${CLAUDE_PLUGIN_ROOT} quoting fix, and stops the host tests from starting a ~340MB background cargo build in their temp dir. §3.6 and §4.9 wait for #7, which owns install, init and the host adapter.

How: new CLIs events, intent, lessons, ids, targets, impact plus _events.py; budget logic in budget, stats, _usage.py; small hooks in _gatelib.sh, task-worktree, gate-final, gate-intake, gate-memory, gate-stage2-complete, session-start, agentic-init. Docs in SKILL.md, agent personas, CHANGELOG and ROADMAP (each item marked with what remains open).

Evidence

New tests: budget-soft-telemetry 6, budget-hard-stop 4, budget-meter 4, budget-roles 4, budget-classify 7, sprint-admission 5, planner-feedback 5, events 6, handoff-resume 4, metrics 5, intent-contract 6, lesson-candidates 5, ids-integrity 5, semantic-targets 5, commit-trace 6, impact-provider 3. Existing budget-worktree, codex-hooks 15 and opencode-plugin 19 updated.
make test-hosts pycheck eval-validate json pass locally.
A trial merge with feat: v0.11.0 — rename to aloop, first end-to-end live run, gate hardening #7 conflicts in budget, hooks.json, SKILL.md, CHANGELOG and agentic-init. Whichever PR lands second resolves them.

🤖 Generated with Claude Code

https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

Crossing the soft token limit no longer tells the worker to wrap up. The budget hook records task.token_soft_limit once per attempt in .agentic/logs/events.jsonl; stats.md counts it and NEXT.md lists the tasks as planner input. The soft time limit still warns; hard limits unchanged. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

claude plugin validate --strict now rejects unquoted placeholders, which turned the plugin CI job red on master-based PRs. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

adeelahmad · 2026-10-17T02:34:38Z

plugin (json · evals · validate) failed on claude plugin validate --strict: the CLI now rejects unquoted ${CLAUDE_PLUGIN_ROOT} in plugin/hooks/hooks.json. That file is untouched by this PR, so the failure also hits master. #6 already has the fix (507f813), and I ported the same change here in 80d25f1. It becomes a no-op once #6 lands.

Generated by Claude Code

At the hard limit the worker is stopped on the crossing call instead of being given one 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 and withdraw. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

The budget charge is now fresh (uncached) input + output by default. Cache read / cache write are kept as separate classes in the attempt state, and context is the latest call's, never cumulative cache traffic. TOKEN_METER=context (defaults.md) or BUDGET_TOKEN_METER (task.env) keeps the previous context + output charge. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

Intake, standards, planner, archivist, structural-reviewer and final-gate are metered against per-role profiles (AGENTIC_BUDGET_<ROLE> in defaults.md overrides). Observe-only: crossings become events; the agent is never told, stopped, or KILLed by budget watch. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

The hook makes a deterministic first classification of each hard stop from facts it owns (usage classes, tool calls and results, which limit tripped) and records it with evidence in the output.md block, the event, budget watch and the new budget classify. The planner confirms or overrides it and acts per class instead of always splitting. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…DMAP §4.3) budget envelope <task> prints the minimal failure envelope (facts and references only). NEXT.md's Planner feedback section applies the grace rule (0-1 troubled tasks: no nudge; 2+: one plan-smaller nudge for the next cycle only) with a calibration verdict from the breach classes. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

_events.py gives every harness event one envelope (ids, parent/caused_by, role, host, model, authority, decision, refs, data) and refuses unknown types. Budget events, real gate verdicts and the worktree lifecycle (created / merged / discarded) are emitted into it. bin/events query and lineage answer from the stream alone, with refs instead of transcripts. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

sprint-close writes sprintN/handoff.json from accepted state (gate verdicts, merge events, open/carried work, nudge, refs); NEXT.md renders it. stats resume-check names tasks shown done without a passing gate verdict; SessionStart appends the live check to the handoff. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

stats.md now reports p50/p90/p95 attempt duration and tokens, breaches by role/class, hard-breach waste, tokens per accepted task, first-pass rate per gate, re-plan rate, cache-hit and churn ratios, context peak and admission closures, all derived from harness files (no model calls). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

events authority records who approved the run, the autonomy mode, scope and overrides (human.approval + .agentic/state/authority.json). events decide records one-line rationale with evidence refs, caused_by the authority; multi-line reasons, unknown kinds and missing authority are refused. Lineage shows decisions inline. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…omous mode (ROADMAP §4.1) bin/intent new issues a canonical time-ordered intent_id (never model text) and the contract skeleton with provenance; intent check validates every field and the clarification policy (assume/default/spike record their resolution; an unanswered ask stops both modes, exit 3); intent summary surfaces defaults/assumptions for approval. gate-intake runs it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…ence rule (ROADMAP §4.3) bin/lessons records symptom/cause/change/applies_to/evidence_refs candidates, lists the groups seen in >= 2 distinct tasks for the archivist, and gate-memory blocks a memory.md row that promotes a one-off without a human keep. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

bin/ids freeze checks the structured references between planning artifacts and issues each story/task alias a frozen UUIDv7 in sprintN/ids.json; retired (split) aliases are never reused. Run by gate-stage2-complete; events for frozen tasks carry story_uid/task_uid. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…ext CLI (ROADMAP §4.6) bin/targets validates the planner's targets.json against tasks.md and the real tree (run by gate-stage2-complete), resolves a task's targets to file:line or a planned shadow entry, and prints budget-capped context for one change. refs/callers/callees report the missing LSP backend (exit 4) instead of guessing. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…milestone 7) gate-stage2-complete emits plan.created/plan.revised caused by the intent, events authority emits plan.approved for the latest plan, and task-worktree remove emits commit.created per merged commit. events trace walks commit -> task -> gates -> plan -> intent -> approver from the stream alone. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

… served (ROADMAP §4.10) Metrics now read the event stream: commit.created (with test files added from git), task.time_soft_limit, and semantic_target.resolved, which targets target|context now emit. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

bin/impact query asks AGENTIC_IMPACT_PROVIDER (any command speaking aladdin.impact/1) for consumers/rationale/migration/standards, keeps only sourced results, saves them as planning provenance and emits artifact.created. An unavailable provider warns and planning continues. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

codex-hooks and opencode-plugin fire SessionStart, which started a ~340MB ensure-tools build per run in the test's temp HOME and kept running after the test exited; locally it filled the disk. Set AGENTIC_NO_AUTOINSTALL=1 (the tests never use the built tools). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

events commit-msg TASK builds the message from the task title in tasks.md, the task's recorded decisions and its task/intent ids. events graph exports the stream as nodes/edges (JSON or DOT), derived and rebuildable. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…OADMAP §4.2) With AGENTIC_TIME_MODE=auto, bin/timebox propose records one stable task duration (min/max, reason) and budget resolve uses it (soft = 2/3); revise needs existing evidence and stays in range, each change is a decision.recorded. Task-level overrides still win. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

bin/sweep prints one action per planned task (DONE, ROLLOVER, WAIT, REPLAN, ACCEPT, RETRY, ESCALATE, SPAWN) from the event stream, attempt states and rollover.md; sweep wait blocks without a model call until an event or attempt state changes. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…ROADMAP §8) docs/TRACKING.md reports every roadmap requirement as IMPLEMENTED_TESTED, IMPLEMENTED_UNTESTED, BLOCKED_HOST or NOT_IMPLEMENTED; check-tracking.py fails if a tested row's test file is missing or not run by the Makefile. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

_lsp.py is a minimal stdio LSP client (references + call hierarchy); targets refs|callers|callees use the server in AGENTIC_LSP_COMMAND. No server or a missing capability exits 4 with the reason; planned targets report none yet. Tested against a deterministic fake server. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…formance 12) _usage.classes marks accuracy (exact: read from the host's own log) and names any class the host never reports (Codex has no cache write) rather than a silent zero; stats.md shows it as Usage accuracy. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

… §4.9) plugin/hosts/capabilities.json and bin/capabilities state what each host advertises (unknown = not advertised). Sprint close names the host's own rotate command; compaction only when chosen and advertised; keeping a session needs a recorded reason. SessionStart records context.rotated / context.compacted and stats.md counts them. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…4.6) With no SCOPE_GLOBS but a targets.json, gate-green-verify enforces the task's target paths (targets scope) instead of skipping the scope check. An explicit SCOPE_GLOBS still wins. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

…map branch Conflicts resolved by keeping both sides: aloop names and aloop:<role> matchers from #7, with this branch's budget-stop matcher for every role, no post-kill narration, the resume check and the boundary rule. The init settings (TOKEN_METER, sprint envelope) move to aloop-init. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

… diff Since #7, workers must commit before their gate runs. With no BASE_REF, changed_paths only listed uncommitted changes, so a committed out-of-scope file passed GREEN's (and RED's tests-only) scope check. It now also takes the branch's commits since it left the main tree's HEAD. targets-scope.test.py failed before. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

Resolves the gate-verdict log (stuck release + the aladdin.event stream), budget watch (STUCK lines + breach class), the Codex test env, the bin README and the CHANGELOG. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QxyVf3NgwsgRyYpBgDDTC

…and #14) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QxyVf3NgwsgRyYpBgDDTC

adeelahmad self-assigned this Oct 17, 2026

adeelahmad changed the title ~~feat(budget): soft token limit is telemetry only (ROADMAP §3.1)~~ feat(budget): soft token limit is telemetry; no post-kill narration (ROADMAP §3.1, §3.5) Oct 17, 2026

adeelahmad marked this pull request as ready for review October 17, 2026 03:04

claude added 3 commits October 17, 2026 04:30

adeelahmad changed the title ~~feat(budget): soft token limit is telemetry; no post-kill narration (ROADMAP §3.1, §3.5)~~ feat(budget): ROADMAP §3.1–3.5 — telemetry soft limit, token classes, every role metered, breach classes, no post-kill narration Oct 17, 2026

claude added 5 commits October 17, 2026 04:41

claude added 4 commits October 17, 2026 05:00

claude added 6 commits October 17, 2026 05:16

claude added 11 commits October 17, 2026 05:30

docs(planner): sync the pipeline persona with the timebox guidance

8940344

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

Merge master (#7)

32a2930

Merge master (#12) into the roadmap branch

72d3928

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014j4wLin3oJTtnvjE9Lq2VV

adeelahmad merged commit 600605c into master Oct 18, 2026
4 checks passed

adeelahmad mentioned this pull request Oct 18, 2026

fix: live e2e run 12 gaps — stale worktree checkouts are not duplicates, stuck release for the reviewer and final gate; ROADMAP §0 statuses #17

Merged

Navigation Menu

Repository navigation

feat: ROADMAP §3.1–3.5, §4.1–4.8, §4.10 — budget semantics, intent contract, ids, semantic targets, provenance, impact seam, metrics - #8

feat: ROADMAP §3.1–3.5, §4.1–4.8, §4.10 — budget semantics, intent contract, ids, semantic targets, provenance, impact seam, metrics#8
adeelahmad merged 33 commits into
masterfrom
claude/project-thread-vm6wyr

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Uh oh!

Evidence

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants