@event4u/agent-config 8.9.0 → 8.11.0

package/dist/agent-src/commands/worktree/verify.md

@@ -0,0 +1,70 @@
+---
+model_tier: medium
+name: worktree-verify
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: worktree
+sub: verify
+skills: [worktree-lifecycle, verify-completion-evidence]
+description: Run the scoped verification for a worktree's declared change — narrow probes matched to the diff, never the full CI pipeline
+suggestion:
+  eligible: true
+  trigger_description: "verify the worktree change, prove this worktree is ready"
+  trigger_context: "a governed worktree with committed changes but no verification evidence attached"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /worktree verify
+## Instructions
+
+Produce fresh, scoped verification evidence for ONE worktree's declared
+change. Narrow probes only — this command never runs the full CI
+pipeline locally (`roadmap-ci-steps-policy` / `quality.local_auto_run`
+default: remote CI on the PR is the gate).
+
+### 1. Resolve target + scope
+
+Target worktree = the current one, or the path/branch given as arg.
+Read its `.worktree-scope.md` (`owns:` paths + task line) per
+[`worktree-lifecycle § Scope lock`](../../../skills/worktree-lifecycle/SKILL.md#2-scope-lock).
+No scope lock → stop and route to `/worktree create` step 3 first.
+
+### 2. Scope-conformance check
+
+```bash
+git diff --name-only "$(git merge-base HEAD <base>)"..HEAD
+```
+
+Paths outside `owns:` → surface as scope creep (`scope-control`) before
+verifying anything; the evidence must describe the declared change.
+
+### 3. Pick the narrowest probes
+
+Map the diff to probes per `verify-completion-evidence` (claim →
+command): the single test filter for touched behavior, the
+type-checker/linter scoped to changed files, a `curl`/spec run for a
+touched endpoint. Never substitute the full CI meta-pipeline for a
+targeted probe.
+
+### 4. Run fresh + record
+
+Run the probes now (no cached/earlier results — `verify-before-complete`),
+capture command + exit code + output tail, and append the evidence to
+the worktree's `.worktree-scope.md` under a `## Verification evidence`
+heading (command, date, result) so `/worktree status` can report it.
+
+### 5. Report
+
+Use the [`worktree-lifecycle § Output format`](../../../skills/worktree-lifecycle/SKILL.md#output-format):
+evidence section carries the probe commands + tails; verdict states
+whether checklist item 3 (evidence attached) now passes.
+
+### Rules
+
+- **Do NOT commit or push.** Evidence lives in the untracked scope note.
+- Red probe → report it plainly and stop; never downgrade to a weaker
+  probe to get green (N=3 budget per `autonomous-execution`).

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

@@ -0,0 +1,85 @@
+---
+model_tier: medium
+name: worktree
+disable-model-invocation: true
+pack: engineering-base
+tier: 2
+visibility: internal
+description: Worktree orchestrator — routes to create, status, verify, cleanup
+cluster: worktree
+type: orchestrator
+auto_detect: true
+suggestion:
+  eligible: true
+  trigger_description: "isolate this in a worktree, which worktrees are active, is the worktree merge-ready, clean up finished worktrees"
+  trigger_context: "parallel work needs an isolated working directory, or existing worktrees need status/verification/removal"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /worktree
+
+Top-level orchestrator for the governed-worktree family — a THIN layer
+over host-native primitives (Claude Code `EnterWorktree`/`ExitWorktree`,
+subagent `isolation: "worktree"`) and plain `git worktree` elsewhere.
+Explicitly OUT of scope: auto-merge, daemons, background watchers,
+dispatch beyond the existing subagent worktree isolation.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/worktree create` | `commands/worktree/create.md` | Create a governed worktree + write the scope-lock note (propose-once branch naming) |
+| `/worktree status` | `commands/worktree/status.md` | List active worktrees — ownership, dirty state, ahead/behind, merge-readiness incl. verification evidence |
+| `/worktree verify` | `commands/worktree/verify.md` | Run the scoped verification for the worktree's declared change — narrow probes, not full CI |
+| `/worktree cleanup` | `commands/worktree/cleanup.md` | Safe removal gate — refuses while the branch has commits on no other ref |
+
+All four route through the
+[`worktree-lifecycle`](../../skills/worktree-lifecycle/SKILL.md) skill;
+creation mechanics live in
+[`using-git-worktrees`](../../skills/using-git-worktrees/SKILL.md).
+
+## Non-interactive & auto-detection
+
+`/worktree` honors the [`non-interactive-contract`](../contexts/execution/non-interactive-contract.md)
+(surface detection, confidence tiers, `--yes`/`--json`, abort schemas,
+the `auto_detect` kill-switch). Detection table:
+
+| Basis (signal) | Sub-command | Confidence |
+|---|---|---|
+| Explicit sub given (`/worktree status`) | that one | — (detection skipped) |
+| "isolate / do this on the side / new worktree for X" | `worktree/create` | HIGH |
+| "which worktrees / what's active / merge-ready?" | `worktree/status` | HIGH |
+| "verify the worktree change", scoped probe intent | `worktree/verify` | MEDIUM |
+| "remove / clean up the worktree(s)" | `worktree/cleanup` | HIGH |
+| No clear signal | — | LOW → menu (interactive) / `ambiguous_routing` (CI) |
+
+`cleanup` is the only destructive sub-command — on MEDIUM-or-lower
+confidence it is never auto-selected; show the menu instead.
+
+## Dispatch
+
+1. Parse the user's argument: `/worktree <sub-command> [args]`.
+2. **Explicit sub** → look it up and route. Otherwise run the detection
+   table above per the non-interactive-contract.
+3. Load the body of the routed file and follow its `## Instructions`
+   section verbatim with the remaining args.
+4. On **LOW** confidence (or `--no-auto-detect`): interactive → print
+   the menu and ask; non-interactive → emit `ambiguous_routing` and stop.
+
+   > 1. create — new governed worktree + scope-lock note
+   > 2. status — list worktrees with merge-readiness
+   > 3. verify — run the scoped verification for a worktree
+   > 4. cleanup — safely remove finished worktrees
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command
+  explicitly authorizes it.
+- **Do NOT chain sub-commands.** One `/worktree <sub>` per turn.
+- **No auto-merge, no watchers.** The cluster reports and gates; the
+  user (or an explicitly invoked command) merges.
+- Auto-detection never guesses past LOW, and never auto-selects
+  `cleanup` below HIGH confidence.

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

@@ -72,6 +72,72 @@ Push, merge, rebase, branch creation, PR operations, and tags
 remain permission-gated by
 [`scope-control § git-operations`](../../rules/scope-control.md#git-operations--permission-gated).
 
+## Opt-in detection — rule-level summary
+
+(Migrated from the [`autonomous-execution`](../../rules/autonomous-execution.md)
+rule per P4 of `road-to-kernel-and-router.md`; the detection algorithm itself
+lives in [`autonomy-detection.md`](autonomy-detection.md) — that file is the
+stronger, operative source.)
+
+In `auto` mode, flip to `on` for the rest of the conversation when the user expresses **"stop asking on trivial steps, just work"**. Recognize **intent**, not the literal substring. Opt-out (same intent, reversed) flips back to `off`. Both directions are **speech-act-checked**: the phrase must be a meta-instruction to the agent, not content / quote / subject / code / third-party reference / hypothetical. In doubt → keep current mode, no speculative flips.
+
+Algorithm and speech-act heuristic: [`autonomy-detection.md`](autonomy-detection.md). Anchor phrases (DE+EN), no-flip patterns, counter-examples, trivial-vs-blocking taxonomy, commit-policy summary, and named failure modes: this file + [`autonomy-examples.md`](autonomy-examples.md).
+
+## Task-scope — two autonomy shapes
+
+Depth for the rule's task-scope Iron Law (`NEW TASK → FRESH CONFIRMATION`).
+Two distinct autonomy shapes — keep them apart:
+
+| Shape | Trigger | Scope |
+|---|---|---|
+| **Conversation-wide trivial-question suppression** | "stop asking on trivial steps, just work" — no deliverable named. | Sticky for the rest of the conversation. Suppresses trivial workflow questions only; never lifts blocking, Hard Floor, or [`scope-control`](../../rules/scope-control.md) gates. |
+| **Task-scoped autonomous execution** | "work autonomously on X", "arbeite die Roadmap Y komplett ab", "do PROJ-123 end-to-end" — a deliverable / artifact / ticket is named. | Bound to **that** task. Ends when the task ends. Does **not** authorize starting a new, distinct task autonomously. |
+
+Litmus test: does the directive name (or unambiguously point to) a single concrete deliverable? Yes → task-scoped, scope ends with the deliverable. No → conversation-wide, trivial-question suppression only.
+
+When the user later issues a **new** request — different ticket, different roadmap, different artifact, different feature — treat it as a fresh task. Re-confirm autonomy for the new scope before:
+
+- creating a branch / worktree / PR / tag for the new work,
+- implementing a roadmap whose **authoring** was the prior turn's deliverable (per [`scope-control § authoring vs implementation`](../../rules/scope-control.md#authoring-vs-implementation--verb-discipline)),
+- expanding scope beyond the new task's literal ask.
+
+In doubt whether the new request inherits or needs fresh confirmation → fresh confirmation. The Hard Floor and [`scope-control`](../../rules/scope-control.md) gates apply to every task regardless.
+
+## Validation-loop budget — mechanics (N=3)
+
+Autonomous flows must not iterate indefinitely on the same validation target. **Validation target** = a single identifiable artefact: a file path, a lint rule ID, a test name, a CI sub-task name. Natural-language clustering ("the linter stuff") does **not** count as a target — agents will rename their way out of the budget.
+
+A "failed attempt" is an iteration that did not move the target from red to green. Tuning the tool around the target (e.g. growing an allowlist, loosening a threshold, suppressing a check) counts as an attempt — and is usually a sign the **tool**, not the content, is wrong.
+
+### Allowlist-growth antipattern — detail
+
+Crossing the 20-entry threshold counts as the 3rd validation-target failure for the linter in question, regardless of prior attempt count. The fix is a tool-shape change (heuristic tightening, scope narrowing, deletion), not more entries. Same logic for: warning-suppression lists growing past ~20, `// noqa` / `# type: ignore` sweeps over many files in one session, test `skip` / `xfail` bulk-adds to chase green.
+
+### Probe efficiency — direct over orchestration
+
+When validating a single target, run the **specific** check, not a meta-task that fans out to dozens of sub-tasks. Use the failing tool's direct entry point (the specific script invocation, the specific runner target, the single-test filter for the project's test runner) rather than the full CI meta-pipeline. Full-pipeline runs are appropriate at phase boundaries, not as a per-iteration probe.
+
+Concrete tool mapping — verify with the narrowest tool that proves the target green: a single `curl` / Playwright spec / browser run for HTTP behavior, the project's test runner with a `--filter` for one test, a debugger / `xdebug` step-through for one frame. Never substitute a meta-pipeline for a tool that pinpoints the failure.
+
+## Adaptive effort & stop (RDP)
+
+Scale effort to task difficulty, and stop when marginal evidence drops — coupled
+to the N=3 budget above, never replacing it. On a host with a native effort knob
+(e.g. an `effort` parameter), the right move is to **set it high** for hard tasks
+rather than scaffold; the scaffold here is for a standard host **without** such a
+knob. The per-dimension uncertainty score (see
+[`notes-first-reasoning`](../../rules/notes-first-reasoning.md)) feeds this
+decision. Engage per [`rdp-gate`](rdp-gate.md).
+
+**Concrete diminishing-returns stop-signal.** Operationalize "marginal evidence
+drops" so it is checkable, not vibes: when **two consecutive investigative probes**
+(a read, a grep, a query) yield **no new load-bearing information** — nothing that
+changes the plan or the hypothesis — stop gathering and act on what you have (or
+ask). The diminishing-returns twin of N=3: N=3 stops fruitless *fixing*, this stops
+fruitless *searching*. Never overrides the read-loop abort in
+[`context-hygiene`](../../rules/context-hygiene.md) — that is the hard ceiling;
+this is the earlier soft signal.
+
 ## End-of-turn checkpoint
 
 Before ending a turn, check the last paragraph of the reply. If it is a

package/dist/agent-src/contexts/execution/orchestration-benchmark-gate.md

@@ -69,6 +69,7 @@ is auditable rather than asserted.
 
 ## Related
 
+- ADR-118 (`docs/decisions/ADR-118-loop-engineering-boundaries.md`) — demotion stays manual human edit by decision; never automated (disposition #1).
 - [`auto-orchestration-activation`](auto-orchestration-activation.md) — the `subagents.auto` key this gate sets the default for.
 - [`host-capability-manifest`](host-capability-manifest.md) — `subagent_spawn` gates the flip.
 - [`orchestration-telemetry`](orchestration-telemetry.md) — the per-dispatch metrics the benchmark aggregates.

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

@@ -21,12 +21,15 @@ v1 forward-compat rule on unknown fields).
   "verify_mode": "deterministic",
   "verdict_changed_outcome": null,
   "task_class": null,
+  "dispatch_mode": null,
   "tier_chosen": null,
   "tier_source": null,
   "dispatch_tokens": null,
   "session_tier": null,
   "escalated_from": null,
-  "verify_result_by_tier": null
+  "verify_result_by_tier": null,
+  "first_pass_success": null,
+  "escalated": null
 }
 ```
 
@@ -34,27 +37,72 @@ v1 forward-compat rule on unknown fields).
 
 | Field | Type | Meaning |
 |---|---|---|
-| `task_size_estimate` | int | Pre-dispatch estimate of the task's size (orchestrator's sizing heuristic). Counts only, no body. |
-| `spawn_count` | int | Subagents dispatched for this task. `0` → handled in-session. |
-| `tiers` | string[] | Model tiers dispatched to, one per spawn class (e.g. `["sonnet","opus"]`). Tier names only, no prompts. |
-| `token_delta` | int | Net token cost vs the in-session baseline. Positive = cost more; negative = saved. Counts only. |
-| `token_delta_provenance` | enum | `"measured"` from host-reported `usage` metadata (preferred); `"estimated"` when self-estimated from response length (mark always when host usage unavailable). |
-| `wall_clock_ms` | int | Dispatch wall-clock duration, milliseconds. |
+| `task_size_estimate` | int | Pre-dispatch estimate of the task's size (the orchestrator's sizing heuristic). Counts only, no body. |
+| `spawn_count` | int | Number of subagents dispatched for this task. `0` → handled in-session. |
+| `tiers` | string[] | Model tiers dispatched to, one entry per spawn class (e.g. `["sonnet","opus"]`). Tier names only, no prompts. |
+| `token_delta` | int | Net token cost of the dispatch versus the in-session baseline. Positive = orchestration cost more; negative = saved tokens. Counts only. |
+| `token_delta_provenance` | enum | `"measured"` when sourced from host-reported `usage` metadata (preferred); `"estimated"` when self-estimated from response length (mark always when host usage is unavailable). |
+| `wall_clock_ms` | int | Wall-clock duration of the dispatch, milliseconds. |
 | `outcome` | enum | One of `DONE` · `DONE_WITH_CONCERNS` · `NEEDS_CONTEXT` · `BLOCKED` · `killed`. |
-| `verify_mode` | enum | How output was verified: `deterministic` · `judge` · `none`. |
-| `verdict_changed_outcome` | bool \| null | **A3 extension (ADR-109 Track A).** For a review/verdict subagent (e.g. `production-validator`): did the verdict change the outcome vs the in-session baseline? `true` = caught a real issue the baseline missed / flipped a false `READY`→`NOT READY`; `false` = no lift; `null` = not a verdict dispatch / not measured. **Negative-control (clean single-file) tasks MUST record `false`** — a `true` on a control = spurious findings, fails Gate A. Additive field on THIS object, not a second schema. Boolean/counts only, no bodies. |
+| `verify_mode` | enum | How the dispatch's output was verified: `deterministic` · `judge` · `none`. |
+| `verdict_changed_outcome` | bool \| null | **A3 extension (ADR-109 Track A).** For a review/verdict subagent (e.g. `production-validator`): did the subagent's verdict actually change the outcome versus the in-session baseline? `true` = it caught a real issue the baseline missed or flipped a false `READY`→`NOT READY`; `false` = same outcome as baseline (no lift); `null` = not a verdict dispatch / not measured. **Negative-control tasks (a clean single-file task) MUST record `false`** — a subagent that reports `true` on a control is producing spurious findings and fails Gate A. This is an additive field on THIS object, not a second schema. Counts/boolean only, no bodies. |
+| `dispatch_mode` | enum \| null | **Form-gate extension (road-to-opt-subagent-harvest P2).** Which orchestration mode the deterministic form gate selected for this dispatch (`do-and-judge`, `do-and-judge-two-stage`, `do-in-steps`, `do-in-parallel`, `do-competitively`, `judge-with-debate`, `do-in-worktrees`, `do-with-live-app-judge`) or `none` (gate declined dispatch). Mode id only. `null` = pre-extension line. Makes the form-gate's value measurable inside the ADR-117 prove-or-drop window. |
 | `task_class` | string \| null | **Routing extension (road-to-cost-aware-model-routing Phase 0).** Category id of the dispatched slice (e.g. `read-only-fanout`, `mechanical-edit`, `implementation`, `review-synthesis`). Enum-style id only, never free-form task text. `null` = pre-extension line / unclassified. |
 | `tier_chosen` | string \| null | Tier the slice was dispatched on (`lite` \| `medium` \| `high`). `null` = pre-extension line. |
 | `tier_source` | enum \| null | Where `tier_chosen` came from: `static` (frontmatter/category pin) · `inferred` (deterministic per-slice inference) · `inherit` (session tier — no downshift decision). Lets the evidence gate score inferred routing separately from static pinning. |
-| `escalated_from` | string \| null | When the slice re-dispatched after a verification failure: tier of the FAILED attempt (e.g. `lite` when a lite return failed verify and the slice re-ran on `medium`). `null` = no escalation. |
-| `verify_result_by_tier` | object \| null | Map tier → verification result per attempt of this slice (e.g. `{"lite":"fail","medium":"pass"}`). Values: `pass` \| `fail` \| `skipped`. Feeds the per-tier verify-pass-rate tripwire. Enums only, no verdict bodies. |
+| `escalated_from` | string \| null | When the slice was re-dispatched after a verification failure: the tier of the FAILED attempt (e.g. `lite` when a lite return failed verify and the slice re-ran on `medium`). `null` = no escalation. |
+| `verify_result_by_tier` | object \| null | Map of tier → verification result for every attempt of this slice (e.g. `{"lite":"fail","medium":"pass"}`). Values: `pass` \| `fail` \| `skipped`. Feeds the per-tier verify-pass-rate tripwire. Enums only, no verdict bodies. |
 | `dispatch_tokens` | int \| null | **Cost-% extension.** Absolute tokens the dispatched slice consumed (measured subagent usage). Feeds the MODELED cost-% in `orchestration_savings_report`, which needs an absolute base the token-count delta lacks. `null` = not recorded. Counts only. |
 | `session_tier` | string \| null | **Cost-% extension.** The orchestrator's OWN tier — the baseline the downshift cost-% measures `tier_chosen` against (a `high`→`lite` downshift is a rate win the token count can't see). `null` = not recorded. |
+| `first_pass_success` | bool \| null | **QUALITY extension (council verdict: quality × cost paired).** `true` = the subagent return was adopted without parent rework; `false` = the parent had to rework the return before adopting. Precise rework definition: § Operationalization below. `null` = pre-extension line / not measured. Boolean only, no bodies. |
+| `escalated` | bool \| null | **QUALITY extension (council verdict: quality × cost paired).** `true` = the slice was retried on a higher tier after a verification failure; `false` = no escalation. Semantics: § Operationalization below. `null` = pre-extension line / not measured. Boolean only, no bodies. |
 
 These routing + cost fields are additive and optional — a line without them is
 still a valid orchestration line; readers ignore unknown fields per the v1
 forward-compat rule.
 
+## Operationalization — `first_pass_success` / `escalated` (definitions, no schema change)
+
+The two quality booleans are only comparable across sessions when "parent
+rework" means the same thing everywhere. The mechanical decision table:
+
+```
+first_pass_success = TRUE iff the parent adopts the subagent work product
+with NO scope-relevant modification and issues NO corrective follow-up
+prompt to the same subagent within the same task scope.
+
+EXCLUDED from "modification" (still TRUE):
+  - auto-formatter output (prettier / eslint --fix / pint --fix)
+  - import sorting
+  - lockfile regeneration
+  - whitespace-only diffs
+
+INCLUDED as rework (FALSE):
+  - any business-logic line diff to the returned work product
+  - added or changed tests
+  - changed API contract / signature
+  - manual conflict resolution
+  - architectural restructuring of the returned diff
+
+escalated = TRUE iff the parent re-dispatched the same slice to a higher
+tier after a verification failure. A mechanism metric, not a quality
+verdict — it records that the escalation path fired, not how good the
+final output was.
+```
+
+**Honest boundary:** both fields are machine-observable proxies from the
+orchestrator's own actions; they do NOT measure output quality directly. An
+adopted-without-rework return can still be mediocre; a rejected return can
+have failed on a formality. Field extensions (`verification_passed`,
+`parent_rework_level`, `regression_detected`, `task_completed`,
+`judge_confidence`, `human_rejected`) are explicitly NOT added: five of the
+six are unobservable without new infrastructure (verification harness, diff
+classifier, judge step, human feedback loop) and would breach the counts-only
+privacy floor or record guesses. Revisit-if: a verification harness exists
+that makes a candidate field machine-observable without content inspection.
+The two-field cap is a council decision (2026-07-10); this section
+operationalizes it rather than widening it.
+
 ## Privacy floor
 
 Counts and ids only — **no bodies**. This preserves the audit-log-v1 privacy
@@ -74,49 +122,58 @@ object is an additive extension on an otherwise standard audit-log-v1 line:
 
 After every auto-dispatched orchestration run, the orchestrating agent writes one
 telemetry line to `agents/runtime/state/audit/YYYY-MM.jsonl` (the existing
-audit-log-v1 path; `YYYY-MM` = current UTC month). The line is a standard
-audit-log-v1 object with `input_kind: "orchestration"` and an `orchestration`
-sub-object carrying this shape.
+audit-log-v1 path, where `YYYY-MM` is the current UTC month). The line is a
+standard audit-log-v1 object with `input_kind: "orchestration"` and an
+`orchestration` sub-object carrying this shape.
 
-**No hook or daemon required.** The agent writes the line directly —
-no-runtime-compatible capture path (decided 2026-06-30, maintainer decision; see
-`road-to-subagent-value-realization.md § Council notes`). Do NOT hand-author the
-JSON: run the recorder, which validates + builds a conformant line from the
-counts you already have:
+**No hook or daemon required.** The agent writes the line directly — the
+no-runtime-compatible capture path (decided 2026-06-30, maintainer decision;
+see `road-to-subagent-value-realization.md § Council notes`). Do NOT
+hand-author the JSON: run the recorder, which validates the inputs and builds a
+conformant audit-log-v1 line from the counts you already have:
 
 ```bash
 ./scripts-run src/scripts/orchestration_record --spawn-count <n> \
   --token-delta <±n> --provenance measured|estimated \
   [--tier-chosen lite|medium|high] [--tier-source static|inferred|inherit] \
-  [--task-class <id>] [--tiers a,b] [--dispatch-outcome DONE|BLOCKED|…]
+  [--task-class <id>] [--tiers a,b] [--dispatch-outcome DONE|BLOCKED|…] \
+  [--first-pass-success true|false] [--escalated true|false]
 ```
 
-A capture **hook** is the wrong tool: the PostToolUse payload carries no subagent
-token usage (only the orchestrator sees it) and a hook reverses the 2026-06-30
-no-hook decision. Reader: `src/scripts/orchestration_savings_report.ts`.
+A capture **hook** is the wrong tool here: the PostToolUse payload carries no
+subagent token usage — only the orchestrator sees it (via the run result) — and
+a hook would reverse the 2026-06-30 no-hook decision. Reader:
+`src/scripts/orchestration_savings_report.ts`.
 
 **`token_delta` sourcing priority:**
 1. Host-reported: read `usage.output_tokens` (and `usage.input_tokens` if
-   available) from each subagent call's response metadata. Use the sum minus the
-   estimated single-agent baseline. Set `token_delta_provenance: "measured"`.
-2. Self-estimate fallback: host usage metadata unavailable → estimate from
+   available) from the response metadata of each subagent call. Use the sum
+   minus the estimated single-agent baseline. Set `token_delta_provenance:
+   "measured"`.
+2. Self-estimate fallback: if host usage metadata is unavailable, estimate from
    response length (chars / 4 ≈ tokens). Set `token_delta_provenance:
-   "estimated"`. Lossy; measured always preferred.
+   "estimated"`. This estimate is lossy; measured is always preferred.
 
 ## Savings report
 
-Aggregate accumulated telemetry into a token-savings report:
+Aggregate the accumulated telemetry into a token-savings report:
 
 ```bash
 ./scripts-run src/scripts/orchestration_savings_report [--dir <path>] [--format text|json]
 ```
 
-Sums `token_delta` across dispatches (negative = net saved); splits by
-provenance (measured vs estimated), `tier_chosen`, `task_class`. Reports
-**ABSOLUTE net tokens saved, never a percentage**: telemetry records net delta,
-not the absolute in-session baseline → "% of session saved" not derivable. A
-percentage needs an additive absolute-baseline field (deferred follow-up).
-Reader: [`src/scripts/_lib/orchestration_savings.ts`](../../../../src/scripts/_lib/orchestration_savings.ts).
+It sums `token_delta` across dispatches (negative = net saved) and splits by
+provenance (measured vs estimated), `tier_chosen`, and `task_class`. **Quality
+and cost render as PAIRED columns** (council verdict — never savings alone):
+`first_pass_success_rate` and `escalation_rate` aggregate over the lines that
+carry the quality booleans (per the § Operationalization definitions above); with ≥ 20 such lines in the window the real rates
+render beside the savings figures, below 20 the quality columns render as
+`n/a (n=<count>)`. It reports
+**ABSOLUTE net tokens saved, never a percentage**: the telemetry records net
+delta, not the absolute in-session baseline, so a "% of session saved" is not
+derivable from this data. A percentage would require an additive
+absolute-baseline field on this object (deferred follow-up). Reader:
+[`src/scripts/_lib/orchestration_savings.ts`](../../../../src/scripts/_lib/orchestration_savings.ts).
 
 ## Related
 

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

@@ -242,6 +242,20 @@ For each open step in the working set (scope-bound — see wrapper):
    every scope (`process-step`, `process-phase`, `process-full`);
    cost is one `git diff` per step.
 
+   **`verify:` gate (when a step carries one).** If the step declares a
+   named `verify:` command (step-field convention, see
+   [`templates/roadmaps.md`](../../templates/roadmaps.md)), a `[x]` flip
+   additionally requires a **fresh green run of that exact command this
+   iteration** — its passing output in this reply or an earlier one this
+   run. Flipping a `verify:`-bearing step without that run is the same
+   class of violation as a forgotten flip: **halt loudly** ("step \<N\>
+   flipped without its `verify:` run — \`<cmd>\`"), do not auto-fix. A
+   check on existing output, not a new loop or script — the agent runs
+   the step's own command, as `think-before-action`'s `step → verify:`
+   planning already asks. Steps with no `verify:` field stay governed by
+   the flip-guard above unchanged (agent-decidable criteria remain the
+   default; `verify:` is the opt-in machine-checkable tightening).
+
 6. **Dashboard regen — cadence-gated.** Run
    `./agent-config roadmap:progress` when due per
    `roadmap.dashboard_regen_cadence` (resolved in § 4):

package/dist/agent-src/contexts/execution/roadmap-writing-source-derived.md

@@ -0,0 +1,65 @@
+# Roadmap Writing — source-derived & capability-adoption roadmaps
+
+Conditional procedure for [`roadmap-writing`](../../skills/roadmap-writing/SKILL.md)
+§ 8. Split out of the skill body to keep it under the size budget. This fires
+**only** for source-derived or capability-adoption roadmaps; an ordinary
+internally-originated roadmap skips it entirely (§§ 0–7 of the skill are the
+whole job). Pull this when the roadmap originates from an external input or
+adopts capabilities into the suite.
+
+## When this section fires
+
+This section fires **only** when the roadmap originates from an
+external input or adopts capabilities into the suite:
+
+- a competitive / capability harvest, an external suggestion, or an
+  external LLM ideation thread, **or**
+- a decision to integrate/adopt new skills, commands, or a pack, **or**
+- a plan whose design has genuinely contested, not-yet-resolved
+  trade-offs.
+
+For an ordinary internally-originated roadmap, **skip this section** —
+§§ 0–7 are the whole job. Do not bolt a Provenance block or a
+gap-table onto a plan that needs neither (template rule 19).
+
+## The four extra moves
+
+When it fires, add these four moves to the §§ 0–7 procedure:
+
+**A. Gap-table before drafting (don't adopt — integrate).** Audit each
+proposed item against the *existing* skill / command / rule surface and
+classify it `KEEP` (verified gap), `FOLD` (into a named existing
+artefact), or `CUT` (already covered). Only `KEEP` items become
+roadmap scope; `FOLD`/`CUT` are recorded so the cut is auditable. A
+negative grep is not proof — open the nearest existing artefacts (per
+[`think-before-action`](../../rules/think-before-action.md) and, for an
+external source, [`external-reference-deep-dive`](../../rules/external-reference-deep-dive.md)).
+
+**B. Resolve contested design in the council *first*, then author.**
+The default council flow (`/roadmap:ai-council`) *challenges a finished
+roadmap*. For a contested or source-derived plan, run the council
+**up front** on the design questions (`/council:design`, or the
+[`ai-council`](../../skills/ai-council/SKILL.md) skill), converge, **then** write
+the roadmap encoding the verdicts — so the plan ships already-decided,
+not as open questions in prose. One run, converge; do not relitigate.
+
+**C. Encode the decision so it survives.**
+- Inline council convergence under a `## Council notes (<date>, <depth>)`
+  block — members + date, **never** a session filepath
+  ([`no-roadmap-references`](../../rules/no-roadmap-references.md)).
+- Add a `## Provenance` block — source by a **neutral descriptor**
+  (never the raw competitor/tool name,
+  [`source-confidentiality`](../../rules/source-confidentiality.md));
+  retain the real link as an `ENC1:` token via
+  `src/scripts/_lib/link_crypto.ts encrypt --value <url>`.
+- Save the locked decision to memory (project type, "don't relitigate")
+  so a future session does not re-derive it.
+
+**D. Make "integration, not dump" a testable acceptance criterion.**
+The AC must encode the anti-dump litmus, decidably: visible commands
+within the pack's `size_class` budget; each new visible command reuses
+≥ 2 existing skills; no new artefact duplicates an existing one;
+governance preflight recorded — `domain-adoption-policy` (does it open a
+new domain?), `persona-governance` (new personas?),
+`framework-neutrality`, `size-enforcement` — with the disposition
+stated in the roadmap.

package/dist/agent-src/contexts/execution/subagent-modes-detail.md

@@ -0,0 +1,84 @@
+# Subagent Modes — worktree + live-app-judge detail
+
+Extended detail for the two heaviest [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md)
+modes — `do-in-worktrees` (mode 7) and `do-with-live-app-judge` (mode 8).
+Split out of the skill body to keep it under the size budget; the mode list,
+selection rules, and the six common modes stay inline in the skill. Pull this
+when you actually dispatch one of these two modes.
+
+## Mode 7 — do-in-worktrees
+
+Cross-wing or cross-skill chain executed across isolated git
+worktrees — each handoff in the chain runs in its own worktree, so
+the workspace state of one step never leaks into the next. Operationalizes
+the worktree boundary clause in
+[`docs/contracts/cross-wing-handoff.md`](../../../../docs/contracts/cross-wing-handoff.md)
+§ 3. State-machine layer only — worktree creation/destruction lives
+in [`using-git-worktrees`](../../skills/using-git-worktrees/SKILL.md) and
+[`finishing-a-development-branch`](../../skills/finishing-a-development-branch/SKILL.md).
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Multi-step cross-wing chain (≥2 senior skills, each ≥30 min) where one step's open files / branch state would confuse the next | Fast iteration where each step < 30 min — worktree overhead exceeds isolation benefit | implementers = same tier per step; judge = one tier up at chain end |
+
+**Handoff shape:** initiator-skill emits the typed output declared in
+its `## Output` block → control passes to delegated-skill in a fresh
+worktree → delegated-skill consumes the input shape declared in its
+`## Input` (or `## When the agent should load this`) block. The
+handoff is auditable; `lint_handoffs.ts` validates the chain.
+
+**Example chain (W3 launch):** `positioning-strategy` (worktree A) →
+`messaging-architecture` (worktree B, consumes positioning's
+`positioning-statement.md`) → `gtm-launch` (worktree C, consumes
+both prior artifacts). Each worktree carries one branch; the chain
+end produces a single integration PR.
+
+**Anti-pattern:** do not use for fast iteration loops where each
+step is under ~30 minutes. The branch-creation, context-switch, and
+worktree-cleanup cost dominates. Stick with mode 1 (do-and-judge)
+or mode 3 (do-in-steps) for those.
+
+**Competitive variant — per-candidate isolation.** When mode 5
+(`do-competitively`) is combined with worktrees, each candidate
+implementer runs in its own worktree (so candidates cannot read each
+other's open files or branch state). Selection rules:
+
+- **No auto-merge.** The orchestrator never merges a candidate
+  branch. Hard Floor per [`non-destructive-by-default`](../../rules/non-destructive-by-default.md) —
+  applies even under standing autonomy. ADR-005 records the reasoning.
+- **Ranked presentation.** Judge ranks candidates (1..N) with a
+  one-line justification per rank; user picks the winner.
+- **Loser worktrees stay.** The orchestrator does not delete losing
+  worktrees automatically — the user keeps the option to harvest a
+  partial idea before cleanup.
+
+## Mode 8 — do-with-live-app-judge (gated — UI-heavy tasks)
+
+Implementer ships the change AND starts the dev server; the judge drives
+the RUNNING application (Playwright / browser) against a written rubric —
+it never reads the diff. Catches the class static review misses: wired-but-
+broken flows, dead buttons, state that renders wrong only at runtime.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| UI-heavy change where "looks right in the diff" ≠ "works in the app"; a dev server + browser tooling exist | Backend/logic change (a diff judge is cheaper and sharper); no runnable app surface | implementer = session; judge = same tier, fresh context, browser tools only |
+
+Rules:
+
+- The judge's rubric is written BEFORE dispatch (what flows to click, what
+  must render) — never improvised from the diff it must not read.
+- Record `dispatch_mode: do-with-live-app-judge` + `verdict_changed_outcome`
+  on every use. **Adoption gate:** this mode stays experimental until its
+  `verdict_changed_outcome` telemetry shows it changes outcomes (caught a
+  real issue a diff judge missed); a mode that never flips a verdict is
+  cost without value and gets removed.
+- No self-play/"adversarial training" framing — this is one judge, one
+  rubric, one running app.
+- **Low-priority future candidate (needs real screenshot tooling — do not
+  build speculatively):** the async silent-verifier shape from
+  [`design-review`](../../skills/design-review/SKILL.md) § Async-verifier pattern — a
+  background verifier that owns UI verification via screenshots, forbids the
+  main agent from self-checking, and stays silent on pass — is the natural
+  mechanism for this mode's judge once dependable screenshot tooling lands.
+  Recorded from road-to-opt-design-polish; gate it behind the same
+  `verdict_changed_outcome` adoption evidence above.