@event4u/agent-config 16.0.0 → 16.2.0

package/docs/contracts/settings-classes.md

@@ -247,8 +247,21 @@ dispatch runs, not WHETHER the layer exists, so they keep their own C rows.
 |---|---|
 | A — preference | 26 |
 | B — consent | 3 |
-| C — guarded | 116 |
-| **Total** | **145** |
+| C — guarded | 124 |
+| **Total** | **153** |
+
+It rose again on 2026-09-13 when `road-to-adversarial-verification-and-long-runs`
+Phase 0 added three C keys: `quality.local_auto_run_in_mission` (`consent` — it
+decides whether local verification runs at all inside a mission, which is the
+same decision `quality.local_auto_run` carries for chat) and the two
+`execution:` leaves, `fix_loop_max` and `escalation` (both `policy` — they bound
+and route an autonomous run's own recovery, and an agent that could widen its own
+bound has no bound). None is `derivable`: each states something no other surface
+computes, so the anti-regrowth ratchet on that disposition is untouched. Two
+branches added keys on the same day, so the totals in both tables are re-derived
+from the class table on the MERGED tree rather than by adding either side's
+delta — which is the arithmetic `lint_settings_classes` checks, and picking a
+side is how a stated count comes to describe a tree that no longer exists.
 
 It rose to 142 on 2026-09-08 from two independent additions that landed in the same
 day and are counted together here: `lean_projection.hosts` (one C, `policy`, from
@@ -369,9 +382,9 @@ the template, which is the drift this contract exists to prevent.
 |---|---|
 | derivable | 83 |
 | un-inferrable | 9 |
-| consent | 44 |
-| policy | 9 |
-| **Total** | **145** |
+| consent | 47 |
+| policy | 14 |
+| **Total** | **153** |
 
 First measured 2026-08-12 at 140 leaves (derivable 88 · consent 38 ·
 un-inferrable 9 · policy 5), from the table below rather than predicted — the
@@ -474,7 +487,7 @@ Rows follow template order, so a diff against the template reads straight down.
 | `projection.rule_packs` | C | `[]` | second allowlist axis on rule projection | derivable — the `auto` derivation already implemented in `src/install/rule_scope.ts` |
 | `discipline_profile` | C | `__DISCIPLINE_PROFILE__` | master switch for the discipline rule tier | derivable — its own `auto` resolution against `src/config/host-capabilities.yml` |
 | `rule_loading_tier` | C | `__RULE_LOADING_TIER__` | legacy master switch for rule loading | derivable — `discipline_profile` supersedes it with a documented mapping (minimal→off, balanced→essential, full→full) |
-| `lean_projection.mode` | C | `eager-all` | `thin` removes rule bodies from the agent's context | derivable — `probe_host_compliance.ts` already computes the per-host thin/eager recommendation |
+| `lean_projection.mode` | C | `delivery` | `thin` and `delivery` remove rule bodies from the agent's standing context. Two defaults, and this column carries the template one: the shipped template has said `delivery` since ADR-267, while the parser fallback for a value that resolves from no layer stays `eager-all` (ADR-267 decision 4) | derivable — `probe_host_compliance.ts` already computes the per-host thin/eager recommendation |
 | `lean_projection.hosts` | C | `[claude-code]` | decides WHICH hosts a thinning mode may thin, so an added id removes rule bodies from that host's context | policy — the value is a package-level decision the tree already holds: ADR-267 scopes the shipped `delivery` flip to `claude-code` alone. NOT `derivable`, and the distinction is the whole reason for this row: the mechanism that would compute an admissible host set, `admissibleUnderE3` in `src/scripts/_lib/injection_effect.ts`, admits **nothing** today — `src/config/host-injection-effect.json` carries 1 `observed-false` and 8 `unobserved` rows and no `observed-true` — so a derivation would yield `[]` rather than the shipped `[claude-code]`. Naming a mechanism that returns empty as the replacement would put a key in the deletion queue whose deletion would silently change the default. Move target: the ADR plus that census, once a host earns an `observed-true` row |
 | `telegraph.speak` | C | `false` | ships a rule body; a token-cost lever in both directions | derivable — the telegraph kill-criterion bench verdict is a package-level decision, not a per-install one |
 | `tokens.rich_skills` | C | `"on"` | token-spend lever | derivable — the skill's own `token_budget_class: rich` declaration plus the CI ceiling in `lint_token_budget_discipline.ts` |
@@ -506,6 +519,11 @@ Rows follow template order, so a diff against the template reads straight down.
 | `project.improvement_pr_branch_prefix` | A | `improve/agent-` | branch-name cosmetics | derivable — the repo's own branch-naming convention, observable from `git branch -r` |
 | `project.audience` | C | `public` | C-test 4 — it governs the agent's own reasoning discipline: `self` makes the § 8-pre demand gate inert. Who a project is built for is a fact only its maintainer knows, so the agent never infers it and never asks; hand-edit or the GUI write route. The default is today's behaviour, so an install that never sets it is unchanged | policy |
 | `github.pr_reply_method` | A | `create_review_comment` | picks between two endpoints of one operation | derivable — the `auto` value already in the enum: the routing detects the working endpoint on first use and writes it back |
+| `delivery.merge` | C | `off` | C-test 1 — it is the configuration half of merge authority, resolved by ADR-268 section 3. An agent that could write it could grant itself the capability the key gates, which is the exact shape the C fence exists to refuse. `off` is today's behavior, so an install that never sets it is unchanged | consent |
+| `delivery.wait_for_ci` | C | `true` | C-test 1 — it authorises the run to keep spending time and tokens driving CI to a verdict rather than ending at push. A standing authorisation over the agent's own consumption is not a preference | consent |
+| `delivery.pr_topology` | C | `single` | C-test 4 — `stacked` is a plan the owner makes, never one the agent picks, and the roadmap surface that consumes it is written before execution. An agent-writable value here would let a run choose its own delivery shape mid-mission | policy |
+| `host_environment.request_size_caps.bash_max_output_length` | C | `null` | C-test 1 — it is written into the HOST's own environment, where it changes behavior the consumer did not ask for. An agent-writable value here would let a run reshape its own request budget in the consumer's settings file, which is the capability the key gates. `null` is today's behavior: nothing is written | policy |
+| `host_environment.request_size_caps.max_mcp_output_tokens` | C | `null` | C-test 1 — same surface and same reason as the row above; the pair is the whole writable set, and no traffic or auto-updater variable is expressible beside them by construction | policy |
 | `augment.rules_use_symlinks` | A | `false` | reversible install mechanics | derivable — dev-mode detection at install time plus a symlink-capability probe on the target filesystem |
 | `eloquent.access_style` | A | `getters_setters` | code convention | derivable — the convention the project's existing models already use; `standards-from-config` reads it off the tree |
 | `chat_history.enabled` | C | `true` | kill-switch over a path that writes conversation content to disk | consent |
@@ -532,10 +550,13 @@ Rows follow template order, so a diff against the template reads straight down.
 | `roadmap.horizon_weeks` | C | `0` | a non-zero value relaxes a lint's plate-token ban | policy |
 | `roadmap.gate_budget.max_cost_per_run_usd` | C | `5` | per-run spend ceiling on class-1 gate execution | consent |
 | `roadmap.gate_budget.max_cost_per_rolling_7d_usd` | C | `25` | rolling spend ceiling on class-1 gate execution | consent |
-| `planning.challenge_on_create` | C | `true` | disables the plan-confidence gate | derivable — the gate's own confidence conditions; a confident plan passes straight through |
+| `planning.closure_pass` | C | `true` | disables the plan-closure pass | derivable — the gate's own confidence conditions; a confident plan passes straight through |
 | `planning.risk_review` | C | `true` | disables the risk-register validator | derivable — `lint_plan_risk_register`'s own scope predicate (ready, non-draft plans only) |
 | `planning.completion_review` | C | `true` | disables the completion-review validator | derivable — `check_completion_review`'s own scope predicate, bound to the current diff hash |
 | `quality.local_auto_run` | C | `false` | governs whether local verification runs at all | consent |
+| `quality.local_auto_run_in_mission` | C | `true` | governs whether local verification runs at all inside an autonomous mission | consent |
+| `execution.fix_loop_max` | C | `10` | bounds how long an autonomous run may keep attempting one failing target | policy |
+| `execution.escalation` | C | `['independent', 'council', 'team', 'owner_owned_check']` | names the rungs an autonomous run walks before any owner ask | policy |
 | `design.fidelity_mode` | C | `strict` | strict-mode selector, one of whose values is a Hard Floor | policy |
 | `design.approximation.enabled` | C | `false` | lets a value change without a per-value confirmation; enabling it is a consumer-facing default flip | consent |
 | `design.approximation.tolerance.color` | C | `null` | decides which colour deviations may be taken silently | policy |

package/docs/guidelines/agent-infra/active-remediation-mechanics.md

@@ -93,6 +93,63 @@ Update stale idioms to the version the project **actually runs** — but only wh
 - Subordinate to `no-cheap-questions` (self-check items 3 & 14 — real trade-off, not a disguised continuation/commit ask), `autonomous-execution` (the end-of-session batch must not read as "shall I continue?"), `user-interaction`, `ask-when-uncertain` (one batched prompt = one question).
 - Threshold to surface at all: a **real, nameable** improvement with a concrete benefit. Cosmetic nitpicks with no trade-off → drop silently. The live-security carve-out is the only case that interrupts or overrides autonomy.
 
+## The other axis — who owns the growth
+
+The ladder above sizes a change: *is this small and aligned enough to do now.*
+It does not say **whose decision it is**, and both must clear before work
+happens inline — something small and council-owned is still not the agent's to
+decide, and something agent-owned and large is still bounded by
+`minimal-safe-diff`.
+
+Three closed lists answer the ownership half: six agent-owned kinds (done
+inline, recorded as a scope delta in the PR body, never asked about), four
+council-owned (routed through the ownership ladder, reaching the owner in none
+of them), and two owner-owned. Anything matching none of them is not scope
+growth at all — it is a follow-up artifact, and the mission does not expand to
+hold it.
+
+Full enumeration: [`scope-growth-ownership`](../../../src/agent-src/contexts/authority/scope-growth-ownership.md).
+One item classifies deterministically with
+`./scripts-run src/scripts/scope_growth "<description>"`; `unknown` is a real
+verdict there, never a fallback to the cheapest rung.
+
+## Inside a mission — the middle rung becomes an artifact
+
+`road-to-adversarial-verification-and-long-runs` 6.1. The ladder's middle rung is
+**note + ask**, and inside an autonomous mission there is nobody to ask. Left
+unreplaced the rung collapses in one of two bad directions, and both are failures
+this suite already names: every spotted issue becomes a fix (the scope creep
+[`minimal-safe-diff`](minimal-safe-diff-mechanics.md) exists to stop), or every
+one becomes silence (the look-away `active-remediation` exists to stop).
+
+So under a mission the middle rung is **emit a follow-up artifact and leave the
+code alone**.
+
+**What may ride along at all** — nine kinds, and the list is closed:
+characterization tests · regression tests · a small adjacent bug · naming · types
+· robustness · local dead code · simplifying code the mission already touched ·
+testability.
+
+**Six criteria, ALL of which must hold** for one of those to ride along: local to
+the path the mission is already touching · small · low blast radius · clearly
+correct · testable in the same commit · carries no new product decision.
+
+```
+THE SIX ARE AND-ED, NEVER SCORED.
+A SCORED VERSION LETS A LARGE CHANGE BUY ITS WAY IN WITH FIVE CHEAP YESES,
+WHICH IS HOW A BOY-SCOUT RULE BECOMES A REFACTOR LICENCE.
+```
+
+The **characterisation is the agent's judgement; the DECISION is mechanical** —
+`_lib/rides_along.ts` takes the six booleans and returns the rung, so the same
+inputs always land the same way and a later reader can check the call rather than
+re-litigate the taste.
+
+**A deferral states every reason it was deferred**, not the first one it hit. The
+artifact exists because the issue is still owed, and "it failed one of six" is not
+something a later triage can act on. A deferral with no reason is the
+note-and-forget this rule already forbids, wearing an artifact's clothes.
+
 ## See also
 
 - [`active-remediation`](../../../src/rules/active-remediation.md) — the rule this file details (Iron Law + ladder + live-security carve-out).

package/docs/guidelines/agent-infra/evaluator-independence-mechanics.md

@@ -86,6 +86,108 @@ point: this rule exists because a process that *looked* followed produced
 fabricated evidence, and claiming coverage it does not have would repeat that.
 
 
+## The audited failure, in full
+
+Migrated out of the rule on 2026-09-13 under the same P4 pattern the rest of this
+page follows: the rule keeps the obligation, this page carries the record. The
+rule was re-sending all of it on every session and every spawn.
+
+Measured, once, at maximum cost (conformance audit 2026-08-06):
+
+> The agent dispatched a "blind reviewer" over its own change. It wrote that
+> reviewer's prompt itself, put **"NO-FINDINGS is expected and welcome"** into it,
+> and narrowed the scope to four files it chose. The reviewer returned
+> NO-FINDINGS. That honest-null was committed as **binding gate evidence**. An
+> unsteered pass over the same delta later found 5 findings, one of them
+> critical, already live on the trunk.
+
+The agent's own retro named it exactly, in the maintainer's own words:
+
+*DE: "Die Fabrikation lag nicht im Weglassen des Reviews — sie lag in meinem Prompt. Ich habe die Antwort vorgeladen und dann als Evidenz verbucht." · EN: "The fabrication was not in skipping the review — it was in my prompt. I pre-loaded the answer and then booked it as evidence."*
+
+The review ran. The process was followed. The evidence was manufactured anyway.
+
+## The softer form — why the phrase list cannot see it
+
+The Iron Law forbids **authoring the verdict** into an evaluator's prompt. There
+is a weaker move that evades it while doing the same work, and it is the one an
+orchestrator reaches for without noticing: **stating an expectation**.
+
+*"NO-FINDINGS is expected"* is a prediction, not a verdict — and it steered a real
+review into an honest-null that five findings on the trunk later refuted. A prompt
+that says what the author thinks the answer is has authored the answer, whatever
+grammatical mood it used. The guard's pre-loaded-verdict detector is a PHRASE
+list, so it catches recurrences of known steering wording and not steering as
+such; this distinction is the gap it cannot close, which is why the obligation is
+stated in the rule rather than delegated to the detector.
+
+## Tests are evaluators — levels, workflow, and the weakening ladder
+
+`road-to-adversarial-verification-and-long-runs` Phase 2. The rule states the
+obligation; this section carries the detail it points at.
+
+### The five levels
+
+| Level | Author | What it actually buys |
+|---|---|---|
+| **L0** | the same agent, same session | nothing against self-confirmation. **Fallback only** — permitted when no other route exists, and then said out loud. |
+| **L1** | another session, same model | a fresh context. **Not** a different judgement: with one provider configured this is the same model reviewing its own work, holding a label that says otherwise. |
+| **L2** | another model | different training, different blind spots. The first level that buys a genuinely second opinion. |
+| **L3** | another provider | independent training data, independent failure modes, independent incentives. |
+| **L4** | a multi-provider council or team | L3 plus disagreement that is visible rather than averaged away. |
+
+**Critical behavior — security, authority, data loss, merge control — targets
+L3 or L4 wherever two providers are configured.** Wherever, not always: with one
+provider the honest ceiling is L2, and the level is read from `agent-config
+council:status`'s actual provider count rather than assumed from a config file
+that may describe an intention.
+
+### The workflow
+
+```
+acceptance behaviour → INDEPENDENT AUTHOR → RED evidence → implementer → GREEN
+→ INDEPENDENT VALIDATOR
+```
+
+Five arrows, and the two capitalised roles are the ones that may not be the
+implementer. **RED evidence** is not ceremony: a test never shown red has unknown
+sensitivity, so a suite that was green from the first run has proven nothing
+about the code and everything about the assertions being vacuous.
+
+### What an implementer may never do silently
+
+Weaken an assertion · delete a failing test · skip or `xfail` it · loosen a
+threshold · change fixture semantics to fit the code.
+
+Each of these is a legitimate change *sometimes*, which is exactly why the
+prohibition is on doing it **silently** rather than on doing it. Where the test
+genuinely looks wrong, the ladder is: **evidence** (what the test asserts, what
+the code does, why they disagree) → **independent test review** → **council or
+team** → change only after an independent verdict.
+
+**The owner is not the arbiter.** Routing this to the owner converts a technical
+disagreement the tree can settle into an interrupt only the owner can clear, and
+it is the same count-to-an-ask move the recovery ladder removes.
+
+### Test-quality validation — one question, before delivery
+
+*Would these tests fail under plausible wrong implementations?* An independent
+instance answers it, looking for: tautologies · algorithm duplication (the test
+re-implements the thing it is testing, so both are wrong together) · snapshot
+overuse · missing boundary and error cases · over-mocking (the mock, not the
+code, is what passes) · expectations changed to fit the code · a test never shown
+red.
+
+The validator's **identity and provider go into the evidence**. An unattributed
+validation is not one — it cannot be checked for the independence it claims, and
+`evaluator-independence`'s own recorded failure is exactly a verdict nobody could
+trace back to the prompt that produced it.
+
+This is deliberately **not** mutation-testing infrastructure (K3 of that
+roadmap). Mutation testing is the industrial form of the same question; one
+independent instance asking it in prose is the cheap first form, and shipping the
+cheap form now beats deferring the question until the infrastructure exists.
+
 ## See also
 
 - [`evaluator-independence`](../../../src/rules/evaluator-independence.md) — the rule this page carries the argument for.

package/docs/guidelines/design-fidelity-routing.md

@@ -13,6 +13,35 @@ Migrated out of `design-fidelity.md` on 2026-09-09 under the council verdict on
 the operative pointers the same verdict requires, not an arbitrary line cut. The
 rule keeps the obligations; this holds the reasoning behind them.
 
+### The matcher, and why each shipped class is shaped that way
+
+Migrated out of `design-fidelity.md` on 2026-09-18 under
+`road-to-design-fidelity-proof` Phase 1.1 — the rule keeps the operative class
+list, this holds the argument behind each one.
+
+Matching is plain lower-cased substring containment on the prompt, plus fnmatch
+over the open files. Three handover classes must reach this rule: an English
+phrasing, a German one, and a prompt carrying **no** keyword at all because the
+artifact is simply attached. The last is covered by two file patterns:
+`*design.html`, the conventional handover filename, and `*.dc.html`, the Claude
+Design canvas artboard — which `*design.html` cannot match, because it compiles
+to `^(?:.*design\.html)$` and `ToDo.dc.html` does not end in `design.html`.
+Neither is `*.html`, which would fire on every HTML edit in every project and be
+strictly worse than the gap it closes; `near-plain-html-open-file` pins that
+form silent. A handover under some other filename needs one word in the prompt.
+
+Two further handover shapes carry the artifact without any of the above:
+
+- **A capability URL.** A published artifact is handed over as a link, not a
+  file — so `phrase: "claude.site/artifacts"` fires on the *published-artifact
+  path*, not on the host. `claude.ai` alone is a chat link and must stay quiet:
+  a keyword on the bare domain would fire on "I pasted this from claude.ai",
+  which is a conversation reference, not a spec.
+- **A design-system directory.** `path_prefix: ".claude/design-system/"` — the
+  conventional location for a handed-over token/component set. The prefix is the
+  vendor-scoped directory, never a bare `design-system/`, which is a normal
+  source folder in a large fraction of frontend repos.
+
 ### The withdrawn builder-URL trigger
 
 A page built in Lovable / v0 / bolt and handed over as a share link is a

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "16.0.0",
+    "version": "16.2.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including the counts in these badges.",
     "license": "MIT",
     "private": false,
@@ -80,7 +80,7 @@
     "scripts": {
         "build:cli": "tsc -p tsconfig.json && chmod +x dist/cli/agent-config.js",
         "build:install-bundle": "esbuild src/scripts/install.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/install/install.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
-        "build:hooks": "esbuild src/scripts/hooks/dispatch_entry.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/hooks/dispatch.js --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_HOOKS_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
+        "build:hooks": "esbuild src/scripts/hooks/dispatch_entry.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/hooks/dispatch.js --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_HOOKS_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\" && node src/scripts/write_bundle_digest.mjs",
         "build:mcp-bundle": "esbuild src/scripts/mcp_server/__main__.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/mcp/server.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_MCP_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
         "clean:cli-delegate": "rm -rf dist/cli-delegate",
         "build:delegates": "npm run clean:cli-delegate && npm run build:cli-delegate && npm run build:agent-src-delegate && npm run build:delegate-aux",
@@ -122,8 +122,8 @@
         "tree-sitter-wasms": "0.1.13",
         "tsx": "^4.23.1",
         "typescript": "^5.9.3",
-        "vite": "^5.4.21",
-        "vitest": "^2.1.9"
+        "vite": "^8.3.1",
+        "vitest": "^5.0.2"
     },
     "dependencies": {
         "@fastify/static": "^10.1.2",

package/src/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/src/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/src/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,
     });
 }
 

package/src/agent-src/templates/scripts/work_engine/directives/ui/app_spec.ts

@@ -11,8 +11,9 @@
  *
  * The gate is **scoped to the greenfield-scaffold path only**. It acts only
  * when `state.ui_audit` records `greenfield == True` and
- * `greenfield_decision == "scaffold"`. Every other UI flow sees this slot as a
- * clean `SUCCESS` no-op, so those flows stay byte-identical.
+ * `greenfield_decision` ∈ `{scaffold, granularity_convention}`. Every other
+ * UI flow sees this slot as a clean `SUCCESS` no-op, so those flows stay
+ * byte-identical.
  */
 import {
     type Any,
@@ -21,6 +22,7 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import { GRANULARITY_CONVENTION } from '../../state.js';
 
 /** Declared ambiguity surfaces for this step. */
 export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
@@ -112,14 +114,18 @@ export function run(state: DeliveryState): StepResult {
  * The gate is inert for every other flow: improve-existing, the `bare` /
  * `external_reference` greenfield picks, and the `diff` / `file` envelopes all
  * leave `ui_audit` without the `greenfield == True` +
- * `greenfield_decision == "scaffold"` pair.
+ * `greenfield_decision` ∈ `{scaffold, granularity_convention}` pair.
  */
 function _is_greenfield_scaffold(state: DeliveryState): boolean {
     const audit = state.ui_audit;
     if (!_isDict(audit)) return false;
+    // `granularity_convention` is option 4 — a scaffold that additionally
+    // organises what it creates under a named convention, so it takes the same
+    // grounding pass. Kept in step with the identical guard in `scaffold`.
     return (
         audit['greenfield'] === true &&
-        audit['greenfield_decision'] === 'scaffold'
+        (audit['greenfield_decision'] === 'scaffold' ||
+            audit['greenfield_decision'] === GRANULARITY_CONVENTION)
     );
 }