Framework: FORGE

Output verbosity (Spec 225): At the start of execution, read forge.output.verbosity from AGENTS.md (default: lean). In lean mode, suppress non-actionable diagnostic output (passing-gate confirmations, KPI tables, calibration deltas, MCP pin status, deprecation scans, signal-by-signal pattern dumps, root-cause groupings, deferred-scope aging when none aged, score-rubric details when unchanged) — write the full content to its file artifact (session log, pattern-analysis.md, etc.) and emit a one-line pointer in chat (or omit entirely if purely informational). In verbose mode, emit full detail as before. Never suppressed in either mode: choice blocks, FAILed gates, push-confirmation prompts, Review Brief "Needs Your Review" items, operator-input prompts, error/abort messages. See docs/process-kit/output-verbosity-guide.md for the full rules and worked examples.

Update and present the prioritization matrix.

If $ARGUMENTS is ? or help: Print:

/matrix — Update and present the full prioritization matrix.
Usage: /matrix
No arguments accepted.
Behavior: Reads backlog and rubric, verifies score arithmetic, detects manual
  overrides vs errors, syncs spec frontmatter, detects status discrepancies,
  re-scores promoted specs, evaluates strategic fit (Spec 110), checks review
  velocity for cognitive debt (Spec 128), recommends sprint bundles, presents
  ranked tables, writes corrections on confirmation.
  When ≥2 dependency-clean parallel-safe lanes exist, Step 11 emits an
  execute-all choice block constructing a `/parallel --batch` command
  spanning all dependency-clean lanes forward (Spec 362).
See: docs/backlog.md, docs/process-kit/scoring-rubric.md

Stop — do not execute any further steps.

Spec 254 — Approach D (Derived view): As of Spec 254, the authoritative source for backlog content is per-spec frontmatter under docs/specs/NNN-*.md. The ranked table portion of docs/backlog.md is regenerated by ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/render_backlog.py. Operator-curated content (Last-updated history, Sprint plan, Deferred Scope) lives in separate sibling files (docs/backlog-history.md, docs/backlog-deferred.md) post-migration. /matrix continues to read docs/backlog.md (which includes the rendered table) for context, and Step 13 below regenerates the table portion via the renderer. See docs/process-kit/derived-view-rendering-guide.md for the operator visibility model.

1. Backlog rows (Spec 399): Run ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/derived_state.py --get-backlog --format=json. Parse the stdout as JSON; the array contains all backlog rows with keys rank, spec_id, title, bv, e, r, sr, score, depends, status. (Helper internalizes mode-detection; do not open docs/backlog.md directly. The helper reads per-spec frontmatter, so any frontmatter edits by /matrix are reflected immediately on subsequent reads.)
2. Read docs/process-kit/scoring-rubric.md. 3a. Input range validation (Spec 148): Before computing scores, validate that each BV, E, R, SR value in every backlog row is an integer between 1 and 5 inclusive. If any value is outside this range, flag it as an input error: "[dimension] must be 1-5 (got [value]) in Spec NNN". Report all input errors before proceeding to arithmetic checks. Do not compute scores for rows with invalid inputs.
3. Score integrity check: For every row in the backlog, recompute the total from BV/E/R/SR using the formula in docs/process-kit/scoring-rubric.md. Report any mismatches:
   • If the BV/E/R/SR values match between spec frontmatter and backlog but the total is wrong → arithmetic error: auto-correct the total immediately (no human confirmation needed). Report what was corrected: "Auto-corrected Spec NNN: listed=X, computed=Y (BV=a E=b R=c SR=d)."
   • If the BV/E/R/SR values differ between spec frontmatter and backlog → manual override detected (flag for human review — may indicate a formula revision need). Do NOT auto-correct these.
4. Frontmatter sync: For each draft/approved spec in the backlog, read the spec file's Priority-Score: frontmatter and compare BV/E/R/SR values against the backlog row. Report discrepancies as a separate section before rankings.
5. Status sync check (Spec 028 — authoritative source enforcement): The spec file Status: field is the single authoritative source of truth for spec status. For each spec in docs/specs/README.md: a. Read the spec file's Status: frontmatter field. b. Compare to README.md index row status. c. Compare to backlog table status. d. If discrepancy found: report as:

   STATUS DRIFT — Spec NNN:
     Spec file (authoritative): implemented
     README.md: draft          ← needs update
     backlog.md: in-progress   ← needs update

   e. On confirmation (step 9), auto-correct README.md and backlog.md to match spec file.
   • Do NOT auto-correct spec file — it is authoritative. If spec file and README/backlog disagree, spec file wins.
   • If drift is found: flag as a process defect: "STATUS DRIFT detected — derived views are out of sync with spec files."
6. Re-score any spec whose status changed to draft (SR likely increased — recalculate and note the delta).

7. Dependency analysis (Spec 087): For each non-closed spec, read its Dependencies: frontmatter field (comma-separated spec IDs) or the Depends column in the backlog table. Classify each spec:

   • Blocked: has a dependency on a spec that is NOT closed. List which dependency is unmet.
   • Ready: all dependencies are closed (or no dependencies). Can be implemented now.
   • Parallel-safe batch: ready specs whose Implementation Summary → Changed files lists have no overlapping paths and that do not both plausibly touch a member of the always-shared / cross-cutting file set (Spec 478). These can be implemented simultaneously in parallel worktrees.
     • Always-shared set (Spec 478): the canonical cross-cutting set is defined in docs/process-kit/parallelism-guide.md § "Always-shared / cross-cutting file set" (the Spec 237 orchestrator-only table plus the update-manifest pair .forge/update-manifest.yaml + template/.forge/update-manifest.yaml). Reference that single source — do NOT hard-code a second list here. A spec is manifest-touching if its declared Changed-files include any template/ path (it will trigger /implement Step 4e) or it declares a manifest path explicitly. Two specs that are declared-file disjoint but both manifest-touching (or where one declares an always-shared member) are NOT fully disjoint — surface a soft-overlap warning rather than declaring them parallel-safe. This does not block batching (additive manifest entries merge cleanly); it prevents a false zero-overlap guarantee.

   Completion-evidence isolation (Spec 501). This classification reads other specs' status only as a dependency gate — never as evidence that the spec under assessment is itself complete. Whether spec X is complete or close-ready is decided solely from X's own ACs and its own Status: field, read from docs/specs/<X>-*.md (authoritative per Spec 028). A different spec's number, status, or closure is NEVER completion evidence for X.

   • Dependency vs. unrelated discriminator (the operational rule). Spec Y is a dependency of X only if Y's number appears in X's own Dependencies:/Depends: frontmatter (the field this step already reads). When such a Y becomes closed, that legitimately moves X Blocked → Ready — but it MUST NOT be read as X itself being complete/closeable. Any other spec Y whose number/closure is in play — because X's body once referenced it, it shares a neighboring number, or it is the prior occupant of a reused/recycled number that now points to an unrelated closed spec — is unrelated for completion purposes: it is not in X's Dependencies: field, so its closure is never X's dependency-satisfaction and never X's completion. A reused/recycled dependency number MUST NOT silently satisfy X's dependency or imply X is done — surface it via the Spec 501 advisory below rather than treating the closed number as evidence.
   • Advisory (Spec 501, non-blocking). When X would be treated as complete or close-ready on the basis of another spec's closure or a reused/neighboring spec number, emit one advisory line: Spec <X> appears complete only via Spec <Y>'s closure — judge <X> from its own ACs/status, not Spec <Y>. The advisory does not auto-edit status, does not gate ranking, and does NOT fire for a legitimate frontmatter-declared dependency (by the discriminator above, that Y is not unrelated). Every spec ID reasoned over here is a canonical numeric ID (matching ^[0-9]{3,}$) already sourced from FORGE's own frontmatter / derived-state helpers — never an identifier parsed out of spec body prose, and never fed into a shell expansion, grep pattern, or file glob.

   Present a dependency summary before the ranked tables:

   ## Dependency status
   Blocked: Spec NNN (waiting on NNN), ...
   Ready: Spec NNN, NNN, NNN
   Parallel batch: Specs NNN + NNN (no shared files)
   Soft-overlap (Spec 478): Specs NNN + NNN are declared-file disjoint but both manifest-touching (`.forge/update-manifest.yaml`) — parallel-OK, expect an additive merge touch.

   (Omit the Soft-overlap line when no always-shared overlap exists.) If no specs have dependencies defined, skip this section silently.

7e. Vet-pending advisory (Spec 395 AC 12): Scan docs/specs/[0-9][0-9][0-9]-*.md files for frontmatter containing Consensus-Status: vet-pending. Compare today's date against the universal SLA date 2026-06-02 (set by Spec 395 Backfill section).

• If today is on or after 2026-06-02 AND N >= 1 vet-pending drafts exist: emit one line N drafts vet-pending past 2026-06-02 SLA — vet-now-or-set-Consensus-Exempt at /implement.
• Pre-SLA (before 2026-06-02): silent regardless of count.
• Zero vet-pending drafts: silent.
• This is advisory only — /matrix does not auto-block ranking. Operators can run /consensus NNN to vet, or set Consensus-Exempt: <reason> in the spec frontmatter to bypass the gate at /implement time.

8. Strategic fit evaluation (Spec 110, extended by Spec 363, sentinel-aware via Spec 382): a. Read the project's CLAUDE.md — extract the project description and mission statement (the first paragraph or "## What this project is" section). b. Read AGENTS.md — check for forge.strategic_scope config under ## Project Context. Use the yaml-aware helper at ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/strategic-scope.py to read the value (NOT regex on raw text — fragile against block-scalar variants per Spec 382 AC6):

   # Capture exit code AND stderr separately so a helper *crash* is surfaced, not swallowed (Spec 419).
   # Discriminator: non-zero exit WITH stderr = real failure (crash / missing PyYAML / Python <3.10 / bad
   # usage — all emit stderr). Non-zero exit with EMPTY stderr = forge.strategic_scope simply absent
   # (read_scope → None) = the expected b2 fall-through below, NOT a failure.
   _scope_err="${TMPDIR:-${TEMP:-/tmp}}/forge-strategic-scope-err.$$"
   strategic_scope_value=$(${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/strategic-scope.py read AGENTS.md 2>"$_scope_err")
   strategic_scope_rc=$?
   strategic_scope_stderr=$(cat "$_scope_err"); rm -f "$_scope_err"
   if [ "$strategic_scope_rc" -ne 0 ] && [ -n "$strategic_scope_stderr" ]; then
     echo "⚠ Step 8 — strategic-scope.py FAILED (exit $strategic_scope_rc) — helper CRASH, not an unconfigured-scope skip:"
     printf '%s\n' "$strategic_scope_stderr" | sed 's/^/      /'
     echo "      → Helper: ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/strategic-scope.py | Strategic-fit eval is being skipped due to FAILURE, not configuration. Do NOT treat the backlog as fully vetted — investigate (missing PyYAML, Python <3.10, file/encoding error, or helper bug) before trusting the ranking."
     strategic_scope_value=""
   fi
   # NOTE (Spec 419 known limitation): a *malformed* YAML block is swallowed by strategic-scope.py read_scope
   # (catches yaml.YAMLError → returns None → exit 1, empty stderr), so it is indistinguishable from "absent"
   # here and is NOT surfaced. Distinguishing it needs a dedicated helper exit code — out of scope (SIG-419-A).

   b1. SKIP-FOR-NOW sentinel check (Spec 382): if the value equals literal SKIP-FOR-NOW (verifiable via ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/strategic-scope.py is-sentinel AGENTS.md), emit the one-line warning and skip the strategic-fit eval entirely:

   ⚠ Step 8 — Strategic scope not yet customized (SKIP-FOR-NOW). Fill forge.strategic_scope in AGENTS.md to enable scope-fit evaluation. Skipping Step 8.

   Do NOT classify any spec as scope-creep against the sentinel. Proceed to step 9. b2. If present (and not the sentinel), use the value as the strategic scope definition. If absent, infer scope from CLAUDE.md's project description. b2. Aging-draft pre-pass (Spec 363): Before classifying, scan every Status: draft spec for valid-until: YYYY-MM-DD in frontmatter. Specs whose valid-until: is populated AND past today are pre-flagged as expired and added to the strategic-fit table (step e) regardless of their on-mission classification — explicit operator engagement (renewal via /revise or direct edit, OR deprecation via this flow) is the renewal mechanism. Drafts lacking valid-until: (pre-backfill state) are NOT pre-flagged — they pass through normal on-mission classification only. Mixed states are handled per-spec. c. The strategic fit test: For each draft spec, ask: "Does this spec's objective directly improve the project's core workflow loop as described in CLAUDE.md / forge.strategic_scope?" If the spec builds runtime infrastructure, a separate product, or features that belong in another tool (e.g., an MCP server, an IDE extension), it fails the test. d. Classify each draft spec:

   • on-mission — directly improves the core workflow (spec lifecycle, gates, evidence, process enforcement)
   • borderline — useful but expands scope beyond the core loop (may be worth keeping with scope adjustment)
   • scope-creep — building a different product or feature that belongs elsewhere
   • expired — valid-until: past today (Spec 363); operator decision needed: renew via /revise, deprecate, or reclassify. May coincide with any of the above; expired status takes precedence in the table. e. Present a Strategic Fit table (per Spec 363, expired drafts surface here as a row alongside scope-creep candidates — same dispositions, no new column):

   ## Strategic Fit Review
   | Spec | Title | Classification | Rationale |
   |------|-------|----------------|-----------|
   | NNN  | ...   | on-mission     | Improves gate integrity via ... |
   | NNN  | ...   | scope-creep    | Builds a runtime scheduler — belongs in a separate product |
   | NNN  | ...   | expired        | valid-until: YYYY-MM-DD past today; renew via /revise or deprecate |

   f. For each scope-creep OR expired spec, recommend a disposition:

   • deprecate — not worth doing in any project (rare for scope-creep; common for expired drafts whose moment has passed)
   • defer-to-<project> — belongs in a specific other project (e.g., defer-to-mcp-server)
   • reclassify — scope can be narrowed to fit (explain how)
   • renew (Spec 363, expired-only) — operator wants to keep working it: run /revise NNN to refresh valid-until: (default today + 90), or edit the field directly. The renewal signal IS the explicit /revise invocation or operator edit. g. Human confirmation gate: Present dispositions and ask for confirmation before applying. The operator can:
   • Confirm all dispositions
   • Override individual classifications (e.g., "keep 094 as draft — I want it here")
   • Skip the strategic fit review entirely ("skip fit") h. On confirmation: update each scope-creep spec's status to deprecated (scope-creep → <disposition>) in the spec file, README.md, and backlog.md. Add a revision log entry: YYYY-MM-DD: Deprecated via /matrix strategic fit review — <rationale>.

   If forge.strategic_scope is absent from AGENTS.md and CLAUDE.md has no clear mission statement, skip this step with a note: "Strategic fit review skipped — no forge.strategic_scope config or CLAUDE.md mission statement found. Add forge.strategic_scope to AGENTS.md to enable."

9. Review Velocity Check (Spec 128 — cognitive debt guardrail, recalibrated by Spec 158): a. Read AGENTS.md — extract forge.review_velocity.threshold (default: 0.6) and forge.review_velocity.window (default: 5). b. Identify specs closed in the last N sessions (where N = window). Read each session log in docs/sessions/ sorted by date descending, collecting spec IDs mentioned as closed. c. For each closed spec, read its ## Evidence section. A spec has "human review evidence" if its Evidence section contains non-placeholder content (not just (pending implementation) or empty bullets). d. Compute: debt_ratio = specs_without_evidence / total_closed_specs. e. If debt_ratio > threshold, emit a warning section:

   ## Review Velocity — COGNITIVE DEBT WARNING
   
   N of M recently closed specs lack human review evidence.
   Specs without evidence: NNN, NNN, NNN
   Threshold: X% (configured in AGENTS.md forge.review_velocity.threshold)
   
   Evidence presence is what matters — closure speed is not a concern.
   Closing 5+ specs in one session is normal for AI-assisted work.

   f. If debt_ratio <= threshold or no specs were closed in the window, emit:

   ## Review Velocity
   Review velocity OK — N of M recently closed specs have human review evidence.

10. Present the full ranked backlog in two tables (process improvement + application/infrastructure), sorted by score descending within each table. Include a Depends column showing dependency spec IDs (or "—") for non-closed specs. Include a TC column showing the Token-Cost indicator ($, $$, $$$, or ? if not set) for non-closed specs. Exclude deprecated specs from the ranked tables (show them in a separate "Deprecated" section below).
11. Sprint lane planning (Spec 156, replaces effort-tier bundles): From on-mission, ready (not blocked) draft specs, construct a dependency-chain sprint plan:

a. Identify dependency chains: Trace all dependency sequences in the backlog (Spec A → B → C where each depends on the previous). Use the Depends column from Step 7 and spec frontmatter Depends: fields.

b. Identify the critical path: Find the longest dependency chain by cumulative E score. Label it explicitly in the output.

c. Group into thematic lanes: Group remaining ready specs (not on the critical path) into thematic bundles based on functional area. Infer theme from spec titles, scope sections, and file overlap analysis (from Implementation Summary → Changed files). Name lanes descriptively (e.g., "Lane 1: Scoring & Calibration", "Lane 2: Session Automation") — not by effort tier.

d. Assign to sprints: Place specs into sprints respecting dependency ordering: - A spec with Depends: NNN where NNN is in Sprint 1 must be in Sprint 2 or later. - Within a sprint, specs in different lanes have no dependency conflicts and no file overlap — they can execute concurrently. - Within a lane, specs may be sequential (dependency chain) or parallel (independent, no file overlap).

e. File-scope isolation check: For specs assigned to the same sprint in different lanes, read each spec's Implementation Summary → Changed files and check for overlapping paths. If a declared path overlaps, flag it as a hard conflict: "File overlap between Spec NNN and NNN on <path> — cannot run in parallel. Move one to a later sprint or sequential lane." - Always-shared / cross-cutting scan (Spec 478): Declared-file disjointness alone does NOT establish parallel-safety, because /implement touches cross-cutting files implicitly. After the declared-path check, also test each same-sprint cross-lane pair against the always-shared set defined in docs/process-kit/parallelism-guide.md § "Always-shared / cross-cutting file set" (the Spec 237 orchestrator-only table plus the update-manifest pair .forge/update-manifest.yaml + template/.forge/update-manifest.yaml). Reference that canonical set — do NOT duplicate it here. If both specs plausibly touch an always-shared file (both declare a template/ path → both touch the manifest pair via /implement Step 4e; or either explicitly declares a member of the set), surface a soft-overlap warning — do NOT silently declare them disjoint: "Soft overlap (Spec 478): Spec NNN and NNN both touch <always-shared path> implicitly — parallel-safe with an expected additive merge touch, not zero-overlap." This warns without blocking (additive shared-file edits merge cleanly per Req 3). A hard declared-path overlap still blocks; a soft always-shared overlap only annotates.

f. Token cost flagging (Spec 158): For any spec with Token-Cost: $$$ in its frontmatter, add a note: "High token cost — consider whether a cheaper approach exists before implementing."

g. Output the sprint table:

## Sprint Plan

**Critical path**: Spec NNN → NNN → NNN (cumulative E=N)

| Sprint | Lane | Specs | TC | Notes |
|--------|------|-------|----|-------|
| 1 | Lane 1: <theme> | NNN | $ | Critical path start |
| 1 | Lane 2: <theme> | NNN, NNN | $$, $ | `/parallel NNN NNN` |
| 2 | Lane 1: <theme> | NNN | $$ | Needs NNN from Sprint 1 |
| 2 | Lane 2: <theme> | NNN | $$$ | High token cost |

### Deferred
| Spec | Title | Blocked by | Reason |
|------|-------|-----------|--------|
| NNN | ... | NNN | Dependency not yet closed |

### Future
| Spec | Title | Score | Reason |
|------|-------|-------|--------|
| NNN | ... | NN | Low priority, no clear sprint assignment |

h. For lanes containing 2+ independent specs (no dependencies between them, no file overlap), suggest a /parallel command: "/parallel NNN NNN".

i. The operator can select a sprint to begin. Report: "Selected Sprint N. Starting with Spec NNN — run /implement NNN or /parallel NNN NNN for parallel lanes."

j. Execute-all choice block (Spec 362): After the sprint plan table, count "dependency-clean parallel-safe lanes" — lanes whose specs are all draft/approved (not blocked by un-closed dependencies) AND have no declared-file overlap with any other lane's specs across the entire plan (not just within their own sprint). If this count is ≥ 2, emit a choice block; if < 2, skip silently (the existing single-lane suggestion in the Notes column is sufficient — Req 7). - Always-shared / cross-cutting note (Spec 478): An always-shared overlap (per the canonical set in docs/process-kit/parallelism-guide.md § "Always-shared / cross-cutting file set" — the Spec 237 orchestrator-only table plus the update-manifest pair) is a soft overlap: it does NOT disqualify a lane from the execute-all batch (additive shared-file edits merge cleanly), but it MUST be surfaced. When constructing the batch, if any two included lanes both plausibly touch an always-shared file, add a one-line note above the choice block: "Soft-overlap (Spec 478): lanes <L> and <M> both touch <always-shared path> — batch is parallel-safe with an expected additive merge touch." Only a hard declared-file overlap excludes a lane from the batch.

  ```
  Execute multiple lanes? Spec 362 added a /parallel --batch path that
  sequences all dependency-clean lanes forward in dependency-respecting order.
  ```

  <!-- safety-rule: session-data — /matrix is a planning command and does not synthesize session data; the safety rule does not fire here in practice. The token is present to satisfy the Spec 320 Req 4 lint and document that the rule was considered. -->

  > **Choose** — type a number or keyword:
  > | # | Rank | Action | Rationale | What happens |
  > |---|------|--------|-----------|--------------|
  > | **1** | 1 | `execute-all` | Multiple ready lanes; batch save N close-all loops | Construct `/parallel --batch '<lane1>' '<lane2>' ...` spanning all dependency-clean lanes forward (Sprint 1 first, then Sprint 2 lanes after their deps clear, etc.). Display the constructed command. Operator confirms by typing the command (no native invoke primitive — operator-mediated handoff per Req 6). |
  > | **2** | 2 | `manual` | Existing flow; pick one lane | Operator picks one lane from the table (existing behavior) |
  > | **3** | — | `stop` | Defer execution decision | End /matrix without proposing a specific run |

  **Construction rules** (Req 6):
  - Lanes appear as bundles in the constructed command IN DEPENDENCY-RESPECTING ORDER. Sprint 1 dependency-clean lanes go first, then Sprint 2 lanes whose dependencies are scheduled in Sprint 1 (so they'll close before Sprint 2 dispatches), then Sprint 3, etc.
  - Each lane becomes one single-quoted bundle string: `'NNN MMM'` (space-separated spec IDs).
  - Lanes whose dependencies are NOT yet closed AND NOT scheduled earlier in the constructed batch are EXCLUDED from the command.
  - **Completion-evidence isolation (Spec 501).** A lane's spec is treated as ready-to-run **solely** from its own `draft`/`approved` `Status:` (read from its own file) — never because a neighboring or reused spec number is `closed`. No spec is dropped from (or kept out of) the batch on the basis of another spec's closure being read as that spec's own completion: a closed unrelated/recycled number is NOT evidence that the spec under assessment is "already done." The only legitimate cross-spec read here is a frontmatter-declared dependency that has closed (which makes the lane dependency-clean per the rule above) — that does NOT mark the lane's own spec complete. If a lane's spec would be excluded as "already done" on the basis of another spec's closure, emit the Spec 501 advisory (`Spec <X> appears complete only via Spec <Y>'s closure — judge <X> from its own ACs/status, not Spec <Y>.`) and keep the lane judged by its own status.
  - The operator's selection of `execute-all` is the operator's confirmation to run the displayed command verbatim — `/matrix` does not auto-execute.

Step 11b — Review Router (Spec 159)

After generating the sprint plan (Step 11) but before presenting highlights (Step 12), run the review router on the sprint plan:

a. Select perspectives: COO (always — process efficiency of sprint sequencing) + CTO (always — architectural coherence of lane groupings). Add CFO if any $$$ specs are in the plan. b. Display selection rationale. c. Run selected perspectives on the sprint plan as a whole — focus on lane assignments, sequencing decisions, and parallel groupings. d. Present the Review Brief after the sprint table. e. BLOCK is advisory — the operator decides whether to adjust the plan.

12. Highlight:

• The top-ranked spec not yet approved (recommend it as next to approve)
• Any spec that moved rank since the last update
• Any proposed spec that is now blocked or unblocked by a recently completed spec
• Blocked specs that cannot be implemented until their dependencies close
• Completion-evidence isolation (Spec 501). Any "complete", "done", or "ready to close" language in this narrative MUST reflect only each spec's own ACs/status (read from its own file, authoritative per Spec 028) — never another spec's number, status, or closure. Do NOT narrate spec X as complete because a related, neighboring, or reused spec number Y closed: a closed Y is, at most, a frontmatter-declared dependency that unblocks X (Blocked → Ready) — which is not the same as X being complete. When X would be narrated as complete on the basis of another spec's closure or a reused/neighboring number, emit the advisory instead: Spec <X> appears complete only via Spec <Y>'s closure — judge <X> from its own ACs/status, not Spec <Y>. (non-blocking; does not auto-edit status). The only spec IDs reasoned over are canonical numeric IDs (^[0-9]{3,}$) from FORGE's own frontmatter / derived-state — never body-parsed identifiers, and never fed into a shell expansion, grep, or glob. 12a. Pre-flight recommendation (Spec 321): For the top-ranked draft spec from Step 12, read its frontmatter Consensus-Review: and parse the Priority-Score: HTML comment for E and R values (format: <!-- BV=N E=N R=N SR=N → ... -->). If Consensus-Review: true AND (R >= 3 OR E >= 3), emit one inline advisory alongside the top-rank presentation:

> **Pre-flight recommendation**: Spec NNN is flagged `Consensus-Review: true` with R=<N> / E=<N>. Run `/consensus NNN` before `/implement` — CI-210 documents concrete rework avoidance on similar specs (Spec 294 saved ~45 files of rework). _(Advisory only — operator can skip.)_

Skip silently if (a) the Priority-Score: comment is missing or unparseable, (b) Consensus-Review: is absent or any value other than literal true, or (c) both R < 3 AND E < 3. The advisory is non-blocking and prompt-level — it does not gate /implement.

Dispatch-gate pointer (Spec 590): when this advisory fires, append one sentence naming the downstream consequence — /parallel Step 2c will not dispatch a Consensus-Review: true spec that has no recorded consensus:

Spec NNN will also be halted at /parallel dispatch by the Step 2c consensus gate until /consensus NNN runs or Consensus-Exempt: is set (Spec 590).

Pointer only — /matrix performs no predicate evaluation of its own and this adds no new logic here. The authoritative check lives in /parallel Step 2c and /implement Step 0d.

12b. Hygiene Pass (Spec 370):

>>> spec-370 hygiene-pass

HYGIENE PASS — Two scans for backlog hygiene. Run after rank/score refresh and Step 12a pre-flight, before Step 13 exit-gate. Skip silently if neither scan surfaces candidates.

1. Deprecation candidates scan: For each Status: draft spec, qualify as a deprecation candidate when both signals hold:
   • valid-until: in frontmatter is populated AND past today (Spec 363 detector).
   • Backlog row rank has been ≥ 30 for ≥ 30 days (bottom-of-backlog dwell). Both signals required to avoid false positives on actively-revised drafts.
2. Deferral candidates scan: For each Status: draft spec, read Dependencies: field. If any named dependency spec's Status: is deferred or deprecated (verified by reading the dependency spec file directly), qualify as a deferral candidate. Inferred re-activation trigger: <dependency-spec-id> closes (operator can override).
3. Idempotency filter: Exclude:
   • Specs already Status: deprecated (deprecation scan).
   • Specs whose Revision Log contains Deferred via /matrix hygiene pass within last 30 days (deferral scan).
4. Overflow handling: If combined candidate count > 10, emit a summary count line first ("Hygiene Pass: N deprecation, M deferral candidates — review which?") so operator picks a category (or both, or skip) before facing the full inventory.
5. Choice Block: Emit candidates with one row per candidate (max 10 per category, paginated). Operator chooses: apply all / pick <indices> / skip / view detail <index>. skip is rank 1 by default — operators running /matrix purely for rank refresh continue to the exit-gate.
6. Disposition (deprecate): update spec frontmatter Status: deprecated + Closed: <today>, append Revision Log "YYYY-MM-DD: Deprecated via /matrix hygiene pass — <reason>." Update README.md status row, backlog.md row marker → ✅ deprecated, append CHANGELOG entry.
7. Disposition (defer): prompt for re-activation trigger; skip-on-empty default — if operator provides empty input or declines, that candidate's deferral is skipped (other candidates still apply). On non-empty trigger: append Revision Log "YYYY-MM-DD: Deferred via /matrix hygiene pass — <reason>. Re-activation trigger: <trigger>." Update backlog row note. Status stays draft.
8. Engagement signal: /close captures apply-rate vs skip-rate per category to docs/sessions/signals.md for next /evolve cycle.

See: docs/process-kit/backlog-hygiene-guide.md — canonical source.

<<< spec-370 hygiene-pass

13. Ask for confirmation, then:

• Write-side mode check (Spec 399): Before any canonical-table-row write, run ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/derived_state.py --skip-canonical-write. Read stdout: if skip, do NOT write status corrections or manual-override resolutions to docs/backlog.md — the canonical artifact is renderer-owned in split-file mode and the writes happen via the renderer in step 261-269 below (status auto-corrections become spec-frontmatter edits, which the renderer picks up on next render). If stdout is proceed, perform the canonical writes (Phase 1 dual-write behavior). If the helper exits nonzero, abort the canonical-write step entirely and surface stderr — do NOT default to either behavior.
• Write status corrections and manual-override resolutions to docs/backlog.md (arithmetic score errors were already auto-corrected in step 3 — manual overrides require human decision here) — but ONLY if the skip-canonical-write check above returned proceed.
• Write strategic fit dispositions (if confirmed in step 8g)
• Update the Last updated: field to today's date
• Spec 254 — Regenerate canonical table (mode=generated only): After spec-file edits land, invoke ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/render_backlog.py --output docs/backlog.md to refresh the generated table portion of the canonical artifact. Skip silently if the project is on mode=delete or pre-Spec-254 monolithic format (no sentinel markers in docs/backlog.md).
• Spec 398 — Split-file rendering (when docs/.generated/ directory exists): renderers always write to docs/.generated/<artifact>.md (no mode-detection on curated parents). After all 3 renders, invoke the assembler for interactive operator stdout view. Skip the Spec 254 mode=generated path above (split-file supersedes it for migrated projects):

  ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/render_backlog.py --mode=split-file
  ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/render_changelog.py --mode=split-file
  ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/render_spec_index.py --mode=split-file
  ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/assemble_view.py docs/backlog.md

  If docs/.generated/ does NOT exist, fall back to the Spec 254 Phase 1 mode-detection above. Curated parents are NEVER opened by /matrix in split-file mode.

[mechanical] Next action

After corrections are written, present a context-aware next action:

• If rank order changed: "Next: review the new top-ranked spec — run /implement next to pick it up."
• If status discrepancies were found: "Next: resolve the status discrepancies above, then run /implement next."
• If a sprint was selected: "Next: implement Sprint N — run /implement NNN to start, or /parallel NNN NNN for parallel lanes."
• If no changes needed: "Backlog is current. Next: run /implement next to continue building."