Skip to content

aloop v0.12.0

Latest

Choose a tag to compare

@adeelahmad adeelahmad released this 20 Oct 01:38
· 354 commits to master since this release
Immutable release. Only release title and notes can be modified.
fd1fd31

The first release of aloop (Aladdin's Loop), the plugin formerly published as agentic-agile.
It carries the 0.11.0 rename (below: Upgrading from agentic-agile) and everything the roadmap
shipped since v0.10.1: the intent contract and the aladdin.event/1 stream with events trace
(a commit on main answers with its task, gates, plan, intent and approver), sprint budget and
admission control, the planning feedback lifecycle, frozen ids, semantic targets, the stuck
release, the impact-provider seam, the portable host core (Claude Code, Codex, OpenCode), run
data under .aladdin/ with a .agentic/ fallback, and seventeen measured live runs of the
north-star loop (make e2e-live), each of which fixed a gate false positive or a dead path.

Upgrading from agentic-agile: uninstall agentic-agile@agentic-agile-marketplace, install
aloop@aloop-marketplace; agentic … commands keep working as aliases and existing .agentic/
project data is read as before (see 0.11.0 → Compatibility, and README → Upgrading).

Changed

  • The README is tested (scripts/test/readme.test.py, in make test-hosts): the §4.11 section
    order, every aloop <tool> / aladdin <sub> it names exists, the install lines name this
    repo's plugin and marketplace, every relative link resolves, and every demo time/cost figure
    is one ROADMAP §0 records. Reason: the README was the last §4.11 row without a test.
  • Run data moves to .aladdin/ (ROADMAP M1). Fresh projects keep transcripts, budgets,
    the ledger, logs, state, host records and task worktrees under .aladdin/, next to
    config.yaml; .aladdin/.gitignore (written by the plugin) keeps everything but
    config.yaml out of git. A project that already has .agentic/ keeps using it until
    aloop layout migrate moves it (refused while worker worktrees are live); aloop layout show says which dir is live and aloop layout check fails unless the run data is
    git-ignored. Every AGENTIC_<KEY> env var and settings key accepts ALADDIN_<KEY>
    (AGENTIC_ wins when both are set). The gates and budget find the task contract in
    either dir, so a supervisor that writes the old literal path is still understood. The
    worktree-local markers (task.env copy, budget-exceeded, scaffold-symbols) move with
    it: written to the worker worktree's .aladdin/ (guarded), read from .agentic/ too.
    Test: scripts/test/layout.test.py; every suite runs on the new layout.
  • Workers append their output.md block before selfcheck (RED/SCAFFOLD/GREEN personas,
    agents and pipeline sources). Reason: the soft-limit line said "run selfcheck, append your
    report", so workers self-checked first and were blocked for a missing report block: 4 of
    run 16's 9 blocks, 3 of run 15's 6.
  • The supervisor never commits on main (SKILL.md): every commit on main arrives through
    task-worktree merge. Reason: live run 16's one untraceable commit was the supervisor's own
    Track Cargo.lock; the e2e fixture now commits the lockfile in its seed.
  • A wave with one dispatchable task runs in the foreground (SKILL.md orchestrator loop).
    Reason: live run 15 dispatched every single-task wave in the background and woke 16 times,
    each wake re-reading the supervisor's context (5.5M cached tokens, $1.26 of $1.42); run 14,
    foreground, woke twice for $0.75. Background dispatch + budget watch stays the rule for
    parallel waves. The host table's "merge a passed task" row names task-worktree merge.
  • 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

  • log-execution --help, a default ledger (the latest docs/agents/sprintN/execution.log) and
    exit 64 with the usage on a wrong call. Reason: it had no usage, so the supervisor read its
    source twice per live run to learn that the last argument is the file. SKILL.md now gives the
    exact call and says the init-block section list is the whole shape (the supervisor also read
    init.template.md four times per run). make e2e-live counts plugin-source reads precisely
    (tool calls naming a plugin path, --schema …/schemas/… excluded): runs 13–15 were 9, 8, 6.

  • task-worktree merge <TASK_ID> <BRANCH> records the §4.7 lineage on Claude Code, where the
    host makes the worktree and the supervisor merges it (so task-worktree remove never runs): a
    --no-ff merge, then worktree.merged + one commit.created per merged commit. SKILL.md tells the
    supervisor to merge with it (a raw git merge left live runs 11–14 with no traceable commits), and
    make e2e-live now checks every merged commit answers events trace.

  • Stuck release: a worker that hits the same gate block 3 times in a row (one gate, task,
    attempt and worktree; AGENTIC_STUCK_BLOCKS) is released unverified instead of
    looping until its time box (live run 10 lost 29 minutes to a RED worker that stopped 29
    times on one unchanged reason). The release is not a pass: the gate leaves
    .agentic/state/stuck/<task>.<attempt> with the reason, budget watch prints a STUCK
    line once, and the supervisor re-dispatches with feedback or re-plans. A different reason
    or a new attempt resets the count; a self-check never releases. Every gate verdict now
    logs its worktree and a checksum of the block reason. 7 conformance checks (§6.9).

  • Portable project config (ROADMAP §4.9). .aladdin/config.yaml (budgets, context,
    semantic, models, provenance, memory, git, plus per-role budget profiles) replaces
    docs/agents/defaults.md as the human's file. aloop config migrate writes it from the
    current settings; when it exists it is authoritative and defaults.md is rendered from it
    (config sync, run by SessionStart and aloop-init --apply), so the bash gates read the
    same values. config check refuses unknown sections, keys, bad numbers and schema.

  • The HostAdapter interface (ROADMAP §4.9). _host.py names, per host, the one place
    the harness does each thing: capabilities, the dispatch vocabulary (spawn / wait / send /
    cancel / subscribe), model and transcript resolution, usage and context pressure,
    compact / rotate, the worktree seam, gate install and enforcement, tool policy. Claude
    Code is the reference; Codex and OpenCode are adapters. aloop host describe prints the
    contract, host check (in make test-hosts) fails if an adapter is incomplete or would
    enforce a gate as a warning. What a host lacks raises Unsupported; nothing is faked.

  • Abstract model routes (ROADMAP §3.6). Roles map to strongest | strong | economical
    and each host resolves the route to its own id (plugin/hosts/routes.json; Codex: the
    session's model). AGENTIC_MODEL_PLANNING / AGENTIC_MODEL_WORKER default to
    strongest / strong; a pinned id still passes through. aloop models resolve is what
    the supervisor passes on dispatch and what aloop install renders; --json makes the
    route observable (conformance 18).

  • 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
    any overrides). events decide records one-line decisions with evidence refs, linked to
    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.

  • The site (ROADMAP §4.11): docs/index.html, one self-contained page for GitHub Pages (from
    /docs): an original lamp mark, the RED explainer ("Give the agent something to make false."),
    the gates table and the audit tree; scripts/test/site.test.py checks it is self-contained and
    that every time/cost number on it is one ROADMAP §0 records.

  • README reordered product-first (ROADMAP §4.11): intent, demo (the measured §0 runs), test-driven
    agents, how the loop works, why failing first matters, gates, install, hosts, evidence, audit,
    architecture, limitations. ROADMAP §0 milestone statuses now match the code (M1–M7 done, M8 in progress).

  • aladdin entry point (ROADMAP §4.11). aladdin "<intent>" records the Intent Contract
    (plus the raw words) and says how to start the run; aladdin status|resume|report read the
    harness files (sweep, the resume rule, NEXT.md, stats.md); aladdin target|context|refs|…
    are the semantic queries; every aloop tool answers under the new name. A /aladdin skill
    defers to /aloop; installs link ~/.local/bin/aladdin and copy the skill. The stray
    bin/aloop-init.orig left by the rename merge is gone.

  • Context-window share (ROADMAP §4.10). stats.md divides the context peak by the new
    AGENTIC_CONTEXT_WINDOW setting (context.window in .aladdin/config.yaml, default 200000):
    hosts do not report the window, so the human states it instead of the harness guessing.

  • Host swap (ROADMAP §4.9). aloop host swap --to codex|opencode|claude hands a sprint to
    another host from portable state only: the sprint dir (handoff.json / plan-ready.md),
    .aladdin/config.yaml and .agentic/logs. A missing piece or a live worker worktree blocks;
    the target's capability gaps are named; SessionStart on the new host resumes the sprint under
    the same resume rule and records the rotation. Test: scripts/test/host-swap.test.py.

  • The semantic plan as the execution source (ROADMAP §4.6). With tasks in a story's
    targets.json, targets render writes tasks.md, validate.md and plan.md as deterministic
    views over it, and targets check (gate-stage2-complete) refuses a hand-edited view, so the
    md files cannot fork from the plan. Test: scripts/test/plan-render.test.py.

  • 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
    plan.md must exist at its path. plan-ready.md lists only what RED wrote, so a test a
    re-plan dropped used to vanish unnoticed (e2e run 6).

  • aloop init seeds docs/agents/memory.md as a schema-valid empty table, and
    gate-memory prints a valid skeleton when it blocks. e2e run 7's archivist guessed
    type: agent-memory and the supervisor's stop was blocked 15 times.

  • gate-dispatch (PreToolUse on Agent/Task): the supervisor's dispatch of an execution
    worker is refused until its prompt opens with TASK_ID: <id> and the contract exists.
    e2e run 6 dispatched the structural reviewer before writing its contract, and its gate
    blocked 25 times on a STORY_DIR the worker could not supply. scripts/test/dispatch.test.py.

  • End-to-end live run (north star). make e2e-live YES=1 turns a one-line intent
    (a semver parser) into planned, tested, merged code in a real Claude Code session with
    the plugin, then checks the artifacts, gate verdicts, merge, tests and cost. First run:
    done end to end in 19 min for $1.15 (sonnet supervisor, haiku workers), 22 tests on main;
    it found the gate-matcher, selfcheck and copy-merge bugs fixed below.

  • Conformance fixtures (ROADMAP §6, M1 slice 1). make conformance runs the real RED
    and GREEN gates on a fixture crate in linked worktrees: 16 checks over §6.3–6.9 (RED that
    passes or edits src/ is rejected, suppressions and out-of-scope diffs are blocked,
    shared-tree workers are blocked, an accepted GREEN merges, a hard breach is released as
    "not a pass"). Items not covered yet are printed with the reason. Runs in CI's rust job.
    §6.2 adds 4 schema checks through the real md-db; task.env tampering adds 6 more (26 in all).

  • Live smoke test (M0). make smoke-live YES=1 runs one short real Claude Code
    session with the plugin and checks the handoff injection, the supervisor-scope block,
    transcripts and the token ledger (~$0.004 on haiku). Not run in CI (needs tokens).

  • Gates fail closed (M0.6). A gate that crashes (exit other than 0 or 2) now blocks
    with "the gate itself failed … failing closed" instead of being a non-blocking hook error
    that lets the action through. Covers every sub-agent gate, and gate-supervisor-scope
    once the repo has a sprint lock. scripts/test/fail-closed.test.py.

Security

  • No role gate ran on Claude Code plugin installs. Claude Code names a plugin's
    sub-agents aloop:<agent>, and a plain-name hook matcher is an exact list, so the
    red-worker, green-worker, … SubagentStop/SubagentStart matchers never matched: every
    "gate" verdict came from the workers' own optional self-checks. Found by the first live
    end-to-end run (all 7 verdicts were self-checks) and confirmed with a probe plugin.
    Matchers now list both <role> and aloop:<role>; scripts/test/hook-matchers.test.py
    failed before.
  • A worker could pass its own gate by editing task.env. The gate library sourced
    .agentic/task.env, which sits in the worker's worktree: appending exit 0 passed a
    failing GREEN, and GATE_RUN_MATRIX=0 or SKIP_HOOKS=1 switched checks off. The file
    is now parsed as data and only the contract keys are read (selfcheck too). Four new
    conformance cases cover it; they failed before the fix. Remaining exposure (a worker
    rewriting its contract keys) is ROADMAP M0.7.
  • A worker could relabel its own role. AGENT_ROLE came from task.env, so a RED
    worker claiming planner skipped the worktree-isolation check. Gates now take the role
    from the host's hook payload (agent_type) and block if task.env contradicts it.
    2 conformance cases (26 in all) failed before.
  • The task contract is the supervisor's (M0.7). The playbook told the supervisor to
    write task.env into the worker's worktree before dispatch, but on Claude Code
    isolation: "worktree" creates that worktree (.claude/worktrees/agent-<id>) at
    dispatch (measured with a live probe), so the contract could only be missing or
    worker-written. The supervisor now writes .agentic/state/tasks/<TASK_ID>.env in the main
    tree and puts TASK_ID: <id> on the dispatch prompt's first line; gates and the time box
    find the contract from that line in the host's transcript. A worktree copy that disagrees
    with the contract blocks the gate, and gate-supervisor-scope stops sub-agents writing
    .agentic/state/ or .agentic/task.env. 4 conformance cases (30 in all) and 4 unit
    checks failed before.
  • Workers could rewrite the contract through Bash. gate-supervisor-scope now also
    sees a sub-agent's Bash calls and blocks a command that names .agentic/state/ or
    .agentic/task.env together with a write (redirect, tee, sed -i, cp, mv, …);
    reading it stays allowed. 2 checks failed before.

Fixed

  • Reviewers and the final gate get the task-contract copy in their host worktree (budget hook).
    Reason: only the three workers did, so every structural reviewer's first selfcheck on Claude
    Code blocked "STORY_DIR unset" (runs 15–17: 2, 1 and 3 blocks) until it guessed the contract.
    The observed role's state now names its task and story dir too.
  • The planner persona states targets check's rules ({"targets": [...]}, symbol only for code
    that exists, planned_symbol with create/extend for new code), so its first targets.json
    passes (live runs 12–14: 2–3 blocks each).
  • The planner persona lists the exact frontmatter and ## sections planning-artifacts.kdl
    requires, so its first write passes (every live run so far wrote each artifact twice: 8–12
    write blocks per run).
  • ctx-symbols (and the gate's grep fallback) no longer scan a host's worktree checkouts
    inside the main tree (.claude/worktrees/agent-<id>/), nor .agentic/ or .transcripts/:
    a stale checkout duplicated every symbol of main and the structural review halted on a
    false HIGH finding 20 times (live e2e run 12). The exclusion applies below the walk root, so a
    reviewer whose own worktree is such a checkout is still scanned. 3 conformance checks (§6.7),
    2 unit tests.
  • The stuck release also covers the structural reviewer and the final gate, whose blocks can name
    a defect only the supervisor can act on (run 12: 10 identical blocks). 1 conformance check.
  • gate-validate-artifact's block now carries md-db's diagnostics (the missing section or field
    and its hint): a PostToolUse block hands the model only stderr, and the bare "failed the
    schema" made the planner guess (live e2e run 11: every planning artifact was written twice,
    12 of 25 gate verdicts).
  • gate-dispatch refuses a task contract with no STORY_DIR, or one naming a dir that does
    not exist, and tells a whole-wave structural review to use the sprint dir
    docs/agents/sprintN/ (run 11: the reviewer's contract had none, 2 blocks the worker could
    not fix). 5 new dispatch checks.
  • OpenCode: a stuck release (exit 0 with STUCK … NOT verified) is reported to the supervisor
    as "released UNVERIFIED, do not merge", never as a silent pass; 2 new checks.
  • make test-hosts masked a failing OpenCode test as "node not found".
  • The host tests (Codex hooks, OpenCode plugin, rename-compat, budget, fail-closed, scope,
    dispatch) each leaked a temp dir, and the Codex and OpenCode ones started a real background
    cargo build over their fake tools (~500MB per run; 57 leaked dirs filled the disk and killed
    e2e run 11 with ENOSPC). They now remove their temp dir on exit and set
    AGENTIC_NO_AUTOINSTALL=1; e2e-live drops its cargo target dirs after the run.
  • The comms gate's "no output.md" block now says HOW to append the report: a shell heredoc
    from the worktree, because Claude Code's Write/Edit refuse a path outside it and
    docs/agents/ lives only in the main tree (e2e run 10: a RED worker stopped 29 times on
    it). The worker personas say the same.
  • A worktree task.env copy OLDER than the supervisor's contract (a re-dispatch bumped
    ATTEMPT) is stale and is ignored, not reported as tampering (e2e run 10: 3 blocks).
  • ensure-tools rebuilds the bundled md-db / ctx-symbols when their sources change, not
    only on a version bump; e2e run 9 ran a stale ctx-symbols that still had the duplicate bug.
  • gate-stage2-complete names the expected sN-NN-<slug>/ story dir (and a misnamed one it
    found); the planner prompt states the naming. e2e run 9: 56 planner retries on S1-01/.
  • Scope globs are no longer expanded against the worktree: tests/** became the files that
    happened to exist, so GREEN was blocked for an in-scope tests/common/mod.rs (e2e run 8: 29 blocks).
  • ctx-symbols conflicts no longer reports the same name in two integration-test files
    (mod common;, a local helper) as a HIGH duplicate; each tests/*.rs is its own crate.
    e2e run 8's structural review halted 57 times on it. The grep fallback skips tests/ too.
  • gate-scaffold-verify's grep fallback (no ctx-symbols) located a test fn instead of the stub,
    depending on directory order; it now uses the same name-anchored match as symbol_count.
  • gate-red-verify no longer blocks a RED report that lists a test already on the base as
    PASS (an earlier task's test, for context); only a NEW test may not pass. e2e run 7: 22 blocks.
  • make shellcheck no longer reports a lint error as "shellcheck not installed" and passes.
  • gate-scaffold-verify skips a symbol path kind header row and Trait for Type impl
    lines in .agentic/scaffold-symbols.
  • Annotated scaffold-symbols lines were split into fake symbols ((enum), @, …), each
    "defined 0 times". The first token of a line is the symbol; non-identifiers are dropped.
  • Sub-agents read the plugin's own source (19–30 commands per e2e run) to work out
    formats selfcheck already reports. The agent prompts now say not to; run 6 had 2, and
    cost its lowest yet: $0.65 in 11 min.
  • A Claude Code worker could get another task's budget. With no task.env in its own
    worktree, the time box guessed "the only green-worker worktree" and applied that task's
    limits. It now takes the worker's own worktree from its cwd first.
  • A worker's selfcheck <role> crashed on good work (AGENT_ROLE: unbound variable)
    when the role came only from the argument; selfcheck now exports it. Found by the e2e run.
  • The supervisor merged by copying files out of worktrees. Workers never committed, so
    their branches were empty and the supervisor cp'd files into main, past the gate's
    diff. RED/SCAFFOLD/GREEN gates now block uncommitted work, the worker prompts say to
    commit, and the playbook says to git merge --no-ff the worktree branch. Found by the
    e2e run.
  • Gates looped on the supervisor's own contract slips. A comma-separated SCOPE_GLOBS
    (34 blocks in e2e run 2) or a mistyped AGENT_ROLE in the main-tree contract blocked a
    worker that cannot edit the contract, so it retried until it gave up. Lists now accept
    commas, and the host's role wins over the contract's with a WARN (a contradicting
    worktree copy still blocks).
  • A worker's selfcheck could not find its task on Claude Code (STORY_DIR unset, once
    per role in e2e run 2): the worktree is made at dispatch and has no task.env. The time
    box's first tool-call hook now copies the supervisor's contract into the worktree (the
    dispatch prompt's TASK_ID picks it); the gates still compare the copy to the contract.
  • GREEN looped on RED's formatting (19 blocks in e2e run 3): RED's test file failed
    cargo fmt --check, and GREEN may not touch tests. RED and SCAFFOLD gates now run the
    matrix's format check, so the file is fixed by the role that wrote it.
  • False "isolation dropped" blocks (27 in e2e run 5): a worker that cds to the main
    tree to read its story left the hook's cwd there. Gates now check the worktree Claude
    Code made for that agent (.claude/worktrees/agent-<agent_id>) first. The Bash contract
    guard is per simple command now (run 5 blocked a read-only probe), and RED's
    out-of-scope message says how to undo the change.
  • The supervisor could write source mid-sprint on Linux. gate-supervisor-scope's
    "recently refreshed lock" arm called stat -f %m first; on Linux that prints a
    filesystem report instead of failing, the arithmetic crashed under set -u, and a
    crashed hook does not block. GNU stat -c %Y now goes first and the value is checked.
    Found by the live smoke test; scripts/test/supervisor-scope.test.py covers it.
  • Valid planner artifacts were blocked by the schema gate. gate-validate-artifact,
    gate-intake and gate-memory ran md-db on the written file's whole directory, and
    gate-stage2-complete on the whole sprint tree. Those directories also hold the
    init.md/output.md comms (and stats.md), which the schema does not know, so every
    valid tasks.md/validate.md/stories.md write in a story that had comms was blocked.
    They now validate only the written file (stage-2: only the planning artifacts). Found by
    the new §6.2 fixture.