@event4u/agent-config 14.8.0 → 14.9.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-290-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-119-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-201-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-107-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
+[![Skills](https://img.shields.io/badge/Skills-291-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-119-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-201-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-108-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 **Try it in 30 seconds** — drop one read-only subagent into any repo and watch it gate "done": `@production-validator check this branch is actually done`. No wizard, no lock-in, nothing else installed — the [30-second wedge ↓](#quickstart) is the whole first step. Start at the proof, not the catalog: **[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/)**.
 

package/agents/templates/.ai-council.yml.example

@@ -289,8 +289,20 @@ quorum: majority
 # markers.
 members:
   anthropic:
+    # `sonnet` is a vendor ALIAS, not a version. `claude --help` documents
+    # 'fable', 'opus' and 'sonnet' as "an alias for the latest model" in their
+    # band, so this line cannot go stale the way a dated id can — the same
+    # property `codex-default` gives the openai member below.
+    #
+    # Until 2026-08-22 this read a dated, several-generation-old id: an enabled
+    # member of a quality council pinned in a template nobody re-reads, with
+    # nothing in the file able to notice. Read from the provider's own CLI
+    # surface, never from recall.
+    #
+    # A member on an alias or a sentinel needs no `verified_at:` — see the
+    # disabled members below for the stamped form.
     enabled: true
-    model: claude-sonnet-4-5
+    model: sonnet
     api_key_ref: file:anthropic.key
     # binary: /usr/local/bin/claude      # only valid when mode == cli
     # Phase 7 — size-fit downgrade ladder (smallest → largest). The
@@ -298,9 +310,9 @@ members:
     # classifier flags a request as oversized, it suggests the next
     # rung *down*; the top rung is the default for complex prompts.
     model_ladder:
-      - claude-haiku-4-5
-      - claude-sonnet-4-5
-      - claude-opus-4-5
+      - haiku
+      - sonnet
+      - opus
     # Prompt caching (GA — no beta header) is ON by default: the stable
     # system + artefact prefix is sent as a cache-controlled block, so
     # members 2..N in a round (and round-2+ within the 5-min TTL) read
@@ -381,20 +393,38 @@ members:
 
   gemini:
     enabled: false
+    # not-listed: gemini — the `gemini` CLI is installed here and its `--help` exposes only `-m, --model <string>` — no listing subcommand and no documented "latest" alias, so no sentinel could be substituted. An honest null for this provider, not a guess.
+    # The pin is therefore stamped as-of the drain date with NO refresh claimed;
+    # `verified_at` records when a human last looked, which is the only thing it
+    # has ever meant. This member ships disabled, so the pin costs nothing today
+    # and `check_council_pin_staleness` will say so when the stamp ages out.
     model: gemini-2.5-pro
+    verified_at: "2026-08-22"
     api_key_ref: env:GEMINI_API_KEY
     # binary: /usr/local/bin/gemini      # only valid when mode == cli
 
   xai:
     enabled: false
+    # not-listed: grok — no `grok` binary on this machine, so the provider's own surface was unreachable.
+    # The pin is therefore stamped as-of the drain date with NO refresh claimed;
+    # `verified_at` records when a human last looked, which is the only thing it
+    # has ever meant. This member ships disabled, so the pin costs nothing today
+    # and `check_council_pin_staleness` will say so when the stamp ages out.
     model: grok-4
+    verified_at: "2026-08-22"
     api_key_ref: env:XAI_API_KEY
     # binary: /usr/local/bin/grok        # The CLI consumes XAI_API_KEY and remains billable=True;
     #                                    # cost_budget.max_total_usd STILL applies. Opt-in only.
 
   perplexity:
     enabled: false
+    # not-listed: sonar — no `sonar` binary on this machine, so the provider's own surface was unreachable.
+    # The pin is therefore stamped as-of the drain date with NO refresh claimed;
+    # `verified_at` records when a human last looked, which is the only thing it
+    # has ever meant. This member ships disabled, so the pin costs nothing today
+    # and `check_council_pin_staleness` will say so when the stamp ages out.
     model: sonar-pro
+    verified_at: "2026-08-22"
     api_key_ref: env:PERPLEXITY_API_KEY
     # binary: /usr/local/bin/perplexity  # The CLI consumes PERPLEXITY_API_KEY and remains billable=True;
     #                                    # cost_budget.max_total_usd STILL applies. Opt-in only.

package/dist/agent-src/commands/pr/merge.md

@@ -134,14 +134,19 @@ pushed ([`git-history-discipline`](../../../../rules/git-history-discipline.md))
 ## 3. Resolve conflicts by class, never by taste
 
 Conflicts between queued PRs are expected, not exceptional: in this repository
-every roadmap PR touches `agents/roadmaps-progress.md` and
-`src/config/estate-count-budget.json`, so each merge re-conflicts every
-remaining PR. Resolve semantically, by these enumerated classes:
+roadmap PRs touch the same handful of shared paths, so each merge can
+re-conflict every remaining PR. Resolve semantically, by these enumerated
+classes.
+
+`src/config/estate-count-budget.json` used to be the second-worst offender here
+and no longer belongs in any class below: ADR-243 removed its stored baseline, so
+it changes on a policy decision rather than once per roadmap touch. A conflict in
+it now means two humans edited the same policy sentence — read both sides.
 
 | Class | Files | Resolution |
 |---|---|---|
 | Roadmap files | `agents/roadmaps/**` | Union of completions. Never un-check a box either side checked; never resurrect a roadmap either side archived or parked. |
-| Generated artefacts | `agents/roadmaps-progress.md` · `src/config/estate-count-budget.json` · `docs/catalog.md` · `docs/command-flows.md` · `agents/index.md` · any file whose first three lines say generated / do-not-edit | Never hand-merge. Take either side, then **regenerate** with the repo's own task and commit the regenerated output. |
+| Generated artefacts | `agents/roadmaps-progress.md` · `docs/catalog.md` · `docs/command-flows.md` · `agents/index.md` · any file whose first three lines say generated / do-not-edit | Never hand-merge. Take either side, then **regenerate** with the repo's own task and commit the regenerated output. |
 | Archive move vs. edit | `agents/roadmaps/{archive,later,skipped}/**` — one side renamed or deleted, the other edited | The archived end-state wins. Re-apply the edit at the new path if it still matters; otherwise drop it and record the drop in the summary. |
 | Evidence files | `agents/evidence/**` | Append-only. Keep both sides. |
 
@@ -169,7 +174,6 @@ regenerate. Exclude those paths before deciding:
 ```bash
 git diff origin/<base>...HEAD --stat -- . \
   ':(exclude)agents/roadmaps-progress.md' \
-  ':(exclude)src/config/estate-count-budget.json' \
   ':(exclude)docs/catalog.md' ':(exclude)agents/index.md'
 ```
 

package/dist/agent-src/commands/review/changes.md

@@ -9,7 +9,7 @@ visibility: internal
 sub: changes
 cluster: review
 skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, judge-synthesis, git-workflow]
-description: Self-review local changes before creating a PR — dispatches to five specialized judges (bug, security, tests, quality, architecture) and consolidates verdicts
+description: Self-review local changes before creating a PR — dispatches to six specialized judges (bug, security, tests, quality, architecture, spec) and consolidates verdicts
 suggestion:
   eligible: false
   rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
@@ -24,7 +24,7 @@ packs:
 ## Instructions
 
 Review all uncommitted and committed-but-not-pushed changes against
-the default branch (`main`) by dispatching to four specialized judge
+the default branch (`main`) by dispatching to six specialized judge
 sub-skills and consolidating their verdicts.
 
 ### 1. Update the current branch
@@ -51,6 +51,18 @@ to make sure the current branch is up to date with its base chain:
 
 ### 2. Gather the diff
 
+**Verify the base ref before diffing against it.** The commands below assume
+`origin/main` exists and is the right base, and nothing checked. This step
+already knows how to ask git a question — `git rev-parse --abbrev-ref HEAD`
+above — so the shape was present and simply not applied to the base:
+
+- `git rev-parse --verify origin/main` — the base ref resolves.
+  - **Does not resolve → stop here and say so.** Do not fall back to a
+    different base, and do not diff against `HEAD` alone. A review whose scope
+    silently became "the whole branch" or "the last commit" reports findings
+    against a diff nobody asked about, and the reader has no way to see that the
+    scope moved. Name the ref that failed.
+
 - `git diff origin/main..HEAD --stat` — overview of changed files
 - `git diff origin/main..HEAD` — full committed-but-not-pushed diff
 - `git diff --stat` + `git diff` — unstaged changes on top
@@ -65,7 +77,39 @@ Read `.agent-settings.yml`:
 
 Unknown alias → stop. Never silently fall back.
 
-### 4. Dispatch to the five judges
+### 3b. Bind the criteria source before dispatching
+
+The spec judge below is only as good as the criteria it reads, so where they
+came from is recorded **before** the dispatch, not reconstructed after it.
+Exactly one of three states, and the state is written into the review report:
+
+| `criteria_source` | When | What the report says |
+|---|---|---|
+| `supplied` | a roadmap, ticket, issue or AC block was explicitly handed in — name it by path or id | the criteria, verbatim, and where they came from |
+| `not_provided` | an ad-hoc branch review with no criteria anywhere | "no acceptance criteria supplied — requirement compliance NOT verified" |
+| `supplied_unparseable` | criteria were handed over and could not be read in a recognised shape | an **error**: the review skipped a dimension it was asked to check |
+
+```
+CRITERIA ARE READ ONLY WHEN SUPPLIED. NEVER DERIVED FROM THE BRANCH,
+THE COMMIT MESSAGES, OR THE PR BODY — AND NEVER FROM THE DIFF.
+A JUDGE THAT INFERS THE REQUIREMENT FROM THE CHANGE IT IS JUDGING
+ALWAYS FINDS THE CHANGE COMPLIANT. SILENCE IS `not_provided`, NEVER A PASS.
+```
+
+There is deliberately **no `derived` state**. Deriving criteria from the branch
+was the alternative considered and rejected: the `derived` label would have to
+be honoured by every consumer of the report to be worth anything, and a label
+that is requested rather than enforced degrades to silence exactly when it
+matters. Decided by AI council on 2026-08-22 (degraded, 1 of 2 seats — the
+second returned an empty response), and the alternative is recorded here rather
+than only in the decision so a later reader can see it was weighed.
+
+`supplied_unparseable` is separated from `not_provided` for the same reason:
+folded together, a handover the reviewer could not parse would report as "there
+was nothing to check", which is the one outcome that hides a real failure
+behind a benign one.
+
+### 4. Dispatch to the six judges
 
 Each judge receives **the same diff plus the task context** (ticket,
 PR body, commit messages) and runs independently. The judges are:
@@ -77,20 +121,37 @@ PR body, commit messages) and runs independently. The judges are:
 | [`judge-test-coverage`](../../skills/judge-test-coverage/SKILL.md) | Missing assertions, uncovered branches, over-mocking, regression-test gaps |
 | [`judge-code-quality`](../../skills/judge-code-quality/SKILL.md) | Naming, SRP, DRY, dead code, consistency with codebase conventions |
 | [`architecture-review-lens`](../../skills/architecture-review-lens/SKILL.md) | Layer violations, dependency direction, leaky abstractions, cross-service contract drift |
+| [`judge-spec-compliance`](../../skills/judge-spec-compliance/SKILL.md) | Does the diff satisfy every acceptance criterion **as stated**? Reads the criteria before the diff, and never infers them from it |
 
-The five judges weight equally in the consolidated verdict — none
+The six judges weight equally in the consolidated verdict — none
 overrides another.
 
+**Why the sixth exists, and why it is not a severity.** The other five all ask a
+craft-or-correctness question, so a change that is correct, clean, well-tested
+and architecturally sound — and **does not do what was asked** — used to pass
+this path with five green verdicts. Its finding does **not** enter the shared
+severity axis: `judge-synthesis` carries it on its own dimension, because "this
+does not do what was asked" is not comparable to "this variable is badly named",
+and on one scale the second can outrank the first whenever three judges raise
+nits and one raises the spec gap.
+
+**When no criteria were supplied** — an ad-hoc branch review — this judge
+returns a no-criteria verdict, never `SATISFIED`. That is not an abstention the
+consolidated verdict may drop: it changes what "done" is allowed to claim to
+*"craft quality verified; requirement compliance NOT verified"*. If that reads as
+most reviews, the honest reading is that most reviews were previously reporting a
+confidence they had not earned.
+
 Pick dispatch mode based on diff size and environment:
 
 - **Sequential** (default, simplest) — run bug-hunter → security-auditor
-  → test-coverage → code-quality → architecture-review-lens, collect
-  each verdict
+  → test-coverage → code-quality → architecture-review-lens →
+  spec-compliance, collect each verdict
 - **Parallel** — if `subagents.max_parallel` in `.agent-settings.yml` is
-  ≥ 5 and subagent dispatch is available, run all five concurrently
+  ≥ 5 and subagent dispatch is available, run all six concurrently
   following the `do-in-parallel` pattern in
   [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md);
-  the five judges operate on the same diff but produce independent
+  the six judges operate on the same diff but produce independent
   reports, so no shared-state risk
 
 Each judge returns its own `Judge / Model / Target / Verdict /
@@ -108,14 +169,14 @@ Read `verbosity.offer_council_in_delivery` from `.agent-settings.yml`
 - `true`: when `ai_council.enabled: true` **and** at least one member
   enabled, ask (in the user's language):
 
-  > 1. Add an external council review alongside the four internal judges? (billable)
+  > 1. Add an external council review alongside the six internal judges? (billable)
   > 2. Skip — internal judges only
 
   Also suppress when `personal.autonomy: on` (council is billable).
 
 If picked **1**:
 
-- Run `/council diff:<base>..<head>` in parallel with the four
+- Run `/council diff:<base>..<head>` in parallel with the six
   internal judges (or sequentially after them — whichever the
   dispatch mode picked in step 4 supports).
 - Treat each council member as one extra "judge" in the consolidated
@@ -140,7 +201,7 @@ Read `subagents.adversarial_council` from `.agent-settings.yml` (default
   which supplies the four slots, the one-question budget, and the storage line
   (not persisted: `subagents.adversarial_council` is class C). What only this
   command knows is *why now*: the diff is high-risk, and the offer is a paid
-  distinct-model red-team for finding coverage against the five internal judges.
+  distinct-model red-team for finding coverage against the six internal judges.
 - `on`: run it automatically on a high-risk diff.
 
 When run, dispatch the
@@ -164,16 +225,36 @@ step 4 (plus any external council blocks from 4b) and produces one report:
 - A **must-fix / should-fix / advisory** split, each entry tagged with the
   judge(s) that raised it
 
+- A **spec-compliance block**, kept apart from that split — the
+  `criteria_source` state from step 3b, the per-criterion verdicts, and the
+  count of `MISSING` plus `PARTIAL`. See
+  [`judge-synthesis` § 4c](../../skills/judge-synthesis/SKILL.md); a spec
+  finding never becomes a craft finding.
+
 `judge-synthesis` emits no single quality score and never auto-gates — it
 structures the verdicts so the next step's decision is informed.
 
+**The report names its criteria source, always.** A reader six months later
+cannot otherwise tell "we checked the requirements and they were met" from
+"nobody checked" — and those are the two readings a bare `proceed` collapses.
+Where the state is `not_provided`, the overall sentence says *craft quality
+verified; requirement compliance NOT verified*, never a plain pass.
+
+**One telemetry line per review** records the structural outcome: which judges
+ran, whether the spec axis was reachable, and whether it changed the
+recommendation. Built and validated by
+`src/scripts/_lib/review_telemetry.ts::buildReviewLine`, which carries no field
+able to hold free-form content and **rejects** an input that adds one. Read the
+window back with `./scripts-run src/scripts/review_axis_report`; it reports
+"nothing observed" and "the axis changed nothing" as two different answers.
+
 ### 6. Decide next steps
 
 - If **any** judge returned `reject` → stop; the approach must change
   before proceeding
 - If **any** judge returned `revise` → fix 🔴 findings automatically,
   ask before fixing 🟡 findings, report 🟢 as suggestions
-- If all five returned `apply` → the diff is ready; report and stop
+- If all six returned `apply` → the diff is ready; report and stop
 
 **Opt-in (never auto-on):** when the `revise` findings are *test-driven*
 (failing checks, not subjective craft) and you want bounded auto-repair
@@ -218,7 +299,7 @@ Per `verbosity.routine_confirmations` (default `false`):
 ## Use this command when
 
 - Preparing a self-review before opening a PR
-- Stress-testing a local branch with the same five lenses a reviewer
+- Stress-testing a local branch with the same six lenses a reviewer
   would apply
 - Sanity-checking a diff before handing it to `/create-pr`
 
@@ -247,6 +328,6 @@ Per `verbosity.routine_confirmations` (default `false`):
 
 - **LLM-as-a-Judge** — [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685)
   MT-Bench and Chatbot Arena — judging LLM outputs with LLM judges.
-  This command adapts the pattern by dispatching to four specialized
+  This command adapts the pattern by dispatching to six specialized
   judges (bug, security, tests, quality) instead of a single generic
   judge, and consolidating their verdicts.

package/dist/agent-src/commands/roadmap/process-full.md

@@ -175,8 +175,8 @@ contract.
 
 **Mergeability is per-PR against a recorded base, never a queue property.**
 When every PR in the estate touches the same generated files — in this
-repository `agents/roadmaps-progress.md` and
-`src/config/estate-count-budget.json` — making PR *n* mergeable against base
+repository `agents/roadmaps-progress.md` and the archive index — making PR *n*
+mergeable against base
 SHA `M` says nothing about its state once PR *n−1* advances the base to `M1`.
 Report "mergeable against base `<SHA>`", never "the queue is mergeable".
 

package/dist/agent-src/contexts/execution/host-capability-manifest.md

@@ -100,6 +100,83 @@ provenance before treating a `false` as a host limitation: on an unrecognized
 host every field is `default`, which is an absence of knowledge and not a
 measurement.
 
+## Observation protocol — what may be written into a registry row
+
+**Added 2026-08-22** (`road-to-host-capability-observations` Phase 1). The
+registry held **one** row while **eight** platform keys were declared, so on
+seven hosts every field was the safe default — and `false` carried two meanings
+at once. This protocol is what makes them distinguishable.
+
+```
+A ROW IS WRITTEN FROM AN OBSERVATION IN A REAL SESSION, NEVER FROM THE HOST'S
+DOCUMENTATION. A CAPABILITY THAT EXISTS ON PAPER AND NOT IN THE SESSION PRODUCES
+A ROUTING DECISION THAT FAILS SILENTLY.
+```
+
+**This is a written criterion a human applies, and deliberately not a script.**
+A prober that decides for itself what counts as evidence is the inference
+`host_capability.ts` already forbids, wearing an executable's authority.
+
+### Per-field criterion — each one transcript-observable
+
+| Field | What counts as an observation |
+|---|---|
+| `subagent_spawn` | a dispatch record showing a **child leg with its own turn** — a start and a stop that pair, so the child's duration is measurable rather than inferred |
+| `parallel_spawn` | **two child legs whose intervals overlap** — concurrently open children at one instant, not two children in sequence |
+| `status_polling` | a **completed poll returning a state the parent did not already hold**. A poll that returns what the parent knew is not an observation of polling |
+| `separate_quota_pool` | a **child leg continuing across a parent quota condition** — the parent constrained, the child proceeding |
+| `worker_respawn` | **one task continuing across a killed and re-spawned worker, same task id.** Never inferred from the fact that spawning and killing both exist separately |
+
+### `agent_teams` is out of scope for a row, by construction
+
+It is resolved **only** by the live environment probe and is never inferred from
+a host id — `host_capability.ts` states that in the field's own doc comment, and
+records that this repository has observed the flag's documented existence and
+never its shape on any host. So: do not add it to a registry row. Observe it, if
+at all, through the live probe.
+
+### Observed-absent is not the same row as never-looked
+
+Both render as `false`, and collapsing them is the defect this protocol opens
+against — a reader then cannot tell whether a capability was tested.
+
+- **Never looked** — the field is **absent from the row**. It resolves to the
+  safe default, and `describeHostCapabilities` reports its source as `default`.
+  This is the state that needs no marker, because the absence *is* the record.
+- **Observed absent** — the field is present and `false`, and carries a
+  `<field>_absent` citation in the same doc comment. Present-and-`false` is the
+  marker: it is only reachable by someone who wrote it deliberately, and the
+  provenance surface then reports `registry` rather than `default` — which is
+  exactly the distinction, readable from `routing:doctor` without opening the
+  file.
+
+### The four-part citation — a row without all four is not admissible
+
+1. **the host** — the platform key from `hook_manifest.yaml`;
+2. **the host version** at the time of observation;
+3. **the transcript or artefact reference** the observation is read from;
+4. **the date**.
+
+Worked example, which a later row can be pattern-matched against:
+
+```
+// subagent_spawn: OBSERVED — claude (Claude Code, Opus 5 1M session, 2026-08-22)
+//   agents/runtime/state/subagent-ledger/2026-08.jsonl: 445 `subagent_start`
+//   records and 420 stops carrying a measured `duration_ms`, i.e. 420 child legs
+//   whose start and stop pair. A measurable child duration is the criterion.
+```
+
+### Pre-state, pinned so the Phase 2 diff reads as an addition
+
+At the commit this protocol landed on, the registry was exactly:
+
+```ts
+const HOST_CAPABILITY_REGISTRY = { claude: { subagent_spawn: true, parallel_spawn: true } };
+```
+
+One host, two fields. Six fields across seven other hosts resolved to the
+all-`false` safe default.
+
 ## Related
 
 - [`subagent-configuration`](../subagent-configuration.md) — the `subagents.*`

package/dist/agent-src/contexts/execution/roadmap-execution-contract.md

@@ -159,6 +159,42 @@ preservation test in that rule already splits them the same way:
      use; the default stays `wait` either way. -->
 
 
+### 2c. `traceability` — requirement to acceptance to evidence, OPTIONAL
+
+**Optional for every complexity, including `structural`.** Absent means *not
+declared*, which is a different claim from "there is no requirement". Nothing
+fails for omitting it, and no gate enforces it — the only consumer is a listing
+inventory (`check_requirements_trace`) that exits 0 always. Requiredness is
+deliberately **not** decided here (AI council 2/2, 2026-08-22): deciding it
+before the listing phase has produced a count is deciding it on intuition.
+
+A repeated **row**, not three flat fields:
+
+```yaml
+traceability:
+  - requirement_id: pointer-reaches-the-worker
+    acceptance_id: pointer-under-line-cap
+    evidence_refs:
+      - src/scripts/dispatch_r2_reviewer.ts
+```
+
+Three flat top-level fields would be **countable but not traceable**: with more
+than one requirement and a shared pool of refs the relation is an ambiguous
+many-to-many, so a gate could report a populated count while providing no
+dependable trace. The row carries the relation.
+
+Both grammars are reused, never invented — the claim-ledger kebab slug
+(`docs/CLAIMS.md` § Entry schema) for the two ids, and the envelope ref-token
+rule (`_lib/subagent_response.ts`) for `evidence_refs`: ref tokens, never
+bodies.
+
+Identity semantics, revision semantics, the three senses of "gate" and the
+`[AC:<id>]` convention — including the verified fact that nothing parses
+`verify:` lines structurally today — are in
+[`guideline:agent-infra/traceability-field-mechanics`](../../../../docs/guidelines/agent-infra/traceability-field-mechanics.md).
+They are not optional reading: a slug grammar does not imply a namespace, and
+`evidence_refs` are syntactically safe tokens rather than verified evidence.
+
 ## 3. Grants activated by acceptance
 
 | Grant | Boundary |

package/dist/agent-src/contexts/execution/subagent-response-contract.md

@@ -31,6 +31,86 @@ orchestrator synthesises and re-verifies.
   chars (~3k tokens against a measured ~251k spawn floor). Constants + checks:
   `src/scripts/_lib/subagent_response.ts`.
 
+## The canonical shape, and the three-way divergence it resolves
+
+**Reconciled 2026-08-22** (`road-to-subagent-envelope-adoption` Phase 0, AI
+council 2/2 convergent). One contract existed in three mutually inconsistent
+states, and the ledger's `0 valid envelopes of 1,845 stops` could not be cited
+as evidence about any one of them, because a reader had to assume which.
+
+```
+THE BODY SCHEMA IS `validateResponse`'S FIVE REQUIRED FIELDS. PRODUCERS CONVERGE
+ON IT; THE VALIDATOR IS NOT WIDENED TO THE UNION OF WHAT PRODUCERS HAPPEN TO SEND.
+```
+
+Direction chosen: **narrow the contract to what the validator already accepts**,
+not widen the validator. Widening makes every future divergence legal by
+construction, which is how one contract came to have three states.
+
+### Per-field divergence, one row per field
+
+| Field | spawn-contract (f) | `team_dispatch` model JSON (`:297`) | `subagent_response.ts` validator | `dispatch_r2_reviewer` |
+|---|---|---|---|---|
+| `summary` | — (not a field clause) | present | **required** | silent |
+| `handoff` | — | **absent** | **required** | silent |
+| `confidence` | — | **absent** | **required** (`low\|medium\|high`) | silent |
+| `findings` | — | present, `{severity, evidence, suggested_fix, location}` | **required**, `{title, evidence_refs?, mutating?}` | silent |
+| `risks` | — | **absent** | **required** | silent |
+| `artifact_paths` | — | absent | optional | silent |
+| `assumptions` | — | absent | optional | silent |
+| `status` | — | present, 3 model values | **not a body field** | silent |
+
+An empty cell is a finding, not a pass. `dispatch_r2_reviewer` is silent on
+every row — 1,292 lines with **0** hits for `envelope`, `DONE_WITH_CONCERNS`,
+`response.contract` or `response_contract`.
+
+### Four boundaries, because "the contract" was conflating them
+
+The council's sharpest correction: schema, lifecycle state, delivery and
+classification were being treated as one thing.
+
+1. **Body schema** — the five required fields above, plus the two optional ones.
+2. **Lifecycle frame** — `DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` from a
+   model, plus `BLOCKED` orchestrator-side only (`team_dispatch.ts:391`'s
+   `_MODEL_STATUSES` is the three-value set a model may send). **Not a body
+   field**, which is why narrowing the body does not delete it.
+3. **Delivery protocol** — serialize once, persist that exact serialization,
+   then emit the identical value as the final text-only message. This is
+   spawn-contract rule (f), and it **survives the narrowing**: its two clauses
+   are delivery invariants, not fields, so they were never candidates for the
+   validator's five.
+4. **Classification** — validate and record against an explicit contract and
+   classifier version.
+
+### Who owns the delivery protocol — and it is not the model
+
+`team_dispatch.ts:280` asks a **read-only** model with no command or filesystem
+access to return its review JSON. That model **cannot** satisfy "disk copy
+written first", so rule (f) is an impossible prompt obligation for this
+producer. The trusted dispatcher owns it: parse the producer's response, project
+it into the canonical body, add the lifecycle frame, write the durable copy,
+then emit the identical serialized value.
+
+Recorded rather than implemented here — the projection adapter is a mechanism
+this roadmap's Phase 1 does not ship, and saying so is cheaper than a contract
+clause nobody can satisfy.
+
+### The validator is not the reason the rate is zero
+
+Checked directly on 2026-08-22, because "zero valid envelopes over 1,845 stops"
+has three possible causes and they need separating: a validator that rejects
+valid input, producers that do not emit the fields, or a shape nobody can
+produce.
+
+`validateResponse` was run by hand against a minimal envelope
+(`{summary, handoff, confidence, findings: [], risks: []}`) and a rich one
+(with `findings[{title, evidence_refs, mutating}]` and `artifact_paths`).
+**Both validate.** The `team_dispatch` model shape fails on four of five.
+
+So the contract is implementable and the validator is correct; the rate is zero
+because producers do not emit the shape. That removes the precondition one
+council seat set before any narrowing.
+
 ## Durable copy — the envelope on disk before the message
 
 ```

package/dist/agent-src/rules/untrusted-input-defense.md

@@ -69,9 +69,15 @@ delegating unbounded execution of everything the task's data happens to say.
 
 No deterministic gate inspects fetched/tool/RAG content for injected
 instructions — the quarantine is carried by the model (ADR-135 lists it in the
-CRITICAL policy class precisely BECAUSE no mechanical backstop exists today;
-a future content-scanning hook would be the first candidate to change this).
-Counting an adjacent lint here would be coverage inflation, so none is counted.
+CRITICAL policy class). Counting an adjacent lint here would be coverage
+inflation, so none is counted.
+
+**A content-scanning hook now exists and this field is unchanged.**
+`injection_scan_hook.ts` is warn-only and default-OFF: it cannot refuse, and a
+hook that cannot refuse does not enforce. This section used to say no such
+backstop existed and that a future one would change the field — the first half
+is now false, the second always was. Detail:
+[`untrusted-input-spotlighting § The content-scanning hook`](../docs/guidelines/agent-infra/untrusted-input-spotlighting.md).
 
 Body migrated to [`guideline:agent-infra/untrusted-input-spotlighting`](../docs/guidelines/agent-infra/untrusted-input-spotlighting.md) (per P4 of `road-to-kernel-and-router.md`) — runtime defense protocol (separate / spotlight / refuse role-takeover / no silent egress / untrusted agent-instruction files), hidden-instruction awareness (invisible Unicode + confusables), injection-signal taxonomy, least-agency → existing-gate OWASP mapping.
 Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).