@event4u/agent-config 13.0.0 → 14.0.0

package/README.md

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

package/dist/agent-src/commands/evals/roadmap.json

@@ -29,6 +29,14 @@
     {
       "prompt": "plan out this feature step by step",
       "expected": "feature"
+    },
+    {
+      "prompt": "process road-to-user-out-of-the-loop.md to completion",
+      "expected": "roadmap"
+    },
+    {
+      "prompt": "either roadmap it or turn it into a feature plan, your pick",
+      "expected": "roadmap"
     }
   ]
 }

package/dist/agent-src/commands/fix/ci.md

@@ -80,8 +80,46 @@ reason to settle first.
 - Re-run the failing tool locally (inside the PHP container) to confirm the fix.
 - If multiple tools failed, fix and verify each one.
 
+### 5. Land it when the CI being fixed belongs to an open PR
+
+```
+"FIX THE CI" NAMES A REMOTE STATE. A LOCAL-ONLY FIX LEAVES THE RED CHECK
+EXACTLY AS RED, WHICH MAKES THE INSTRUCTION A NO-OP.
+COMMIT, PUSH, THEN RE-VERIFY ON THE PUSHED HEAD.
+A GREEN LOCAL RUN IS NOT THE VERDICT. A GREEN CI RUN ON AN EARLIER COMMIT
+IS NOT THE VERDICT EITHER.
+```
+
+Applies only when the failing run belongs to an **open PR for the current
+branch** — that is what makes the deliverable remote. Then:
+
+1. Commit the fix (chunked, the agent picks the split per
+   [`commit-policy`](../../../rules/commit-policy.md) — never ask how).
+2. Update the branch against its PR base first:
+   `./scripts-run src/scripts/sync_pr_branch`, then regenerate any derived files
+   the merge touched (`task sync && task generate-tools`). A PR left behind its
+   base accumulates conflicts for the moment someone wants to merge it, and a
+   push against a moved base is rejected — both cost a round trip that this one
+   call prevents.
+3. Push. The instruction named it; do not raise a separate ask
+   ([`/create-pr` § 4d item 5](../../../git/pr/create/command.md)).
+4. Re-verify remotely: `./scripts-run src/scripts/check_pr_ci_current`, then
+   settle the check set on the new head. Report the *remote* verdict, never the
+   local one.
+
+Bounded by N=3 per failing target ([`autonomous-execution`](../../../rules/autonomous-execution.md)).
+
 ### Rules
 
-- **Do NOT commit or push.** Only apply local fixes.
+- **No open PR for this branch → do NOT commit or push.** Apply local fixes only
+  and hand back. Without a PR there is no remote state the instruction could be
+  about, so the deliverable really is the working tree.
+- **A push is authorized for the named failure only.** Once the checks the user
+  pointed at are green, further pushes need their own instruction — a one-off
+  authorization is spent on the operation it was given for.
+- **Never force-push over a commit you did not author** — including a
+  GitHub *Update branch* merge on your own PR branch. Merge it in; the ask-first
+  floor is [`git-history-discipline`](../../../rules/git-history-discipline.md)
+  and nothing here reaches it.
 - **Do NOT skip or ignore errors** — fix the root cause.
 - If a fix is unclear, explain the error and ask the user for guidance.

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

@@ -149,6 +149,21 @@ than less: the gate can now read the PR's real `baseRefName` from the forge, so
 a stacked or release-line PR is measured against the branch it will actually
 merge into instead of against the repo default.
 
+**The resolution is executable now, not just described.**
+`./scripts-run src/scripts/sync_pr_branch` resolves the base from the open PR
+(so a stacked or release-line PR is measured against what it actually merges
+into), fetches, and merges it in when the branch is behind. On a conflict it
+STOPS and splits the conflicted paths into generated and authored — the first has
+one correct resolution (regenerate), the second has none a script may choose.
+Deliberately not in the pre-push hook: it mutates the tree, and a hook that
+rewrites the tree mid-push turns one rejected push into an unreviewed commit.
+Detection belongs in the hook and is already there; resolution is a step you run
+with the result in front of you.
+
+After it merges, REGENERATE — a clean auto-merge of a generated file is still
+wrong, and this is the step that produced the one stale-dashboard conflict on
+every merge of this branch.
+
 Where the project wires this gate into its pre-push chain, a push that goes out
 through the hook is covered without a separate step. Run it by hand when you push
 with the hook bypassed, or when you are about to open the PR some time after the
@@ -430,12 +445,58 @@ turns on `gh pr checks` every minute is the tool-loop
 4. **Bounded at N=3 per failing target** ([`autonomous-execution`](../rules/autonomous-execution.md)).
    Same failure signature twice → the hypothesis is wrong; change approach
    rather than spending the third attempt on a near-identical retry.
-5. **The push stays gated.** `git push` is a Hard Floor
+5. **The push stays gated — and a fix-the-CI instruction IS the gate being
+   cleared.** `git push` is a Hard Floor
    ([`non-destructive-by-default`](../rules/non-destructive-by-default.md)) and a
    one-off authorization is spent on the push it was given for
-   ([`commit-policy`](../rules/commit-policy.md)). Fix in the working tree and
-   push only under a fresh or still-standing instruction. A CI-fix loop that
-   re-pushes on its own authority is not on the table.
+   ([`commit-policy`](../rules/commit-policy.md)). What that forbids is a loop
+   that re-pushes on its **own** authority. It does not forbid delivering the
+   instruction the user actually gave.
+
+   ```
+   AN INSTRUCTION WHOSE DELIVERABLE IS A REMOTE STATE NAMES THE PUSH.
+   "FIX THE CI" · "RESOLVE THE CONFLICT WITH MAIN" · "UPDATE THE PR" ·
+   "MAKE THE CHECKS GREEN" → THE PUSH IS THAT INSTRUCTION, NOT A SECOND
+   OPERATION ON TOP OF IT. DO NOT RAISE A SEPARATE ASK FOR IT.
+   ```
+
+   The test is **where the deliverable lives**, and it is decidable: a red check,
+   a `CONFLICTING` merge state and a stale PR head are all facts about the
+   remote. An unpushed local fix leaves every one of them exactly as it was, so
+   treating the push as optional turns the instruction into a no-op and hands the
+   user back the state they asked to have changed. This is the same reading
+   [`no-cheap-questions`](../rules/no-cheap-questions.md) IL 5 gives prerequisite
+   work and IL 6 gives an already-named destination.
+
+   **What is still NOT covered**, so the floor keeps its teeth: an instruction
+   about the *code* only ("fix the type error", "use file X for the tests") — that
+   authorizes the edit, never the push. A push to a branch or base the user did
+   not name. A push after the named deliverable is already green. And a
+   force-push over a commit you did not author, which
+   [`git-history-discipline`](../rules/git-history-discipline.md) gates
+   separately and which this clause never reaches.
+
+6. **Re-verify remotely after the re-push — the fix is not done until the
+   REMOTE says so.**
+
+   ```
+   A GREEN LOCAL RUN IS NOT THE VERDICT. A GREEN CI RUN ON AN EARLIER
+   COMMIT IS NOT THE VERDICT EITHER. THE VERDICT IS A SETTLED CHECK SET
+   WHOSE HEAD SHA IS THE BRANCH HEAD YOU JUST PUSHED.
+   ```
+
+   Loop back to the top of § 4d — settle again, on the new head. Two traps make
+   this more than a restatement:
+
+   - **Stale green.** `gh pr checks` reports the last run it has, which may have
+     run against the pre-fix commit. Compare the SHA the checks ran against with
+     the PR head before reading a green as yours.
+   - **The re-push may not have landed.** A pre-push hook can refuse, and the
+     branch can be behind its OWN remote counterpart because someone pressed
+     *Update branch*. `git push` exiting non-zero means the PR still carries the
+     failure — never report the fix as delivered off a local verification.
+
+   `./scripts-run src/scripts/check_pr_ci_current` answers both in one call.
 
 **When the verdict cannot be reached** — network down, `gh` failing, the run
 never registering — say so plainly and name what is unverified. A background

package/dist/agent-src/commands/roadmap/next.md

@@ -236,15 +236,38 @@ diagnose and fix in the working tree on red, within the N=3 budget per
 [`autonomous-execution`](../../rules/autonomous-execution.md).
 
 ```
-THE LOCAL FIX IS AUTONOMOUS. THE RE-PUSH IS NOT.
-git push IS A HARD-FLOOR TRIGGER AND THE FLOOR REFUSES A STANDING
-DIRECTIVE BY CONSTRUCTION. FIX, VERIFY, THEN SAY WHAT IS READY.
-NEVER INVENT A PER-PR "STANDING MANDATE" WORKAROUND.
+THE LOCAL FIX IS AUTONOMOUS. A RE-PUSH ON THE AGENT'S OWN AUTHORITY IS NOT.
+BUT AN INSTRUCTION WHOSE DELIVERABLE IS A REMOTE STATE — "FIX THE CI",
+"RESOLVE THE CONFLICT WITH MAIN", "UPDATE THE PR" — NAMES THE PUSH, AND
+DELIVERING IT IS NOT A SECOND OPERATION TO ASK ABOUT.
+NEVER INVENT A PER-PR "STANDING MANDATE" FOR A PUSH NOBODY ASKED FOR.
+AND NEVER CALL A CI FIX DONE OFF A LOCAL RUN — RE-VERIFY ON THE PUSHED HEAD.
 ```
 
+The full reading, its decidable test, and what it deliberately does **not**
+cover live in [`/create-pr` § 4d items 5–6](../../git/pr/create/command.md);
+this is the pointer, not a second copy.
+
+Measured on this command's own run, 2026-08-17: a `/roadmap:next` invocation
+raised a separate push ask **three times** — after a CI fix, after a
+cross-reference fix, and after resolving a merge conflict the user had asked
+for by name. Each ask cost a turn and returned the same answer, and the third
+was for a conflict whose entire existence is a remote fact. That is the friction
+this clause removes; the floor it keeps is the *unnamed* push.
+
+**Before every push to the open PR**, bring the branch up to its base with
+`./scripts-run src/scripts/sync_pr_branch` and regenerate afterwards. Measured on
+this run: the base moved three times, the push was rejected twice for it, and the
+PR reached `CONFLICTING` in between. Verify the result afterwards with
+`./scripts-run src/scripts/check_pr_ci_current` — a green local gate says nothing
+about a fix that was never pushed, and a green CI run on an earlier commit says
+nothing about the current one.
+
 The cheapest CI-fix loop is the one that never fires: run `task
 preflight` before the first push, which runs the same
-`skill_linter --changed` gate CI does.
+`skill_linter --changed` gate CI does. Two gates it does NOT reach are
+`check_references` and `check_r2_manifest`, both remote-only — measured on this
+run, each forced one extra commit and therefore one extra review re-bind.
 
 ### 8. Report
 

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

@@ -149,6 +149,22 @@ engine owns the verdict.
 | `medium` | PARTIAL halt | Engine emits the assumptions report; surface verbatim, wait for the user. On confirm, write `state.input.data.confidence_confirmed=true` and re-run. On refine, replace `state.input.data.raw` with the new prompt, clear `reconstructed_ac` + `assumptions`, and re-run |
 | `low` | BLOCKED halt | Engine emits exactly one clarifying question on the weakest dimension (per [`ask-when-uncertain`](../rules/ask-when-uncertain.md) Iron Law). Surface verbatim, wait for the user, append their answer to `state.input.data.raw`, clear `reconstructed_ac` + `assumptions`, and re-run |
 
+**Elicitation is the contract's, not this command's.** The bands above decide
+*whether* the run may proceed; they do not each own a question surface. When
+`/work` derives an execution contract, the `medium`-band assumptions report and
+the `low`-band clarifying question are rows of the
+[`contract-decision-sheet`](../contexts/execution/contract-decision-sheet.md)
+rendered inside that contract screen — the same derivation
+[`roadmap-execution-contract`](../contexts/execution/roadmap-execution-contract.md)
+runs for `/roadmap:process-*`, reused rather than reimplemented here. `/work`
+carrying a second elicitation mechanism is exactly the drift the single-surface
+principle exists to stop, and reusing the derivation means a fix to the sheet
+reaches both entry points at once.
+
+Unchanged by that reuse: the engine still owns the band verdict (never flip it
+yourself), a `low` band still blocks, and the locked decision classes still
+escalate individually rather than becoming sheet rows.
+
 Once the gate releases, the rest of the loop is identical to
 `/implement-ticket`: `create-plan`, `apply-plan`, `run-tests`,
 `review-changes` directives flow through the same dispatch table. The

package/dist/agent-src/contexts/contracts/command-suggestion-flow.md

@@ -42,12 +42,59 @@ rank()     →  apply floor, drop blocklisted, anti-noise heuristics,
 apply_cooldown()  →  drop (command, evidence) pairs shown in window
    │
    ▼
+tier()     →  HIGH | MEDIUM | LOW  (see § Tier matrix)
+   │
+   ├── HIGH  → route directly + one-line basis statement
+   │
+   └── MEDIUM / LOW
+        │
+        ▼
 render()   →  numbered-options block + Recommendation line
    │
    ▼
 agent emits the block as the first and ONLY thing this turn
 ```
 
+## Tier matrix — the one case that routes without a block
+
+Extends the non-interactive contract's tier matrix onto this layer
+(road-to-user-out-of-the-loop Phase 1). The principle it serves is
+single-elicitation: when the routed command **has its own contract screen**,
+showing an options block first makes the user confirm the same intent twice.
+
+**HIGH** requires ALL of the following. They are deterministic facts, not a
+confidence score, because a threshold on a fuzzy score is exactly what would
+turn "unique match" into "usually right":
+
+1. The signal names the command **uniquely** — the roadmap file named in the
+   prompt exists on disk, or the phrase matches a `trigger_description`
+   **exactly** (not a substring hit).
+2. **No second candidate above the floor.** Two candidates, even at very
+   different scores, is MEDIUM.
+3. The routed command **shows its own confirmation** (a contract screen, a
+   plan-confidence gate, or an explicit accept step). A command that would
+   begin acting on arrival is never HIGH, whatever the signal.
+
+HIGH routes directly and prints **one line** naming its basis:
+
+```
+Routing to /roadmap:process-full — the named roadmap file exists and no second
+candidate scored above the floor. Its contract screen is your confirmation.
+```
+
+MEDIUM and LOW keep the numbered-options block, unchanged.
+
+**What HIGH does not do.** It does not skip a confirmation; it removes a
+*duplicate* one. Condition 3 is what makes that true rather than rhetorical —
+strip it and this becomes auto-execution. It also never applies to a Hard-Floor
+action, which is gated by [`non-destructive-by-default`](../../rules/non-destructive-by-default.md)
+regardless of how it was reached.
+
+**Kill criterion** (from the originating roadmap's Risk 3): more than 5 %
+mis-routes across 50 auto-routes reverts this to block-always. The instrument
+for that count does not exist yet — until it does, a mis-route is a reportable
+defect, and the honest position is that the rate is unmeasured rather than low.
+
 ## Scoring breakdown
 
 Per match, `match.ts` computes:

package/dist/agent-src/contexts/execution/contract-decision-sheet.md

@@ -0,0 +1,94 @@
+# Contract Decision Sheet
+
+Loaded by [`roadmap-execution-contract`](roadmap-execution-contract.md)'s
+derivation, so every consumer of the contract inherits it without binding to a
+command. One place asks the user: the contract screen. The plan-confidence
+interview, artifact understand-questions, and in-run clarifications feed *this*
+surface instead of opening rounds of their own.
+
+## The Iron Law
+
+```
+ONE SHEET PER CONTRACT DISPLAY. EVERY QUESTION THE PRE-SCAN FOUND IS ON IT,
+EACH WITH A DEFAULT, PLUS AN ACCEPT-ALL-DEFAULTS PATH.
+A QUESTION THAT COULD HAVE BEEN ON THE SHEET AND IS ASKED MID-RUN INSTEAD
+IS A DEFECT, NOT A CLARIFICATION.
+THE LOCKED CLASSES NEVER ENTER THE SHEET — THEY ESCALATE WHEN THEY FIRE.
+```
+
+## What goes on the sheet
+
+Pre-scan class 4 (open questions / ambiguity) produces the rows. A row is
+sheet-eligible when **all** hold:
+
+- it is answerable **before** the run starts — its answer does not depend on
+  something the run itself produces;
+- its decision class is `trivial`, `low_impact`, or `medium_impact`
+  ([`ai-council-config`](../../../docs/contracts/ai-council-config.md)
+  § decision_resolution);
+- a **conservative default** exists and can be stated in one line.
+
+Anything else is not a sheet row. In particular:
+
+| Not on the sheet | Why | Where it goes instead |
+|---|---|---|
+| `high_impact` / `user_required` | Locked to the user by an Iron Law no config lifts | Escalates during the run, at the moment it fires |
+| A question whose answer depends on run output | Cannot be answered at contract time; a guessed default would be a fabrication | The in-run escalation path |
+| A question with no conservative default | An option set with no safe side is a real decision, not a preference | Its own escalation |
+
+## Shape
+
+```
+Decision sheet — <N> question(s), all answerable now
+
+1. <question>
+   default: <option> — <one clause on why this is the conservative side>
+   alt:     <option> · <option>
+2. <question>
+   default: <option> — <why>
+   alt:     <option>
+
+A. Accept all defaults
+B. Change some (name them: "1=x, 2=y")
+C. Ask me these one at a time instead
+```
+
+The sheet is rendered **inside** the contract screen, above its Accept line —
+never as a second block and never as a second turn. Accepting the contract with
+`A` is one decision point answered by one keystroke, which is what makes it one
+question under [`ask-when-uncertain`](../../rules/ask-when-uncertain.md)'s
+Iron Law rather than N questions wearing a table.
+
+`C` exists because the batch is a convenience the user may decline. It is not a
+fallback the agent may choose: only the user picks `C`.
+
+## Recording — every answer is auditable after the fact
+
+Each answered row is written to the run's decision-memo directory with the
+question, the chosen option, and whether it came from `A` (default accepted) or
+an explicit override. Risk 1 of the originating roadmap is that a batched sheet
+invites accepting a decision that deserved thought; the mitigation is not to
+make the sheet harder to accept, it is to make every accepted default
+reviewable afterwards. A default accepted without being read is recoverable
+when it is on the record and invisible when it is not.
+
+## Why one sheet is not "fewer safeguards"
+
+The count of *decisions the user makes* is unchanged. What changes is the number
+of times the run stops to collect them: N stops become one. The locked classes
+still stop the run individually, when they fire, because their whole point is
+that they are seen at the moment they matter rather than pre-answered in a batch.
+
+Measured motivation: [`roadmap-process-loop § 3a`](roadmap-process-loop.md)
+records that 27 of 37 active roadmaps carried no `execution.mode` and therefore
+derived no contract at all — so before this surface existed, the questions this
+sheet batches were not asked once, they were asked one at a time, mid-run,
+by whichever mechanism happened to hit them first.
+
+## See also
+
+- [`roadmap-execution-contract`](roadmap-execution-contract.md) — the screen this renders inside; its single Accept is the authorization.
+- [`roadmap-process-loop § 3`](roadmap-process-loop.md) — the pre-scan that produces the rows, and the § 3a ladder that decides whether a contract is derived at all.
+- [`ai-council-config`](../../../docs/contracts/ai-council-config.md) § decision_resolution — the class table and the locked-class Iron Law.
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — one question per turn; one sheet answered by one keystroke is one question.
+- [`user-interaction`](../../rules/user-interaction.md) — the numbered-options shape and the single recommendation line.

package/dist/agent-src/contexts/execution/plan-confidence-gate.md

@@ -91,6 +91,36 @@ inline with the same stop conditions:
    summary (goal + in/out + constraints + AC) is stable for two turns.
 4. **Then author** via the surface's normal flow.
 
+#### 3c-batch — the batch branch, when a contract is being derived
+
+Serial is correct when the gate runs on its own. It is the wrong shape when the
+gate runs **inside** a contract derivation
+([`roadmap-execution-contract`](roadmap-execution-contract.md)), because the
+contract's whole premise is that the user is asked once. N serial turns inside a
+one-confirmation flow is the flow contradicting itself.
+
+So when the gate runs under a contract derivation, replace steps 2–3 with:
+
+1. **One sheet at seed time.** Every load-bearing branch known after step 1
+   becomes a row of the
+   [`contract-decision-sheet`](contract-decision-sheet.md), each with a
+   conservative default. Not two blocks, not two turns.
+2. **At most two rounds, and round two is narrow.** Round two exists only for
+   branches *created by round-one answers* — never for branches that were
+   knowable at seed time and were missed. A branch that could have been on
+   round one and appears on round two is a defect in the step-1 resolve, and
+   is recorded as one rather than silently re-asked.
+3. **Remaining ambiguity resolves to its conservative default plus a decision
+   memo** — never to a third round and never to a silent guess. The memo makes
+   the default reviewable after the fact, which is what allows the round cap to
+   be a cap rather than a loss.
+
+Unchanged, deliberately: the locked classes never enter a sheet
+(`high_impact` / `user_required` escalate when they fire), and **the C→R1 state
+file below is written exactly as before**. Batching changes how the questions
+are *collected*, never what is recorded — so R1 still never re-asks a resolved
+branch and no plan is interviewed twice.
+
 ### 4. C→R1 handoff — write the state file
 
 On completing the gate (either path that ran an interview), write

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

@@ -1,9 +1,14 @@
 # Roadmap Execution Contract
 
-Loaded by [`roadmap-process-loop § 3`](roadmap-process-loop.md) when the
-resolved roadmap declares `execution.mode` in frontmatter
-(`autonomous` | `phase-checkpoints`; absent / `interactive` = legacy
-behavior, this context stays unloaded). Defines the run-start pre-scan,
+Loaded by [`roadmap-process-loop § 3`](roadmap-process-loop.md) when the run's
+**derived** mode is `autonomous` or `phase-checkpoints`. The mode comes from the
+§ 3a ladder — explicit invocation suffix, then frontmatter `execution.mode`,
+then the invocation form — so an ABSENT frontmatter field no longer keeps this
+context unloaded: under `process-full` / `/roadmap:next` it derives
+`autonomous`, under `process-phase` it derives `phase-checkpoints`. Only a
+*derived* `interactive` (asked for explicitly, declared in frontmatter, or
+`process-step`) leaves this context unloaded and falls back to the legacy
+commit-step scan. Defines the run-start pre-scan,
 the contract summary the user confirms ONCE, the grants that
 confirmation activates, and the per-mode gate table.
 
@@ -37,7 +42,13 @@ Scan every open step (text + inline notes) for:
 4. **Open questions / ambiguity** — explicit `?` markers, "decide
    whether", options left unresolved, or steps matching the
    [`ask-when-uncertain`](../../rules/ask-when-uncertain.md)
-   vague-trigger patterns.
+   vague-trigger patterns. These become the rows of the
+   [`contract-decision-sheet`](contract-decision-sheet.md), rendered inside the
+   summary below — one numbered block, a default per row, and an
+   accept-all-defaults path. Loading is part of this derivation, not of any
+   command, so every consumer of the contract inherits the sheet. The locked
+   classes (`high_impact`, `user_required`) never become rows: they escalate
+   during the run, at the moment they fire.
 
 ## 2. Contract summary — shown once, confirmed once
 
@@ -49,10 +60,12 @@ Git: branch <feat/<roadmap-slug>> · commits: chunked (N commit steps
      · PR: open against <default branch> (description only — no merge)
 Artifacts: <N> planned (skills/rules/commands/guidelines) —
      batched overlap check: <result — run NOW, against current state>
-Open questions: <N> → resolved via AI council (<members | "none
-     configured — will halt on ambiguity">)
+Open questions: <N> → decision sheet below (<M> rows); the rest via AI
+     council (<members | "none configured — will halt on ambiguity">)
 Quality: <cadence> · Dashboard: <cadence>
 
+<decision sheet, per contract-decision-sheet — omitted entirely when M = 0>
+
 Always active regardless of this contract (never lifted):
   • Hard Floor per-commit diff gate (bulk deletions / infra)
   • Push anywhere except feat/<roadmap-slug>; any merge
@@ -90,7 +103,7 @@ These grants satisfy [`scope-control`](../../rules/scope-control.md)'s
 |---|---|---|
 | `autonomous` | All steps `[x]` · quality green per cadence · work committed in chunks on `feat/<roadmap-slug>` · pushed · PR open · archival sweep run. **Merge out of scope, always.** | Safety floors only (+ quality-red, + step reveals out-of-roadmap work) |
 | `phase-checkpoints` | Same end state | Safety floors + a compact status + "continue?" prompt at each phase boundary |
-| `interactive` (absent field) | Legacy: work lands, no git delivery without per-op permission | All gates as authored by their owning rules |
+| `interactive` (derived, never from an absent field) | Legacy: work lands, no git delivery without per-op permission | All gates as authored by their owning rules |
 
 If the roadmap contains **no** delivery need and no commit steps, the
 git grants are omitted from the contract (nothing to authorize —

package/dist/agent-src/contexts/execution/roadmap-process-loop.md

@@ -76,7 +76,7 @@ options + wait):
 > Phase 2: `<name>` — 0/4
 > Next open step: `<description>`
 > Scope: **step | phase | full**
-> Execution mode: **autonomous | phase-checkpoints | interactive** (frontmatter `execution.mode`; absent = interactive)
+> Execution mode: **autonomous | phase-checkpoints | interactive** (derived per § 3a — name the rung: `invocation suffix` | `frontmatter` | `invocation form`)
 > AI council: **on | off** (`<member list or "no members configured">`)
 > Quality cadence: **end_of_roadmap | per_phase | per_step**
 > Commit steps in roadmap: **N** (see § 3)
@@ -91,11 +91,55 @@ does not fire.
 
 ## 3. Pre-scan — execution contract or commit-step ask
 
-Read `execution.mode` from the roadmap's frontmatter
-(`autonomous` | `phase-checkpoints` | `interactive`; absent =
-`interactive`).
-
-**`mode: autonomous` or `phase-checkpoints`** → load
+### 3a. Mode derivation ladder — first source wins
+
+```
+AN ABSENT `execution.mode` IS NOT A DECLARATION OF `interactive`.
+IT IS THE ABSENCE OF A DECLARATION, AND IS DERIVED — NEVER DEFAULTED SILENTLY.
+```
+
+Resolve the mode from the first source that answers, and **state which rung
+answered** in the pre-run summary so the derivation is auditable rather than
+implicit:
+
+| # | Source | Wins when |
+|---|---|---|
+| 1 | **Explicit invocation suffix** — `… autonomous` / `… phase-checkpoints` / `… interactive` in the invocation | the user typed it this turn |
+| 2 | **Frontmatter `execution.mode`** | the roadmap declares one |
+| 3 | **Invocation form** (table below) | neither of the above answered |
+
+Rung 3, by wrapper:
+
+| Wrapper | Derived mode | Contract |
+|---|---|---|
+| `/roadmap:process-full`, `/roadmap:next` | `autonomous`, **preselected** | offered |
+| `/roadmap:process-phase` | `phase-checkpoints` | offered |
+| `/roadmap:process-step` | — | none (one step needs no run contract) |
+
+Still **exactly one confirmation**, never two: rung 3 changes which option the
+contract screen arrives preselected on, never whether the screen is shown. The
+screen's `3. Run interactive instead` option
+([`roadmap-execution-contract § 2`](roadmap-execution-contract.md)) stays on it
+in every case, so a derived mode is always one keystroke from being refused.
+
+**Why the old fallback was a defect and not a conservative default.** Absent
+`execution.mode` used to mean the legacy commit-step scan, which derives no
+contract at all — no batched artifact drafting, no council auto-enable, no
+push/PR grant. Measured 2026-08-17: **27 of 37 active roadmaps carry no
+`execution.mode`**, so roughly three quarters of the corpus ran the degraded
+path *under the wrapper built for the opposite*, and silently — the user saw a
+`process-full` invocation behave like an interactive one with no line saying so.
+A default that contradicts the wrapper the user just typed is a wrong answer,
+not a safe one.
+
+**What this does NOT change.** A derived mode grants nothing on its own:
+authorization is still the single Accept on the contract screen, per
+[`roadmap-execution-contract § Principle`](roadmap-execution-contract.md). The
+Hard Floor, the locked decision classes, and the kernel-edit soak are untouched.
+
+### 3b. Contract or commit-step ask
+
+**Derived `autonomous` or `phase-checkpoints`** → load
 [`roadmap-execution-contract`](roadmap-execution-contract.md) and run
 its four-class pre-scan over every open step:
 
@@ -114,8 +158,11 @@ cached for the run, never re-asked. The contract never lifts a Hard
 Floor or any safety floor; boundaries + per-mode gate table live in the
 contract context.
 
-**`mode: interactive` (or field absent)** → legacy commit-step scan
-only: lines matching `commit:` / `git commit` / `Commit phase`.
+**Derived `interactive`** — i.e. the user asked for it explicitly (rung 1), the
+frontmatter declares it (rung 2), or the invocation was `process-step` (rung 3)
+→ legacy commit-step scan only: lines matching `commit:` / `git commit` /
+`Commit phase`. An ABSENT field no longer reaches this branch; that is the whole
+change in § 3a.
 
 - **No commit steps** → nothing to ask. Never commit, never re-ask
   per [`commit-policy`](../../rules/commit-policy.md).

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

@@ -31,6 +31,48 @@ orchestrator synthesises and re-verifies.
   chars (~3k tokens against a measured ~251k spawn floor). Constants + checks:
   `src/scripts/_lib/subagent_response.ts`.
 
+## Durable copy — the envelope on disk before the message
+
+```
+THE FINAL MESSAGE IS A SINGLE TEXT-ONLY ENVELOPE. NEVER END ON A TOOL CALL.
+THE SAME ENVELOPE IS WRITTEN TO THE RUNTIME ARTIFACT DIR BEFORE IT IS EMITTED.
+DISK IS THE DURABLE CHANNEL. THE MESSAGE IS THE FAST CHANNEL.
+A RETURN THAT WAS PAID FOR AND NEVER DELIVERED IS THE FAILURE THIS PREVENTS.
+```
+
+The envelope reaches the orchestrator twice, and the two copies are not two
+result shapes:
+
+- **The message** — the worker's final assistant message, text only, carrying
+  the envelope verbatim. Fast, and the channel that can vanish.
+- **The file** — the same envelope written into the runtime artifact dir
+  (gitignored) as `response-envelope.json` *before* the final message is
+  emitted, so it exists even when the message never arrives.
+
+This does not weaken *the envelope is the ONLY return channel* above. That
+clause governs what the orchestrator may **ingest** — one envelope shape, never
+a wholesale transcript. The disk copy carries that same shape, so the
+orchestrator still reads exactly one; what changes is that it can still read it
+after a delivery failure.
+
+**Why the ordering is load-bearing.** A subagent whose last block is a
+`tool_use` delivers nothing to its parent on host 2.1.229 — measured with a
+matched control dispatched in the same turn: `(no output)` after 3 tool uses and
+18,242 tokens, against a control ending on assistant text that returned the
+complete report
+([`subagent-lifecycle-phase0-return-channel.md`](../../../../agents/evidence/investigations/subagent-lifecycle-phase0-return-channel.md)
+§ F1). The tokens were spent either way. Writing the envelope first is what
+turns a dropped message into a recoverable read instead of a paid-for discard.
+
+**Honest status — a convention, not a checked invariant.** Nothing in the tree
+writes, reads, or validates `response-envelope.json`: the filename is fixed here
+so that a durable channel is *findable* rather than nominal, and the clause
+travels in the dispatch prompt (spawn contract rule (f)), which is where a
+worker actually reads its duties. A `subagent_stop` concern that finds the file
+and injects its path when the message is empty is planned and **not shipped** —
+said plainly, because "the durable channel" must not be read as a recovery
+mechanism that already runs.
+
 ## Budget-hit partial result
 
 When the worker's `max_tokens_per_worker` stop-loss fires