@event4u/agent-config 14.12.0 → 14.13.0

package/dist/agent-src/commands/analyze/inbox.md

@@ -121,11 +121,75 @@ Resolve the argument. Directory mode: list files with size and line count, and
 say up front how many there are. **A large inbox is a triage problem, not a
 throughput problem** — never open ten files at full depth in one pass.
 
+#### The inbox directory name is opaque, or the whole chain leaks
+
+```
+AN INBOX DIRECTORY UNDER agents/tmp/ CARRIES AN OPAQUE ROUND IDENTIFIER.
+NEVER NAME IT AFTER THE SOURCE. THE TRUE SOURCE IS RECORDED ONCE, `ENC1:`
+ENCRYPTED, IN THE ROUND'S OWN INTAKE NOTE. ROADMAP `Source:` LINES CITE THE
+CODENAME ONLY.
+```
+
+`agents/tmp/` is gitignored, so a speaking directory name looks free. It is not:
+the name gets **quoted** into a tracked roadmap `Source:` header, into an
+evidence artefact, into a review-snapshot filename and into a PR body, and each
+quote republishes it in a public repository. Measured at
+`road-to-source-silence` Phase 0: 190 block-tier occurrences of quoted
+non-opaque `agents/tmp(.old)/<name>/` paths across the tracked tree, plus one
+tracked findings file named after a round. **The directory name is the root of
+the leak chain — if it is opaque, nothing readable exists to be quoted.**
+
+Accepted forms — `isOpaqueRoundId` in `src/scripts/_lib/source_shape.ts` is the
+authority, and the gate enforces the same predicate:
+
+| Form | Example |
+|---|---|
+| round-dated, optional 1-3 char disambiguator | `inbox-2026-08-h` |
+| content-free hex | `round-a91f3c`, `set-a91f3c` |
+| set number | `S17` |
+
+Anything that reads is speaking by construction. If a round arrives under a
+speaking name, **rename the directory before Phase 2** and record the mapping as
+below; renaming after the first quote lands means chasing the quotes.
+
+**Record the true source exactly once, encrypted.** In the round's intake note
+(`agents/tmp/<round-id>/intake.md`):
+
+```bash
+printf '%s' '<the real source, url or description>' \
+  | ./scripts-run src/scripts/_lib/link_crypto encrypt
+```
+
+Paste the `ENC1:` token into the intake note. That token, and the codename map at
+`agents/evidence/reports/source-codename-map.md`, are the only places the
+correspondence may exist. Never a second plaintext copy — not in the roadmap, not
+in the PR body, not in a commit message.
+
 ### Phase 2 — Triage (cheap, all files)
 
 One pass per file, shallow, producing a table before any deep read:
 
-| file | genre | age | drafted-against | recurrence | first-impression disposition |
+| file | genre | age | drafted-against | recurrence | lineage | first-impression disposition |
+
+`lineage` is `n/a` for a file that claims no consolidation, `complete` for one
+whose declared parent set matches the siblings present, or `omits: <names>` /
+`ghost: <name>` / `undeclared`. Fill it from one command over the folder, not by
+reading:
+
+```bash
+./scripts-run src/scripts/lint_consolidation_lineage --root <the inbox folder>
+```
+
+The column exists because a consolidating artifact is the one genre that reads
+as *finished* while being incomplete: it presents its content as adjudicated —
+parents named, conflicts resolved, a kill register for what was rejected — so a
+parent missing from that list is not *killed*, it is *undiscussed*, and nothing
+in the artifact distinguishes those two states. Measured over four inbox folders
+carrying a declared consolidation, four had an incomplete lineage
+(`agents/evidence/analysis/consolidation-lineage-census-2026-08-26.md`). It sits
+in the triage table rather than in a deep read for the same reason `recurrence`
+does: it is one command, and by the time a deep read starts the artifact has
+already been believed.
 
 `recurrence` is `first-seen` or a pointer to the earlier artifact — the marker in
 the file's own words, or a hit in `agents/tmp.old/` on the same subject (Phase
@@ -400,6 +464,16 @@ visibly not a new one, and the resulting learning is emitted as an artefact in
 Phase 5 like any other survivor — never as a line in the reply that nothing reads
 again.
 
+**A status-update prediction naming a concrete mechanism becomes a stub or a
+roadmap in the SAME run, never a line in a file about to be consumed.** That is
+the "right, never recorded" outcome caught at its source: the round before
+`inbox-2026-08-g` already named the hook-concern axis as the next ratchet
+candidate at 68→69, the sentence sat in an untracked inbox file, the file was
+consumed, and nothing under `agents/roadmaps/` inherited it — so the same
+recommendation arrived again a round later, correct both times and durable
+neither. A prediction that names a mechanism is already an artefact; the only
+question is whether anyone writes it down before its carrier disappears.
+
 ### Phase 5 — Map survivors onto this suite's artefact types
 
 The question is never "what does the file say" but **"what does it become here"**:
@@ -413,6 +487,29 @@ The question is never "what does the file say" but **"what does it become here"*
 | reference material read on demand | a `guideline` or `context` |
 | a measured finding | a `decision-record`/ADR, not a rule |
 | a defect claim | a roadmap item, once verified |
+| a consolidation omitting a parent | **not an artifact — a discharge, see below** |
+
+**An omitted parent is discharged, never left silent.** When Phase 2's `lineage`
+column read anything but `n/a` or `complete`, this phase says what happened to
+each omitted parent. Exactly three discharges are legal, and the choice is the
+operator's:
+
+1. **Fold it in** — read the omitted parent and carry its surviving items into
+   the consolidation, marking them as coming from it.
+2. **Record a kill ID for it** — the consolidation's kill register gains a row
+   naming the parent and why its content does not survive.
+3. **State that it was read and adds nothing** — one sentence, in the artifact,
+   naming the parent.
+
+**Silence is the failure mode; any of the three is a complete discharge.** The
+obligation is to *name* it, never to consolidate it — whether the omission was
+correct is a judgement the operator makes and this command does not. A finding
+that is usually wrong gets ignored, which is why a false positive costs one
+sentence (discharge 3) rather than a re-run.
+
+A `ghost:` reading — a declared parent with no matching file — has the same three
+discharges plus a fourth that is really a correction: fix the name. A lineage
+naming a plan nobody can open is the cheaper half of the same defect.
 
 Three hard defaults, from this repo's own scar tissue:
 
@@ -449,10 +546,20 @@ transcription. Phase 4b states this obligation for Phases 5 and 6 both; it is
 repeated here because this is the phase that writes the artefact, and an
 obligation named only upstream is one a Phase-6 executor never sees.
 
+**The `Source:` line carries the codename, never the source.** Per Phase 1's
+naming rule the round directory is already opaque, so
+`> **Source:** \`agents/tmp.old/inbox-2026-08-h/\`` is a compliant header and a
+speaking one is not. The gate's `source-header` and `tmp-quote` classes both
+block inside `agents/**`, so a speaking value fails CI rather than merely
+reading badly. If the roadmap needs to say *what kind* of source it was, describe
+the class ("an external acceptance-pipeline reference") and put the identity in
+the encrypted intake note.
+
 Then the inbox contract from
 [`agents-layout`](../../../../docs/contracts/agents-layout.md), in the **same
 reply**: `mv` the consumed file to `agents/tmp.old/`, point the roadmap's
-`Source:` line at its new path, and regenerate the dashboard. A consumed file
+`Source:` line at its new path — still the codename — and regenerate the
+dashboard. A consumed file
 left in `agents/tmp/` is a rule violation, not untidiness. Move only the files
 actually processed — never sweep the rest of the inbox.
 

package/dist/agent-src/commands/feature/dev.md

@@ -7,7 +7,7 @@ cluster: feature
 sub: dev
 description: Full 7-phase feature development workflow for complex features.
 argument-hint: "[description]"
-skills: [laravel, php-coder]
+skills: [laravel, php-coder, test-driven-development]
 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)."
@@ -88,7 +88,12 @@ Do NOT use for single-line fixes, trivial changes, or urgent hotfixes.
 3. Follow chosen architecture from Phase 4.
 4. Follow codebase conventions strictly (read guidelines).
 5. Update task list as progress is made.
-6. Write tests alongside the implementation.
+6. Work **one behavior at a time**: write the failing test for that behavior,
+   observe it fail, write the minimum code that makes that one behavior pass,
+   then take the next behavior. A test phase followed by a code phase is
+   batch-TDD, not test-first — it buys the ordering and loses the feedback.
+   The only exceptions are the Do-NOT list in the `test-driven-development`
+   skill; a skipped test-first cycle is recorded in the decision log, never silent.
 
 ### Phase 6: Quality Review
 

package/dist/agent-src/commands/ghostwriter/write.md

@@ -81,7 +81,11 @@ Style fidelity may be lower."* Non-blocking.
 Per [`write-engine § 2`](../../../docs/contracts/write-engine.md).
 Flag form: `--tone=<formal|casual|neutral>`,
 `--length=<words>`, `--channel=<linkedin-post|tweet|blog|freeform>`,
-`--audience=<text>`. Missing flags → interactive prompt, **one
+`--audience=<text>`. The channel values and their length defaults are
+the schema-validated set in `src/config/drafting-channels.yml` — edit
+that file and `write-engine.md` together, never one alone;
+`tests/scripts/drafting_channels_schema.test.ts` fails on drift, and on
+the short form `linkedin`, which is not a value. Missing flags → interactive prompt, **one
 question per turn**, in the order Topic → Tone → Length → Channel →
 Audience. Tone / length defaults derive from the per-channel table
 and the vocab-register → tone mapping in the engine contract.

package/dist/agent-src/commands/implement-ticket.md

@@ -7,7 +7,7 @@ routes_to: [refine-ticket, feature-planning]
 replaces: []
 visibility: visible
 skills: [refine-ticket, feature-planning]
-description: Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — Option-A loop over the `work_engine` engine, block-on-ambiguity, no auto-git.
+description: Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — Option-A loop over `work_engine`, block-on-ambiguity, no auto-git, test-first enforced.
 argument-hint: "[ticket-key | url | bundle-path | pasted-text]"
 suggestion:
   eligible: true

package/dist/agent-src/commands/mission/upgrade.md

@@ -122,7 +122,7 @@ catalog fixes are test-driven — a bounded generate→run→revise→re-run loo
 a numeric threshold (then a judge confirms), reusing the same N=3 cap. Use
 test/quality verdicts only; the live-app Playwright verdict stays deferred. The
 loop is multi-turn reasoning, not a runtime — it honors
-[`no-runtime-boundary`](../../docs/contracts/no-runtime-boundary.md) exactly as
+[`resident-process-governance`](../../docs/contracts/resident-process-governance.md) exactly as
 the mission does.
 
 Handle exit codes per the `/work` contract:

package/dist/agent-src/commands/orchestrate.md

@@ -5,7 +5,7 @@ pack: meta
 visibility: internal
 cluster: orchestrate
 skills: [subagent-orchestration]
-description: Run a YAML pipeline defined under `.agent-config/orchestrations/` — chains personas / skills / commands / sub-agents per the orchestration-dsl-v1 contract
+description: Run a YAML pipeline defined under `.agent-config/orchestrations/` — chains personas / skills / commands / subagents per the orchestration-dsl-v1 contract
 argument-hint: "<pipeline-name | path> [key=value ...]"
 suggestion:
   eligible: true
@@ -23,7 +23,7 @@ packs:
 
 Execute a YAML pipeline file from `.agent-config/orchestrations/`
 against the current workspace. Pipelines are deterministic chains of
-personas, skills, commands, and sub-agents pinned by the
+personas, skills, commands, and subagents pinned by the
 [`orchestration-dsl-v1`](../docs/contracts/orchestration-dsl-v1.md)
 contract.
 

package/dist/agent-src/commands/post-as/me.md

@@ -75,7 +75,11 @@ operator notes, not voice signal.
 Per [`write-engine § 2`](../../../docs/contracts/write-engine.md).
 Flag form: `--tone=<formal|casual|neutral>`,
 `--length=<words>`, `--channel=<linkedin-post|tweet|blog|freeform>`,
-`--audience=<text>`. Missing flags → interactive prompt, **one
+`--audience=<text>`. The channel values and their length defaults are
+the schema-validated set in `src/config/drafting-channels.yml` — edit
+that file and `write-engine.md` together, never one alone;
+`tests/scripts/drafting_channels_schema.test.ts` fails on drift, and on
+the short form `linkedin`, which is not a value. Missing flags → interactive prompt, **one
 question per turn**, in the order Topic → Tone → Length → Channel →
 Audience. Defaults inherit from the engine's per-channel table and
 the pace mapping above.

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

@@ -287,9 +287,9 @@ built bundle.
 ## 7. Expiry is a reported state, never a stall
 
 ```
-WHEN THE AUTHORIZATION WINDOW CLOSES WITH WORK LEFT, THE RUN STOPS CLEANLY
-AND REPORTS. IT NEVER RETRIES THE GUARD, AND IT NEVER EDITS THE GUARD,
-ITS SOURCE, OR ITS BUNDLES — READ-ONLY VERIFICATION ONLY.
+WHEN THE AUTHORIZATION WINDOW CLOSES WITH WORK LEFT, THE RUN PAUSES, REPORTS,
+AND ASKS FOR RE-AUTHORIZATION. IT NEVER RETRIES THE GUARD, AND IT NEVER EDITS
+THE GUARD, ITS SOURCE, OR ITS BUNDLES — READ-ONLY VERIFICATION ONLY.
 ```
 
 **Unreachable while the merge step is gated**, and stated rather than left for
@@ -298,9 +298,22 @@ operation (`push` and `commit` are `WARN_OPS`), so the window governs nothing
 it does. This section is the contract for when the gate opens.
 
 Write the summary as-is with a `window-expired` disposition per unprocessed PR
-and name the exact re-authorization needed. Widening `LEDGER_MAX_AGE_MS` is
-forbidden practice: on 2026-08-21 it was patched to six hours for a drain run
-and the widening reached the trunk.
+and name the exact re-authorization needed. Then STOP and wait — do not end the
+run, and do not proceed to the next PR. ADR-251 (2026-08-30) decided this
+shape: expiry is a pause, not a termination.
+
+**The operator's reply is what resumes it, and it renews the window through the
+path that already exists.** `git_authorization_hook.ts` rewrites this session's
+ledger with a fresh `detected_at` on every human-typed prompt, so a reply
+carrying the re-authorization you named resets the age the guard compares
+against — no new mechanism, and the signal still comes from text the user typed.
+Re-verify the manifest entry (number and head SHA) before resuming, exactly as
+§ 8 requires: the pause is a window in which the world can move.
+
+Widening `LEDGER_MAX_AGE_MS` is still forbidden practice, and ADR-251 kept the
+30-minute value deliberately rather than by omission: on 2026-08-21 it was
+patched to six hours for a drain run and the widening reached the trunk. The run proposes no value for it, edits neither it nor its bundles,
+and treats a refusal as the answer.
 
 ## 8. Kill switches, and what happens after a merge
 

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

@@ -313,11 +313,25 @@ branch setting, push, open a PR, re-run CI, update a merge base, fix a failing
 test, authorise spend inside a budget — is machine-executable by the agent, and
 is therefore remediation work rather than a blocker.
 
-| Outcome | When | Success? |
-|---|---|---|
-| `complete` | `count_open == 0` and the PR is open | yes — archival check runs |
-| `blocked` | every remaining open step is **externally impossible** for the agent | **no** — partial progress, labelled as such |
-| a halt | one of the five conditions fired | **no** — the halt is reported |
+| Outcome | When | Success? | terminal state |
+|---|---|---|---|
+| `complete` | `count_open == 0` and the PR is open | yes — archival check runs | `success` |
+| `blocked` | every remaining open step is **externally impossible** for the agent | **no** — partial progress, labelled as such | `blocked`, or `approval-required` where the work is finished and waiting on a human |
+| a halt | one of the five conditions fired | **no** — the halt is reported | `exhausted` when a declared budget ran out; `stagnated` when the same failure signature repeated with budget left |
+
+**The closing report names the terminal state by word**, from
+[`terminal-states`](../../../../src/agent-src/contexts/execution/terminal-states.md).
+The reason is the failure that vocabulary exists to stop: a run that stopped at
+its iteration cap and one that finished both leave the roadmap looking the same,
+because the checkbox glyphs cannot express `exhausted`, `stagnated` or
+`approval-required` — they collapse into `[ ]` and `[~]`. Three of the six states
+are therefore invisible in the dashboard and visible only in the report, which is
+why the report has to say the word.
+
+`exhausted` and `stagnated` are **never** reported as `complete`, whatever
+partial progress exists, and they are kept apart on purpose: `exhausted` says the
+budget may have been too small and raising it is a legitimate response;
+`stagnated` says more of the same will not help and raising it is the wrong one.
 
 `blocked-preflight` no longer exists. A run always starts.
 

package/dist/agent-src/commands/tdd/red.md

@@ -6,7 +6,7 @@ visibility: internal
 cluster: tdd
 sub: red
 skills: [test-driven-development]
-description: TDD red phase — enumerate cases, write ONE failing test, watch it fail at an assertion (not an import error)
+description: TDD red phase — enumerate cases, write ONE failing test, watch it fail for a reason that is about the behaviour under test
 argument-hint: "[behavior to test]"
 suggestion:
   eligible: false
@@ -26,6 +26,16 @@ Drives the **Design → Test-Red** phases of
 
 1. State the behavior in one sentence; enumerate the cases (happy / boundary / error).
 2. Write ONE failing test for the first case.
-3. Run it; confirm it fails at an **assertion**, not an import/collection error.
+3. Run it; confirm the failure is **about the behavior under test**. Valid:
+   a failing **assertion** · a **missing target** (class-not-found, or a
+   compile/type error naming the unimplemented symbol) · a **contract
+   failure**. Invalid: a broken **fixture** · a **syntax error** in the test ·
+   a missing **unrelated dependency** · a **runner or environment** fault —
+   those would fail identically with the behavior fully implemented, so they
+   measure nothing. A symbol that does not exist yet can only fail at load;
+   demanding an assertion there would force a production stub first, which is
+   what this phase exists to prevent. Taxonomy owner:
+   [`test-driven-development`](../../../skills/test-driven-development/SKILL.md)
+   § What makes a RED valid.
 4. Honor the Test-Red Forbidden block: **no production edits** (diff = `tests/**` only).
 5. Output: the failing test + its observed failure reason. Hand to `/tdd green`.

package/dist/agent-src/commands/work.md

@@ -7,7 +7,7 @@ routes_to: [refine-prompt, command-routing]
 replaces: []
 visibility: visible
 skills: [refine-prompt, command-routing]
-description: Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` engine, confidence-band gated, no auto-git.
+description: Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over `work_engine`, confidence-band gated, no auto-git, test-first.
 argument-hint: "[prompt]"
 suggestion:
   eligible: true

package/dist/agent-src/contexts/communication/rules-auto/token-efficiency-mechanics.md

@@ -115,3 +115,43 @@ the enumerated-set carve-out.
 - User explicitly asks for full output — show it.
 
 → Detailed patterns: `docs/guidelines/agent-infra/output-patterns.md`
+
+## Independent calls go in ONE block — the evidence
+
+```
+CALLS WITH NO DEPENDENCY BETWEEN THEM GO IN THE SAME BLOCK.
+A SECOND CALL THAT DOES NOT READ THE FIRST ONE'S RESULT IS NOT A SECOND TURN.
+BEFORE EMITTING A SINGLE CALL, ASK WHAT ELSE IS ALREADY KNOWN TO BE NEEDED.
+```
+
+The ceiling above forbids repetition; this forbids the opposite failure —
+splitting work that had no reason to be split. It is stated because it is
+**measured, not suspected**: over ten sessions of this package,
+`probe_turnaround` reports a mean tool-call batch size of **1.01**, with 27 of
+2,889 tool-using requests (0.93 %) carrying more than one call. At a 4.7 s
+median generation latency, a request that fans out to 42 calls spends about five
+minutes on serialization before a single tool runs.
+
+**Nothing in this package caused that, and nothing in it can fix it.** The cause
+was looked for and is recorded as absent
+(`agents/evidence/analysis/agent-turnaround-2026-08-30.md` § E2): no rule, skill
+or template forbids parallel calls, and parallel calls do occur — so 1.01 is a
+tendency, not a floor with a mechanism behind it.
+
+**The discriminator is the dependency, never the count.** Two greps over
+different files, a status and a log, three independent reads named before the
+first one runs — one block. A read whose path comes out of the previous result —
+two blocks, and batching them would be guessing.
+
+**Do not read this as "write shorter commands".** In the same corpus, 98.1 % of
+`Bash` calls are already compound or heredoc, and the 18 % that exceed 1,500
+characters carry 75 % of all command bytes — those are one-shot scripts that each
+replace three to six round-trips. Splitting them trades one expensive call for
+several cheap ones and makes the number worse while looking like a fix.
+
+**Honest enforcement — `instruction-only`.** No gate can observe a call that was
+not batched: a transcript records the calls that happened, never the block they
+could have shared. `probe_turnaround` reports the rate afterwards and refuses to
+gate on a store CI does not have. This paragraph is the whole mechanism, and the
+roadmap that added it pre-committed to recording a null if the rate does not
+move rather than repeating the reminder more loudly.

package/dist/agent-src/contexts/execution/auto-dispatch-classification.md

@@ -232,8 +232,11 @@ NEVER A SILENTLY DEGRADED ANSWER. NO LLM CLASSIFIER FALLBACK (CUT C3).
 **Why rg-first** (council 2026-07-28, 2 rounds): the pre-registered benchmark
 behind the `code-graph-retrieval-null` claim (`docs/CLAIMS.md`) measured
 native-graph recall 0.365 vs grep 0.797 on graph-shaped questions — an
-indexing gap that keeps `code_graph.enabled` false permanently. The accelerant
-clause in the table above is that bound's escape hatch and is inert today.
+indexing gap that keeps `code_graph.enabled` false BY DEFAULT — not
+permanently: the 2026-08-15 withdrawal retracted that, and the figures predate
+the 2026-08-22 extractor repair. The accelerant clause above is that bound's
+escape hatch; `classifyLookup` reads the flag, so turning it on is the whole
+change.
 
 **Escalation, not degradation:** a primitive that returns nothing (index miss,
 pattern too ambiguous, report script absent) — **or an unusable result**

package/dist/agent-src/contexts/execution/autonomy-mechanics.md

@@ -157,6 +157,27 @@ When validating a single target, run the **specific** check, not a meta-task tha
 
 Concrete tool mapping — verify with the narrowest tool that proves the target green: a single `curl` / Playwright spec / browser run for HTTP behavior, the project's test runner with a `--filter` for one test, a debugger / `xdebug` step-through for one frame. Never substitute a meta-pipeline for a tool that pinpoints the failure.
 
+### Progress-primary ordering — and why the cap stays
+
+Where the objective is **countable** — findings closed, tests passing,
+occurrences remaining — the primary stop signal is **no progress** or a **new
+minimum**, and the N=3 iteration cap is the **backstop**. A counter alone cannot
+tell three attempts that each closed a finding from three that changed nothing.
+
+**Do not remove the cap.** A no-progress signal is only as good as the metric
+behind it, and a metric that stops moving because the MEASUREMENT broke looks
+exactly like one that stops moving because the work is done. The cap bounds the
+damage when the primary signal is wrong.
+
+The two stops are different outcomes and are reported as different words: the cap
+firing is `exhausted`, a repeating failure signature with budget left is
+`stagnated` — see
+[`terminal-states`](terminal-states.md). Collapsing them invites the wrong
+remedy, because raising a budget helps the first and never the second.
+
+Where the objective is NOT countable, the cap is the only signal and the N=3
+budget above applies unchanged.
+
 ## Adaptive effort & stop (RDP)
 
 Scale effort to task difficulty, and stop when marginal evidence drops — coupled

package/dist/agent-src/contexts/execution/orchestration-telemetry.md

@@ -39,6 +39,7 @@ v1 forward-compat rule on unknown fields).
 |---|---|---|
 | `task_size_estimate` | int | Pre-dispatch estimate of the task's size (the orchestrator's sizing heuristic). Counts only, no body. |
 | `spawn_count` | int | Number of subagents dispatched for this task. `0` → handled in-session. |
+| `empty_cycles` | int \| null | Trigger fires suppressed as duplicates since the last outcome record. Reported as its OWN quantity and never folded into a success rate's numerator or denominator: a duplicate is not an outcome, and it is also not nothing — a rising count is what an idle loop looks like from outside. `null` = not tracked by this producer, which is **not** the same as zero duplicates observed. Deduplication rule in `src/scripts/_lib/empty_cycles.ts`: same key AND inside the window, both conjuncts required. |
 | `tiers` | string[] | Model tiers dispatched to, one entry per spawn class (e.g. `["sonnet","opus"]`). Tier names only, no prompts. |
 | `token_delta` | int | Net token cost of the dispatch versus the in-session baseline. Positive = orchestration cost more; negative = saved tokens. Counts only. |
 | `token_delta_provenance` | enum | `"measured"` when sourced from host-reported `usage` metadata (preferred); `"estimated"` when self-estimated from response length (mark always when host usage is unavailable). |

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

@@ -47,6 +47,46 @@ 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.
 
+## Why success is gated, and not accepted
+
+```
+AN UNVERIFIED SELF-REPORT IS INDISTINGUISHABLE FROM A RESULT.
+A RETURN THAT CLAIMS SUCCESS AND SHOWS NO CHANGE AGAINST ITS OWN DECLARED
+OUTPUT CONTRACT IS NOT EVIDENCE OF SUCCESS. IT IS EVIDENCE OF A CLAIM.
+```
+
+**The failure this prevents.** Every downstream aggregation reads the recorded
+outcome, not the return. `src/scripts/extract_audit_patterns.ts` mines repeated
+patterns from it, and the per-asset effectiveness report is built on the same
+stream. A forged `success` does not stay one line: it becomes signal, and the
+report then recommends keeping an asset that never worked and retiring one that
+did. Nothing downstream can detect it, because at that point the forgery is
+indistinguishable from the thing it imitates — which is the whole reason the
+check has to happen where the record is written rather than where it is read.
+
+**Why the gate reads the declared output contract and not the diff.** The
+obvious rule — claimed success plus an empty diff is never a success — is wrong
+here, and wrong in a way that is worse than doing nothing. Analysis, review and
+read-only research dispatches are a large share of this repository's subagent
+traffic, and every one of them legitimately produces no diff. The unconditional
+rule would mark them all as failures and poison the same aggregation in the
+opposite direction. **Zero diff may be valid, so "zero diff = failure" must not
+be global.** The gate therefore fires only where the dispatch itself declared
+that a code change was the expected output.
+
+**An unmeasured diff is not an empty diff.** Where the producer did not measure,
+the gate does not fire. Treating "not measured" as zero manufactures the same
+forgery with the opposite sign, and an aggregation cannot tell the two apart any
+better than it can tell a forged success from a real one.
+
+Implemented by `envelopeOutcome` in `src/scripts/_lib/orchestration_record.ts`,
+the tree's only cross-domain outcome mapping. Because it is the only one, the
+mapping is **versioned**: lines carry `outcome_semantics`, and an absent field
+means the pre-2026-08-30 unconditional semantics. `audit-log-v1` is append-only,
+so a labelling change cannot be rolled back the way a gate can — a reader
+aggregating across the cutover segments on that field rather than inferring from
+a date.
+
 ### Per-field divergence, one row per field
 
 | Field | spawn-contract (f) | `team_dispatch` model JSON (`:297`) | `subagent_response.ts` validator | `dispatch_r2_reviewer` |

package/dist/agent-src/contexts/execution/subagent-steering.md

@@ -104,11 +104,23 @@ doing its job; the orchestrator verifies (or revises) the parent first.
 ## Rollback guardrails — surfaced, not auto-disabled
 
 ```
-A CONFIG PACKAGE RUNS NO DAEMON. THERE IS NO AUTOMATIC COHORT-DISABLE.
+A RESIDENT PROCESS HERE IS GOVERNED, NEVER AUTOMATIC. NO COHORT-DISABLE.
 BREACHES ARE SURFACED FROM THE AUDIT LOG FOR THE MAINTAINER / USER TO ACT ON.
 THE ONLY AUTOMATIC STOP IS THE PER-TARGET N=3 BUDGET.
 ```
 
+> **Amended 2026-08-27 (ADR-249).** The first line used to read *"A CONFIG
+> PACKAGE RUNS NO DAEMON"*, and that premise no longer holds: a **supervised**
+> resident process is permitted in core under four governance conditions
+> (`docs/contracts/resident-process-governance.md`, class P1). The block's force
+> is unchanged, because the daemon clause was never what it governed — the rule
+> here is that a breach never stops a cohort by itself, and that is if anything
+> more load-bearing now than when nothing could be running. The replacement
+> states the adopted constraint rather than an absence, which is the wording rule
+> the same reversal imposes on every surface: name what the repository holds
+> itself to, never a state of the world.
+
+
 The guardrail thresholds (`breachedGuardrails()`), read off the
 [`orchestration-telemetry`](orchestration-telemetry.md) audit signals:
 

package/dist/agent-src/contexts/execution/terminal-states.md

@@ -0,0 +1,96 @@
+# Terminal states — what a run REPORTS when it stops
+
+> `road-to-skill-ecosystem-runtime-enforcement` Phase 4. Loaded on demand;
+> the obligation surface is [`verify-before-complete`](../../rules/verify-before-complete.md).
+
+A run has exactly one terminal state, and reporting the wrong one is not a
+wording problem. **An error or an exhausted budget is never reported as
+success.** The failure this vocabulary exists to stop is the one that reads
+identically to a win: a loop that hit its iteration cap, a gate that could not
+run, an approval that never came — each ending with a summary that says the work
+is done.
+
+## The six states
+
+| state | what it means | what it is NOT |
+|---|---|---|
+| `success` | The stated objective is met AND verified by a command run this turn. | Not "the edits landed". Landing is not verifying. |
+| `clean-no-op` | Nothing needed doing, and that was **established**, not assumed. | Not "I found nothing" from a scan that never ran. A dead scope is `blocked`. |
+| `blocked` | An external precondition is missing: a credential, a permission, a service, a decision only the user can make. | Not "hard". A blocker is a thing that is absent, not a thing that is difficult. |
+| `approval-required` | The work is ready and the next action crosses a gate the agent may not cross alone. | Not `blocked`: nothing is missing, and the run produced a deliverable. |
+| `exhausted` | A declared budget ran out — iterations, tokens, spend, wall-clock. | **Never** `success`, whatever partial progress exists. The cap firing IS the outcome. |
+| `stagnated` | The budget has not run out and progress has stopped: the same failure signature is repeating. | Not `exhausted`. Stagnation is detected by a NO-PROGRESS signal, not by a counter. |
+
+**Why `exhausted` and `stagnated` are separate**, when both stop a loop: they
+have different remedies and different next actions. `exhausted` says *the work
+may be fine and the budget was too small* — raising it is a legitimate response.
+`stagnated` says *more of the same will not help* — raising the budget is the
+wrong response, and a vocabulary that collapses them invites exactly that.
+
+## The mapping onto roadmap glyphs, and the three states glyphs cannot express
+
+Roadmap checkboxes carry four glyphs. They describe a **step's disposition**, not
+a **run's outcome**, and the gap is not an oversight — it is what makes a
+budget-exhausted stop indistinguishable from a completed one in a dashboard.
+
+| glyph | meaning | nearest terminal state |
+|---|---|---|
+| `[x]` | done | `success` — and only when a verify clause was met |
+| `[ ]` | open | *(no state — the step has not run)* |
+| `[~]` | deferred | `blocked` or `approval-required`, undistinguished |
+| `[-]` | cancelled | *(a decision, not a run outcome)* |
+
+**Three states have no glyph, and they are exactly the ones a validation budget
+and a hard-blocker class produce:**
+
+1. **`exhausted`** — the run stopped at its cap with the step still open. The
+   glyph stays `[ ]`, which is identical to *never attempted*. A reader cannot
+   tell three failed attempts from zero.
+2. **`stagnated`** — same `[ ]`, and the distinction that matters (retrying is
+   pointless) is invisible.
+3. **`approval-required`** — collapses into `[~]` alongside `blocked`, so a
+   roadmap cannot show that the work is FINISHED and waiting on a human, versus
+   not startable at all.
+
+**This is recorded rather than fixed.** Adding glyphs would change a format that
+`update_roadmap_progress`, `check_roadmap_trackable`, `lint_empty_roadmaps` and
+every archived roadmap already parse — a migration, not a step. What the
+vocabulary buys today is that a run's CLOSING REPORT can say the word the glyph
+cannot.
+
+## Progress-primary ordering
+
+When the objective is **countable** — findings closed, tests passing, occurrences
+remaining — the primary stop signal is **no progress** or a **new minimum**, and
+the iteration cap is the **backstop**.
+
+**Do not remove the cap.** A no-progress signal is only as good as the metric
+behind it, and a metric that stops moving because the measurement broke looks
+exactly like a metric that stops moving because the work is done. The cap is what
+bounds the damage when the primary signal is wrong.
+
+Where the objective is not countable, the cap is the only signal and the N=3
+validation budget in [`autonomous-execution`](../../rules/autonomous-execution.md)
+applies unchanged.
+
+## Reporting contract
+
+A closing report names the state **by one of the six words above**, and where the
+state is not `success` it names what would change it:
+
+- `exhausted` — the budget that ran out, its value, and what was achieved inside it.
+- `stagnated` — the repeating failure signature, and the attempts it survived.
+- `blocked` — the missing thing, by name.
+- `approval-required` — the exact action awaiting approval.
+- `clean-no-op` — what was scanned, so "nothing to do" is distinguishable from
+  "nothing was read".
+
+## See also
+
+- [`verify-before-complete`](../../rules/verify-before-complete.md) — no
+  completion claim without fresh evidence; this names what to claim when the
+  claim is not completion.
+- [`autonomous-execution`](../../rules/autonomous-execution.md) — the N=3
+  validation budget whose firing is `exhausted`.
+- [`autonomy-mechanics`](autonomy-mechanics.md) — the budget's mechanics and the
+  adaptive-effort ordering this page's progress-primary section states.

package/dist/agent-src/rules/artifact-drafting-protocol.md

@@ -44,7 +44,7 @@ Fires once per creation task, not once per edit.
 
 ## The three phases
 
-**A — Understand** (≤ 5 clarifying questions: problem, trigger surface, should-trigger examples, near-misses, artifact type) · **B — Research** (mandatory four-surface overlap scan; open + skim the 3 nearest matches; extend-vs-create decision) · **C — Draft** (2-3 description variants first, then the body; live size enforcement). Per-phase procedure + the roadmap batch-mode carve-out: the mechanics guideline below.
+**A — Understand** (≤ 5 clarifying questions: problem, trigger surface, should-trigger examples, near-misses, artifact type) · **B — Research** (mandatory four-surface overlap scan; open + skim the 3 nearest matches; extend-vs-create decision, written into the artifact as `composition_review:`) · **C — Draft** (2-3 description variants first, then the body; live size enforcement). Per-phase procedure + the roadmap batch-mode carve-out: the mechanics guideline below.
 
 ## Golden rules
 

package/dist/agent-src/rules/broken-access-control.md

@@ -25,6 +25,10 @@ collision_ok:
   "tenant": "cross-tenant isolation is this rule's core subject"
 # obligation: line 55
 obligation_frequency: "per-edit"
+evidence:
+  source_type: external-standard
+  verified_on: 2026-08-30
+  normative_level: recommended
 ---
 
 # Broken Access Control