@event4u/agent-config 8.11.0 → 8.12.0

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,32 +231,35 @@ 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 (step-field convention, see
+   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 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
+   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
@@ -279,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
 
@@ -338,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/rules/architecture.md

@@ -8,6 +8,8 @@ triggers:
   - keyword: "service"
   - keyword: "module"
   - intent: "structural decision"
+routes_to:
+  - "skill:module-detect-on-the-fly"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
 ---
@@ -20,6 +22,8 @@ ALWAYS VALIDATE AT THE REQUEST BOUNDARY. NEVER INLINE-VALIDATE INSIDE THE HANDLE
 ALWAYS READ AGENTS.MD AND PROJECT-LOCAL DOCS BEFORE STRUCTURAL DECISIONS.
 ```
 
+Fires on new files, classes, controllers, modules, or any structural decision about project organization.
+
 ## General Principles
 
 - **HTTP handlers stay thin** — no business logic; delegate to a service / use-case / domain layer.
@@ -34,27 +38,6 @@ ALWAYS READ AGENTS.MD AND PROJECT-LOCAL DOCS BEFORE STRUCTURAL DECISIONS.
 → Symfony: see [`symfony-workflow`](../skills/symfony-workflow/SKILL.md).
 → Next.js / TypeScript backends: see [`nextjs-patterns`](../skills/nextjs-patterns/SKILL.md).
 
-## Project Detection
-
-Detect the current project type from the **Git remote URL**, **directory name**, or **project files**:
-
-- **PHP** — `composer.json` (framework slot: Laravel via `artisan`, Symfony via `bin/console`, standalone otherwise).
-- **JS / TS** — `package.json` (framework slot: Next.js via `next` dep, Nuxt via `nuxt`, Express / Fastify / NestJS via deps; plain Node otherwise).
-- **Python** — `pyproject.toml` / `requirements.txt` (framework slot: Django via `django`, FastAPI via `fastapi`, Flask via `flask`).
-- **Go** — `go.mod` (framework slot: `gin`, `echo`, `fiber`, stdlib `net/http`).
-- **Ruby** — `Gemfile` (framework slot: Rails via `rails` gem, Sinatra otherwise).
-- **Rust** — `Cargo.toml` (framework slot: `axum`, `actix-web`, `rocket`).
-- Check `AGENTS.md` or `agents/` for project-specific documentation.
-
-Tooling lives in a runner file at the project root — detect once and reuse the result:
-`Taskfile.yml` → `task`, `Makefile` → `make`, `package.json` `scripts:` → `npm` / `pnpm` / `yarn`, `pyproject.toml` `[tool.poetry.scripts]` or `[project.scripts]` → `poetry` / `uv`, framework CLIs (`artisan`, `bin/console`, `manage.py`, `bin/rails`) when the matching manifest is present.
-
-## Project-Specific Architecture
-
-Each project documents its own architecture in `./agents/` and/or `AGENTS.md`.
-**Always read those files** before making structural decisions. Do not rely on this rule file
-for project-specific directory layouts, database conventions, or module systems.
-
 ## Architectural Decision Records (ADRs)
 
 When a structural decision is non-trivial (kernel membership, contract change, library swap,
@@ -64,33 +47,5 @@ skill — it numbers the file (`ADR-NNN-<slug>.md`), writes the standard templat
 index via `scripts/adr/regenerate_index.ts`. ADRs land in `docs/adr/` by default; legacy
 projects use `docs/decisions/`. Reversible refactors and minor cleanups do **not** need ADRs.
 
-## Module-Level Documentation
-
-Some projects use a module system (e.g. `app/Modules/` in Laravel, `apps/`/`packages/` in a Turborepo, `src/modules/` in NestJS, `internal/` in Go).
-Module roots and the per-module agent-docs folder are configured via
-`modules.root_paths` and `modules.agent_folder` in `.agent-settings.yml`
-(resolve at runtime via `scripts/_lib/agent_settings.ts::enumerate_modules()`).
-Modules may have their own agent docs under
-`{module_root}/*/{agent_folder}/` (Laravel shape: `app/Modules/*/agents/`) with:
-
-- Module descriptions and feature docs
-- Module-specific roadmaps (`agents/roadmaps/`)
-- Module-specific documentation (`Docs/`)
-
-When working on a module, **always check for module-level agent docs** first.
-
-## Packages
-
-Packages (Composer, npm, etc.) may also use `./agents/` in their root
-for package-specific docs and roadmaps. Treat them the same way as projects.
-
-## Build / Task Runner Detection
-
-Projects use either `Makefile` or `Taskfile.yml` (or both) for common commands.
-**Always check which one exists** and read it to discover available targets for
-testing, quality checks, container access, migrations, etc.
-
-- `Makefile` → use `make <target>`
-- `Taskfile.yml` → use `task <target>`
-
-Prefer these targets over raw `docker compose exec` commands when available.
+Body migrated to [`skill:module-detect-on-the-fly`](../skills/module-detect-on-the-fly/SKILL.md) (per P4 of `road-to-kernel-and-router.md`) — project-detection table, project-specific architecture docs, module-level documentation mechanics, packages, build/task-runner detection.
+Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).

package/dist/agent-src/rules/code-comment-discipline.md

@@ -22,7 +22,7 @@ packs: [engineering-base]
 
 # Code Comment Discipline
 
-AI-written code over-comments: docblocks mirroring the signature, comments narrating the next line, banner headers, change-log notes. Every redundant comment costs tokens on every future read, bloats the file, rots into misinformation when code changes. Default for any new comment: **no** — a comment must earn its place.
+AI-written code over-comments: docblocks that mirror the signature, comments that narrate the next line, banner headers, change-log notes. Every redundant comment costs tokens on every future read, bloats the file, and rots into misinformation the moment the code changes. The default for any new comment is **no** — a comment must earn its place.
 
 ## The Iron Law
 
@@ -39,110 +39,26 @@ WHEN IN DOUBT: NO COMMENT. SHORTER IS BETTER. NONE IS OFTEN BEST.
 
 Exactly five legitimate jobs — everything else is noise:
 
-1. **A why** — non-obvious reason this approach beat the obvious one.
-2. **An invariant or constraint** code can't express — ordering, units, concurrency assumptions, "must run before X".
-3. **A warning** — known trap, workaround for a specific upstream bug (name it), performance cliff.
-4. **Machine-relevant type precision** the native type system can't carry — see carve-out below.
-5. **A spec linkage** where an external contract defines behavior (RFC section, protocol field) — the contract, not ticket history.
+1. **A why** — the non-obvious reason this approach was chosen over the obvious one.
+2. **An invariant or constraint** the code cannot express — ordering requirements, units, concurrency assumptions, "must run before X".
+3. **A warning** — a known trap, a workaround for a specific upstream bug (name it), a performance cliff.
+4. **Machine-relevant type precision** the native type system cannot carry — carve-out in the guideline.
+5. **A spec linkage** where an external contract defines the behavior (RFC section, protocol field) — the contract, not the ticket history.
 
 Test before writing any comment: *would deleting it leave a future reader confused about a non-obvious constraint?* No → don't write it.
 
-## Banned comment classes
-
-| Banned | Example | Instead |
-|---|---|---|
-| What-narration | `// increment the counter` above `counter++` | Nothing — code says it |
-| Signature-mirroring docblock | `@param string $name The name` on `string $name` | Nothing — typehint says it |
-| Redundant `@return` | `@return bool` on `): bool` | Nothing |
-| Banner / section divider | `// ---------- Helpers ----------` | Structure the file; extract a class |
-| Change-log comment | `// added for the export feature`, `// per ticket #123` | Commit message / PR description |
-| Reviewer-directed justification | `// this is safe because my change …` | PR description |
-| Redundant property docblock | `/** @var LoggerInterface */` on a typed property | Nothing — property type says it |
-| Type-restating JSDoc in typed TS | `/** @param {string} id */` on `id: string` | Nothing — TS carries the type |
-| Obvious docstring | `"""Return the user."""` on `get_user()` | Nothing, or a real contract note |
-| Commented-out code | dead code kept "for reference" | Delete — git history is the tombstone |
-
-## Carve-out — machine-relevant precision docblocks STAY
-
-Docblock carrying type info the native type system can't express is **not** redundant — static analyzers + IDEs consume it. Keep (and write):
-
-- PHP generics / array shapes for PHPStan/Psalm: `@return Collection<int, Post>`, `@param array<string, User> $usersByEmail`, `@template T`, `@phpstan-type`.
-- Union/shape refinements the language can't express natively.
-- Tool-consumed markers: `@deprecated` (with successor), `@internal`, `@throws` for checked flows callers must handle.
-- Python typing only a docstring/stub can carry in the project's toolchain.
-
-The line: docblock must add information **beyond** the native signature. `@param array<int, Order> $orders` earns its place; `@param array $orders` does not.
-
-## Public-API carve-out — `code_style.docblocks`
-
-Read `code_style.docblocks` from `.agent-settings.yml` (missing → `minimal`):
-
-- `minimal` (default) — full discipline above; exported/public symbols get no summary docblock unless one of the five legitimate jobs applies.
-- `full` — **exported public surface of a library package** (published API consumers see in their IDE) MAY carry one-line summary docblock per symbol. Redundancy ban holds in `full`: no `@param`/`@return` lines mirroring the signature, ever.
-
-## Worked examples
-
-```php
-// ❌ Redundant — every line restates the signature
-/**
- * Get the user by id.
- *
- * @param int $id The user id.
- * @return User|null The user or null.
- */
-public function getUserById(int $id): ?User
-
-// ✅ Nothing to add — the signature is the documentation
-public function getUserById(int $id): ?User
-```
-
-```php
-// ✅ Docblock KEPT — the generic is machine-relevant (PHPStan), the native type can't carry it
-/** @return Collection<int, Post> */
-public function publishedPosts(): Collection
-```
-
-```ts
-// ❌ Redundant — TS already knows all of this
-/**
- * Formats the price.
- * @param amount - the amount
- * @returns the formatted price
- */
-export function formatPrice(amount: number): string
-
-// ✅ A real constraint the signature can't show
-// Rounds half-up to match the invoice PDF renderer; Intl default is half-even.
-export function formatPrice(amount: number): string
-```
-
-```python
-# ❌ Narration
-# loop over the items and sum the totals
-total = sum(item.total for item in items)
-
-# ✅ A why that survives
-# Stripe amounts are integer cents; convert once at the boundary, never downstream.
-total_cents = sum(item.total_cents for item in items)
-```
-
-## Scope boundary
-
-Governs **new and edited code only**. Never a license to strip comments from untouched code — [`minimal-safe-diff`](minimal-safe-diff.md) wins on diff shape ("no docstrings/comments on untouched code" cuts both ways: don't add, don't remove). Sweeping a file's existing comments = separate, explicitly-requested cleanup task.
-
 ## When NOT to fire
 
 - Prose surfaces: docs, READMEs, roadmaps, config commentary — different register, not code comments.
-- User explicitly asks for documented code / teaching examples ("erkläre im Code", "annotate this for juniors") — that turn's ask wins.
+- The user explicitly asks for documented code / teaching examples ("erkläre im Code", "annotate this for juniors") — that turn's ask wins.
 - License headers or file-level pragmas a toolchain requires.
 
-## Fixtures
-
-Behavioral baseline: `tests/code-comments/eval-fixtures.md` (`ccd-php-class-generation`, `ccd-ts-module-generation`, `ccd-untouched-preservation`, `ccd-explicit-teaching-override`); decidable criteria proven by `tests/scripts/code_comment_fixtures.test.ts`.
+Body migrated to [`guideline:code-clarity § Comment discipline`](../docs/guidelines/code-clarity.md#comment-discipline--state-a-constraint-not-a-narration) (per P4 of `road-to-kernel-and-router.md`) — banned-classes table, machine-relevant precision carve-out, `code_style.docblocks` public-API carve-out, per-language keep/drop tables, worked examples, scope boundary, fixtures pointer.
+Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).
 
 ## See also
 
-- [`code-clarity.md § Comment discipline`](../docs/guidelines/code-clarity.md#comment-discipline--state-a-constraint-not-a-narration) — canonical long-form with per-language keep/drop tables.
+- [`code-clarity.md § Comment discipline`](../docs/guidelines/code-clarity.md#comment-discipline--state-a-constraint-not-a-narration) — canonical long-form with the migrated body.
 - [`minimal-safe-diff`](minimal-safe-diff.md) — diff-shape twin; no comment additions or removals on untouched code.
 - [`output-discipline`](output-discipline.md) — adjacent but distinct: bans placeholder prose (`// TODO: implement`); this rule bans redundant prose.
 - `docs/guidelines/php/php-coding-patterns.md` § PHPDoc — PHP-specific operationalization.

package/dist/agent-src/rules/decision-revisit-gate.md

@@ -12,6 +12,8 @@ triggers:
   - keyword: "already decided"
   - keyword: "locked decision"
   - keyword: "budget blocks"
+routes_to:
+  - "skill:decision-review"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
 ---
@@ -34,88 +36,18 @@ and offers the user a path to re-evaluate the lock. Progress means
 adaptation: locks encode what was true when they were written, not a
 ceiling on what the package may ever become.
 
-## What counts as a "lock"
+**Mechanism-match check comes FIRST**: a verdict settles the *mechanism it
+tested*, not every future proposal that resembles it — if the blocked change
+is a different mechanism, the lock does not apply; proceed, noting the
+distinction.
 
-- An eval verdict recorded as an honest null (a mechanism was tested,
-  showed no lift, and the disposition says "don't rebuild without new
-  evidence").
-- A memory entry or `agents/settings/contexts/` note tagged "don't
-  relitigate" / "settled" / a locked council convergence.
-- A budget or frugality-canon line (`token-budget-discipline`,
-  `telegraph-speak`, thin-projector trimming) that rejects a change on
-  cost grounds alone.
-- An ADR whose decision is being cited as a blocker for the current change.
-- A **hard structural cap** (kernel size, per-domain persona cap, rich-skill
-  ratio). A change that genuinely *qualifies* to cross the cap — e.g. a new
-  rule that truly meets the kernel-membership inclusion criteria — triggers a
-  **cap-raise proposal + maintainer/council approval**, never a silent
-  downgrade of the rule to fit the old number (e.g. demoting a must-always-fire
-  rule to `auto` just because the kernel says 9). Fitting the cap is not a
-  reason to weaken a qualifying rule; but a rule that does **not** meet the
-  criteria stays out — the cap is not the reason, the criteria are.
-
-## What to do when it fires
-
-1. **Mechanism-match check — do this FIRST.** A verdict settles the
-   *mechanism it tested*, not every future proposal that resembles it.
-   Before applying the lock, verify the blocked change is actually the
-   same mechanism — not merely a similar-sounding one. A null on
-   hardened blocking enforcement does not automatically cover
-   discretionary contextual nudges; a null on one architecture does not
-   cover a materially different one. If the mechanism differs, the lock
-   does not apply — proceed, noting the distinction.
-2. **If the mechanism genuinely matches**, do not silently comply.
-   Surface, in one short block:
-   - What change is blocked.
-   - Which lock blocks it (cite the memory/context/ADR).
-   - Under what conditions the lock was recorded (date, evidence, or
-     "maintainer decision" if settled-by-decision rather than
-     settled-by-evidence).
-   - What has changed since (new evidence, new model generation, new
-     tooling, repeated encounters) that makes revisiting worth the cost.
-3. **Offer numbered options** (per [`user-interaction`](user-interaction.md)),
-   always including: re-evaluate the lock in the AI council. Other
-   options: keep the lock as-is, or proceed without the blocked change.
-4. **On re-evaluation:** route to [`decision-review`](../skills/decision-review/SKILL.md)
-   for the backward-audit procedure and to [`ai-council`](../skills/ai-council/SKILL.md)
-   for the debate mechanics. This rule owns the obligation to surface;
-   those skills own the procedure.
-5. **Record the outcome** with scope + `revisit-if` per
-   [`ai-council`](../skills/ai-council/SKILL.md)'s convergence-summary
-   contract — every re-evaluated lock gets a fresh, correctly-scoped
-   disposition, not a re-statement of the old one.
-
-## When NOT to fire
-
-- The blocked change has no real benefit — this rule is not a lever to
-  reopen every settled question; [`no-cheap-questions`](no-cheap-questions.md)
-  still governs whether the resulting numbered-options block is a real
-  question or noise. A revisit-offer with a genuine trade-off is never
-  a "cheap question" under that rule — but a revisit-offer with no
-  actual case for change is.
-- The mechanism-match check (step 1) shows the lock is the same
-  mechanism and no new evidence exists — apply the lock, no surfacing
-  needed; this is the lock working as intended.
-- The user already declined a revisit on this exact lock this
-  conversation — per [`scope-control § Decline = silence`](scope-control.md),
-  do not re-ask.
-
-## Failure modes
-
-- Treating a "don't relitigate" memory as permanently closed instead of
-  as settled-under-conditions-X.
-- Applying a null verdict to a superficially similar but architecturally
-  different mechanism without running the mechanism-match check.
-- Letting the token-frugality canon auto-reject a net-positive change
-  without surfacing the trade-off — see [`token-budget-discipline`](token-budget-discipline.md)'s
-  value-over-budget clause.
-- Silently dropping a good idea because "we already decided this" —
-  the canonical failure this rule exists to stop.
+Body migrated to [`skill:decision-review` § Decision-revisit gate — mechanics](../skills/decision-review/SKILL.md) (per P4 of `road-to-kernel-and-router.md`) — what-counts-as-a-lock catalog (honest nulls, don't-relitigate notes, budget-canon lines, ADRs, hard structural caps), the five fire steps, when-NOT-to-fire, failure modes.
+Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).
 
 ## See also
 
 - [`decision-review`](../skills/decision-review/SKILL.md) — the backward-audit
-  procedure this rule routes to when a lock is genuinely re-evaluated.
+  procedure + the migrated gate mechanics.
 - [`ai-council`](../skills/ai-council/SKILL.md) — the re-evaluation mechanism;
   owns the convergence-summary scope + `revisit-if` contract.
 - [`decision-record`](../skills/decision-record/SKILL.md) — forward-flow decision