@event4u/agent-config 14.6.0 → 14.8.0

package/dist/agent-src/skills/quality-tools/references/php-tools.md

@@ -0,0 +1,222 @@
+# quality-tools — PHP quality tools
+
+> Mode body of the [`quality-tools`](../SKILL.md) skill (router-head
+> retrofit, 2026-08-20). Content moved VERBATIM from SKILL.md — load this
+> file when the mode table in SKILL.md routes here.
+
+# PHP Quality Tools
+
+## Tool Detection
+
+Check `composer.json` to determine which tools are available and how to run them.
+Use the **first matching** command style:
+
+| `composer.json` contains | Command style | Example |
+|---|---|---|
+| A project-specific quality wrapper (exposes `quality:*` commands) | `php artisan quality:*` or `composer quality:*` | `php artisan quality:phpstan` |
+| `phpstan/phpstan` or `larastan/larastan` | `vendor/bin/phpstan` | `vendor/bin/phpstan analyse` |
+| `rector/rector` | `vendor/bin/rector` | `vendor/bin/rector process` |
+| `symplify/easy-coding-standard` | `vendor/bin/ecs` | `vendor/bin/ecs check --fix` |
+
+**Priority:** If a project ships a `quality:*` wrapper (Artisan or Composer script), always prefer it —
+wrappers typically add git-aware execution, caching, automatic baseline regeneration, and memory
+management on top of the native tools.
+
+If none of the above is installed → skip quality checks, inform the user.
+
+All commands run **inside the Docker container** if Docker is used (`docker compose exec` or `make console`).
+
+## Commands
+
+### PHPStan — Static Analysis
+
+```bash
+# Native:
+vendor/bin/phpstan analyse                          # Analyse all configured paths
+vendor/bin/phpstan analyse --memory-limit=512M      # With memory limit
+vendor/bin/phpstan analyse --error-format=github    # CI-friendly format
+
+# With a project-specific quality wrapper:
+php artisan quality:phpstan          # Laravel
+composer quality:phpstan             # Composer
+```
+
+**Native flags:**
+
+| Flag | Description |
+|---|---|
+| `--memory-limit=SIZE` | Set memory limit (e.g. `512M`, `1G`) |
+| `--debug` | Activate debug mode |
+| `--error-format=FORMAT` | Output format: `table` (default), `github`, `gitlab` |
+| `--pro` | Toggle PHPStan Pro |
+
+**Wrapper-only flags** (typical of a `quality:*` wrapper — verify in the project):
+
+| Flag | Description |
+|---|---|
+| `--baseline` | Generate/update phpstan baseline file |
+| `--ignore-git` | Skip Git check, analyse all files |
+| `--xdebug` | Activate Xdebug mode |
+
+### ECS — Easy Coding Standard
+
+```bash
+# Native:
+vendor/bin/ecs check                  # Dry-run
+vendor/bin/ecs check --fix            # Auto-fix
+
+# With a project-specific quality wrapper:
+php artisan quality:ecs --fix         # Laravel
+composer quality:ecs -- --fix         # Composer
+```
+
+**Native flags:**
+
+| Flag | Description |
+|---|---|
+| `--fix` | Fix errors automatically |
+| `--clear-cache` | Clear the ECS cache |
+
+**Wrapper-only flags** (typical of a `quality:*` wrapper — verify in the project):
+
+| Flag | Description |
+|---|---|
+| `--ignore-git` | Skip Git check, check all files |
+| `--paths-to-scan[=PATHS]` | Custom paths, e.g. `--paths-to-scan='["./core"]'` |
+| `--source-branch[=BRANCH]` | Source branch (default: HEAD) |
+| `--target-branch[=BRANCH]` | Target branch to compare against |
+
+### Rector — Automated Refactoring
+
+```bash
+# Native:
+vendor/bin/rector process              # Auto-fix
+vendor/bin/rector process --dry-run    # Preview changes
+
+# With a project-specific quality wrapper:
+php artisan quality:rector --fix       # Laravel
+composer quality:rector -- --fix       # Composer
+```
+
+**Native flags:**
+
+| Flag | Description |
+|---|---|
+| `--dry-run` | Preview changes without applying |
+| `--clear-cache` | Clear the Rector cache |
+
+**Wrapper-only flags** (typical of a `quality:*` wrapper — verify in the project):
+
+| Flag | Description |
+|---|---|
+| `--ignore-git` | Skip Git check, check all files |
+| `--paths-to-scan[=PATHS]` | Custom paths |
+| `--source-branch[=BRANCH]` | Source branch (default: HEAD) |
+| `--target-branch[=BRANCH]` | Target branch to compare against |
+
+### Combined Commands
+
+There is no native single command for running all three tools. Run them in sequence:
+
+```bash
+# Full pipeline (native):
+vendor/bin/rector process && vendor/bin/ecs check --fix && vendor/bin/phpstan analyse
+
+# With a project-specific quality wrapper (if it ships these combined commands):
+php artisan quality:refactor --fix     # Rector + ECS
+php artisan quality:finalize           # Rector + ECS + PHPStan (full pipeline)
+```
+
+## Procedure: Run quality checks
+
+1. Run PHPStan — fix all errors
+2. Run Rector + ECS with auto-fix — fix style + refactoring
+3. Run PHPStan again — verify step 2 didn't introduce new issues
+
+If step 3 finds errors → fix and repeat from step 2.
+
+Detect commands from project (see Tool Detection above).
+
+## Configuration
+
+Config files are typically in the **project root**. Do NOT modify without explicit user permission.
+
+Detect config location:
+- Check project root first: `phpstan.neon`, `ecs.php`, `rector.php`
+- Some projects use `phpstan.neon.dist` instead of `phpstan.neon`
+
+### Standard config files
+
+| File | Tool | Purpose |
+|---|---|---|
+| `phpstan.neon` | PHPStan | Level, paths, extensions, `ignoreErrors`, disallowed calls |
+| `phpstan-baseline.neon` | PHPStan | Baseline for existing errors (auto-managed, do NOT edit) |
+| `ecs.php` | ECS | Code style: rule sets, configured rules, skip list |
+| `rector.php` | Rector | Refactoring: rule sets, PHP version sets, skip list |
+
+### Understanding the project's config
+
+Read the actual config files to understand what rules are active:
+
+- **phpstan.neon**: Check `level`, `paths`, `ignoreErrors`, `includes` (baselines, extensions)
+- **ecs.php**: Check which rule sets are active (PSR-12, PHP-CS-Fixer sets), skip list
+- **rector.php**: Check PHP version sets, active rule sets, skip list
+
+Common patterns across projects:
+- PHPStan at high levels (8-9) with `disallowedFunctionCalls` banning `var_dump()`, `dd()`
+- ECS with PSR-12 base, trailing commas, Yoda style
+- Rector with PHP version migration sets and naming conventions
+
+## Baseline policy
+
+- **NEVER** edit `phpstan-baseline.neon` by hand.
+- **NEVER** add errors, update counts, or regenerate manually.
+- If the project ships a quality wrapper (exposing `quality:*` commands), it may regenerate the baseline automatically.
+
+## PHPStan error handling
+
+Priority order for dealing with PHPStan errors:
+
+1. **Fix the code** — always the first choice. Fix the actual type issue.
+2. **Add type hints / PHPDoc** — if the code is correct but PHPStan can't infer the type.
+3. **Inline ignore (last resort)** — only for confirmed false positives:
+   ```php
+   // @phpstan-ignore-next-line — false positive: reason here
+   ```
+
+### When `phpstan.neon` changes ARE allowed
+
+Adding `ignoreErrors` entries to `phpstan.neon` is allowed when:
+
+- The error is a **structural limitation** of the toolchain (e.g., Pest tests bind `$this` at runtime, PHPStan can't resolve `artisan()`,
+  `get()`, etc. on `PHPUnit\Framework\TestCase`)
+- The pattern applies **broadly** to a category of files (e.g., all test files), not just one specific line
+- The fix would require abandoning the project's conventions (e.g., rewriting Pest tests as PHPUnit classes)
+
+**If unsure whether a `phpstan.neon` change is appropriate → ask the user before making the change.**
+
+### NEVER do these
+
+- Add entries to baseline files (`phpstan-baseline.neon`)
+- Add `ignoreErrors` for individual files or specific code issues that should be fixed
+- Use `@phpstan-ignore-next-line` without a reason comment
+
+See also: `php-coding` rule → PHPStan section.
+
+## Testing framework
+
+- **Always write tests in Pest**, not PHPUnit class syntax — unless the user explicitly asks for PHPUnit.
+- Pest tests in `tests/Unit/` automatically use `UnitTestCase` as the base class (configured in `tests/Pest.php`).
+- PHPStan cannot fully resolve Pest's runtime bindings — this is handled via `ignoreErrors` patterns in `phpstan.neon`.
+
+## Git-aware execution
+
+By default, all tools only check files changed since the last commit.
+
+| Flag                         | Effect                                        |
+|------------------------------|-----------------------------------------------|
+| (default)                    | Only changed files (fast, for iterative work) |
+| `--ignore-git`               | All files (cache still applies)               |
+| `--clear-cache`              | Changed files, but ignore cache               |
+| `--ignore-git --clear-cache` | Complete fresh run of all files               |
+

package/dist/agent-src/skills/roadmap-management/SKILL.md

@@ -98,419 +98,25 @@ actual paths in the current project; never assume `app/Modules/`.
 The file `.augment/templates/roadmaps.md` defines the canonical structure.
 **Always read it first** before creating or modifying roadmaps.
 
-## Roadmap structure
 
-Every roadmap follows this structure:
+## Modes
 
-```markdown
-# Roadmap: {Short descriptive title}
+This skill is a router head. The dashboard-sync obligation above, the procedure
+skeleton, and the location table are true in every mode and stay here. The
+per-mode procedure bodies live in `references/`; load the one the task calls
+for, not the set.
 
-> {One sentence: What is the expected outcome?}
-
-## Prerequisites
-
-- [ ] Read `AGENTS.md` and relevant docs
-- [ ] {specific prerequisites}
-
-## Context
-
-{Why this roadmap exists. Which module/domain. Links to Jira tickets.}
-
-## Phase 1: {Phase name}
-
-- [ ] **Step 1:** {Clear, actionable instruction}
-- [ ] **Step 2:** {Next step — reference files/classes}
-- [ ] ...
-
-## Phase 2: {Phase name}
-
-- [ ] **Step 1:** {description}
-- [ ] ...
-
-## Acceptance Criteria
-
-- [ ] {Observable, testable criterion}
-- [ ] All quality gates pass — the project's type-checker, auto-fixer, linter, and full test suite (see the `quality-tools` skill for stack-specific invocations)
-
-## Notes
-
-{Edge cases, decisions, links}
-```
-
-## Key rules for roadmaps
-
-### Checkboxes — mandatory, not decorative
-
-- **Every active roadmap MUST contain at least one `- [ ]` per non-intro phase.** Decision tables, ICE matrices, and block-sequencing tables are valid rationale, but they do not satisfy this rule on their own — pair them with a `## Phase N` or `## Implementation Checklist` section whose checkboxes execute the decision. A roadmap without checkboxes is invisible to `agents/roadmaps-progress.md` and violates [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md) Iron Law #2.
-- Every actionable step uses `- [ ]` (unchecked) or `- [x]` (completed).
-- Mark steps as `[x]` immediately after completing them.
-- Never remove completed steps — they serve as history.
-- **Status is binary: `ready` (default, implicit) or `draft`.** New roadmaps are created **ready** unless the user explicitly says otherwise — `ready` is implicit and need not be written. A roadmap that is still being authored, awaiting upstream decisions, or capturing options without a worked plan declares `status: draft` in YAML frontmatter at the top of the file. Drafts are hidden from `agents/roadmaps-progress.md` until the flag is removed or flipped to `ready`. There are no other status values; legacy banners (`**Status: directional**`, `Status: capture-only`, `mode: feedback`) are removed.
-
-### Awaiting evidence — a blocker entry, never a new glyph
-
-- Waiting on **evidence that has not arrived** (soak still running, benchmark unfunded, adopter absent) is neither `[~]` nor `[-]`. Signal it with a structured `## Blockers` entry — five-field shape in [`templates/roadmaps.md` rule 20](../../agent-src/templates/roadmaps.md) — whose `Resolved when:` names the decidable signal ending the wait. The item stays `- [ ]` and points at it: `<!-- blocked-by: <id> -->`.
-- **No new glyph.** `[ ]` + `blocked-by:` = open, awaiting named evidence (stays active) · `[~]` = deferred by decision (bars archival, Iron Law 3) · `[-]` = cancelled with a reason (does not bar it). A fifth state buys nothing the entry above does not already carry.
-
-### Phases
-
-- Group related steps into phases (e.g. "Preparation", "Migration", "Cleanup").
-- Complete one phase before starting the next (unless steps are independent).
-- After completing a phase, summarize what was done.
-
-### Quality gates
-
-Every roadmap implicitly includes the project's quality pipeline
-(static analysis, autofixes, tests). Whether the agent runs it locally
-at all is gated by `quality.local_auto_run`: `false` or missing (the
-default) → the agent never runs the pipeline locally; the user runs it
-manually and remote CI on the PR is the authoritative gate (run-end
-report: *"quality gates delegated to remote CI"*; new-gate carve-out
-steps still run once). When `local_auto_run: true`, **when** the
-pipeline runs during `/roadmap:process-step|phase|full` is controlled
-by `roadmap.quality_cadence` in `.agent-settings.yml`:
-
-| Cadence | Pipeline runs (`local_auto_run: true` only) | Trade-off |
-|---|---|---|
-| `end_of_roadmap` (default) | Once before archiving | Fastest, fewest tokens; errors compound across phases |
-| `per_phase` | After every completed phase + final | Balanced; catches drift at phase boundaries |
-| `per_step` | After every completed step + final | Legacy verbose; highest token cost |
-
-The default is `end_of_roadmap` because most steps are checkbox-only
-content edits and a final pipeline run is the cheapest way to satisfy
-`verify-before-complete`. Switch to `per_phase` for risky migrations or
-unfamiliar codebases.
-
-**Always-on, regardless of cadence:**
-
-- Step checkboxes flip `[ ] → [x]` and the dashboard regenerates **same
-  response** (enforced by `roadmap-progress-sync`).
-- Before any "roadmap complete" claim or archival, the pipeline runs
-  fresh (enforced by `verify-before-complete`).
-
-### Step granularity
-
-- Each step should be completable in one session (< 1 hour of work).
-- If a step is too large, break it down into sub-steps.
-- Steps should reference specific files/classes when possible.
-
-### Language
-
-- Roadmap files are written in **English** (per project convention).
-- Step descriptions should be precise and actionable, not vague.
-
-## Working with roadmaps
-
-### Creating a roadmap
-
-1. Ask the user for goal, context-create, and phases.
-2. Use the template structure from `.augment/templates/roadmaps.md`.
-3. Review with the user iteratively until approved.
-4. **Branch & release questions — at most once, only if genuinely useful.**
-   Default: stay on the current branch, no version numbers in the
-   roadmap. Only propose a separate branch when there is concrete,
-   evidence-based reason (e.g. risky migration benefits from a spike).
-   Never include release versions, deprecation dates, or git tags in
-   the roadmap text. If the user declines, do **not** re-propose during
-   `/roadmap:process-*`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
-5. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
-   **Before writing**, scan the entire roadmap namespace for a
-   collision — active, `archive/`, `skipped/`, and nested subdirs —
-   with `find agents/roadmaps -type f -iname "<name>.md"`. If any
-   hit comes back, stop and ask the user to rename, open the
-   existing file, or abort. Never silently overwrite an archived
-   or skipped roadmap. Detailed prompt in
-   [`commands/roadmap/create.md`](../../commands/roadmap/create.md)
-   step 6.
-6. Regenerate the dashboard so the new roadmap is included.
-
-### Executing a roadmap
-
-0. Resolve the mode per `roadmap-process-loop` § 3a: suffix, frontmatter
-   `execution.mode`, invocation form (absent = derived, not
-   `interactive`). Under `/roadmap:process-*` the mode selects the
-   interaction pattern via the run-start execution contract — see
-   [`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md).
-   The manual flow below describes `interactive`; under `autonomous`
-   / `phase-checkpoints` step 4's per-step ask is replaced by the
-   accepted contract. **Mode never changes archival semantics** —
-   glyph counting, the closure decision table, and the Iron Law 3
-   deferred-resolution gate below apply identically in every mode.
-1. Read the full roadmap.
-2. Find the next unchecked step (`- [ ]`).
-3. Summarize what needs to be done.
-4. Ask the user before implementing (numbered options: implement / adjust / skip).
-5. After implementation: mark `[x]`, run quality gates, then regenerate the dashboard.
-6. Move to the next step.
-
-### Resuming a roadmap
-
-When picking up a roadmap in a new session:
-1. Read the roadmap to understand the full context.
-2. Check which steps are already completed (`[x]`).
-3. Summarize progress to the user.
-4. Continue from the next open step.
-
-### Completing, archiving & skipping a roadmap
-
-Every roadmap ends in exactly one of four states:
-
-| State | Folder | Trigger |
+| Task | Mode body | Covers |
 |---|---|---|
-| **Active** | `agents/roadmaps/` | Work in progress or planned **and workable now** |
-| **Archived** | `agents/roadmaps/archive/` | Work was done (fully or partially) and no more work is planned |
-| **Skipped** | `agents/roadmaps/skipped/` | Decision against pursuit — superseded, scope rejected, wrong direction. Typically **0 items `[x]`** |
-| **Later** | `agents/roadmaps/later/` | Open work remains but is **blocked-for-later** — gated on an external trigger or a decision, **will resume** when unblocked. Set frontmatter `status: later` + a `Blocked until` / `Trigger` resume line. Excluded from the dashboard and `/roadmap:process-*` (parked, not abandoned). |
-
-**Active vs. Later — the test:** can the agent make progress on this roadmap *now*, autonomously? If every open item is gated on something outside this roadmap (a real consumer repo, a benchmark re-open, host-model access, a kernel soak, a pruning track, a human decision), it is **not** active — move it to `later/` with its resume condition. A blocked roadmap left in the active tree silently lies to the dashboard and to `/roadmap:process-*`, which will keep trying to execute it. The `lint_roadmap_later_disposition` guard enforces the placement↔`status: later` contract.
-
-After the last step of a roadmap is done, check completion status:
-
-0. **Completion review (Gate R2)** — last open item done → findings BEFORE
-   fixes, before any archival decision:
-   - `dispatch_r2_reviewer` builds the reviewer input; a **fresh subagent
-     without the implementation context** writes
-     `agents/evidence/reviews/<slug>.findings.md`.
-   - Work findings in priority order — each ends `fixed` / `accepted-risk` /
-     `deferred`. No code surface → explicit skip, never silent.
-   - Grammar, scope-hash binding, escape hatch:
-     [`plan-review-gates § 2`](../../../docs/contracts/plan-review-gates.md).
-
-1. **Scan the file** for all checkbox markers: `- [x]`, `- [ ]`, `- [~]`, `- [-]`.
-2. **Classify:**
-   - `[x]` = completed
-   - `[ ]` = open (not done)
-   - `[~]` = deferred (intentionally pushed out, may come back)
-   - `[-]` = cancelled (individual item dropped)
-
-3. **Decision rule — `count_open == 0` means the roadmap has no active
-   work left. `[x]`, `[-]` are final states. `[~]` deferred items
-   block silent closure — they carry plans the user has not consented
-   to drop (enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
-   Iron Law 3).**
-
-   | count_x | count_open | count_deferred | count_cancelled | Action |
-   |---|---|---|---|---|
-   | ≥ 1 | 0 | 0 | 0 | **Auto-archive** (silent) — pure completion |
-   | ≥ 1 | 0 | 0 | ≥ 1 | **Auto-archive** (silent) — done with explicit drops |
-   | ≥ 1 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Surface deferred items, present the options, resolve by the preservation test (council where the item survives, user where it does not). See step 4b. |
-   | 0 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Was this a scope-drop or deferred-to-later? Same options and same routing as 4b. |
-   | 0 | 0 | 0 | ≥ 1 | **Auto-skip** (silent) — no work, all cancelled |
-   | ≥ 0 | ≥ 1 | ≥ 0 | ≥ 0 | **Ask the user** — open work remains (step 4a) |
-
-   Show on auto-move:
-
-   - Archive: `✅  Roadmap archived → agents/roadmaps/archive/{filename}`
-   - Skip:    `⏭️  Roadmap skipped → agents/roadmaps/skipped/{filename}`
-   - Later:   `🕒  Roadmap parked for later → agents/roadmaps/later/{filename}`
-
-   `[-]` cancelled items remain searchable inside the archived file —
-   they were explicit drops. `[~]` deferred items, by contrast, may
-   not silently follow the file into archive: they represent work the
-   user planned and would lose track of. Step 4b is the gate.
-
-4a. **Open items remain (`count_open ≥ 1`)** → **Ask the user.** Show what's incomplete:
-
-   ```
-   📋 Roadmap completion check:
-
-     ✅  Completed: {count_x}
-     ⬜  Open:      {count_open}  — {list of open items, 1 line each}
-     ⏭️  Deferred:  {count_deferred}  — {list of deferred items, 1 line each}
-     ❌  Cancelled: {count_cancelled} — {list of cancelled items, 1 line each}
-
-   > 1. Archive — mark open items as cancelled [-] and archive now
-   > 2. Keep active — I want to finish the open items
-   > 3. Mark open items as deferred [~] and archive (triggers Iron Law 3 flow)
-   > 4. Skip — move to skipped/ (no meaningful work done, not pursuing)
-   > 5. Later — park in later/ (open work is blocked on an external trigger / decision but will resume)
-   ```
-
-   Option 4 is only appropriate when `count_x == 0` or the completed items were
-   trivial (e.g. prerequisites only). If the user picks 4 despite meaningful work
-   being done, confirm once — archive is usually the right choice. Picking option 3
-   does NOT archive immediately — it converts open → deferred and re-enters the
-   `count_deferred > 0` branch, which runs step 4b.
-
-   **Option 5 (Later) is the right choice when the open items are real but
-   cannot proceed now** — gated on an external trigger or a decision. Set the
-   roadmap's frontmatter `status: later`, ensure it carries a `Blocked until` /
-   `Trigger` resume line, `git mv` it to `agents/roadmaps/later/`, migrate any
-   inbound references to the new path, and regenerate the dashboard. The open
-   `[ ]` items stay open (they are not cancelled or deferred) — the roadmap is
-   parked whole, ready to resume when the trigger fires. **Roadmaps with open
-   tasks deferred for later are always moved to `later/`**, never left to rot in
-   the active tree.
-
-4b. **Deferred items present (`count_deferred ≥ 1`, `count_open == 0`)** — Iron Law 3 flow.
-   Archive **blocked** until resolved. WHO resolves is the preservation test in
-   [`roadmap-progress-sync § Who resolves it`](../../rules/roadmap-progress-sync.md),
-   never the mode — same menu either way, only the resolver differs:
-
-   - **1, 2, 4** keep the item alive → **council**, recorded at the item (2 only
-     if the follow-up lands in the SAME change).
-   - **3, 5** drop or weaken it → **user**, always. In doubt: user.
-
-   ```
-   📋 Roadmap closure check — deferred items must resolve before archive:
-
-     ✅  Completed: {count_x}
-     ⏭️  Deferred:  {count_deferred}
-     {for each deferred item:}
-       - Phase {N}: {step text}  {<!-- deferred: <annotation> --> if present}
-
-   These items carry plans you would lose to a silent archive.
-
-   > 1. Spawn follow-up roadmap as DRAFT
-   >    → agents/roadmaps/road-to-{auto-slug}.md, status: draft,
-   >      parent_roadmap: {this-slug}. Hidden from the dashboard until
-   >      you flip status to "ready".
-   > 2. Spawn follow-up roadmap as READY (with blocked-until note)
-   >    → status: ready (default), parent_roadmap: {this-slug}, plus
-   >      a `> Blocked until <condition>` line in the body. Visible
-   >      in the dashboard; execution waits on the condition.
-   > 3. Keep deferred items in this archive — confirm "no follow-up"
-   >    is an intentional drop. Items stay searchable in archive/.
-   > 4. Restore selected items to [ ] — finish them here before archive.
-   > 5. Convert selected items to [-] cancelled — drop with rationale.
-   ```
-
-   Picks 1 or 2 → see "Spawn follow-up from deferred items" procedure below.
-   Picks 3, 4, or 5 → apply the change in this roadmap; re-evaluate the
-   decision table; archive when the gate clears.
-
-### Spawn follow-up from deferred items (procedure)
-
-When the user picks option 1 or 2 in step 4b:
-
-1. **Derive the slug.** Default `<parent-slug>-followup` (e.g.
-   `road-to-x.md` → `road-to-x-followup.md`). If a user-supplied
-   slug was given in the picker, use that. Avoid collisions with
-   `agents/roadmaps/` (active + `archive/` + `skipped/`).
-
-2. **Write the new file** at `agents/roadmaps/<slug>.md`:
-
-   ```markdown
-   ---
-   complexity: lightweight            # bump if the parent was structural
-   status: draft                      # option 1; omit for option 2 (= ready)
-   parent_roadmap: <parent-slug>      # back-link to source
-   ---
-
-   # Roadmap: Follow-up to <parent-title>
-
-   > <One sentence stating the carried-over outcome.>
-
-   ## Context
-
-   This roadmap collects items deferred from
-   [`agents/roadmaps/archive/<parent-slug>.md`](archive/<parent-slug>.md).
-   See the parent's archive entry for the original rationale.
-
-   ## Prerequisites
-
-   - [ ] Read `AGENTS.md` and the parent archive entry.
-   {parent prerequisites still relevant, copied verbatim}
-
-   <!-- Option 2 only — body note, NOT a frontmatter key: -->
-   > Blocked until <condition>. Execution starts when the condition clears.
-
-   ## Phase 1: <name carried from parent>
-
-   - [ ] {deferred step text, copied verbatim with parent-phase pointer}
-   {repeat per deferred item, regrouped by parent phase}
-
-   ## Acceptance Criteria
-
-   - [ ] {restate or adjust per the deferred scope}
-   - [ ] All quality gates pass — see `quality-tools`.
-   ```
-
-3. **In the parent roadmap** (still in the working tree), append a
-   line at the bottom (above any final `---`):
-
-   ```
-   <!-- Deferred items migrated to agents/roadmaps/<followup-slug>.md on YYYY-MM-DD -->
-   ```
-
-   Do **not** delete the `[~]` lines — keep them visible in the
-   archived parent so the trail stays grep-able. The follow-up
-   carries forward the executable copy.
-
-4. **Regenerate the dashboard.** The follow-up appears (draft hidden,
-   ready visible) and the parent — once moved — drops off.
-
-5. **Archive the parent** (`git mv` → `archive/`) and regen one
-   more time per [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
-   Iron Laws 1 + 3.
-
-5. **Move the file** with `git mv` so history is preserved:
-
-   ```bash
-   # Archive (work was done)
-   git mv agents/roadmaps/{file} agents/roadmaps/archive/{file}
-
-   # Skipped (not pursuing)
-   git mv agents/roadmaps/{file} agents/roadmaps/skipped/{file}
-   ```
-
-6. **Regenerate the dashboard** (see "Command" below). The moved roadmap is
-   excluded from the active set once it sits in `archive/` or `skipped/`.
-
-### When to use `skipped/` vs `archive/`
-
-| Situation | Destination |
-|---|---|
-| Finished all phases | `archive/` |
-| Finished some phases, rest deferred/cancelled on purpose | `archive/` |
-| Whole roadmap deferred or cancelled (no `[x]` at all) | `skipped/` |
-| Never started, scope decision reversed | `skipped/` |
-| Superseded by another roadmap | `skipped/` — add a pointer line at the top: `> Superseded by agents/roadmaps/{other}.md` |
-| Research proved the direction wrong | `skipped/` — add a 1-line reason at the top |
-
-If in doubt: archive beats skipped. `skipped/` is reserved for roadmaps where
-no meaningful work was invested and the scope itself was rejected.
-
-## Progress dashboard — `agents/roadmaps-progress.md`
-
-A generated dashboard aggregates progress across every open roadmap. It sits at
-`agents/roadmaps-progress.md` (outside `roadmaps/` to keep the folder clean) and
-is rewritten by `.augment/scripts/update_roadmap_progress.ts`.
-
-**Always regenerate in the SAME response** after any of the following
-(enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)):
-
-- Creating a new roadmap (`/roadmap:create`)
-- Marking a step `[x]`, `[~]`, or `[-]` during `/roadmap:process-*`
-- Archiving or moving a roadmap to `skipped/`
-- Adding, renaming, or removing a phase
-
-Command:
-
-```bash
-./agent-config roadmap:progress           # rewrite the dashboard
-./agent-config roadmap:progress-check     # CI: fail if stale
-```
-
-The `./agent-config` wrapper lives in the project root (written by the
-package installer, gitignored) and delegates to the master CLI inside
-`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
-No global tooling required.
-
-The dashboard is a **read-only snapshot**. Do not edit it by hand — regenerate it.
-
-### Blockers on the dashboard
-
-The overview table's `Blocker` column counts each roadmap's open
-`## Blockers` entries (or the legacy `> Blocked until` note) and links
-to the per-roadmap breakdown, which lists every open blocker with
-owner, blocked scope, and full instructions. Authoring shape:
-[`templates/roadmaps.md` rule 20](../../agent-src/templates/roadmaps.md);
-authoring guidance: [`roadmap-writing § 5b`](../roadmap-writing/SKILL.md).
-Clearing a blocker flips its `Status: resolved` and regenerates the
-dashboard in the same reply, same cadence as a checkbox flip. The
-blocker entry is also the canonical **awaiting-evidence** signal —
-see [§ Awaiting evidence](#awaiting-evidence--a-blocker-entry-never-a-new-glyph).
+| Author a roadmap — structure and the rules it must satisfy | [`references/authoring.md`](references/authoring.md) | The canonical structure block, checkbox semantics, awaiting-evidence as a blocker entry, phases, quality gates, step granularity, language |
+| Create, execute, or resume a roadmap | [`references/lifecycle.md`](references/lifecycle.md) | Creating a roadmap, executing one step by step, resuming a partially-done one |
+| Complete, archive, or skip a roadmap | [`references/archival.md`](references/archival.md) | The four end states, the archival sweep and its manual fallback, spawning a follow-up from deferred items, `skipped/` versus `archive/` |
+| Regenerate or read the progress dashboard | [`references/dashboard.md`](references/dashboard.md) | The generated dashboard, its regeneration cadence, blockers on the dashboard |
+
+Archival is the mode with the sharpest failure: an archive that buries deferred
+work or open blockers is the thing the sweep refuses to do, so load
+[`references/archival.md`](references/archival.md) before archiving anything
+rather than working from memory of it.
 
 ## Rubric pass (optional, surfacing-only)