@event4u/agent-config 16.0.0 → 16.1.0

package/dist/agent-src/skills/existing-ui-audit/SKILL.md

@@ -163,10 +163,20 @@ Read `components.json` for the registered style + base color, then read the `pac
 ### 4b. Prefer a live Storybook read over the hand-read inventory — when one is running
 
 When the project carries `@storybook/addon-mcp` **and** a Storybook is running, query it
-instead of reading files: `list-all-documentation` for the inventory, then `get-documentation`
-for the components that matter. **The live read wins; the hand-read inventory of step 4 is the
-fallback and is never removed** — an agent that cannot reach a running Storybook must still be
-able to inventory the library. The channel disappearing is normal, not an error.
+instead of reading files: `docs-list` for the inventory, then `docs-show` for the components
+that matter. **The live read wins; the hand-read inventory of step 4 is the fallback and is
+never removed** — an agent that cannot reach a running Storybook must still be able to
+inventory the library. The channel disappearing is normal, not an error.
+
+**The names are version-bound, and these are the current ones.** Own derivation, from a
+throwaway `npm install` on 2026-09-13, not from any document: at `@storybook/addon-mcp@10.6.0`
+the docs tools are registered by `storybook`'s own `createDocsToolset` under the method ids
+`docs.list` / `docs.show` / `docs.showStory`, and `toMcpToolName` renders those as `docs-list`,
+`docs-show` and `docs-show-story`. The older `list-all-documentation` / `get-documentation` were
+the literal names at `@storybook/addon-mcp@0.7.0` (via `@storybook/mcp@0.8.0`); at 10.6.0 they
+survive only as the tools' human-readable **titles**. There is no 10.5.x of the addon — it goes
+0.7.0 → 10.6.0 — so a project on the current scaffold gets the `docs-*` names. If a live
+`tools/list` disagrees, the live read wins over this paragraph.
 
 **React-only while the toolset is in preview.** Storybook's own MCP FAQ (docs **10.5**,
 `docs/ai/mcp/overview` § FAQ) states the documentation toolset supports React only during

package/dist/agent-src/skills/experiment-loop/SKILL.md

@@ -91,7 +91,37 @@ twice, leaving the branch one iteration ahead of its own record.
 1. **The register path**, and the iteration count actually run against the bound.
 2. **A metric line**: baseline → final, and the number of keeps versus reverts.
 3. **The exit condition that fired**, named — bound reached, or exit signal.
-4. **Every reverted iteration listed** with its reason. A revert is a result the
+4. **A `run_terminal` value** — the exit in the vocabulary every other loop in
+   this tree reports in, so a reader can count this run's stop alongside the
+   continuation hook's and the self-fix lanes' without a per-surface
+   translation table.
+
+   | exit condition | `run_terminal` |
+   |---|---|
+   | `score >= target` — the run had a destination and reached it | `success` |
+   | `iterations_run >= max_iterations` — the declared bound | `exhausted` |
+   | `consecutive_reverts >= N` — the exit signal fired | `stagnated` |
+   | the evaluator was red on the unchanged tree, so no iteration ran | `clean-no-op` |
+   | the run stopped on a missing precondition (metric unreadable, verifier absent) | `blocked` |
+
+   The value set is `RunTerminalState` — `success`, `clean-no-op`, `blocked`,
+   `approval-required`, `exhausted`, `stagnated`, `premise-invalidated` —
+   declared once at `src/scripts/_lib/outcome_vocabularies.ts`
+   (`RUN_TERMINAL_STATES`) and described in
+   [`terminal-states`](../../agent-src/contexts/execution/terminal-states.md).
+   A new exit condition maps onto an existing member or it is not a terminal
+   state; never invent a value here.
+
+   `exhausted` and `stagnated` stay distinct on purpose. This skill's own pivot
+   ladder already treats them differently — a spent bound may deserve a larger
+   one, while consecutive reverts mean the hypothesis class is done and route to
+   the ladder instead. Reporting both as "stopped" throws away the part that
+   decides what happens next.
+
+   Reaching the bound is a normal exit, not a failure, and `exhausted` does not
+   say otherwise — it says where the run stopped, never whether it was worth
+   running. A published null is still a result.
+5. **Every reverted iteration listed** with its reason. A revert is a result the
    next run needs, not noise to summarise away.
 
 ## Gotcha

package/dist/agent-src/skills/roadmap-writing/SKILL.md

@@ -191,7 +191,7 @@ the owner can decide in one sitting: one option named and why, what the delay
 costs, a command or path per option rather than prose, and an offer to walk
 them through it. Ratcheted by `lint_roadmap_blockers`. Full shape:
 [`templates/roadmaps.md` rule 20](../../agent-src/templates/roadmaps.md).
-Omit it entirely when there is no such gate; run the § 4c gate-test first.
+Omit it entirely when there is no such gate; run the § 4c gate-test first. A **hold** is the publication-side twin — a blocker stops execution, a hold stops publication; ask once whether an intermediate tree state must stay unpublished (default **no**; roadmap incompleteness never is one), walk `re-sequence → guard → hold`, and record the avoided outcome as well as the taken one, per [`templates/roadmaps.md` rule 28](../../agent-src/templates/roadmaps.md) and the § 5c self-check in [`/roadmap:create`](../../domains/product-basic/roadmap/create/command.md).
 
 ### 5c. Risk review (Gate R1) — after draft, before save
 

package/dist/agent-src/skills/storybook-workshop/SKILL.md

@@ -52,6 +52,43 @@ single prop's effect because every value is co-present. Split it, one axis per s
 Stories render under the **same semantic tokens** as the app and the `.dark` class; a
 hardcoded preview theme makes the workshop lie about what the component looks like in place.
 
+### The five behavioral stories — assert a value, never an image
+
+`Hover`, `Focus`, `Active`, `Keyboard` and `ReducedMotion` join the set above, and they
+carry one extra rule: **each asserts a resolved computed style or a handler effect, never a
+screenshot.** A component that owes a state checklist and proves it with a pixel diff has
+not proved it — a screenshot is a resting frame, and none of these five is a resting frame.
+
+| Story | Drive | Assert |
+|---|---|---|
+| `Hover` | `userEvent.hover(el)` | the resolved property the hover rule is supposed to change actually changed |
+| `Focus` | focus the element | the `:focus` styles resolve as intended |
+| `Keyboard` | `userEvent.tab()` until the element is active | a visible `:focus-visible` indicator resolves — programmatic focus does **not** set it in Chromium, so a `.focus()` call reports a real focus ring as absent |
+| `Active` | press and hold | what pressing adds **on top of hover** — a pointer cannot press without hovering, so asserting against the resting style makes one removed hover rule fail two stories |
+| `ReducedMotion` | emulate `prefers-reduced-motion: reduce` | what the surface presents *instead of* the motion, per [`accessibility-auditor`](../accessibility-auditor/SKILL.md) § 2 — not that the media block exists |
+
+The `Active` and `Keyboard` rows are not style advice. Both are measured failure modes from
+building the probe that backs this set, recorded here so the next author does not rediscover
+them: the first produced a duplicate finding for a single defect, the second reports a focus
+ring that is present as missing.
+
+### Responsive rows — one row per declared breakpoint
+
+Beside the state stories, each responsive component owes a row per declared breakpoint
+(1440 / 768 / 375 / 320) asserting **the layout property that is supposed to change there** —
+`flex-direction`, `grid-template-columns`, `display`. One row per breakpoint, not one per
+property: a single media rule usually moves several properties at once, and one finding each
+counts one defect several times.
+
+**Where a workshop is absent, this set is still assertable.** These stories are a contract
+about what is asserted, not about a particular runner — the `ui_conformance_probe` script
+exercises the same five states and the same breakpoint rows against a file URL. It and its
+sensitivity fixture live in the package repository and are **not** shipped to consumers,
+which is why both are named rather than linked: a path to either resolves nowhere in an
+install. The fixture is the evidence for the two sensitivity claims above — removing one
+hover rule turns exactly the hover assertion red and nothing else, and removing one media
+rule turns exactly the matching breakpoint row red.
+
 ## JSDoc `@summary` is required, and the reason is mechanical
 
 The manifest an agent reads **truncates descriptions**. A component whose summary is a
@@ -81,7 +118,7 @@ files otherwise — and only then decide whether anything needs writing.
 1. **Inspect the existing story set before authoring anything.** Read what the library
    already has — via the MCP channel below when it is available, otherwise by reading the
    story files — and check the component against it by name and by shape.
-   - **Source of truth:** the story files, or `list-all-documentation` over a running Storybook.
+   - **Source of truth:** the story files, or `docs-list` over a running Storybook.
    - **Verify:** the component you are about to write does not already exist under another name.
 2. **One story per concept**, named from the state set above.
    - **Verify:** no story name joins two axes with `And`.
@@ -142,10 +179,12 @@ up yet"*, so its presence is not evidence the channel works.
 
 When the project has `@storybook/addon-mcp` **and** a running Storybook,
 [`existing-ui-audit`](../existing-ui-audit/SKILL.md) prefers the live tools —
-`list-all-documentation`, then `get-documentation` for the components that matter — over the
+`docs-list`, then `docs-show` for the components that matter — over the
 hand-read inventory. **The live read wins; the file read is the fallback**, and the fallback
 is never removed: an agent that cannot reach a running Storybook must still be able to
-inventory the library.
+inventory the library. The tool names are version-bound and were re-derived from a throwaway
+installation on 2026-09-13 — [`existing-ui-audit`](../existing-ui-audit/SKILL.md) § 4b carries
+the derivation and the version boundary; do not restate it here.
 
 **React-only while in preview.** Storybook's own MCP FAQ (docs 10.5) states the documentation
 toolset supports React only during preview, so Vue, Angular, and Web Components take the

package/dist/agent-src/skills/threat-modeling/SKILL.md

@@ -25,8 +25,8 @@ triggers:
 > "<surface description>"` returns the surface class, ATT&CK/CWE-cited
 > threats, required controls, and negative tests, with confidence +
 > evidence-gap. Propose grounded findings; the human confirms. Corpus:
-> [`data/threats.csv`](data/threats.csv) (MITRE ATT&CK v16 / OWASP
-> ASVS-derived, owner + cadence in the manifest).
+> [`data/threats.csv`](data/threats.csv) (MITRE ATT&CK v19.x / OWASP
+> ASVS 5.0.0-derived, owner + cadence in the manifest).
 
 > You are a reviewer specialized in **pre-implementation threat analysis**.
 > Your only job is to produce a compact threat model for a planned change —
@@ -215,8 +215,13 @@ run tests**.
   *Threat Modeling: Designing for Security* (2014). Framing basis for the
   Actors / Assets / Entry Points / Trust Boundaries / Abuse Cases rubric.
   [learn.microsoft.com/en-us/security/engineering/threat-modeling-tool-threats](https://learn.microsoft.com/en-us/security/engineering/threat-modeling-tool-threats)
-- **OWASP ASVS v4.0.3** — Authorization (V4), Validation & Encoding (V5),
-  Session Management (V3) — default baseline for "Missing control" entries.
+- **OWASP ASVS v5.0.0** — Authorization (V8), Encoding and Sanitization (V1)
+  + Validation and Business Logic (V2), Session Management (V7) — default
+  baseline for "Missing control" entries. Renumbered from 4.0.3's V4/V5/V3
+  per the standard's own 4.0→5.0 migration guide (`5.0/en/0x05-For-Users-Of-4.0.md`
+  in the ASVS repo) — 5.0.0 splits the old V5 Validation/Sanitization/Encoding
+  chapter into separate Encoding-and-Sanitization and Validation-and-Business-Logic
+  chapters, and drops direct CWE/NIST cross-mappings from the requirements.
   [owasp.org/www-project-application-security-verification-standard/](https://owasp.org/www-project-application-security-verification-standard/)
 - **OWASP Top 10 2021** — A01 Broken Access Control, A04 Insecure Design,
   A05 Security Misconfiguration — cross-reference when naming abuse cases.

package/dist/agent-src/skills/threat-modeling/data/manifest.json

@@ -76,8 +76,8 @@
   "owner": "package-maintainer",
   "refresh_cadence": "quarterly",
   "upstream": {
-    "repo": "derived: MITRE ATT&CK + CWE + OWASP API Top 10 / ASVS 4.0",
-    "sha": "ATT&CK v16 / ASVS 4.0.3",
-    "last_checked": "2026-06-07"
+    "repo": "derived: MITRE ATT&CK + CWE + OWASP API Top 10 / ASVS 5.0",
+    "sha": "re-derived 2026-09-27 against ATT&CK v19.x and ASVS 5.0.0: every ATT&CK id cited in threats.csv's Source Refs column (T1110, T1563, T1105, T1090, T1499, T1552, T1552.001, T1190, T1078.004) resolves in the current Enterprise matrix and none is deprecated or revoked \u2014 threats.csv itself carries no ASVS identifiers, so there is nothing to remap there. SKILL.md's References section cited ASVS 4.0.3's V3/V4/V5 by the old numbering; updated to 5.0.0's V7 Session Management, V8 Authorization, and V1 Encoding and Sanitization + V2 Validation and Business Logic, per the standard's own 4.0\u21925.0 migration guide",
+    "last_checked": "2026-09-18"
   }
-}
+}

package/dist/agent-src/skills/verify-repair-loop/SKILL.md

@@ -83,7 +83,15 @@ regressions are detectable. Pick the verdict commands per the project's
 
 Each iteration is agent turns, never executing control-flow code:
 
-1. **Generate / revise** — make the smallest change toward the contract.
+1. **Read the failure, then revise** — before changing a line, inspect what the
+   previous run actually reported: which checks failed, the assertion text, and
+   whether this failure signature matches the last one. Analyze the existing
+   code path the failing check exercises rather than pattern-matching the error
+   string. A revision written without reading the failure is the blind retry
+   both the plateau rule below and
+   [`autonomous-execution`](../../rules/autonomous-execution.md) exist to stop —
+   and on attempt 1 there is no previous run, so this is the baseline green set
+   from step 1. Then make the smallest change toward the contract.
 2. **Run** — execute the verdict commands; parse the **structured** result
    (counts green/total, which checks failed). This is one tool call, read in
    context.
@@ -183,6 +191,7 @@ verify-repair-loop
 Contract:   <one-line requirement> · threshold <X> · allow_regressions false
 Attempts:   <k>/<max>  scores: [s1, s2, …]   stop: threshold|plateau|cap|regression|reject
 Verdict:    DONE | DONE_WITH_CONCERNS | BLOCKED
+run_terminal: success | blocked | exhausted | stagnated
 Judge:      <judge skill> → apply|revise|reject
 Evidence:   <green/total> · regressions: none | <named checks>
 ```
@@ -193,9 +202,34 @@ Required fields (ordered):
 2. **Attempts** — `k/max`, the score history, and the exact stop reason
    (`threshold` / `plateau` / `cap` / `regression` / `reject`).
 3. **Verdict** — `DONE`, `DONE_WITH_CONCERNS`, or `BLOCKED`.
-4. **Judge** — the dispatched judge skill and its `apply` / `revise` /
+4. **run_terminal** — this loop's stop in the vocabulary every other loop in
+   this tree reports in. The verdict above is local to this skill; this field is
+   the one a reader can aggregate across the continuation hook, the self-fix
+   lanes and this loop without a per-surface translation table.
+
+   | stop reason | `run_terminal` | why |
+   |---|---|---|
+   | `threshold` (judge `apply`) | `success` | the contract is met |
+   | `cap` | `exhausted` | the attempt budget ran out — a bigger budget might help |
+   | `plateau` | `stagnated` | scores stopped moving — a bigger budget will not help |
+   | `regression` | `blocked` | a baseline-green check broke; the loop must not proceed |
+   | `reject` | `blocked` | the judge refused the work |
+
+   The value set is `RunTerminalState`, whose members are `success`,
+   `clean-no-op`, `blocked`, `approval-required`, `exhausted`, `stagnated` and
+   `premise-invalidated`. It is declared once, at
+   `src/scripts/_lib/outcome_vocabularies.ts` (`RUN_TERMINAL_STATES`), and
+   described in [`terminal-states`](../../agent-src/contexts/execution/terminal-states.md).
+   Never emit a value outside that set: a sixth stop reason maps onto an
+   existing member or it is not a terminal state.
+
+   `exhausted` and `stagnated` are deliberately distinct. Both mean "stopped
+   without a green", and they call for opposite responses — raise the budget
+   against the first, change approach against the second. Collapsing them loses
+   the only part of the stop a reader can act on.
+5. **Judge** — the dispatched judge skill and its `apply` / `revise` /
    `reject` verdict (omit only when the loop stopped before escalation).
-5. **Evidence** — final `green/total` and any regressed checks by name.
+6. **Evidence** — final `green/total` and any regressed checks by name.
 
 ## Examples
 

package/dist/agent-src/templates/agent-settings.md

@@ -654,7 +654,7 @@ the canonical narrative lives in
 | `commands.create_pr.api_paths` | glob list | `[]` | Optional globs pinning API-endpoint detection; empty = light heuristic, fail-open. |
 | `verbosity.preview_artifacts` | `true`, `false` | `false` | Show generated commit messages, PR titles/bodies, branch names before acting. `false` = use generated content directly. See the token-frugality plate under `agents/roadmaps/` (Phase 2/3). |
 | `verbosity.routine_confirmations` | `true`, `false` | `false` | Confirmation prompts for routine workflow steps when there is one obvious answer ("looks good — commit?"). Iron-Law gates (`commit-policy`, `scope-control` git-ops, `non-destructive-by-default`) ALWAYS ask regardless. |
-| `verbosity.offer_council_in_delivery` | `true`, `false` | `false` | Offer "run AI Council on this?" inside delivery commands (`/feature-plan`, `/review-changes`, `/roadmap-create`). Council commands themselves are unaffected. |
+| `verbosity.offer_council_in_delivery` | `true`, `false` | `false` | Offer "run AI Council on this?" inside delivery commands (`/feature-plan`, `/review-changes`). Council commands themselves are unaffected. `/roadmap:create` no longer reads it — under a mission the council is a step, resolved from `agent-config council:status`, never an offer. |
 | `verbosity.post_action_reports` | `off`, `minimal`, `full` | `minimal` | Multi-line status / summary blocks after a successful action. `off` = no report; `minimal` = one-line confirmation; `full` = bullet list. |
 | `verbosity.intent_announcements` | `true`, `false` | `false` | Intent announcements ("Let me check…", "Now I will…", "Found it") in skill bodies. `false` = act and emit the result. |
 | `telegraph.speak` | `true`, `false` | `false` | Whether the telegraph-speak rule ships at all. `false` (default) = dormant: the projector omits the rule from `dist/router.json`, so its body never reaches a host. The rule body states its own grammar scope and carve-outs (numbered options, Iron-Law literals, code, paths), so this is the only lever. |

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "16.0.0"
+agent_config_version: "16.1.0"
 
 # --- Project identity ---
 project:

package/dist/agent-src/templates/roadmaps.md

@@ -64,6 +64,16 @@ that was never a judgement call.
     "Target release: X.Y.Z", never plan git tags or deprecation dates. Release
     and tag decisions belong to the user and are taken outside the roadmap.
     This is enforced by [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
+
+    **What the prohibition does not reach — a state, not a schedule.** The five
+    sentences above are unchanged and stay the rule: a roadmap does not decide
+    *when* or *in which version* work ships. It MUST, however, declare any
+    intentionally unreleasable intermediate tree state, together with the
+    machine-verified condition that clears it, per rule 28. Naming a state that
+    must not be published is not a release decision — it is a fact about the tree
+    that the release path has no other way to learn, and today cannot learn: the
+    release entry points read no roadmap at all. Declaring the state is
+    mandatory; deciding what to do about it at a cut is still the operator's.
 14. **No automatic branch switches mid-roadmap.** Roadmap work runs on the
     branch the user is on. If a separate branch (spike, hotfix, experiment)
     would be genuinely useful, the agent may propose it **once** while
@@ -231,6 +241,32 @@ that was never a judgement call.
     edge source stays the single one already defined above; `relates:` never
     becomes a second dependency source.
 
+    **Sibling block, same frontmatter — `delivery:`.** Optional, and unlike
+    `execution:` it describes what happens to the BRANCH rather than to the
+    run's interaction pattern:
+
+    ```yaml
+    delivery:
+      pr_topology: stacked      # single (default) | stacked
+    ```
+
+    `pr_topology: stacked` declares a dependent series of pull requests. It is
+    a plan the owner writes before execution and is **never** chosen by the
+    agent and never asked about at roadmap creation — see the `delivery:` block
+    in `agent-settings.template.yml`, where all three keys are Class C for that
+    reason. A roadmap declaring `stacked` owes a `## PR plan` section naming
+    the series and the order; `single` owes nothing, which is why it is the
+    default.
+
+    **Not yet a live override, and this is the honest state rather than an
+    omission.** `load_agent_settings` has four layers and none of them is a
+    roadmap, so a `delivery:` block here is read by no code today. It is
+    documented now because the key it mirrors is Class C — the owner has to
+    have a place to write the plan that is not an agent-writable setting — and
+    the cascade layer that would read it is scheduled by ADR-268, not yet
+    built. Until it is, treat a `delivery:` block here as a note to the next
+    human reader rather than as configuration.
+
     An explicit `relates: []` is a complete answer and the common one, but only
     when it carries the probe's `scanned:` line as its justification:
 
@@ -301,6 +337,13 @@ that was never a judgement call.
     step gated by a specific blocker may cross-reference it inline:
     `- [ ] … <!-- blocked-by: <blocker-id> -->`.
 
+    **A blocker stops execution; a hold stops publication.** The two are not
+    interchangeable and never substitute for one another. A blocker says the work
+    cannot proceed and is cleared by a person; a release hold (rule 28) says the
+    work may proceed but its intermediate tree state must not ship, and is
+    cleared by a checkbox whose `verify:` a machine runs. A roadmap that is
+    merely unfinished has neither — incompleteness is not a release condition.
+
     **A user-decision blocker's annotation records whether the question
     was actually put.** Where the blocker's `Owner:` is the maintainer,
     the user or the owner, the marker carries an `asked:` field —
@@ -400,6 +443,22 @@ that was never a judgement call.
     on nothing until an author declares a class and there is no backlog
     to grandfather.
 
+    **A judgement call is never parked here.** A blocker records a decision
+    the agent **correctly did not own**. A technical judgement call — two
+    valid architectures, a dependency trade-off, an unclear boundary with no
+    new product semantics — is not one of those: it routes back through the
+    closure pass and is resolved at the lowest rung that owns it (evidence,
+    convention, the agent, an independent session, the council, the team),
+    then recorded as a `## Decisions` row per rule 27. A technical decision
+    does not become owner-owned because it is hard (ADR-268 § 10).
+
+    An entry MAY declare `- **Ownership:** <class>`, and when it does the
+    class must be one of the three owner-owned ones — `product-owned`,
+    `business-owned`, `destructive-owned`. A technical class there is the
+    parked judgement call this retires, and `lint_roadmap_blockers` reds it.
+    The field is optional and HARD rather than ratcheted, on the same
+    no-backlog-to-grandfather ground as `Class:`.
+
     **Legacy fallback.** A body-level `> Blocked until <condition>`
     note (the follow-up-roadmap convention from rule 17) is parsed by
     the dashboard generator as one implicit roadmap-level blocker
@@ -582,6 +641,126 @@ that was never a judgement call.
     tracked estate; blocking is earned by tracked-scope evidence, not
     assumed).
 
+27. **A ready roadmap carries no unresolved decision — it carries a
+    `## Decisions` table.** A plan enters execution as an **execution
+    contract**: every foreseeable decision closed before the first step,
+    so a long run never meets a question planning could have closed.
+
+    The section is a six-column table, and the two vocabularies in it are
+    closed sets:
+
+    ```markdown
+    ## Decisions
+
+    | ID | ownership | resolved by | decision | evidence | revisit if |
+    |---|---|---|---|---|---|
+    | D1 | contested-technical | council:2026-09-13 | NDJSON on disk | streaming read at bounded RSS | the reader stops streaming |
+    ```
+
+    `ownership` is one of the eight ownership classes — `deterministic`,
+    `reversible-technical`, `contested-technical`, `critical-technical`,
+    `product-owned`, `business-owned`, `destructive-owned`,
+    `spend-exhaustion`. The axis is **ownership, not impact**: a technical
+    decision does not become owner-owned because it is hard
+    (ADR-268 § 10). `resolved by` is one of `evidence`, `agent`,
+    `independent:<session or model>`, `council:<record>`, `team:<record>`,
+    `owner` — the prefixed forms carry their record, because a resolver
+    with no record is a claim rather than a resolution.
+
+    `revisit if` names the condition that reopens the row. Execution reads
+    the table **before any step**, and a closed decision is re-asked only
+    when its `revisit if` condition became true — not because a context
+    reset lost it, which is the repeat the ask census counts.
+
+    Enforced by `lint_decision_classes`: in a ready roadmap an unresolved
+    marker (`TBD`, *to be decided*, *decide later*, *open question*)
+    outside the section is a finding, and the same marker resolved into a
+    row is not. `## Blockers` is the other discharge — a five-field
+    structured blocker IS the record of a decision the agent correctly did
+    not own, so an open item there is not an unclosed one.
+
+    The section is owed where there is a decision to record. A plan that
+    closed everything inline carries no table and no marker, and is
+    complete; an empty table written to satisfy a template records
+    nothing, exactly as rule 25 says of a perfunctory pre-mortem.
+
+28. **Release holds — declare an unreleasable intermediate state, or there is
+    not one.** A roadmap whose intermediate tree state must not be published
+    declares that state in a `## Release holds` section. Nothing else in the
+    repository can express it, and the release path reads no roadmap today, so
+    an undeclared unreleasable state is invisible to every release boundary.
+
+    **Non-goal, stated first because it is the failure mode closest to hand:
+    roadmap *incompleteness* is never a release condition.** An unfinished
+    roadmap does not block a release, has never blocked one, and must not start
+    to. A hold is a positive declaration about a named tree state, never a side
+    effect of open checkboxes.
+
+    **Authoring order — `re-sequence → guard → hold`, in that order.** A hold is
+    the last resort, not the first tool:
+
+    1. **Re-sequence.** Can the phases be cut so that no intermediate state is
+       broken? A continuous shape needs no hold and is always preferred.
+    2. **Guard.** Can the half-built surface be hidden behind a flag, an unwired
+       entry point, or a default that keeps it inert? A guarded state is
+       publishable and needs no hold.
+    3. **Hold.** Only when neither works. Every hold entry therefore carries a
+       mandatory `Why not a guard:` field naming the concrete reason the guard
+       rung failed. A hold entry without it is malformed and reddens CI.
+
+    **Entry shape** (one entry per hold, inside `## Release holds`):
+
+    ```markdown
+    ## Release holds
+
+    ### hold: <kebab-id>
+    - **Channel:** all             <!-- all | latest -->
+    - **Opened by:** <phase.step>  <!-- the checkbox whose [x] opens the window -->
+    - **Cleared by:** <phase.step> <!-- the checkbox whose [x] closes it -->
+    - **State:** {the one sentence naming what is broken in the tree while open.}
+    - **Why not a guard:** {why rung 2 failed, concretely.}
+    ```
+
+    **Marker grammar.** Both named steps carry an inline marker so the binding is
+    readable from the checkbox and not only from the section:
+    `- [ ] … <!-- opens-hold: <hold-id> -->` and
+    `- [ ] … <!-- clears-hold: <hold-id> -->`. The clearing step MUST carry a
+    `verify:` field (rule 23) — a hold cleared by an unverified flip is a hold
+    cleared by assertion.
+
+    **Channel vocabulary.** `all` (the default, and what an omitted `Channel:`
+    parses to) refuses every cut. `latest` refuses a stable `X.Y.Z` cut and
+    permits a `-next.N` prerelease, for a state safe to publish to an opt-in
+    channel but not to the default one. There is no third value and no override:
+    a plain `X.Y.Z` cut is never silently converted to a prerelease, and the
+    choice between finishing the clearing step, cutting `-next.N`, and using a
+    release line stays the operator's.
+
+    **State table.** A hold is in exactly one of four states, and only the first
+    is publishable:
+
+    | State | How it is reached | Release boundary |
+    |---|---|---|
+    | `unopened` | the opening checkbox is not `[x]` | permits |
+    | `open` | opener `[x]`, clearer not `[x]` | **refuses**, per `Channel:` |
+    | `cleared` | both `[x]` | permits |
+    | `not-evaluable` | the declaration is malformed, the file unreadable, or the evaluator errored or timed out | **refuses**, always, on every channel |
+
+    `not-evaluable` refusing is the load-bearing row: there is no path on which
+    "could not evaluate" reads as safe. A malformed declaration additionally
+    reddens normal CI, so a broken hold cannot fail open by being unparseable.
+
+    **Per-folder lifecycle.** A window does not disappear by moving the file.
+    A roadmap with an open window may not be moved to `archive/` or `skipped/` —
+    the move is refused naming the hold id. It may be moved to `later/`, and the
+    open window is then named in the `entry_condition.what` part; it still lists
+    and still refuses. Deletion is a known residual, not a mitigation: rule 12
+    already forbids it and no gate can see a file that is gone.
+
+    **No versions inside a hold entry.** Rule 13's prohibition applies inside
+    `## Release holds` exactly as it does everywhere else. A hold names a *state*
+    and its clearing *checkbox*; it never names a version, a tag, or a date.
+
 ---
 
 ## Quality Gates (remote CI by default)
@@ -672,6 +851,15 @@ complexity: lightweight
 - [ ] {Observable, testable criterion}
 - [ ] All quality gates pass (PHPStan, Rector, tests)
 
+<!-- ## Decisions — INCLUDE when the closure pass closed a decision this
+     plan would otherwise have met mid-run (rule 27). OMIT entirely when
+     nothing was open: an empty table records nothing.
+## Decisions
+
+| ID | ownership | resolved by | decision | evidence | revisit if |
+|---|---|---|---|---|---|
+| D1 | {ownership class} | {resolver} | {what was decided} | {file:line, record, probe} | {condition that reopens it} | -->
+
 <!-- ## Blockers — INCLUDE ONLY when a gate exists that only the user /
      a maintainer can clear (decision, external dependency, evidence
      threshold, soak window). OMIT entirely when there are none — see

package/dist/agent-src/templates/scripts/work_engine/directives/backend/_self_fix.ts

@@ -78,6 +78,41 @@ export const VOLATILE_KEYS: ReadonlyArray<string> = [
 /** Why the loop stopped, or that it has budget left. */
 export type SelfFixKind = 'retry' | 'exhausted' | 'no_progress';
 
+/**
+ * `SelfFixKind` in the vocabulary a reader can aggregate across surfaces.
+ *
+ * `Outcome.PARTIAL` says the loop stopped without a green; it cannot say
+ * whether the budget ran out or the target stopped moving, and those want
+ * different responses — a bigger budget against the first, a different
+ * approach against the second. Until now the distinction left this module only
+ * inside a free-text `message`, so the continuation hook's stops were
+ * countable and this loop's were not.
+ *
+ * The two values are members of `RunTerminalState`, whose authoritative
+ * declaration is `src/scripts/_lib/outcome_vocabularies.ts:RUN_TERMINAL_STATES`
+ * and whose prose home is `contexts/execution/terminal-states.md`. They are
+ * written as literals rather than imported because this file is a TEMPLATE:
+ * it ships into consumer projects that have no `src/scripts/_lib` to import
+ * from, and reaching across that boundary would break every install. It is a
+ * two-member projection across a packaging boundary, not a second vocabulary —
+ * nothing here may add a member the registry does not have.
+ */
+export const RUN_TERMINAL_BY_KIND: Readonly<Record<Exclude<SelfFixKind, 'retry'>, string>> = {
+    exhausted: 'exhausted',
+    no_progress: 'stagnated',
+};
+
+/**
+ * The run-terminal value for a decision, or `null` while the loop is still live.
+ *
+ * `retry` has no terminal by construction — the loop has not stopped — and the
+ * null is returned rather than defaulted so a caller cannot accidentally stamp
+ * a terminal value onto a run that is still going.
+ */
+export function run_terminal_for(kind: SelfFixKind): string | null {
+    return kind === 'retry' ? null : RUN_TERMINAL_BY_KIND[kind];
+}
+
 /** Verdict of {@link decide} — pure, so the caller owns every mutation. */
 export interface SelfFixDecision {
     kind: SelfFixKind;
@@ -147,6 +182,27 @@ export function record_attempt(state: DeliveryState, lane: string, signature: st
     state.self_fix = container;
 }
 
+/**
+ * Stamp the lane's run-terminal value onto `state.self_fix`.
+ *
+ * Written into the state the module already owns and the dispatcher already
+ * persists, rather than onto `StepResult` — `StepResult` carries `outcome`,
+ * `questions` and `message` and is shared by every directive in the engine, so
+ * widening it for one loop's stop reason would be a change to all of them.
+ *
+ * A `retry` decision writes nothing: the loop has not stopped, and a terminal
+ * value recorded mid-loop would be read as one by anything aggregating the
+ * field.
+ */
+export function record_run_terminal(state: DeliveryState, lane: string, decision: SelfFixDecision): void {
+    const run_terminal = run_terminal_for(decision.kind);
+    if (run_terminal === null) return;
+    const container = _pyTruthy(state.self_fix) ? (state.self_fix as Record<string, Any>) : {};
+    const lane_state = _lane_state(state, lane);
+    container[lane] = { ...lane_state, run_terminal };
+    state.self_fix = container;
+}
+
 /** DoD entries the agent has not recorded as proven. Never inferred. */
 export function unmet_dod(state: DeliveryState): Array<Record<string, Any>> {
     const dod = (state.ticket ?? {})['dod'];
@@ -213,8 +269,11 @@ export function partial_exit(args: {
     decision: SelfFixDecision;
     unmet: Array<Record<string, Any>>;
     rerun_directive: string;
+    /** Written the run-terminal value onto, when the caller has the state in hand. */
+    state?: DeliveryState;
 }): StepResult {
-    const { lane, ticket_id, verdict, decision, unmet, rerun_directive } = args;
+    const { lane, ticket_id, verdict, decision, unmet, rerun_directive, state } = args;
+    if (state !== undefined) record_run_terminal(state, lane, decision);
     const reason =
         decision.kind === 'no_progress'
             ? `two consecutive attempts produced an identical \`${lane}\` verdict, ` +
@@ -244,7 +303,8 @@ export function partial_exit(args: {
         ],
         message:
             `Ticket ${ticket_id} ${lane} verdict is \`${String(verdict)}\` after ` +
-            `${decision.attempts} self-fix attempt(s) (${decision.kind}); exiting PARTIAL.`,
+            `${decision.attempts} self-fix attempt(s) (${decision.kind}); exiting PARTIAL ` +
+            `(run_terminal: ${String(run_terminal_for(decision.kind))}).`,
     });
 }
 

package/dist/agent-src/templates/scripts/work_engine/directives/backend/test.ts

@@ -225,6 +225,7 @@ function _blocked_on_bad_verdict(state: DeliveryState, verdict: Any): StepResult
         decision,
         unmet: unmet_dod(state),
         rerun_directive: 'run-tests',
+        state,
     });
 }
 

package/dist/agent-src/templates/scripts/work_engine/directives/backend/verify.ts

@@ -201,6 +201,7 @@ function _blocked_on_bad_verdict(state: DeliveryState, verdict: Any): StepResult
         decision,
         unmet: unmet_dod(state),
         rerun_directive: 'review-changes',
+        state,
     });
 }