@event4u/agent-config 8.11.0 → 8.13.0

package/dist/agent-src/commands/team/adversarial.md

@@ -0,0 +1,96 @@
+---
+model_tier: inherit
+name: team-adversarial
+disable-model-invocation: true
+pack: product-reasoning
+tier: 2
+visibility: internal
+skills: [adversarial-review]
+description: Thin wrapper — adversarial cross-model review on a named focus via the official plugin (/codex:adversarial-review). Escalation rung above the single-model adversarial-review skill.
+cluster: team
+sub: adversarial
+suggestion:
+  eligible: true
+  trigger_description: "adversarial cross-model review, attack this change with a second model, stress-test the diff with GPT, hostile review by another model"
+  trigger_context: "ai_team.enabled is true AND single-model self-review found nothing or the stakes are high — escalate the Attack-Defend-Revise frame to a second strong model"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - product-reasoning
+---
+
+# /team adversarial
+
+## Instructions
+
+Thin wrapper: adversarial cross-model review on a named focus. Same
+Attack-Defend-Revise frame as the `adversarial-review` skill, different
+attacker — a second strong model with repo access instead of the host model
+critiquing itself. Use it as the **escalation rung**: single-model
+self-review found nothing, or the stakes are high.
+
+### 1. Gate — `ai_team.enabled`
+
+Read `ai_team.enabled` from `.agent-settings.yml`. Missing or `false` →
+print the enable pointer from `/team` (master) § "Default-off gate" and
+**STOP**.
+
+### 2. Gate — plugin presence (fail closed)
+
+On a Claude Code host, verify the official plugin is installed. Absent →
+print the fail-closed block from `/team` (master) § "Fail-closed contract"
+(`agent-config doctor --check team`) and **STOP**. Never reimplement the
+adversarial review inline; never silently no-op.
+
+On a non-Claude-Code host: state that the cross-model adversarial path
+currently requires the Claude Code plugin, offer the single-model
+`adversarial-review` skill as the available rung, and stop.
+
+### 3. Resolve the focus
+
+The user invoked `/team adversarial <focus>` — e.g. `security`,
+`error handling`, `the tenant-scope change in UserService`. If no focus was
+supplied, ask (one question per turn, per `ask-when-uncertain`):
+
+> What should the adversarial review attack?
+>
+> 1. A named surface (e.g. security, error handling, concurrency)
+> 2. A specific file / change (name it)
+> 3. Cancel
+
+### 4. Delegate
+
+Invoke the plugin with the focus passed through unchanged:
+
+- `/team adversarial <focus>` → `/codex:adversarial-review <focus>`
+
+### 5. Return the findings verbatim
+
+Render the plugin's findings unchanged — do not soften, dedupe, or re-rank.
+The call counts into the `cli_call_budget.max_calls_per_day.openai` quota;
+on quota exhaustion surface the transport's refusal, do not retry.
+
+## Output format
+
+- The plugin's adversarial findings, verbatim.
+- Gate failures print exactly one block (enable pointer or fail-closed
+  block) and stop.
+
+## Do NOT
+
+- Do NOT run when `ai_team.enabled` is false — enable pointer, stop.
+- Do NOT reimplement the adversarial pass inline when the plugin is absent —
+  fail closed with the doctor pointer.
+- Do NOT skip the free first rung reflexively — the single-model
+  `adversarial-review` skill costs nothing; escalate when it finds nothing
+  or the stakes justify a second model.
+- Do NOT edit files, commit, push, or open a PR — read-only.
+- Do NOT claim a defect-finding lift; the benchmark verdict is pending (see
+  `/team` master § "No-claims note").
+
+## See also
+
+- `adversarial-review` skill — the single-model Attack-Defend-Revise frame
+  this escalates.
+- `/team review` — the non-adversarial cross-model review.
+- `/team` — master orchestrator: gates, boundary table vs `/council`.

package/dist/agent-src/commands/team/delegate.md

@@ -0,0 +1,109 @@
+---
+model_tier: inherit
+name: team-delegate
+disable-model-invocation: true
+pack: product-reasoning
+tier: 2
+visibility: internal
+description: Thin wrapper — hand a task to the second model as a native worker via the official plugin (/codex:rescue). The only write-access wrapper; double-gated behind ai_team.allow_delegate.
+cluster: team
+sub: delegate
+suggestion:
+  eligible: false
+  rationale: "Only write-access wrapper in the family; delegation of write access must be explicitly typed by the user, never suggested."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - product-reasoning
+---
+
+# /team delegate
+
+## Instructions
+
+Thin wrapper: hand a task to the second model as a **native worker** in the
+repo. On Claude Code hosts it delegates to the official plugin's
+`/codex:rescue`. This is the **only wrapper that delegates write access**,
+so it carries a second opt-in on top of the family gate.
+
+### 1. Gate — `ai_team.enabled`
+
+Read `ai_team.enabled` from `.agent-settings.yml`. Missing or `false` →
+print the enable pointer from `/team` (master) § "Default-off gate" and
+**STOP**.
+
+### 2. Gate — `ai_team.allow_delegate` (second opt-in)
+
+Read `ai_team.allow_delegate`. Missing or `false` (the shipped default) →
+refuse with the enable pointer and **STOP**:
+
+> `/team delegate` is disabled (`ai_team.allow_delegate: false`, the
+> default). It is the only team-mode wrapper that hands **write access** to
+> the second model, so it needs its own opt-in:
+>
+> ```yaml
+> ai_team:
+>   enabled: true
+>   allow_delegate: true
+> ```
+>
+> Key reference: `docs/contracts/ai-team-config.md`.
+
+### 3. Gate — plugin presence (fail closed)
+
+On a Claude Code host, verify the official plugin is installed. Absent →
+print the fail-closed block from `/team` (master) § "Fail-closed contract"
+(`agent-config doctor --check team`) and **STOP**. Never reimplement the
+worker inline; never silently no-op.
+
+On a non-Claude-Code host: there is **no** delegate fallback — the
+worker-via-bundle path is deferred by a recorded internal null. State that
+delegation requires the Claude Code plugin and stop.
+
+### 4. Resolve the task
+
+The user invoked `/team delegate <task>`. If the task text is missing, ask
+(one question per turn, per `ask-when-uncertain`) for a one-line task
+description; do not invent scope.
+
+### 5. Delegate
+
+Invoke the plugin with the task passed through unchanged:
+
+- `/team delegate <task>` → `/codex:rescue <task>`
+
+The Codex worker runs natively in the working tree under the user's
+subscription. The call counts into the
+`cli_call_budget.max_calls_per_day.openai` quota; on exhaustion surface the
+transport's refusal, do not retry.
+
+### 6. Return the result verbatim
+
+Render the plugin's result unchanged. Any edits the worker made are in the
+working tree for the user to review — this wrapper never commits, pushes, or
+opens a PR on top of them.
+
+## Output format
+
+- The plugin's rescue/delegation result, verbatim.
+- Gate failures print exactly one block (enable pointer, allow_delegate
+  refusal, or fail-closed block) and stop.
+
+## Do NOT
+
+- Do NOT run when `ai_team.enabled` is false — enable pointer, stop.
+- Do NOT run when `ai_team.allow_delegate` is false — refusal block, stop.
+  Never treat `enabled: true` alone as delegate authorization.
+- Do NOT reimplement the worker inline when the plugin is absent — fail
+  closed with the doctor pointer.
+- Do NOT commit, push, or open a PR over the worker's edits — review is the
+  user's call.
+- Do NOT claim a productivity or quality lift; the benchmark verdict is
+  pending (see `/team` master § "No-claims note").
+
+## See also
+
+- `/team` — master orchestrator: gates, boundary table vs `/council`.
+- `/team review` — the read-only default lens; prefer it unless the user
+  explicitly wants the second model to do the work.
+- `docs/contracts/ai-team-config.md` — `ai_team.allow_delegate` semantics.

package/dist/agent-src/commands/team/review.md

@@ -0,0 +1,84 @@
+---
+model_tier: inherit
+name: team-review
+disable-model-invocation: true
+pack: product-reasoning
+tier: 2
+visibility: internal
+description: Thin wrapper — cross-model review of the current diff via the official plugin (/codex:review). Gated on ai_team.enabled; fails closed when the plugin is absent.
+cluster: team
+sub: review
+suggestion:
+  eligible: true
+  trigger_description: "team review, second model review, cross-model review of my changes, GPT drüberschauen lassen, review the diff with another strong model"
+  trigger_context: "ai_team.enabled is true AND there is an uncommitted / staged diff the user wants a second strong model to review with repo access"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - product-reasoning
+---
+
+# /team review
+
+## Instructions
+
+Thin wrapper: cross-model review of the current change. On Claude Code hosts
+it delegates verbatim to the official plugin's `/codex:review` — this wrapper
+owns only the governance gates around it.
+
+### 1. Gate — `ai_team.enabled`
+
+Read `ai_team.enabled` from `.agent-settings.yml`. Missing or `false` →
+print the enable pointer from `/team` (master) § "Default-off gate" and
+**STOP**. No plugin probe, no partial run.
+
+### 2. Gate — plugin presence (fail closed)
+
+On a Claude Code host, verify the official plugin is installed (its
+`/codex:*` commands are available). Absent → print the fail-closed block
+from `/team` (master) § "Fail-closed contract" — the remediation path is
+`agent-config doctor --check team` — and **STOP**. Never reimplement the
+review inline; never silently no-op.
+
+On a non-Claude-Code host: the repo-diff-bundle fallback is a later phase.
+State that team review currently requires the Claude Code plugin, point to
+`agent-config doctor --check team`, and stop.
+
+### 3. Delegate
+
+Invoke the plugin:
+
+- `/team review` → `/codex:review`
+- `/team review --background` → `/codex:review --background`
+
+Pass the flag through unchanged. Scope resolution (what counts as "the
+diff") is the plugin's job — do not pre-compute or filter the diff here.
+
+### 4. Return the review verbatim
+
+Render the plugin's review output unchanged. Do not summarize, re-rank, or
+soften findings. The call counts into the
+`cli_call_budget.max_calls_per_day.openai` quota (one subscription, one
+counter); if the quota is exhausted the transport refuses — surface that
+refusal, do not retry.
+
+## Output format
+
+- The plugin's review, verbatim.
+- Nothing else on success; gate failures print exactly one block (enable
+  pointer or fail-closed block) and stop.
+
+## Do NOT
+
+- Do NOT run when `ai_team.enabled` is false — enable pointer, stop.
+- Do NOT reimplement the review inline when the plugin is absent — fail
+  closed with the doctor pointer.
+- Do NOT edit files, commit, push, or open a PR — this wrapper is read-only.
+- Do NOT claim a review-quality lift; the benchmark verdict is pending (see
+  `/team` master § "No-claims note").
+
+## See also
+
+- `/team` — master orchestrator: gates, boundary table vs `/council`.
+- `/team adversarial` — focused adversarial variant.
+- `adversarial-review` skill — single-model self-review, the free first rung.

package/dist/agent-src/commands/team/status.md

@@ -0,0 +1,92 @@
+---
+model_tier: inherit
+name: team-status
+disable-model-invocation: true
+pack: product-reasoning
+tier: 2
+visibility: internal
+description: Thin wrapper — plugin job status via /codex:status plus a ledger line with today's cli_call_budget openai count. Gated on ai_team.enabled; fails closed when the plugin is absent.
+cluster: team
+sub: status
+suggestion:
+  eligible: false
+  rationale: "Read-only state query; users invoke it explicitly when they want job or quota status — suggesting it adds noise."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - product-reasoning
+---
+
+# /team status
+
+## Instructions
+
+Thin wrapper: team-mode status. On Claude Code hosts it delegates to the
+official plugin's `/codex:status` and appends **our** quota ledger line —
+the one piece of state the plugin does not know about.
+
+### 1. Gate — `ai_team.enabled`
+
+Read `ai_team.enabled` from `.agent-settings.yml`. Missing or `false` →
+print the enable pointer from `/team` (master) § "Default-off gate" and
+**STOP**.
+
+### 2. Gate — plugin presence (fail closed)
+
+On a Claude Code host, verify the official plugin is installed. Absent →
+print the fail-closed block from `/team` (master) § "Fail-closed contract"
+(`agent-config doctor --check team`) and **STOP** — never a silent no-op.
+
+On a non-Claude-Code host: state that plugin job status requires the Claude
+Code plugin, then still print the ledger line (Step 4) — the quota counter
+is ours and host-independent.
+
+### 3. Delegate
+
+Invoke the plugin:
+
+- `/team status` → `/codex:status`
+
+Render its job/status output verbatim.
+
+### 4. Append the quota ledger line
+
+Read today's openai CLI-call count from the shared counter state at
+`~/.event4u/agent-config/cli-calls.json` (daily UTC reset — the same file
+the council's CLI transport maintains for
+`cli_call_budget.max_calls_per_day.openai`). Append one line:
+
+```
+Ledger: <N> openai CLI calls today (UTC) · cap: <max_calls_per_day or "unset">
+```
+
+- `<N>` = today's openai count from the counter file; `0` when the file or
+  today's entry is absent.
+- `<cap>` = `ai_team.max_calls_per_day` when set; fall back to
+  `cli_call_budget.max_calls_per_day.openai`; `unset` when neither exists.
+- One counter, one subscription — never introduce a parallel team-only
+  counting file.
+
+## Output format
+
+- The plugin's status output, verbatim.
+- Exactly one trailing `Ledger:` line in the format above.
+- Gate failures print exactly one block (enable pointer or fail-closed
+  block) and stop.
+
+## Do NOT
+
+- Do NOT run when `ai_team.enabled` is false — enable pointer, stop.
+- Do NOT fabricate a count when the counter file is unreadable — print
+  `Ledger: unavailable (<reason>)` instead of a guessed number.
+- Do NOT write to `cli-calls.json` — the transport owns the counter; this
+  wrapper is read-only.
+- Do NOT reimplement job tracking inline when the plugin is absent — fail
+  closed with the doctor pointer (the ledger line alone is still printed on
+  non-Claude-Code hosts, per Step 2).
+
+## See also
+
+- `/team` — master orchestrator: gates, boundary table vs `/council`.
+- `docs/contracts/ai-team-config.md` — `ai_team.max_calls_per_day`.
+- `ai-council` skill — the shared CLI transport that maintains the counter.

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

@@ -0,0 +1,147 @@
+---
+model_tier: inherit
+name: team
+disable-model-invocation: true
+pack: product-reasoning
+intent: "Route a cross-model team-mode request (review, adversarial, delegate, status) to the official plugin under ai_team governance"
+routes_to: [team-review, team-adversarial, team-delegate, team-status]
+replaces: []
+tier: 2
+visibility: internal
+description: Team orchestrator — cross-model depth review (one strong model builds, a second reviews the real diff); routes to review, adversarial, delegate, status
+cluster: team
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "second model, GPT drüberschauen lassen, cross-model review, review gate, let another strong model check the diff, team review"
+  trigger_context: "ai_team.enabled is true AND the user wants a second strong model to review the actual working-tree diff with repo access (depth) — not a neutral artefact opinion (that is /council)"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - product-reasoning
+---
+
+# /team
+
+Top-level orchestrator for the `/team` family — governed **team mode**: the
+depth complement to the council. One strong model builds; a second strong
+model reviews the **real diff with repo access** and iterates. On Claude Code
+hosts every sub-command is a **thin delegation** to the official
+`openai/codex-plugin-cc` plugin (`/codex:*`) — this family adds governance
+(default-off gate, delegate opt-in, quota visibility, fail-closed setup
+checks), never a reimplementation.
+
+## What team mode is — and is not
+
+- **Is:** a single strong reviewer running inside the working tree via the
+  Codex CLI under the user's subscription. It reads git state itself,
+  iterates build → review → fix, and returns an opinionated review of the
+  actual change.
+- **Is not:** the council. The council is breadth under a neutrality
+  contract — N members see the artefact text only, never the repo, never the
+  host's framing. Team mode is the inverse on every axis (table below). The
+  council's neutrality contract is untouched by team mode.
+
+## Boundary — /council vs. /team
+
+| Axis | `/council` | `/team` |
+|---|---|---|
+| Shape | Breadth — N members, one round by default | Depth — one strong reviewer, iterated |
+| Context | Artefact text only; never the repo, never host framing (neutrality contract) | Full repo access — the reviewer reads git state itself |
+| Cost model | Billable API members by default; USD cost gate | Subscription-authed Codex CLI; daily call quota (`cli_call_budget.max_calls_per_day.openai`) |
+| Model choice | Mid-tier default (cost decision) | Strongest available — `ai_team.model: 'auto'` defers to the CLI default |
+| Write access | Never (text only; one opt-in PR comment under `pr`) | Read-only by default; `/team delegate` is the single write path, behind a second opt-in |
+
+## Default-off gate — check FIRST, before anything else
+
+Read `ai_team.enabled` from `.agent-settings.yml`. Missing key or `false`
+(the shipped default) → print the enable pointer and **STOP**. Do not route,
+do not suggest a sub-command, do not probe for the plugin:
+
+> Team mode is disabled (`ai_team.enabled: false`, the default).
+> Enable it in `.agent-settings.yml`:
+>
+> ```yaml
+> ai_team:
+>   enabled: true
+> ```
+>
+> Key reference: `docs/contracts/ai-team-config.md`. Then run
+> `agent-config doctor --check team` to verify plugin + auth setup.
+
+Every sub-command repeats this check independently — the gate holds even when
+a wrapper is invoked directly.
+
+## Sub-commands
+
+| Sub-command | Delegates to (Claude Code) | Purpose |
+|---|---|---|
+| `/team review [--background]` | `/codex:review` | Cross-model review of the current working-tree / staged diff |
+| `/team adversarial <focus>` | `/codex:adversarial-review` | Adversarial cross-model review on a named focus — the escalation rung above the single-model `adversarial-review` skill |
+| `/team delegate <task>` | `/codex:rescue` | Hand a task to the second model as a native worker — the only write-access wrapper; gated behind `ai_team.allow_delegate` |
+| `/team status` | `/codex:status` + ledger line | Plugin job status plus today's `cli_call_budget` openai count |
+
+## Dispatch
+
+1. Run the default-off gate above. Disabled → enable pointer, stop.
+2. Parse the user's argument: `/team <sub-command> [args]`.
+3. Look up the sub-command in the table above; load the routed file and
+   follow its `## Instructions` verbatim with the remaining args.
+4. Unknown or missing sub-command → print the table and ask:
+
+   > 1. review — cross-model review of the real diff (optionally `--background`)
+   > 2. adversarial — adversarial cross-model review on a focus
+   > 3. delegate — hand a task to the second model (write access; second opt-in)
+   > 4. status — plugin jobs + today's call-quota ledger
+
+## Fail-closed contract (all wrappers)
+
+When the official plugin is absent on a Claude Code host, every wrapper
+fails **closed** with the doctor remediation pointer — never a silent no-op,
+never an inline reimplementation of the plugin:
+
+> ❌ Team mode is enabled, but the official plugin is not installed on this
+> Claude Code host. `/team <sub>` fails closed — it never reimplements the
+> plugin inline and never silently no-ops.
+>
+> Run the guided check and follow its remediation block:
+>
+> ```bash
+> agent-config doctor --check team
+> ```
+
+On non-Claude-Code hosts the fallback transport (repo-diff bundle via the
+council's `OpenAICliClient`) is a later phase; until it lands, wrappers state
+that plainly and stop — same fail-closed principle.
+
+## No-claims note
+
+The review-lift value of cross-model team review is **unproven** until the
+pre-registered three-arm benchmark (team review vs. single-model adversarial
+self-review vs. `council:pr`) has run. Never assert "two strong models catch
+each other's errors", a defect-finding lift, or any quantified quality claim
+in output, docs, or suggestions. Team mode is offered as a workflow, not as a
+measured improvement.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR.** `/team` produces text; the plugin's
+  review output is returned verbatim.
+- **Do NOT chain sub-commands.** One `/team <sub>` per turn.
+- **Write access exists only via `/team delegate`**, and only when
+  `ai_team.allow_delegate: true` (default `false`). Every other wrapper is
+  read-only.
+- **Quota:** every team call counts into the existing
+  `cli_call_budget.max_calls_per_day.openai` bucket — one subscription, one
+  counter. No parallel counting system.
+- If the user invokes `/team` with no argument, **show the menu** — do not
+  guess which sub-command they meant.
+
+## See also
+
+- `/council` — breadth under a neutrality contract; the complement, not the
+  competitor.
+- `adversarial-review` skill — the free single-model first rung below
+  `/team adversarial`.
+- `docs/contracts/ai-team-config.md` — the `ai_team` settings block
+  (`enabled`, `model`, `allow_delegate`, `max_calls_per_day`).

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.