@event4u/agent-config 8.10.0 → 8.12.0

package/dist/agent-src/contexts/execution/roadmap-ci-steps-mechanics.md

@@ -0,0 +1,117 @@
+# Roadmap CI-Steps — Mechanics
+
+Migrated body of the [`roadmap-ci-steps-policy`](../../rules/roadmap-ci-steps-policy.md)
+rule (per P4 of `road-to-kernel-and-router.md`). Loaded by
+[`roadmap-process-loop § 5` step 0](roadmap-process-loop.md#5-step-loop) and by
+the rule's routing line. The Iron Law stays in the rule; this file carries the
+pattern table, carve-outs, linter contract, inline-skip mechanics, and failure
+modes.
+
+## Forbidden step patterns (authoring + execution)
+
+A step is **CI-shaped** when its text matches any of the patterns
+below. Case-insensitive. Pattern matching is line-bounded — the
+literal must appear inside the step's `- [ ]` line or its immediate
+inline note (the next indented `<!-- … -->` or `(…)` annotation).
+
+| Pattern | Example |
+|---|---|
+| `task ci` | `Run task ci before the boundary` |
+| `task ci-strict` | `task ci-strict release gate` |
+| `task ci-fast` | `task ci-fast smoke` |
+| `make test` | `Run make test on phase boundary` |
+| `make ci` | `make ci pre-merge` |
+| `npm run check` / `pnpm run check` / `yarn check` | `npm run check before commit` |
+| `composer test` | `composer test on every phase` |
+| `vendor/bin/phpunit` (whole-suite, no path arg) | `vendor/bin/phpunit` |
+| `php artisan test` (no `--filter`) | `php artisan test` |
+
+Targeted commands (`vendor/bin/phpstan analyse <module-path>` such as
+`vendor/bin/phpstan analyse app/Modules/X` in Laravel,
+`php artisan test --filter=…`, `npm run lint -- --fix path/`) are
+**not** CI-shaped — they are narrow verifications, allowed regardless
+of the setting.
+
+## Carve-outs — when CI-shaped steps are still allowed
+
+1. **New CI gate / smoke test / test file landed by this roadmap.**
+   Once-locally execution is mandatory under
+   [`verify-before-complete`](../../rules/verify-before-complete.md) carve-out
+   (see `templates/agent-settings.md` § `quality.local_auto_run`).
+   Mark the step with `<!-- carve-out: new-gate-verification -->`
+   on the same line; the linter and the execution loop both honour
+   the marker and let the step run.
+2. **`quality.local_auto_run: true`.** Setting opt-in restores the
+   pre-policy behaviour — the linter no-ops and the execution loop
+   runs CI steps unmodified.
+3. **Acceptance-criteria block at end of roadmap.** Final-gate prose
+   like "All quality gates pass (`task ci`)" inside an
+   `## Acceptance criteria` section is documentation, not an
+   executable step (no `- [ ]` checkbox in front of the literal).
+   Linter ignores; execution loop never reaches it as a step.
+
+## Authoring — linter blocks at write-time
+
+`task lint-roadmap-ci-steps` (wired into `task ci-fast` /
+`lint-roadmap-complexity` cadence) scans `agents/roadmaps/*.md` and
+per-module roadmap dirs resolved via
+`scripts/_lib/agent_settings.ts::enumerate_modules()`
+(`{module_path}/{modules.agent_folder}/roadmaps/*.md`; Laravel shape:
+`app/Modules/*/agents/roadmaps/*.md`). Exit code:
+
+- `0` — no CI-shaped steps, or setting is `true`, or every match is
+  carve-out-marked.
+- `1` — at least one CI-shaped step in an active (non-archived,
+  non-skipped) roadmap with `quality.local_auto_run: false` and no
+  carve-out marker. Linter prints the file, line, matched literal,
+  and suggested rewording.
+
+Archive (`agents/roadmaps/archive/`) and skipped
+(`agents/roadmaps/skipped/`) are out of scope — they record history,
+not future work.
+
+## Execution — process-loop skips inline
+
+Wrappers `/roadmap:process-step|phase|full` honour the policy at the
+top of [`roadmap-process-loop § 5`](roadmap-process-loop.md#5-step-loop):
+
+1. Before running a step, match its text against the patterns above.
+2. If CI-shaped **and** `quality.local_auto_run: false` **and** no
+   carve-out marker → flip the checkbox to `[-]` (cancelled), append
+   a one-line reason as inline note, regenerate the dashboard,
+   continue to the next step. **Never** run the gate.
+3. If CI-shaped **and** `quality.local_auto_run: true` → run the
+   step normally.
+4. If carve-out-marked → run the step regardless of the setting.
+
+The `[-]` reason format is fixed:
+`<!-- skipped: quality.local_auto_run=false → remote CI is the gate -->`.
+Per [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md) the flip and
+the dashboard regen happen in the **same reply** that decides to
+skip; saving skips for the archive commit is a rule violation.
+
+## Failure modes
+
+- Authoring `- [ ] Run task ci` while `local_auto_run: false` — linter
+  fails the PR.
+- Executing a CI-shaped step without the inline-skip flip — Iron Law
+  violation; the loop never reaches the gate.
+- Adding a carve-out marker to bypass the gate for an *existing*
+  pipeline run — abuse; the marker is reserved for **new** gates
+  introduced by the same roadmap.
+- Hiding the literal inside a fenced bash block to dodge the linter —
+  the linter matches inside fenced blocks too (see
+  `scripts/lint_roadmap_ci_steps.ts`).
+
+## See also
+
+- [`roadmap-ci-steps-policy`](../../rules/roadmap-ci-steps-policy.md) — the
+  Iron Law + trigger surface this file backs.
+- [`verify-before-complete`](../../rules/verify-before-complete.md) — the
+  Iron Law the policy narrows; carve-out cites it.
+- [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md) — inline flip
+  + dashboard regen contract.
+- `templates/agent-settings.md` § `quality.local_auto_run` — source
+  of the toggle and its carve-out wording.
+- [`roadmap-process-loop`](roadmap-process-loop.md) — § 5 owns the
+  inline-skip step gate.

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

@@ -30,22 +30,23 @@ roadmaps with open work that is blocked-for-later — parked, not active).
 
 ### Live merge-state before any "in-flight / merged / handled" claim
 
-Selection reasoning that **excludes** a roadmap — or a pre-run summary,
-decision, or user-facing message that **describes** one — as *in-flight*,
-*handled by an open PR*, *already merged*, or *not yet merged* → verify **live
-at claim time** (`gh pr view <n> --json state,mergedAt` / `gh pr list --search
-"<slug>"`). Never infer merge state from:
-
-- **dashboard open-count** — lags: a completed roadmap archives in the
-  **merging** PR, so it can read "open" on `main` while its PR is already
-  merged, or read "open" seconds before a merge you never re-checked;
-- **session memory** ("opened a PR for this earlier") or an **earlier fetch** —
-  a merge can land between fetch and message.
-
-Stale merge-state claim ships an unnecessary message about work already done —
-the failure this prevents. The [`direct-answers`](../../rules/direct-answers.md)
-Iron-Law-2 live-state rule (git/PR state never from memory), applied to
-roadmap selection.
+When selection reasoning would **exclude** a roadmap — or a pre-run summary,
+decision, or any user-facing message would **describe** one — as *in-flight*,
+*handled by an open PR*, *already merged*, or *not yet merged*, verify that
+claim **live at the moment of the claim** (`gh pr view <n> --json state,mergedAt`
+or `gh pr list --search "<slug>"`). Never infer merge state from:
+
+- the **dashboard's open-count** — it lags: a completed roadmap is archived in
+  the **merging** PR, so a roadmap can still read "open" on `main` while its PR
+  is already merged (archive not yet on your checkout), or read "open" seconds
+  before a merge you never re-checked;
+- **session memory** ("I opened a PR for this earlier") or an **earlier fetch** —
+  a merge can land between your fetch and your message.
+
+A stale merge-state claim ships an unnecessary user-facing message about work
+that is already done — the exact failure this clause prevents. This is the
+[`direct-answers`](../../rules/direct-answers.md) Iron-Law-2 live-state rule
+(git/PR state never from memory), applied to roadmap selection.
 
 ## 2. Pre-run summary — gate or inline note
 
@@ -90,7 +91,7 @@ does not fire.
 
 ## 3. Pre-scan — execution contract or commit-step ask
 
-Read `execution.mode` from roadmap's frontmatter
+Read `execution.mode` from the roadmap's frontmatter
 (`autonomous` | `phase-checkpoints` | `interactive`; absent =
 `interactive`).
 
@@ -101,17 +102,17 @@ its four-class pre-scan over every open step:
 1. commit-shaped steps (patterns below),
 2. git-shape needs (branch / push / PR / delivery),
 3. artifact-authoring steps (new or materially rewritten skill / rule /
-   command / guideline — feeds batched drafting-protocol research
+   command / guideline — feeds the batched drafting-protocol research
    pass, run at contract time against current artifact state),
 4. open questions / ambiguity markers (incl. `ask-when-uncertain`
    vague-trigger patterns).
 
-Surface contract summary; user's single **Accept** activates all run
-grants (branch, chunked commits, push to run's own feature branch
-only, PR-open, batched artifact drafting, council auto-enable) —
-cached for run, never re-asked. Contract never lifts a Hard Floor or
-any safety floor; boundaries + per-mode gate table live in contract
-context.
+Surface the contract summary; the user's single **Accept** activates
+all run grants (branch, chunked commits, push to the run's own feature
+branch only, PR-open, batched artifact drafting, council auto-enable) —
+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`.
@@ -135,11 +136,11 @@ Read both keys from `.agent-settings.yml` once and cache for the whole
 run. Do **not** re-read inside the step loop.
 
 **`roadmap.quality_cadence`** — when to run the quality pipeline.
-Only relevant when `quality.local_auto_run` is `true`; `false` or
-missing (default) → local pipeline runs suppressed at EVERY cadence —
-remote CI is the gate, run-end report states *"quality gates delegated
-to remote CI"* instead of a pass claim (new-gate carve-out steps still
-run once).
+Only relevant when `quality.local_auto_run` is `true`; when it is
+`false` or missing (the default), local pipeline runs are suppressed at
+EVERY cadence — remote CI is the gate, and the run-end report states
+*"quality gates delegated to remote CI"* instead of a pass claim
+(new-gate carve-out steps still run once).
 
 | Value | Pipeline runs (`local_auto_run: true` only) |
 |---|---|
@@ -183,7 +184,8 @@ For each open step in the working set (scope-bound — see wrapper):
    on the same line, regenerate the dashboard, continue to the next
    step. Never run the gate. Carve-out marker present → run normally
    (new gate must be verified once locally). Setting `true` → run
-   normally.
+   normally. Full pattern table, carve-outs, linter contract, failure
+   modes: [`roadmap-ci-steps-mechanics`](roadmap-ci-steps-mechanics.md).
 1. **Bundled read — one parallel tool-call block.** The step
    description, the immediately-relevant code files, and any
    guideline/context the step cites are **independent** reads and
@@ -201,17 +203,18 @@ For each open step in the working set (scope-bound — see wrapper):
 2. Analyze the codebase for what the step requires.
 3. Decide and act — implement. **No "should I implement this?" prompt.**
 4. **Open question handling:**
-   - **Council on** (toggled manually, or auto-enabled for run by
-     accepted execution contract — § 3) → invoke per
+   - **Council on** (toggled manually, or auto-enabled for the run by
+     an accepted execution contract — § 3) → invoke per
      [`ai-council`](../../skills/ai-council/SKILL.md), integrate
-     convergence, proceed. Token spend was opted in (contract summary
-     named members). `high_impact` / `user_required` classifications
-     still escalate to user per
+     convergence, proceed. Token spend was opted in (the contract
+     summary named the members). `high_impact` / `user_required`
+     classifications still escalate to the user per
      [`ask-when-uncertain`](../../rules/ask-when-uncertain.md).
    - **Council off / not configured** → halt, surface once, wait.
-     Resume on next turn. Execution contract cannot enable a council
-     with no configured members — contract summary says so upfront,
-     and in-run ambiguity halts (never silent guessing).
+     Resume on next turn. An execution contract cannot enable a
+     council that has no configured members — the contract summary
+     says so upfront, and in-run ambiguity halts (never silent
+     guessing).
 5. **Atomic flip — same reply, every step.**
    Flip the checkbox in `agents/roadmaps/<file>.md`: `[x]` done ·
    `[~]` partial · `[-]` skipped. **Non-skippable, non-batchable**
@@ -228,19 +231,36 @@ For each open step in the working set (scope-bound — see wrapper):
    git status --porcelain -- agents/roadmaps/<file>.md
    ```
 
-   (`git status --porcelain`, not `git diff` — roadmap file still
-   **untracked** (e.g. fresh worktree) is invisible to `git diff`,
-   would false-halt; `--porcelain` reports both `M` and `??`.)
+   (`git status --porcelain`, not `git diff` — a roadmap file that is
+   still **untracked**, e.g. in a fresh worktree, is invisible to
+   `git diff` and would false-halt; `--porcelain` reports both `M`
+   and `??`.)
 
    Empty output → Iron Law 2 was violated this iteration: the step
    landed work but no checkbox flipped. **Halt loudly**, surface
    "step <N> landed without checkbox flip — flip then resume", and
    stop the run. Do not auto-fix; the user resumes on the next turn.
 
-   Deterministic counterpart to the rule's pre-send self-check —
-   catches a forgotten flip per step, not only at run end. Runs in
-   every scope (`process-step`, `process-phase`, `process-full`);
-   cost is one `git diff` per step.
+   This guard is the deterministic counterpart to the rule's
+   pre-send self-check — it catches a forgotten flip per step, not
+   only at run end. It runs in every scope (`process-step`,
+   `process-phase`, `process-full`); the cost is one `git diff` per
+   step.
+
+   **`verify:` gate (when a step carries one).** If the step declares a
+   named `verify:` command (roadmap 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 present in this reply or an earlier
+   one this run. Flipping a `verify:`-bearing step to `[x]` without that
+   fresh green 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. This is a check on existing output, not a
+   new loop or a new script — the agent runs the step's own command, the
+   same way `think-before-action`'s `step → verify:` planning already
+   asks. Steps with no `verify:` field are governed by the flip-guard
+   above unchanged (agent-decidable exit/acceptance 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
@@ -265,36 +285,38 @@ For each open step in the working set (scope-bound — see wrapper):
 - Test failure or quality red on `per_step`
 - Council off + true ambiguity — under an **accepted execution
   contract** ([§ 3](#3-pre-scan--execution-contract-or-commit-step-ask))
-  this halt exists only when no council is configured: contract
-  auto-enables council for run, so in-run open questions resolve
+  this halt exists only when no council is configured: the contract
+  auto-enables council for the run, so in-run open questions resolve
   silently (`high_impact` / `user_required` classifications still
   escalate per [`ask-when-uncertain`](../../rules/ask-when-uncertain.md));
   with no council configured, true ambiguity halts — never silent
   guessing.
 
-An accepted execution contract **never lifts a Hard Floor** or any
-other halt above — it removes redundant *asks* (git shape, artifact
-drafting, council enablement), not safety.
+An accepted execution contract **never lifts a Hard Floor** or any of
+the other halts above — it removes redundant *asks* (git shape,
+artifact drafting, council enablement), not safety.
 
 On halt: stop, surface state, do **not** auto-fix outside the failing step.
 
 ### Forbidden non-halt reasons — agent-invented cautions
 
-Halt list above is exhaustive. Never stop a `process-full` (or any wrapper) run
-for an invented reason not on it. NOT halt conditions — stopping for them
-violates the command + user's will:
+The halt list above is **exhaustive**. An agent running `process-full` (or any
+wrapper) must **never** stop the run for a reason it invented that is not on
+that list. In particular these are NOT halt conditions and stopping for them is
+a violation of the command and the user's will:
 
-- "low context / token budget" — keep landing complete steps until context
-  actually runs out; never announce a boundary-stop by choice.
-- "quality would degrade / deserves a fresh focused run later"
-- "avoid a PR pile-up" / "let open PRs merge first"
-- "this phase is large / deep subsystem"
-- "phase-checkpoints, so I'll checkpoint and wait" — under `process-full` a
-  phase boundary emits a non-blocking status line and the run continues; the
-  stop-and-wait reading applies only to `process-phase`.
+- "running low on context / token budget" — keep landing complete steps until
+  context actually runs out; never announce a boundary-stop by choice.
+- "quality would degrade / this deserves a fresh focused run later"
+- "avoid a PR pile-up" / "let the open PRs merge first"
+- "this phase is large / touches a deep subsystem"
+- "phase-checkpoints mode, so I'll checkpoint and wait" — under `process-full`
+  a phase boundary emits a non-blocking status line and the run **continues**;
+  the stop-and-wait reading of `phase-checkpoints` applies only to
+  `process-phase`.
 
-Genuine inability to continue = one of the five real halt conditions fired —
-surface THAT, not a manufactured caution.
+If the work genuinely cannot continue, it will be because one of the five real
+halt conditions fired — surface THAT, not a manufactured caution.
 
 ### Non-halt — gating notes, "optional" tags
 
@@ -324,47 +346,51 @@ execution either way.
 - **End state under an accepted execution contract** (per-mode table:
   [`roadmap-execution-contract § 4`](roadmap-execution-contract.md)):
   all steps `[x]` · quality green per cadence · work committed in
-  chunks on run's feature branch · pushed to that branch · ONE PR
-  open (description-only flow) · archival sweep run. **Merge is out
-  of scope in every mode — always conversational.** Without a
-  contract (interactive mode), the run ends after the archival check
-  with no git delivery beyond explicitly authorized commit steps.
+  chunks on the run's feature branch · pushed to that branch · ONE PR
+  open (description-only flow) · archival sweep run. **Merge is out of
+  scope in every mode — always conversational.** Without a contract
+  (interactive mode), the run ends after the archival check with no
+  git delivery beyond explicitly authorized commit steps.
 - **If the entire roadmap reached `count_open == 0`** → run the full
   project quality pipeline. On red → stop, surface failures, do **not**
-  archive. On green → run **deferred-resolution gate** below before
+  archive. On green → run the **deferred-resolution gate** below before
   archival.
 
 ### 6a. Deferred-resolution gate — Iron Law 3
 
-Before any `git mv` to `archive/`, count `[~]` items in closing
-roadmap. If `count_deferred > 0`, archival **blocked** per
+Before any `git mv` to `archive/`, count `[~]` items in the closing
+roadmap. If `count_deferred > 0`, archival is **blocked** per
 [`roadmap-progress-sync § Iron Law 3`](../../rules/roadmap-progress-sync.md).
-Loop MUST:
+The loop MUST:
 
 1. Enumerate every `[~]` step (phase + text + optional
    `<!-- deferred: ... -->` annotation).
-2. Surface numbered-options block from
+2. Surface the numbered-options block from
    [`roadmap-management § 4b`](../../skills/roadmap-management/SKILL.md) —
    five choices: follow-up (draft), follow-up (ready + blocked),
    keep-in-archive (intentional drop), restore to `[ ]`, convert
    to `[-]` cancelled.
-3. Wait for user. Autonomous mandate (`/work`,
+3. Wait for the user. The autonomous mandate (`/work`,
    `/roadmap:process-full`, "decide for me") does **not** lift this
    gate — Iron Law 3 calls it "the canonical lost-information failure
    mode this rule exists to prevent."
-4. On picks 1 / 2 → run "Spawn follow-up from deferred items"
+4. On picks 1 / 2 → run the "Spawn follow-up from deferred items"
    procedure in [`roadmap-management`](../../skills/roadmap-management/SKILL.md).
-   On picks 3 / 4 / 5 → apply change, re-evaluate decision table,
-   archive when gate clears.
-
-`count_deferred == 0` → archive. **Primary:** `archive_completed_roadmaps --all`
-— untracked-safe (`git mv`, or plain `mv` in a pre-first-commit / untracked
-consumer), rewrites inbound refs (index when tracked, filesystem when not),
-regens dashboard; PR-independent (gap B). **Fallback (script not vendored):**
-emit a one-line vendor instruction (`agents:init`), then the manual procedure in
+   On picks 3 / 4 / 5 → apply the change, re-evaluate the decision
+   table, archive when the gate clears.
+
+`count_deferred == 0` → archive. **Primary path:** run the
+`archive_completed_roadmaps --all` sweep — it is untracked-safe (`git mv`,
+or a plain `mv` in a pre-first-commit / untracked consumer), rewrites inbound
+refs (on the index when tracked, on the filesystem when not), and regenerates
+the dashboard. This entry point is **PR-independent** (gap B): it does not need
+`/create-pr` to have run. **Fallback only when that script is not vendored** in
+the consumer: emit a one-line instruction to vendor it (run `agents:init`),
+then apply the manual procedure in
 [`roadmap-management`](../../skills/roadmap-management/SKILL.md) (mkdir
-`archive/`, `mv`, ref-rewrite, regen). NEVER silently `git mv` (fails on
-untracked, leaves a completed roadmap rotting).
+`archive/`, `mv`, inbound-ref rewrite, dashboard regen). NEVER silently
+delegate to a bare `git mv` that fails on untracked files and leaves a
+completed roadmap rotting in the active tree.
 
 ## Scope deltas — what each wrapper binds
 

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.