@zigrivers/scaffold 3.29.0 → 3.31.0

package/content/guides/review-workflow/index.md

@@ -0,0 +1,248 @@
+---
+title: The Code-Review Workflow
+topic: review-workflow
+description: When and how to run multi-model review — entry points, input modes, verdicts, the round limit, and degraded mode
+category: workflows
+order: 30
+---
+
+## What this guide covers
+
+This is the **workflow** around multi-model review: *when* to review, *which*
+entry point to reach for, *which* input mode matches your target, how to read
+the verdict, and how the fix loop is bounded. It does **not** re-explain the
+review engine itself — channels, reconciliation, the `finding_key`, the verdict
+algorithm, and `.mmr.yaml` all live in the [MMR reference](../mmr/index.md).
+Read that guide for "what is a channel"; read this one for "I have a change, now
+what do I run."
+
+:::callout{type=tip}
+**Two layers.** `mmr review` is the engine. `scaffold run review-pr` and
+`review-code` are *workflow wrappers* on top — they pick the input mode, add the
+Superpowers code-reviewer agent channel via `mmr reconcile`, handle auth
+recovery, and bound the fix loop. `post-implementation-review` is a separate,
+release-time full-codebase review with its own flow (see Step 1). This guide is
+about driving those entry points; the engine details are in
+[the MMR reference](../mmr/index.md).
+:::
+
+## Step 1 — Pick the entry point
+
+Two of these are wrappers over `mmr review` — `review-pr` and `review-code` —
+sharing the same engine and verdict semantics, differing in *scope* and *what
+they synthesize*. `post-implementation-review` is **not** a `mmr review` wrapper:
+it's an independent release-time review of the whole codebase that runs its own
+channel flow and writes its own report under `docs/reviews/`, with MMR
+reconciliation only as an optional add-on. Consult its own doc for specifics.
+
+```mermaid
+flowchart TD
+  Q{What are you reviewing?} --> A[An open PR]
+  Q --> B[Local changes
+before commit/push]
+  Q --> C[The whole codebase
+after all tasks land]
+  A --> AR["scaffold run review-pr
+(mmr review --pr N)"]
+  B --> BR["scaffold run review-code
+(synthesized delivery candidate)"]
+  C --> CR["scaffold run post-implementation-review
+(two-phase: systemic + per-story)"]
+```
+
+| Entry point | Target | Notes |
+| --- | --- | --- |
+| `scaffold run review-pr` | One PR (`--pr N`, auto-detected from the branch) | **MMR wrapper.** Adds auth checks, the Superpowers agent channel, the per-finding round bookkeeping, an opt-in Beads bridge over a bare `mmr review`. |
+| `scaffold run review-code` | Local pre-push: committed branch diff + staged + unstaged, as one synthesized "delivery candidate" | **MMR wrapper.** Adds the same agent channel + round bounding, plus file & standards context for the file-blind CLIs. **Untracked files are not covered.** |
+| `scaffold run post-implementation-review` | The full implemented codebase against stories + standards | **Independent, not an MMR wrapper.** A release-time review (systemic sweep + per-story functional review via parallel agents) with its own report under `docs/reviews/`; MMR injection is optional. Consult its own doc. |
+
+:::callout{type=note}
+**The mandatory one.** After `gh pr create`, running `review-pr` is mandatory
+before moving to the next task (a PostToolUse hook reminds you).
+`review-code` is the recommended preflight before a push but isn't gated.
+`post-implementation-review` is a release-time sweep, not a per-change gate.
+:::
+
+### When no wrapper fits
+
+The wrappers are conveniences, not gates on the engine. For any target a wrapper
+doesn't cover — a branch range, an existing patch file, a single doc — call
+`mmr review` directly with the matching input flag. The
+[MMR reference](../mmr/index.md) lists every flag; the next step is the workflow
+view of the same choice.
+
+## Step 2 — Choose the input mode
+
+`mmr review` resolves a diff from exactly one input source. Pick the one that
+describes your target. The `--diff -` (stdin) form is the universal escape hatch:
+anything you can express as a unified diff, you can pipe in.
+
+```mermaid
+flowchart TD
+  S{Where is the change?} --> PR[On a GitHub PR]
+  S --> ST[Staged in the index]
+  S --> BR[A branch, vs a base]
+  S --> DC[Local working tree:
+committed + staged + unstaged]
+  S --> UF[A brand-new file
+git doesn't track yet]
+  PR --> PRc["mmr review --pr N"]
+  ST --> STc["mmr review --staged"]
+  BR --> BRc["mmr review --base main --head BRANCH"]
+  DC --> DCc["git diff MERGE_BASE | mmr review --diff -
+(this is what review-code synthesizes)"]
+  UF --> UFc["(diff -u /dev/null FILE || true) | mmr review --diff -"]
+```
+
+| Target | Command | Notes |
+| --- | --- | --- |
+| A PR | `mmr review --pr 123` | Fetches the diff via `gh pr diff`. This is `review-pr`'s mode. |
+| Staged changes | `mmr review --staged` | Just the index (`git diff --cached`) — the pre-commit slice. |
+| A branch range | `mmr review --base main --head "$BRANCH"` | Committed work only; no staged/unstaged. |
+| Full delivery candidate | `git diff "$MERGE_BASE" \| mmr review --diff -` | Committed branch diff + staged + unstaged in one patch. `review-code` synthesizes this for you. |
+| A single tracked file's pending edits | `git diff HEAD -- path/file.ts \| mmr review --diff -` | Fails with "no diff content" if the file has no local changes — use the next row. |
+| A brand-new / untracked file | `(diff -u /dev/null path/file.ts \|\| true) \| mmr review --diff -` | Synthesizes an "all-added" diff from current contents. |
+| An existing patch | `mmr review --diff path/changes.patch` | Reads diff-format content directly. |
+
+:::callout{type=danger}
+**Untracked files are silently skipped — this is the trap.** `review-code`
+reviews the committed branch diff plus staged and unstaged changes *to tracked
+files*. A brand-new file you've never `git add`-ed is **not** in any of those
+diffs, so it sails through review with zero findings — not because it's clean,
+but because no channel ever saw it. To review a new file, pipe it in explicitly:
+`(diff -u /dev/null path/to/new-file.ts || true) | mmr review --diff -`. The
+`|| true` guard is required: `diff` exits non-zero whenever files differ, which
+would otherwise kill the pipeline under `set -o pipefail`. The wrappers cannot
+guess which untracked files you meant to include
+:cite[content/tools/review-code.md:37].
+:::
+
+The `--diff` flag expects **diff-format content** — a path to a `.patch`/`.diff`
+file, or `-` for stdin. It does not accept raw document text; wrap the target in
+a diff first.
+
+## Step 3 — Read the verdict, then act
+
+Every review collapses to exactly one of four verdicts. The verdict, not the raw
+findings, is what decides whether you proceed. The
+[MMR reference](../mmr/index.md) defines the gate, the severity tiers, and the
+exact derivation algorithm; this table is the *action* you take for each outcome.
+
+| Verdict | Exit | Do |
+| --- | --- | --- |
+| `pass` | 0 | **Proceed** — merge / push / next task. |
+| `degraded-pass` | 0 | **Proceed**, noting reduced coverage. The max achievable verdict once any channel was compensated. |
+| `blocked` | 2 | **Stop.** Fix the blocking findings (Step 4), then re-review. Do not merge. |
+| `needs-user-decision` | 3 | **Stop and surface to the user.** Automated iteration can't resolve this. |
+
+A review is `blocked` when any unacknowledged finding sits at or above the fix
+threshold (:sev[P2]{level=p2} by default; override per-run with
+`--fix-threshold`). See the [MMR reference](../mmr/index.md) for how the verdict
+is derived from gate result + channel health.
+
+:::callout{type=warning}
+**Proceed only on `pass` or `degraded-pass`.** On `blocked` or
+`needs-user-decision`, never merge automatically — surface the verdict and the
+remaining findings to the user. The wrappers enforce this: a `blocked` /
+`needs-user-decision` outcome takes the "Stop path" and does **not** print the
+ready-for-merge message :cite[content/tools/review-pr.md:610].
+:::
+
+## Step 4 — Fix the blocking findings (bounded)
+
+When the verdict is `blocked`, the loop is: fix the findings at or above the
+threshold → re-review → repeat. The guard rail is that this loop is **bounded
+per finding**, so a finding the model can't actually fix doesn't trap you in an
+infinite cycle.
+
+### The 3-round-per-finding limit
+
+The limit is **3 attempts per finding**, not 3 rounds total. Each round that
+surfaces *genuinely new* findings is healthy iteration — keep going. The loop
+stops only when one specific finding has been attempted three times without
+resolution.
+
+A "finding" here is its **stable identity**, not its wording, so a re-worded
+report of the same defect still counts against the same finding. (The
+[MMR reference](../mmr/index.md) covers how that identity is computed.) Co-equal
+stop conditions:
+
+- A finding's identity reaches 3 recorded attempts.
+- The same underlying defect recurs across 3 rounds even if the reviewer's
+  wording produces a new identity each time.
+- Channels genuinely contradict each other (→ `needs-user-decision`).
+- The user explicitly asks to stop.
+
+When you stop, **do not merge**. Document each unresolved finding (severity,
+location, attempt count) and hand the decision to the user
+:cite[content/tools/review-pr.md:610].
+
+### Where the bookkeeping lives today
+
+The engine ships **native** multi-round sessions — `mmr review --session <id>
+--round N --max-rounds M` :cite[packages/mmr/src/commands/review.ts:289] — and a
+stable, line-number-independent `finding_key`
+:cite[packages/mmr/src/core/stable-id.ts:115]. (See the
+[MMR reference](../mmr/index.md) for how that key collapses the same issue at
+different severities.)
+
+The scaffold **wrappers** have not yet migrated to native sessions. Until they
+do, `review-pr` and `review-code` enforce the 3-strike rule with their own
+bookkeeping: a per-session attempts file at
+`.scaffold/review-attempts/<session-id>.json`. Each fix round computes a hash
+over the same four identity components, increments that finding's counter, and
+the `_review_at_strike_limit` helper blocks once it hits 3
+:cite[content/tools/review-pr.md:468]. The wrapper hash deliberately mirrors the
+engine's `finding_key` components, so the eventual swap to
+`mmr review --session` is a clean migration rather than a re-think.
+
+:::callout{type=note}
+**Practical takeaway.** You drive the fix loop through the wrapper; the attempts
+file under `.scaffold/review-attempts/` is the current source of truth for the
+strike count. For a very noisy loop you may narrow the gate for one run with
+`--fix-threshold P1` — but don't permanently lower the project default (P2).
+:::
+
+## Step 5 — Handle degraded mode
+
+A review never silently runs with fewer reviewers. A channel is *degraded* when
+its binary isn't installed, auth fails, it times out, or it errors out. The
+workflow's response is to **compensate and tell you how to recover**, then cap
+the verdict at `degraded-pass`. The mechanics — how compensation runs and the
+per-channel auth checks — live in the [MMR reference](../mmr/index.md); below is
+what it means for *your* workflow.
+
+- **Compensating pass.** For each degraded *external* channel, MMR runs a
+  compensating pass focused on that channel's strength area and records the
+  source as `compensating-<channel>` :cite[packages/mmr/src/core/compensator.ts:162].
+  The compensator defaults to `claude -p` unless `defaults.compensator.channel`
+  overrides it :cite[packages/mmr/src/core/compensator.ts:74]. These findings
+  are single-source, low confidence. With the default compensator, a missing
+  Claude CLI has no compensator of its own. (The bracket labels like
+  `[compensating: Grok-equivalent]` you'll see are the *manual fallback* summary
+  wording, distinct from the engine's `compensating-<channel>` source name.)
+- **Auth recovery is never silent.** The workflow surfaces the exact recovery
+  command for the failed channel; the channel's `recovery` string drives this
+  :cite[packages/mmr/src/core/auth.ts:65]. See the
+  [MMR reference](../mmr/index.md) for the per-channel auth-check + recovery
+  table.
+
+:::callout{type=warning}
+**Foreground only.** When the `mmr` CLI is unavailable and a wrapper falls back
+to invoking Codex / Gemini / Claude / Grok directly, run them as **foreground**
+Bash calls — never with `run_in_background`, `&`, or `nohup`. Background
+execution produces empty output, which the parser then reads as a degraded
+channel :cite[content/tools/review-code.md:265].
+:::
+
+Once any channel was compensated, the best possible verdict is
+`degraded-pass` — full `pass` requires all channels to have completed for real.
+
+## See also
+
+- [MMR reference](../mmr/index.md){mode=advisory} — channels, reconciliation,
+  the `finding_key`, verdict internals, and `.mmr.yaml`.
+- The wrapper meta-prompts themselves:
+  :cite[content/tools/review-pr.md:15]{mode=advisory},
+  :cite[content/tools/review-code.md:16]{mode=advisory}, and
+  :cite[content/tools/post-implementation-review.md:16]{mode=advisory}.

package/dist/guides/build.d.ts

@@ -1,5 +1,5 @@
 import type { LintResult } from './lint.js';
-export declare function loadThemeCss(): string;
+export declare function loadGuideStyles(): string;
 export interface BuildGuideArgs {
     guideDir: string;
     css: string;

package/dist/guides/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/guides/build.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,wBAAgB,YAAY,IAAI,MAAM,CAQrC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CACpD;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAoBpF;AAED,wBAAsB,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQxE"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/guides/build.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAG3C,wBAAgB,eAAe,IAAI,MAAM,CAexC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CACpD;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAwBpF;AAED,wBAAsB,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQxE"}

package/dist/guides/build.js

@@ -3,17 +3,25 @@ import path from 'node:path';
 import { atomicWriteFile, getPackageRoot, getPackageGuidesDir } from '../utils/fs.js';
 import { buildGuidesIndex, extractGuideFrontmatter } from './loader.js';
 import { renderGuideBody } from './render.js';
-import { remarkCallout, remarkTabs, remarkFilterTable, remarkChart, remarkSev } from './directives.js';
+import { remarkCallout, remarkTabs, remarkFilterTable, remarkChart, remarkSev, remarkCite } from './directives.js';
 import { remarkMermaid, pruneDiagrams } from './mermaid.js';
 import { wrapInChrome } from './template.js';
 import { renderIndexPage } from './index-page.js';
 import { lintGuide } from './lint.js';
-export function loadThemeCss() {
-    const p = path.join(getPackageRoot(), 'dist', 'guides', 'dashboard-theme.css');
-    if (!fs.existsSync(p)) {
-        throw new Error(`Missing ${p} — run \`npm run build\` (the build copies lib/dashboard-theme.css into dist/guides/).`);
-    }
-    return fs.readFileSync(p, 'utf8');
+import { findBrokenRelativeLinks } from './links.js';
+export function loadGuideStyles() {
+    // The guide stylesheet is the design tokens (dashboard-theme.css) followed by
+    // the guide-specific layout + component styles (guides.css). Both are inlined
+    // into each guide's <style> so the output stays self-contained.
+    const dir = path.join(getPackageRoot(), 'dist', 'guides');
+    const parts = ['dashboard-theme.css', 'guides.css'].map((name) => {
+        const p = path.join(dir, name);
+        if (!fs.existsSync(p)) {
+            throw new Error(`Missing ${p} — run \`npm run build\` (the build copies lib/${name} into dist/guides/).`);
+        }
+        return fs.readFileSync(p, 'utf8');
+    });
+    return parts.join('\n');
 }
 export async function buildGuide(args) {
     const md = fs.readFileSync(path.join(args.guideDir, 'index.md'), 'utf8');
@@ -23,13 +31,17 @@ export async function buildGuide(args) {
     }
     for (const w of lint.warnings)
         process.stderr.write(`warning: ${w}\n`);
+    const brokenLinks = findBrokenRelativeLinks(md, args.guideDir);
+    if (brokenLinks.length) {
+        throw new Error(`guide has broken relative link(s):\n  ${brokenLinks.join('\n  ')}`);
+    }
     const fm = extractGuideFrontmatter(md);
     if (!fm)
         throw new Error(`invalid or missing frontmatter in ${path.join(args.guideDir, 'index.md')}`);
     const diagramIds = [];
     const { body, headings } = await renderGuideBody(md, {
         plugins: [
-            remarkCallout, remarkTabs, remarkFilterTable, remarkChart, remarkSev,
+            remarkCallout, remarkTabs, remarkFilterTable, remarkChart, remarkSev, remarkCite,
             remarkMermaid({ guideDir: args.guideDir, render: args.mermaidRender, collect: diagramIds }),
         ],
     });
@@ -39,7 +51,7 @@ export async function buildGuide(args) {
     return { lint };
 }
 export async function buildAllGuides(projectRoot) {
-    const css = loadThemeCss();
+    const css = loadGuideStyles();
     const guidesDir = getPackageGuidesDir(projectRoot);
     const index = buildGuidesIndex(guidesDir);
     for (const entry of index.values()) {

package/dist/guides/build.js.map

@@ -1 +1 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/guides/build.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/guides/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAClH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErC,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAEpD,MAAM,UAAU,eAAe;IAC7B,8EAA8E;IAC9E,8EAA8E;IAC9E,gEAAgE;IAChE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAA;IACzD,MAAM,KAAK,GAAG,CAAC,qBAAqB,EAAE,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC/D,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAC9B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,WAAW,CAAC,kDAAkD,IAAI,sBAAsB,CACzF,CAAA;QACH,CAAC;QACD,OAAO,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACnC,CAAC,CAAC,CAAA;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAQD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAoB;IACnD,MAAM,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,CAAA;IACxE,MAAM,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC,CAAA;IAC1B,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACtE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;IACtE,MAAM,WAAW,GAAG,uBAAuB,CAAC,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC9D,IAAI,WAAW,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,yCAAyC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACtF,CAAC;IACD,MAAM,EAAE,GAAG,uBAAuB,CAAC,EAAE,CAAC,CAAA;IACtC,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC,CAAA;IACrG,MAAM,UAAU,GAAa,EAAE,CAAA;IAC/B,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,eAAe,CAAC,EAAE,EAAE;QACnD,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU;YAChF,aAAa,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;SAC5F;KACF,CAAC,CAAA;IACF,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;IACxC,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IAC7E,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,CAAA;IAC7D,OAAO,EAAE,IAAI,EAAE,CAAA;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,WAAoB;IACvD,MAAM,GAAG,GAAG,eAAe,EAAE,CAAA;IAC7B,MAAM,SAAS,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAA;IAClD,MAAM,KAAK,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAA;IACzC,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACnC,MAAM,UAAU,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAA;IAChD,CAAC;IACD,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,eAAe,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;AAChG,CAAC"}

package/dist/guides/build.test.js

@@ -44,6 +44,14 @@ describe('buildGuide', () => {
         await expect(buildGuide({ guideDir: dir, css: CSS, mermaidRender: async () => '' }))
             .rejects.toThrow(/text-equivalent/i);
     });
+    it('throws when a relative link target does not resolve', async () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gb-'));
+        const dir = path.join(root, 'mmr');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'index.md'), GUIDE_MD + '\nSee [concepts](../concepts/index.md).\n');
+        await expect(buildGuide({ guideDir: dir, css: CSS, mermaidRender: async () => '' }))
+            .rejects.toThrow(/broken relative link/i);
+    });
 });
 describe('renderIndexPage', () => {
     it('lists guides by order with links', () => {
@@ -58,6 +66,45 @@ describe('renderIndexPage', () => {
         expect(html).toContain('MMR');
         expect(html).toContain('review');
     });
+    it('groups guides into ordered category card sections', () => {
+        const html = renderIndexPage([
+            /* eslint-disable @typescript-eslint/no-explicit-any */
+            ({ topic: 'cli', frontmatter: {
+                    title: 'CLI', topic: 'cli', description: 'commands', category: 'reference', order: 20,
+                } }),
+            ({ topic: 'pipeline', frontmatter: {
+                    title: 'Pipeline', topic: 'pipeline', description: 'the pipeline', category: 'concepts', order: 10,
+                } }),
+            /* eslint-enable @typescript-eslint/no-explicit-any */
+        ], CSS);
+        // category section headings (ids derived by catId) + labels
+        expect(html).toContain('id="cat-concepts"');
+        expect(html).toContain('id="cat-reference"');
+        expect(html).toContain('>Concepts<');
+        expect(html).toContain('>Reference<');
+        // card markup, not a bare list
+        expect(html).toContain('class="guide-card" href="pipeline/index.html"');
+        expect(html).toContain('class="guide-card-title"');
+        // CATEGORY_ORDER puts concepts before reference regardless of input order
+        expect(html.indexOf('cat-concepts')).toBeLessThan(html.indexOf('cat-reference'));
+    });
+    it('appends unknown categories after the known ones with a capitalized label', () => {
+        const html = renderIndexPage([
+            /* eslint-disable @typescript-eslint/no-explicit-any */
+            ({ topic: 'odd', frontmatter: {
+                    title: 'Odd', topic: 'odd', description: 'misc', category: 'experimental', order: 5,
+                } }),
+            ({ topic: 'cli', frontmatter: {
+                    title: 'CLI', topic: 'cli', description: 'commands', category: 'reference', order: 20,
+                } }),
+            /* eslint-enable @typescript-eslint/no-explicit-any */
+        ], CSS);
+        // Unknown 'experimental' category gets a capitalized label and an id…
+        expect(html).toContain('id="cat-experimental"');
+        expect(html).toContain('>Experimental<');
+        // …and sorts AFTER the known 'reference' category despite a lower order
+        expect(html.indexOf('cat-reference')).toBeLessThan(html.indexOf('cat-experimental'));
+    });
     it('escapes < and & in frontmatter fields', () => {
         const html = renderIndexPage([
             /* eslint-disable @typescript-eslint/no-explicit-any */

package/dist/guides/build.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"build.test.js","sourceRoot":"","sources":["../../src/guides/build.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build.test.js","sourceRoot":"","sources":["../../src/guides/build.test.ts"],"names":[],"mappings":"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"}

package/dist/guides/chrome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chrome.d.ts","sourceRoot":"","sources":["../../src/guides/chrome.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAGqD,CAAA;AAEjF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,EAAE,MA4FlB,CAAA"}
+{"version":3,"file":"chrome.d.ts","sourceRoot":"","sources":["../../src/guides/chrome.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAGqD,CAAA;AAEjF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,EAAE,MAmKlB,CAAA"}

package/dist/guides/chrome.js

@@ -39,12 +39,69 @@ export const CHROME_JS = /* js */ `(function(){
       });
     });
 
-    // ─── Mobile nav ──────────────────────────────────────────────────────────
+    // ─── Mobile nav (drawer + backdrop; aria-expanded + Escape-to-close) ──────
+    function setNav(open) {
+      var rail = document.querySelector('.rail');
+      if (rail) rail.classList.toggle('open', open);
+      var toggle = document.querySelector('.nav-toggle');
+      if (toggle) toggle.setAttribute('aria-expanded', open ? 'true' : 'false');
+      // Modal-drawer focus containment: while open, make the page content inert
+      // (out of tab order + a11y tree) and move focus into the drawer; on close,
+      // restore content and return focus to the toggle.
+      var main = document.querySelector('.content');
+      if (main) main.inert = open;
+      if (open) {
+        var first = rail && rail.querySelector('a, button, [tabindex]:not([tabindex="-1"])');
+        if (first) first.focus();
+        else if (rail) { rail.setAttribute('tabindex', '-1'); rail.focus(); }
+      } else if (toggle) {
+        toggle.focus();
+      }
+    }
+    // If the viewport grows past the mobile breakpoint while the drawer is open,
+    // the rail becomes the desktop sidebar and the toggle hides — clear the open
+    // state so .content doesn't stay inert with no way to close it.
+    if (window.matchMedia) {
+      var mq = window.matchMedia('(max-width: 860px)');
+      var onMq = function() {
+        if (mq.matches) return;
+        var rail = document.querySelector('.rail');
+        if (rail) rail.classList.remove('open');
+        var toggle = document.querySelector('.nav-toggle');
+        if (toggle) toggle.setAttribute('aria-expanded', 'false');
+        var main = document.querySelector('.content');
+        if (main) main.inert = false;
+      };
+      if (mq.addEventListener) mq.addEventListener('change', onMq);
+      else if (mq.addListener) mq.addListener(onMq);
+    }
     document.querySelectorAll('[data-action="nav"]').forEach(function(btn) {
       btn.addEventListener('click', function() {
         var rail = document.querySelector('.rail');
-        if (rail) rail.classList.toggle('open');
+        setNav(!(rail && rail.classList.contains('open')));
+      });
+    });
+    // Selecting a TOC link closes the drawer (so the now-active content isn't
+    // left inert behind the panel) before the anchor navigation scrolls.
+    var drawerRail = document.querySelector('.rail');
+    if (drawerRail) {
+      drawerRail.querySelectorAll('a').forEach(function(a) {
+        a.addEventListener('click', function() {
+          if (drawerRail.classList.contains('open')) setNav(false);
+        });
       });
+    }
+    document.addEventListener('keydown', function(e) {
+      var rail = document.querySelector('.rail');
+      if (!rail || !rail.classList.contains('open')) return;
+      if (e.key === 'Escape') { setNav(false); return; } // setNav restores focus to the toggle
+      // Trap Tab within the open drawer (modal pattern).
+      if (e.key !== 'Tab') return;
+      var f = rail.querySelectorAll('a[href], button, [tabindex]:not([tabindex="-1"])');
+      if (!f.length) return;
+      var first = f[0], last = f[f.length - 1];
+      if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
     });
 
     // ─── Copy buttons ─────────────────────────────────────────────────────────
@@ -71,17 +128,31 @@ export const CHROME_JS = /* js */ `(function(){
       wrapper.insertBefore(btn, pre);
     });
 
-    // ─── Tabs ─────────────────────────────────────────────────────────────────
+    // ─── Tabs (ARIA pattern: aria-selected + roving tabindex + arrow keys) ────
+    function activateTab(group, btn, focus) {
+      var idx = btn.getAttribute('data-tab');
+      group.querySelectorAll('.tab-btn').forEach(function(b) {
+        var on = b === btn;
+        b.classList.toggle('active', on);
+        b.setAttribute('aria-selected', on ? 'true' : 'false');
+        b.setAttribute('tabindex', on ? '0' : '-1');
+      });
+      group.querySelectorAll('.tabpane').forEach(function(pane) {
+        pane.classList.toggle('active', pane.getAttribute('data-tab') === idx);
+      });
+      if (focus) btn.focus();
+    }
     document.querySelectorAll('.tabs').forEach(function(group) {
-      group.querySelectorAll('.tab-btn').forEach(function(btn) {
-        btn.addEventListener('click', function() {
-          var idx = btn.getAttribute('data-tab');
-          group.querySelectorAll('.tab-btn').forEach(function(b) {
-            b.classList.toggle('active', b === btn);
-          });
-          group.querySelectorAll('.tabpane').forEach(function(pane) {
-            pane.classList.toggle('active', pane.getAttribute('data-tab') === idx);
-          });
+      var btns = [].slice.call(group.querySelectorAll('.tab-btn'));
+      btns.forEach(function(btn, i) {
+        btn.addEventListener('click', function() { activateTab(group, btn, false); });
+        btn.addEventListener('keydown', function(e) {
+          var ni = -1;
+          if (e.key === 'ArrowRight' || e.key === 'ArrowDown') ni = (i + 1) % btns.length;
+          else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') ni = (i - 1 + btns.length) % btns.length;
+          else if (e.key === 'Home') ni = 0;
+          else if (e.key === 'End') ni = btns.length - 1;
+          if (ni >= 0) { e.preventDefault(); activateTab(group, btns[ni], true); }
         });
       });
     });

package/dist/guides/chrome.js.map

@@ -1 +1 @@
-{"version":3,"file":"chrome.js","sourceRoot":"","sources":["../../src/guides/chrome.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,8DAA8D;IAC9D,4FAA4F;IAC5F,+EAA+E,CAAA;AAEjF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,SAAS,GAAW,QAAQ,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA4FpC,CAAA"}
+{"version":3,"file":"chrome.js","sourceRoot":"","sources":["../../src/guides/chrome.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,8DAA8D;IAC9D,4FAA4F;IAC5F,+EAA+E,CAAA;AAEjF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,SAAS,GAAW,QAAQ,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAmKpC,CAAA"}

package/dist/guides/dashboard-theme.css

@@ -41,9 +41,13 @@
     --yellow:       #d97706;
     --yellow-bg:    #fffbeb;
     --yellow-border:#fde68a;
+    --red:          #dc2626;
+    --red-bg:       #fef2f2;
+    --red-border:   #fecaca;
     --gray:         #9ca3af;
     --gray-bg:      #f3f4f6;
     --gray-border:  #e5e7eb;
+    --scrim:        rgba(15, 17, 23, 0.45);
 
     /* Semantic: Next Banner */
     --next-bg:      #eef2ff;
@@ -126,9 +130,13 @@
     --yellow:       #fbbf24;
     --yellow-bg:    rgba(120, 53, 15, 0.25);
     --yellow-border:rgba(251, 191, 36, 0.20);
+    --red:          #f87171;
+    --red-bg:       rgba(127, 29, 29, 0.25);
+    --red-border:   rgba(248, 113, 113, 0.22);
     --gray:         #6b7294;
     --gray-bg:      #252940;
     --gray-border:  #363c58;
+    --scrim:        rgba(0, 0, 0, 0.6);
 
     /* Semantic: Next Banner */
     --next-bg:      rgba(30, 27, 75, 0.50);

package/dist/guides/directives-cite.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=directives-cite.test.d.ts.map

package/dist/guides/directives-cite.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives-cite.test.d.ts","sourceRoot":"","sources":["../../src/guides/directives-cite.test.ts"],"names":[],"mappings":""}

package/dist/guides/directives-cite.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { renderGuideBody } from './render.js';
+import { remarkCite } from './directives.js';
+describe('remarkCite', () => {
+    it('renders a blocking citation as an fp span the citation checker matches', async () => {
+        const { body } = await renderGuideBody('See :cite[src/foo.ts:42] for details.\n', {
+            plugins: [remarkCite],
+        });
+        expect(body).toContain('class="fp"');
+        expect(body).toContain('data-path="src/foo.ts:42"');
+        expect(body).toContain('>src/foo.ts:42<');
+    });
+    it('preserves a line range in data-path', async () => {
+        const { body } = await renderGuideBody(':cite[src/bar.ts:10-20]\n', { plugins: [remarkCite] });
+        expect(body).toContain('data-path="src/bar.ts:10-20"');
+    });
+    it('renders an advisory citation without the fp class so the gate does not block on it', async () => {
+        const { body } = await renderGuideBody(':cite[docs/x.md:3]{mode=advisory}\n', {
+            plugins: [remarkCite],
+        });
+        expect(body).toContain('class="cite-advisory"');
+        expect(body).toContain('data-path="docs/x.md:3"');
+        expect(body).not.toContain('class="fp"');
+    });
+});
+//# sourceMappingURL=directives-cite.test.js.map

package/dist/guides/directives-cite.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives-cite.test.js","sourceRoot":"","sources":["../../src/guides/directives-cite.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,wEAAwE,EAAE,KAAK,IAAI,EAAE;QACtF,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,eAAe,CAAC,yCAAyC,EAAE;YAChF,OAAO,EAAE,CAAC,UAAU,CAAC;SACtB,CAAC,CAAA;QACF,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAA;QACpC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,2BAA2B,CAAC,CAAA;QACnD,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAA;IAC3C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;QACnD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,eAAe,CAAC,2BAA2B,EAAE,EAAE,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;QAC9F,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,8BAA8B,CAAC,CAAA;IACxD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,oFAAoF,EAAE,KAAK,IAAI,EAAE;QAClG,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,eAAe,CAAC,qCAAqC,EAAE;YAC5E,OAAO,EAAE,CAAC,UAAU,CAAC;SACtB,CAAC,CAAA;QACF,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,uBAAuB,CAAC,CAAA;QAC/C,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,yBAAyB,CAAC,CAAA;QACjD,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}