@seanyao/roll 3.618.3 → 3.620.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "3.618.3",
+  "version": "3.620.1",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {

package/skills/README.md

@@ -27,9 +27,9 @@ roll 的**技能契约**仓——AI agent 在 roll 项目里工作时加载并
 - `roll-.review` / `roll-.qa` — TCR 内嵌自审与测试金字塔基准
 
 **Observation · 观察与汇报**
-- `roll-brief` — owner 简报；`roll-notes` — 项目日记
-- `roll-sentinel` — 生产抽查巡检；`roll-.dream` — 夜间架构/文档健康扫描
-- `roll-doctor` — 工具链体检；`roll-doc` — 存量文档自动化
+- `roll-notes` — 项目日记
+- `roll-.dream` — 夜间架构/文档健康扫描
+- `roll-doctor` — 工具链体检；`roll-doc-audit` — 文档/产品一致性审计与存量文档自动化
 
 **Lifecycle & misc · 生命周期与杂项**
 - `roll-onboard` — 存量项目交互式接入

package/skills/docs/skill-authoring.md

@@ -42,9 +42,10 @@ Every hub must include `## Gotchas` or `## Known Failure Modes`.
 - If a gotcha comes from a missed load, add a positive route case.
 - If a gotcha comes from an off-target load, add a negative route case.
 - Treat the section as append-mostly unless an entry is proven obsolete.
-- Never instruct agents to `source "$(command -v roll)"`: the TS-native `roll`
-  is a bundled CLI, not a bash library, and sourcing it executes JS as shell
-  (FIX-274). Skill steps call `roll <command>` directly.
+- Never instruct agents to source the `roll` binary as if it were a shell
+  library: the TS-native `roll` is a bundled CLI, not a bash script, and
+  `source "$(command -v roll)"` executes JS as shell (FIX-274). Skill steps call
+  `roll <command>` directly.
 - Skills do NOT self-score (FIX-343). The working agent never scores its own
   story; the Review Score is a runner-side peer-review outcome, produced by a
   Reviewer in a FRESH, separate session (never a sub-agent of the builder's

package/skills/reports/skill-audit-summary.md

@@ -32,7 +32,7 @@ The initial `SKILL.md` line baseline was 7,929 lines. Current hub-only
 | roll-build | 884 | 48 | `references/full-contract.md` |
 | roll-fix | 641 | 48 | `references/full-contract.md` |
 | roll-debug | 607 | 48 | `references/full-contract.md`, `assets/injectable-bb.js` |
-| roll-doc | 595 | 46 | `references/full-contract.md` |
+| roll-doc-audit | 595 | 46 | `references/full-contract.md` |
 | roll-loop | 563 | 47 | `references/full-contract.md` |
 | roll-.changelog | 465 | 47 | `references/full-contract.md` |
 | roll-.dream | 374 | 47 | `references/full-contract.md` |

package/skills/roll-.dream/references/full-contract.md

@@ -146,12 +146,12 @@ The catalog is auto-updated by the release script (maintainer-private at `roll-m
 
 ### Scan 6 — 文档新鲜度 (Doc Freshness)
 
-**Dependency gate**: Skip Scan 6 entirely when `$roll-doc` (US-SKILL-008) is not yet deployed.
-Check: `[ -f "$ROLL_HOME/skills/roll-doc/SKILL.md" ]`. If absent, log "Scan 6 skipped — roll-doc not deployed" in the dream log and stop. No fallback.
+**Dependency gate**: Skip Scan 6 entirely when `$roll-doc-audit` (US-SKILL-008) is not yet deployed.
+Check: `[ -f "$ROLL_HOME/skills/roll-doc-audit/SKILL.md" ]`. If absent, log "Scan 6 skipped — roll-doc-audit not deployed" in the dream log and stop. No fallback.
 
-When deployed, each finding produces a REFACTOR entry with `$roll-doc` as execution hint:
+When deployed, each finding produces a REFACTOR entry with `$roll-doc-audit` as execution hint:
 ```markdown
-| REFACTOR-XXX | docs: <description> — flagged by dream <date> (hint: $roll-doc) | 📋 Todo |
+| REFACTOR-XXX | docs: <description> — flagged by dream <date> (hint: $roll-doc-audit) | 📋 Todo |
 ```
 
 #### Check A — Stale Docs

package/skills/roll-build/references/full-contract.md

@@ -84,32 +84,31 @@ reason: <one short line — which condition triggered, with numbers>
 ```
 
 When `verdict: ok` → continue to Step A2 normally.
-When `verdict: too_big` → go to **US-AGENT-008 self-downgrade path**, **but** first run the **US-AGENT-009 chain_depth cap check**:
-
-```bash
-# 0a. Cap check: refuse the third consecutive auto-split.
-#     exit 0 → split allowed; exit 1 → cap hit, take cap-hit path instead.
-if ! bash -c 'source "$(command -v roll)"; _loop_chain_depth_cap_check US-XXX-NNN'; then
-  # Cap hit (chain_depth ≥ 2): hold + ALERT, exit cleanly.
-  bash -c 'source "$(command -v roll)"; _loop_split_cap_hit US-XXX-NNN "depth >= 2, human triage required"'
-  exit 0
-fi
-
-# 1. Invoke roll-design to re-split the story into smaller sub-stories.
-#    Each sub-story carries chain_depth = (parent.chain_depth + 1).
-#    Sub-stories land as 📋 Todo with depends-on:<parent> chained.
-Skill("roll-design", "--from-story US-XXX-NNN")
-
-# 2. After the sub-stories are written to BACKLOG, flip the parent
-#    to 🚫 Hold and emit the downgrade event. The helper handles ALERT.
-bash -c 'source "$(command -v roll)"; _loop_self_downgrade US-XXX-NNN "too_big: <reason from verdict>" "US-XXX-NNNa,US-XXX-NNNb"'
-
-# 3. Exit cleanly — no TCR commits this cycle. The next loop cycle picks
-#    up the first sub-story (which is smaller and should pass pre-flight).
-exit 0
-```
-
-If `roll-design` cannot produce ≥2 sub-stories (story is already irreducible), fall through to **US-AGENT-009 cap-hit path** by invoking `_loop_split_cap_hit` directly. The cap is purely about stopping infinite split chains; even on the first re-split, if the design step gives up, the cap-hit handler raises ALERT for human triage.
+When `verdict: too_big` → **self-downgrade** rather than burn the cycle on a guaranteed miss:
+
+1. Invoke `roll-design` to re-split the story into ≥2 smaller sub-stories. Each
+   sub-story inherits the parent's ORIGINAL inbound dependencies — **never** the
+   parent itself (depending on the about-to-be-parked parent would deadlock the
+   child forever).
+2. Hand the split to the loop with the v3 command:
+
+   ```bash
+   roll loop self-downgrade <story-id> "<one-line reason>" <subA,subB,...>
+   ```
+
+   It parks the parent at 🚫 Hold (a grouping row the picker skips), appends the
+   sub-stories as 📋 Todo rows (correct `depends-on`, `chain_depth = parent + 1`,
+   never pointing at the parent), closes any open PR for the parent and deletes
+   its branch (invariant I3), and records a `story:split` event for reconciliation.
+3. Exit cleanly — **no TCR commits this cycle**. The next loop cycle picks up the
+   first sub-story (smaller, should pass pre-flight).
+
+The command enforces the **chain-depth cap** (US-AGENT-009): a story whose chain
+has already auto-split twice (`chain_depth ≥ 2`), or one that yields fewer than 2
+sub-stories (irreducible), is **not** split again — `roll loop self-downgrade`
+parks the parent at 🚫 Hold and raises an ALERT for human triage (a `story:split`
+with `capped: true`) instead of recursing. Pass the sub-ids you have (or none);
+the command decides. The cap exists purely to stop infinite split chains.
 
 > Pre-flight is honest, not paranoid: a small story (est_min ≤ 8 — the `easy` tier — with chain_depth=0) should almost always go `ok`. The check pays off on the long tail — stories with a large `est_min` that, on inspection, plainly compose far more files and behaviours than one cycle can land green.
 
@@ -389,12 +388,7 @@ When any signal appears, **do not stop — flag it**:
 
 Then continue implementing the current Story normally.
 
-**Event emission** — after all TCR micro-steps for a Story complete, emit a `build` event so the cycle event stream reflects the work done:
-
-```bash
-# _tcr_count = number of "tcr:" prefix commits made during this Story
-_loop_event build "$US_ID" "${_tcr_count} commits" "" 2>/dev/null || true
-```
+**Event emission** — after all TCR micro-steps for a Story complete, emit a `build` event so the cycle event stream reflects the work done. The v3 runner writes events natively; do not call the retired bash helper `_loop_event`.
 
 ### Phase 4: E2E Deposit
 
@@ -883,6 +877,28 @@ Verdict values:
 - `ok` — shipped but with at least one documented trade-off (use rationale).
 - `regression` — story landed but another behaviour broke (rare; open a FIX).
 
+#### Reviewer-triggered resize (US-AGENT-041)
+
+A low score (≤ 5) can mean two different things, and the Reviewer distinguishes
+them. When the delivery fell short because of a **quality** problem (a bug, a
+weak test), the Reviewer just scores low — the loop retries. But when it fell
+short because the **scope was simply too large for one cycle** (whole ACs or
+surfaces left uncovered, not defects), the Reviewer ALSO emits, alongside the
+SCORE/VERDICT/RATIONALE lines:
+
+```
+RESIZE: <one line — why the scope exceeds one cycle>
+GAPS: <gap one; gap two; gap three>
+```
+
+On a RESIZE signal (low score), the loop runs `roll loop review-resize <story>`:
+`$roll-design` mints sub-stories from the gaps, ≥2 **heterogeneous** reviewers
+gate the split by consensus (all agree → auto-land via `roll loop self-downgrade`,
+which parks the parent at 🚫 Hold + appends the sub-stories; any objection →
+pause + ALERT, backlog unchanged), and the chain-depth cap (US-AGENT-009) stops
+runaway splits. The human is **on** the loop (alerted only on consensus failure
+or the cap), not in it. A RESIZE is never emitted for a pure quality problem.
+
 ---
 
 ## TCR Recovery Patterns

package/skills/roll-doc-audit/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: roll-doc-audit
+license: MIT
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(date:*,find:*,stat:*,wc:*)"
+description: "Load when checking README, guides, site pages, CLI help, and docs against implemented behavior, or when auditing documentation inventory, docs/INDEX coverage, undocumented modules, and draft fills from code evidence."
+---
+# Roll Doc Audit
+
+This hub keeps the routing boundary, hard gates, and execution skeleton in the initial context. Load the heavier runbook only when the task actually needs the detailed contract.
+
+## Load
+
+Load when checking README, guides, site pages, CLI help, and docs against implemented behavior. Also load when a project needs documentation inventory, docs/INDEX generation, undocumented module detection, or draft documentation fills for existing code.
+
+## When Not to Use
+
+- Presentation deck generation; load roll-deck.
+- Toolchain diagnosis; load roll-doctor.
+
+## Read On Demand
+
+- Read [the full contract](references/full-contract.md) before executing the workflow end to end, recovering from failures, or checking exact output templates.
+- Keep this hub in context for trigger boundaries and hard gates.
+
+## Workflow Skeleton
+
+0. Consistency audit (Phase 0, first): enumerate shipped surfaces (CLI `--help`, console pages, site copy) and assert each is documented + accurate; check changelog covers the release delta and `site/roll-data.js` matches the real guides/pages/skills. Emit the Consistency Report.
+1. Scan documentation, user guidance, site pages, CLI help, and code surfaces.
+2. Flag docs/product drift against implemented behavior.
+3. Generate or update docs/INDEX.md when inventory is part of the request.
+4. Identify undocumented modules.
+5. Draft fills from code evidence.
+
+## Hard Gates
+
+- Do not invent behavior without source evidence.
+- Keep docs linked and indexable.
+- Treat README, guides, site pages, help output, and code behavior as one consistency surface.
+- This skill is the judgment-heavy auditor/drafter; the deterministic subset is also enforced by the `roll release` consistency gate (`release-consistency.ts`). Run the skill to investigate/fix; the gate is the floor that blocks silent drift.
+
+## Gotchas
+
+- Draft missing docs from current code evidence; do not hallucinate module behavior from filenames alone.
+- Documentation inventory is not a product deck or owner brief.
+- A release consistency audit should report drift clearly before drafting new docs.
+
+## Maintenance
+
+- Description changes require updates in `route-cases/skills.json`.
+- New observed failures should add a gotcha and the matching positive or negative route case.
+- Heavy examples, templates, recovery paths, and deterministic snippets belong in `references/`, `assets/`, or `scripts/`, not in this hub.

package/skills/{roll-doc → roll-doc-audit}/references/full-contract.md

@@ -4,9 +4,9 @@ This file preserves the detailed contract extracted from SKILL.md. Read it when
 
 ---
 
-# roll-doc
+# roll-doc-audit
 
-Four-phase legacy documentation automation (plus deep-read Phase 3b): scan → index → gap analysis → fill (directory-level) → deep read (cross-directory topics).
+Documentation/product consistency audit plus legacy documentation automation (and deep-read Phase 3b): consistency audit (Phase 0 — shipped surfaces vs docs) → scan docs, user guidance, site pages, CLI help, and code surfaces → index → gap analysis → fill (directory-level) → deep read (cross-directory topics).
 
 Works on any project root. No manual mode switching — reads the project state and decides what to do.
 
@@ -14,7 +14,8 @@ Works on any project root. No manual mode switching — reads the project state
 
 - Starting to work on a legacy project with scattered or missing documentation
 - `docs/INDEX.md` is out of date or doesn't exist yet
-- `roll-.dream` Scan 6 flagged undocumented modules (REFACTOR entry referencing roll-doc)
+- README, guides, site pages, CLI help, or docs may be drifting from implemented behavior
+- `roll-.dream` Scan 6 flagged undocumented modules (REFACTOR entry referencing roll-doc-audit)
 - You want a complete picture of what's documented and what isn't
 
 ## When Not to Use
@@ -26,11 +27,212 @@ Works on any project root. No manual mode switching — reads the project state
 ## Invocation
 
 ```
-$roll-doc              # Full four-phase run
-$roll-doc --dry-run    # Phases 1–2 only; print Phase 3 plan without writing any files
-$roll-doc --force      # Re-generate drafts even for existing files
+$roll-doc-audit              # Full consistency/inventory run
+$roll-doc-audit --dry-run    # Phases 1–2 only; print Phase 3 plan without writing any files
+$roll-doc-audit --force      # Re-generate drafts even for existing files
 ```
 
+## Phase 0 — Consistency Audit
+
+Run this phase **first**, before the inventory phases (1–3b). The inventory phases ask
+*"what is undocumented?"*; Phase 0 asks the sharper release-time question: *"does every shipped
+user-facing surface have a doc, and does that doc still tell the truth?"* It is the
+judgment-heavy pass — enumerate the real surfaces, compare them against the docs, and draft the
+drift fixes.
+
+**Skill vs. gate.** This skill is the **investigator + drafter**: a human (or agent) runs it to
+find drift and write the fix. The *deterministic, enumerable* subset of these same checks is
+**also** enforced inside the `roll release` consistency gate (`release-consistency.ts`), so a
+drift cannot silently ship even when nobody runs this skill. The gate is the **floor** (it
+blocks the release on the mechanical mismatches it can prove); this skill is the **ceiling** (it
+also catches the judgment cases — a description that is technically present but stale, a doc that
+contradicts behavior — that a mechanical check cannot decide). Run the skill to investigate and
+fix; trust the gate to keep the floor from dropping.
+
+**Scope:** Phase 0 reads only — it never writes during the audit itself. Its output is the
+**Consistency Report** (template at the end of this phase) plus a list of drafted fixes the
+operator reviews and applies. As with every other phase, do not fabricate behavior: every
+"Accurate?" verdict must cite the source (help text, code path, or guide line) it was checked
+against.
+
+This phase has three check-classes. Run all three.
+
+### 0.1 — Shipped-surface coverage
+
+Enumerate every user-facing surface the product ships, then assert each one is **documented**
+AND **described accurately** (the doc's description matches actual behavior, not a stale copy).
+
+**Surface 1 — CLI commands.**
+
+Gather the evidence:
+
+```
+# every top-level command
+roll --help            # or: node dist/roll.mjs --help
+
+# every subcommand of a command that has subcommands
+roll <command> --help  # e.g. roll loop --help, roll agent --help
+```
+
+Parse the command/subcommand list and each one-line description out of the help output. For each
+command, locate its documentation in `guide/{en,zh}/*.md` and/or `README.md` (grep the command
+name).
+
+- **Pass:** the command appears in at least one guide page or `README.md`, AND the documented
+  description does not contradict the `--help` description / actual behavior.
+- **Fail (undocumented):** a command exists in `--help` but no guide/README mentions it.
+- **Fail (stale):** a command is documented, but the doc's description disagrees with `--help`
+  or with the implemented behavior (e.g. renamed flag, removed option, changed default).
+
+Draft the fix: for an undocumented command, draft the missing guide section (purpose, synopsis,
+options) from the `--help` text and the command's source. For a stale description, draft the
+corrected sentence and cite the `--help` line or code path that proves the new truth.
+
+**Surface 2 — Web-console pages / machine-global breadcrumb entries.**
+
+The product's console exposes a fixed set of machine-global pages (e.g. **Agents · Skills ·
+Tools · Conventions · About**). Each shipped page must be reflected in the site copy
+(`site/roll-data.js`) and in the guides.
+
+Gather the evidence:
+
+```
+# the breadcrumb / nav set as the site renders it
+grep -nE "Agents|Skills|Tools|Conventions|About" site/roll-data.js
+
+# the guide pages that should describe those surfaces
+ls guide/en guide/zh
+```
+
+- **Pass:** every shipped console page is present in `site/roll-data.js` and has a corresponding
+  guide treatment.
+- **Fail:** a console page ships but `site/roll-data.js` (or the guide) never reflects it, or the
+  site lists a page that no longer exists.
+
+Draft the fix: add/correct the `site/roll-data.js` entry and draft the guide paragraph for the
+missing page; cite the page's source.
+
+**Verdict for 0.1:** flag *any* shipped surface with **no doc**, or **a doc whose description
+contradicts the implementation**. Each flag becomes a row in the Consistency Report.
+
+### 0.2 — Changelog coverage of the release delta
+
+Assert that every user-facing card merged since the last release is reflected in `CHANGELOG.md`.
+
+Gather the evidence:
+
+```
+# latest release tag (roll tags look like v2026.601.4)
+LATEST=$(git describe --tags --abbrev=0 --match 'v*')
+
+# commits merged since that tag
+git log "$LATEST"..HEAD --oneline
+
+# card ids in the delta (US-/FIX-/REFACTOR-)
+git log "$LATEST"..HEAD --format='%s%n%b' | grep -oE '(US|FIX|REFACTOR)-[0-9]+' | sort -u
+```
+
+For each card id in the delta, decide whether it is **user-facing** (changes CLI behavior,
+output, flags, console pages, or documented workflow) — purely internal refactors that change no
+surface are out of scope. Then:
+
+- **Pass:** the user-facing card has a `CHANGELOG.md` entry **or** its spec carries an explicit
+  `changelog_exempt:` marker (read the card's spec under `.roll/features/` to check).
+- **Fail:** a user-facing delta card has neither a `CHANGELOG.md` entry nor a `changelog_exempt:`
+  marker — it would ship undocumented.
+
+Check changelog presence:
+
+```
+grep -nE '(US|FIX|REFACTOR)-[0-9]+' CHANGELOG.md
+```
+
+Draft the fix: for each missing user-facing card, draft a plain-language `CHANGELOG.md` line
+(what changed / what the user can now do) from the card's spec and merged diff — no internal
+jargon. If the card is genuinely not user-facing, note that it needs a `changelog_exempt:`
+marker rather than a changelog line, and say why.
+
+**Verdict for 0.2:** report every user-facing delta card that would ship undocumented.
+
+### 0.3 — Site-copy ↔ generated-console consistency
+
+Assert that `site/roll-data.js` matches reality on three axes. This is the class where a new
+guide page or console page ships but the site index is never updated to link it.
+
+Gather the evidence:
+
+```
+# every guide file that exists on disk
+ls guide/en guide/zh
+
+# the guide nav / page list the site actually exposes
+grep -nE "guide|slug|nav|page" site/roll-data.js
+
+# the machine-global breadcrumb description and the skill tiles
+grep -nE "Agents|Skills|Tools|Conventions|About|skill" site/roll-data.js
+```
+
+Then check each axis:
+
+1. **Guide reachability** — every `guide/<lang>/*.md` file on disk is reachable from the site
+   guide nav defined in `site/roll-data.js`.
+   - **Fail:** a guide file exists but is not linked from the nav (orphaned page), or the nav
+     links a guide slug that has no file (dead link).
+2. **Breadcrumb completeness** — the machine-global breadcrumb description in `site/roll-data.js`
+   lists the **real** set of machine pages (the same set verified in 0.1, Surface 2).
+   - **Fail:** the breadcrumb omits a shipped page or lists a removed one.
+3. **Skill-tile correctness** — the skill tiles in `site/roll-data.js` match the actual skill
+   set (the `roll-*` skill directories that ship).
+   - **Fail:** a shipped skill has no tile, or a tile points to a retired skill.
+
+Draft the fix: add the missing nav entry / breadcrumb item / skill tile to `site/roll-data.js`,
+or remove the stale one; cite the on-disk file (or its absence) that proves the drift.
+
+**Verdict for 0.3:** flag every stale or missing `site/roll-data.js` entry.
+
+### Consistency Report
+
+After running 0.1–0.3, emit one report. One row per surface checked; group by check-class. The
+`Fix` column states the drafted correction (and, for an undocumented surface, the path of the
+draft).
+
+```markdown
+> roll-doc-audit — Consistency Report (YYYY-MM-DD)
+> Phase 0 read-only audit. Floor enforced by `roll release` consistency gate (release-consistency.ts).
+
+## 0.1 Shipped-surface coverage
+
+| Surface | Documented? | Accurate? | Drift | Fix |
+|---------|-------------|-----------|-------|-----|
+| `roll loop` (CLI) | ✅ guide/en/loop.md | ❌ | guide says `--once`, help says `--single` | draft: rename flag in loop.md:42, cite `roll loop --help` |
+| `roll agent swap` (CLI) | ❌ | — | command ships, no guide/README mention | draft guide/en/agents.md §swap from `roll agent swap --help` |
+| Console: Tools page | ✅ guide | ❌ site | page ships, missing from site/roll-data.js | draft: add Tools entry to site/roll-data.js |
+
+## 0.2 Changelog coverage of the release delta
+
+| Card | User-facing? | In CHANGELOG / exempt? | Drift | Fix |
+|------|--------------|------------------------|-------|-----|
+| US-AGENT-041 | yes | ❌ | merged since v2026.601.4, no entry | draft CHANGELOG line from spec |
+| REFACTOR-118 | no | — | internal only | mark `changelog_exempt:` in spec |
+
+## 0.3 Site-copy ↔ generated-console consistency
+
+| Surface | Documented? | Accurate? | Drift | Fix |
+|---------|-------------|-----------|-------|-----|
+| guide/zh/consistency.md | ✅ on disk | ❌ nav | file exists, not linked in site nav | draft: add nav entry to site/roll-data.js |
+| Skill tile: roll-doc-audit | ✅ | ❌ | tile still labeled `roll-doc` | draft: update tile id in site/roll-data.js |
+
+## Summary
+
+- Surfaces checked: N (CLI N / console N / changelog cards N / site entries N)
+- Drift found: N (undocumented N / stale N / unlinked N)
+- Drafted fixes: N — review and apply, then re-run.
+```
+
+A clean run prints the report with no drift rows and the summary line `Drift found: 0`.
+
+---
+
 ## Phase 1 — Scan & Index
 
 Scan the project root for all `*.md` files and known convention files.
@@ -63,7 +265,7 @@ ARCHITECTURE.md   ADR-*.md
 ```markdown
 # Documentation Index
 
-> Auto-generated by roll-doc on YYYY-MM-DD. Edit individual docs, not this file.
+> Auto-generated by roll-doc-audit on YYYY-MM-DD. Edit individual docs, not this file.
 
 ## Index
 
@@ -139,7 +341,7 @@ When `AGENTS.md` has no `## Where to Look` section, generate and append one:
 Draft output format:
 
 ```markdown
-> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+> **Draft** — auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
 
 ## Where to Look
 - **Domain model**: `.roll/domain/context-map.md` — Contexts: {list from context-map, or "see file"}
@@ -151,7 +353,7 @@ Only include lines for directories that already exist in the project.
 **Every generated file starts with this exact header line:**
 
 ```
-> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+> **Draft** — auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
 ```
 
 **Minimum draft content:**
@@ -244,7 +446,7 @@ If no chain meets the ≥ 3 directory threshold, skip generation entirely (no em
 **Output document structure** (`docs/data-flows.md`):
 
 ```markdown
-> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+> **Draft** — auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
 
 # Data Flows
 
@@ -288,7 +490,7 @@ generation entirely (no empty `docs/state-machines.md`).
 **Output document structure** (`docs/state-machines.md`):
 
 ```markdown
-> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+> **Draft** — auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
 
 # State Machines
 
@@ -341,7 +543,7 @@ matches inside comments and test fixtures (`*.test.*`, `*.spec.*`, `tests/`,
 **Output document structure** (`docs/integrations.md`):
 
 ```markdown
-> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+> **Draft** — auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
 
 # External Integrations
 
@@ -386,7 +588,7 @@ fields of the symbol table.
 **Output document structure** (`docs/deployment.md`):
 
 ```markdown
-> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+> **Draft** — auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
 
 # Deployment
 
@@ -449,7 +651,7 @@ fewer than 3 subdirectories, skip — the project is too small to warrant a base
 **Output document structure** (`AGENTS.md`) — at minimum three required sections:
 
 ```markdown
-> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+> **Draft** — auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
 
 # {Project Name}
 
@@ -529,7 +731,7 @@ a claim, omit the row rather than invent a location.
 After all phases complete, output a summary:
 
 ```
-📚 roll-doc complete
+📚 roll-doc-audit complete
 
 Phase 1 — Index
   N docs scanned, docs/INDEX.md updated
@@ -576,13 +778,13 @@ Phase 3b — Deep Read  (plan)
 If no gaps were found:
 
 ```
-✅ roll-doc: no gaps found. docs/INDEX.md updated.
+✅ roll-doc-audit: no gaps found. docs/INDEX.md updated.
 ```
 
 If `--dry-run`:
 
 ```
-🔍 roll-doc --dry-run: N drafts would be generated (nothing written).
+🔍 roll-doc-audit --dry-run: N drafts would be generated (nothing written).
 ```
 
 ## Rules

package/skills/roll-fix/references/full-contract.md

@@ -127,20 +127,27 @@ the `hard`-tier boundary: a FIX estimated past it is a sanity signal that the
 Emit `verdict: ok` or `verdict: too_big` (with `reason:`) as the first cycle output line.
 
 - `ok` → continue with step 1 below normally
-- `too_big` → self-downgrade per US-AGENT-008, **gated by US-AGENT-009 cap check**:
+- `too_big` → **self-downgrade** rather than TCR a half fix:
 
-```bash
-# Cap check first (chain_depth ≥ 2 → refuse third auto-split).
-if ! bash -c 'source "$(command -v roll)"; _loop_chain_depth_cap_check FIX-XXX-NNN'; then
-  bash -c 'source "$(command -v roll)"; _loop_split_cap_hit FIX-XXX-NNN "depth >= 2"'
-  exit 0
-fi
-Skill("roll-design", "--from-story FIX-XXX-NNN")
-bash -c 'source "$(command -v roll)"; _loop_self_downgrade FIX-XXX-NNN "too_big: <reason>" "FIX-XXX-NNNa,FIX-XXX-NNNb"'
-exit 0
-```
+  1. Invoke `roll-design --from-story FIX-XXX` to mint ≥2 smaller sub-stories.
+     Each inherits the original FIX's inbound dependencies — never the FIX itself
+     (the parked parent would deadlock its children).
+  2. Hand the split to the loop:
 
-Original FIX goes to 🚫 Hold with `→ split to ...` annotation; sub-stories carry `chain_depth + 1`. Cap-hit path raises ALERT for human triage. Do NOT TCR a half fix.
+     ```bash
+     roll loop self-downgrade FIX-XXX "<one-line reason>" <subA,subB,...>
+     ```
+
+     It parks the FIX at 🚫 Hold, appends the sub-stories as 📋 Todo rows (correct
+     `depends-on`, `chain_depth + 1`, never the parent), closes any open PR for
+     the FIX and deletes its branch (invariant I3), and records a `story:split`
+     event.
+  3. Exit cleanly — **no TCR commits this cycle**.
+
+The command enforces the chain-depth cap (US-AGENT-009): a FIX whose chain has
+already auto-split twice, or one that yields fewer than 2 sub-stories, is parked
+at 🚫 Hold with an ALERT for human triage (a `story:split` with `capped: true`)
+rather than recursing. Do NOT TCR a half fix.
 
 Bug fixes are usually small (est_min ≤ 5), so pre-flight is mostly a sanity barrier for FIXes whose underlying issue turns out structural — e.g. a "simple null check" that requires touching 12 files. Catching that upfront is cheaper than burning a cycle.
 
@@ -535,6 +542,26 @@ Verdict values:
 - `ok` — shipped but with documented trade-offs (use rationale to explain).
 - `regression` — the fix re-broke something else (rare; consider re-opening).
 
+#### Reviewer-triggered resize (US-AGENT-041)
+
+A low score (≤ 5) splits two ways. A **quality** shortfall (weak test, narrow
+fix) just scores low and the loop retries. But when the FIX turned out
+**structurally too large for one cycle** (whole sub-problems uncovered, not
+defects), the Reviewer ALSO emits, beside SCORE/VERDICT/RATIONALE:
+
+```
+RESIZE: <one line — why the scope exceeds one cycle>
+GAPS: <gap one; gap two; ...>
+```
+
+On a RESIZE signal (low score) the loop runs `roll loop review-resize FIX-XXX`:
+`$roll-design` mints sub-stories from the gaps, ≥2 **heterogeneous** reviewers
+gate the split by consensus (all agree → auto-land via `roll loop self-downgrade`,
+parking the FIX at 🚫 Hold + appending sub-stories; any objection → pause +
+ALERT, backlog unchanged), with the chain-depth cap (US-AGENT-009) stopping
+runaway splits. The human is on the loop (alerted only on consensus failure or
+the cap), not in it. Never emit RESIZE for a pure quality problem.
+
 ## Rubric
 
 Quality evaluation for a completed fix. Score each dimension independently.