@seanyao/roll 3.610.1 → 3.610.2

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

@@ -0,0 +1,594 @@
+# Full Contract Reference
+
+This file preserves the detailed contract extracted from SKILL.md. Read it when the hub points here for exact workflow steps, templates, rubrics, or recovery branches.
+
+---
+
+# roll-doc
+
+Four-phase legacy documentation automation (plus deep-read Phase 3b): scan → 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.
+
+## When to Use
+
+- 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)
+- You want a complete picture of what's documented and what isn't
+
+## When Not to Use
+
+- The project has up-to-date, maintained docs — no need to rebuild the index
+- You need authoritative documentation reviewed and approved (drafts only; human reviews and commits)
+- You want to write a specific known doc from scratch — write it directly
+
+## 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
+```
+
+## Phase 1 — Scan & Index
+
+Scan the project root for all `*.md` files and known convention files.
+
+**Exclusions — never scan these directories:**
+
+```
+node_modules/   .git/   dist/   build/   .shared/   .roll/dream/   .roll/briefs/
+```
+
+**Convention files — detect by filename anywhere in the tree:**
+
+```
+AGENTS.md   CLAUDE.md   GEMINI.md   CONVENTIONS.md   CONTRIBUTING.md
+ARCHITECTURE.md   ADR-*.md
+```
+
+**Classification rules:**
+
+| Category | Criteria |
+|----------|----------|
+| `guide` | Path under `guide/` |
+| `domain` | Path under `.roll/domain/` |
+| `convention` | Filename matches convention markers list above |
+| `module` | File is `<dir>/README.md` for a source directory |
+| `stray` | None of the above (top-level, unorganized, or orphaned) |
+
+**Output — produce/update `docs/INDEX.md`:**
+
+```markdown
+# Documentation Index
+
+> Auto-generated by roll-doc on YYYY-MM-DD. Edit individual docs, not this file.
+
+## Index
+
+| Path | Title | Category | Last Modified |
+|------|-------|----------|---------------|
+| guide/en/loop.md | Loop User Guide | guide | 2026-05-01 |
+| AGENTS.md | Agent Conventions | convention | 2026-04-28 |
+
+## Coverage Summary
+
+- Total docs indexed: N
+- By category: guide (N) / domain (N) / convention (N) / module (N) / stray (N)
+
+## Gap Report
+
+Directories with ≥3 source files and no linked documentation:
+
+| Directory | Source Files | Missing Doc |
+|-----------|-------------|-------------|
+| src/commands/ | 8 | README.md |
+```
+
+`docs/INDEX.md` is always overwritten on each run — it is a derived artifact, not authoritative content.
+
+## Phase 2 — Gap Analysis
+
+Walk every directory (applying Phase 1 exclusions):
+
+1. Count non-hidden, non-`.md` source files directly in the directory
+2. If count ≥ 3 AND no `README.md` in that directory AND no `docs/INDEX.md` entry links to it → **module gap**
+3. **High fan-in gap**: a directory imported by **≥ 5 other source files** is a gap targeting `<dir>/README.md`, **even if it has < 3 source files** — critical low-volume modules (shared utils, single-file core) must not be skipped by the file-count threshold. The existing count ≥ 3 rule (rule 2) continues to apply independently; high fan-in only widens what qualifies, it never overrides rule 2.
+
+**Special gaps (checked once per project):**
+- No `.roll/domain/` directory or empty → gap: `.roll/domain/context-map.md`
+- No `CONVENTIONS.md` or `docs/CONVENTIONS.md` exists → gap: `docs/CONVENTIONS.md`
+
+**Threshold**: a directory qualifies for a module README gap when **file count ≥ 3 OR imported by ≥ 5 other source files** (default). The fan-in count comes from the Phase 3b symbol table `imports` edges; exclude test files (`*.test.*`, `*.spec.*`, `tests/`) when counting referencing files. An existing `<dir>/README.md` is never overwritten unless `--force`. Tune by editing the skill.
+
+Record all gaps — they become Phase 3 input.
+
+## Phase 3 — Fill
+
+**Skip this phase entirely when:**
+- `--dry-run` was passed (print the fill plan to stdout, write nothing)
+- Phase 2 found zero gaps
+
+**Idempotency rule**: Without `--force`, re-running when no new gaps exist is a **no-op** — no files are written, no existing drafts are modified.
+
+For each gap:
+1. Read up to 20 source files from the target directory to infer module purpose, key exports, dependencies, and configuration patterns
+2. Generate a draft document at the conventional location (see table below)
+3. **Skip if the target file already exists**, unless `--force` was passed
+
+**Draft locations by gap type:**
+
+| Gap Type | Draft Location |
+|----------|---------------|
+| Module with no README | `<dir>/README.md` |
+| No `.roll/domain/` entries | `.roll/domain/context-map.md` |
+| No conventions doc | `docs/CONVENTIONS.md` |
+| Missing `AGENTS.md` `## Where to Look` section | `AGENTS.md` (append or create) |
+
+**AGENTS.md Where to Look bootstrap:**
+
+When `AGENTS.md` has no `## Where to Look` section, generate and append one:
+
+1. Scan which doc directories actually exist: `.roll/domain/`, `.roll/features/`, `.roll/verification/`, etc.
+2. Generate pointer lines **only for directories that actually exist** — never fabricate pointers to missing paths
+3. If `.roll/domain/context-map.md` exists, read it to extract Bounded Context names for a one-line summary
+4. Append the section to the end of `AGENTS.md` with the standard draft header
+5. **Idempotency**: if `## Where to Look` already present, do not overwrite or duplicate — skip this gap
+
+Draft output format:
+
+```markdown
+> **Draft** — auto-generated by roll-doc 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"}
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+```
+
+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.
+```
+
+**Minimum draft content:**
+
+- Module README: purpose (1–2 sentences), key files with one-line descriptions, dependencies (imports from / depended on by)
+- Context map: bounded contexts identified in the project, their responsibilities, relationships
+- Conventions: detected patterns — ENV vars, naming conventions, repeated file structure templates
+
+Do not fabricate details — infer only from source files actually read.
+
+## Phase 3b — Deep Read
+
+Deep-read phase that builds a full project symbol table (without truncation) and auto-detects
+cross-directory topics that directory-level Phase 3 alone cannot discover.
+
+**Trigger conditions** — Phase 3b runs when either is true:
+- Phase 2 found any gap (module or special gap)
+- The project exhibits code characteristics that Phase 3a cannot capture:
+  cross-directory import chains spanning ≥ 3 directories, state enums referenced by
+  multiple files, external URL/endpoint calls, or CI pipeline configuration files
+
+Pure documentation-only projects (no source code gaps, no code characteristics) skip Phase 3b.
+
+### Step 1 — Build Symbol Table
+
+Read each source file through the context-feed budget (US-CTX-001), not by hard-stuffing whole
+files unconditionally. The existing Phase 3 "up to 20 source files" count limit does not apply —
+Phase 3b aims for a complete project symbol table — but per-file material still goes through the
+feed budget: files within budget are read in full, and over-budget files are summarized/chunked
+with an explicit notice (never silently truncated) so the inner agent's context window is not
+blown. This replaces the previous "read every source file in full, no truncation" unbounded path.
+
+**Exclusion directories** (same as Phase 1):
+
+```
+node_modules/   .git/   dist/   build/   .shared/   .roll/dream/   .roll/briefs/
+```
+
+**Symbol table fields:**
+
+| Field | Content |
+|-------|---------|
+| `exports` | class / interface / type / function / const declarations, per file |
+| `imports` | source file → target file mapping (dependency graph edges) |
+| `enums` | enum declarations with enumerated values, per file |
+| `external_urls` | `fetch(...)` / `axios` / `http.*` calls, `API_ENDPOINT` / `*_URL` / `*_HOST` constants, hardcoded `https?://` strings (exclude comments and test fixtures) |
+| `configs` | CI workflow YAML files, build config paths, test framework config file paths |
+
+**`--dry-run` behavior:** print symbol table summary counts per category (e.g. "exports: 42, imports: 156, enums: 7, external_urls: 4, configs: 3") plus top-N examples per category. Write nothing to disk.
+
+**`--force` behavior:** unchanged — `--force` only affects draft generation (Phase 3/3b output files).
+The symbol table itself is rebuilt from scratch on every run regardless of flags.
+
+### Step 2 — Topic Detection
+
+Using the symbol table from Step 1, detect cross-directory topics. Each topic type has a
+detection rule and a target output file. Skip any topic whose target file already exists
+(unless `--force`). Skip any topic whose detection rule finds no matches.
+
+| Topic | Detection Rule | Output |
+|-------|---------------|--------|
+| 数据流 / 调用链 | Entry files (`bin/`, `cmd/`, `main.*`, `index.*`) → trace import chain to leaf nodes; require ≥ 1 chain spanning ≥ 3 directories | `docs/data-flows.md` |
+| 状态机 | Enums matching `*State` / `*Status` referenced by ≥ 2 source files | `docs/state-machines.md` |
+| 外部集成 | `external_urls` entries from symbol table (exclude comment/test-fixture matches) | `docs/integrations.md` |
+| 部署管线 | `.github/workflows/*.yml` / `.gitlab-ci.yml` / `circle.yml` / `Jenkinsfile` present, with deploy URL patterns detected | `docs/deployment.md` |
+| Agent 入口 (AGENTS.md) | Project root has no `AGENTS.md` AND `src/` (or equivalent source root) has ≥ 3 subdirectories | `AGENTS.md` |
+| 高引用目录 | Directory imported by ≥ 5 other source files, even if directory itself has < 3 source files | `<dir>/README.md` |
+
+#### Data Flow / Import Chain Tracing
+
+**Entry point selection:** start from entry files — any file matching patterns:
+`bin/*`, `cmd/**/*`, `main.*` (e.g. `main.ts`, `main.py`), `index.*` (e.g. `index.ts`, `index.jsx`),
+`App.*`, `server.*`. Exclude `node_modules/`, `dist/`, `build/`, test files (`*.test.*`, `*.spec.*`, `tests/`).
+
+**Chain construction:**
+1. For each entry file, read its imports from the symbol table's `imports` field.
+2. Recursively follow each imported file to its own imports, building a directed call graph.
+3. Stop at leaf nodes — files that import nothing or whose imports all point to:
+   - External packages (node_modules / stdlib / third-party)
+   - Already-visited nodes (cycle termination)
+4. Each distinct path from an entry file to a leaf is one call chain.
+
+**Threshold (cross-directory filter):**
+A call chain is valid for inclusion only if it spans **≥ 3 distinct source directories**.
+Count based on the unique parent directories of files in the chain:
+  `src/cli/main.ts → src/commands/build.ts → lib/utils/fs.ts` = 3 directories ✅
+  `src/cli/main.ts → src/cli/config.ts → lib/utils/fs.ts` = 2 directories ❌
+If no chain meets the ≥ 3 directory threshold, skip generation entirely (no empty `docs/data-flows.md`).
+
+**Output document structure** (`docs/data-flows.md`):
+
+```markdown
+> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+
+# Data Flows
+
+## Flow: {short descriptive name from entry file purpose}
+
+**Entry point:** `{entry_file}:{line}`
+**Directories spanned:** N ({comma-separated list})
+
+### Complete Call Chain
+
+{entry_file}
+  → import {symbol} from "{file}" ({line})
+    → import {symbol} from "{file}" ({line})
+      → ... (leaf node)
+
+### Files Involved
+
+| Step | File:Line | Function / Method |
+|------|-----------|-------------------|
+| 1 | `path/to/file:12` | `functionName` |
+| 2 | `path/to/file:34` | `otherFunction` |
+| ... | ... | ... |
+```
+
+- Sort flows by number of directories spanned, descending (widest cross-cutting flow first).
+- If an entry file produces multiple distinct call chains, list each one as a separate flow entry.
+- `file:line` annotations must come from actual symbol table records — do not fabricate.
+
+**Idempotency:** skip (do not overwrite) if `docs/data-flows.md` already exists, unless `--force`.
+
+#### State Machine
+
+**Detection rule:** enums whose name matches `*State` or `*Status` (case-insensitive)
+AND that are imported/referenced by **≥ 2 distinct source files**. Only count
+imports from source files — exclude test files (`*.test.*`, `*.spec.*`, `tests/`)
+and declaration files (`*.d.ts`).
+
+**Threshold:** if no enum meets the ≥ 2 cross-file reference threshold, skip
+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.
+
+# State Machines
+
+## State: `{EnumName}`
+
+**Defined in:** `{file}:{line}`
+
+### States
+{list of all enum values}
+
+### Referenced By
+
+| File:Line | Context |
+|-----------|---------|
+| `path/to/file:12` | `function processOrder(status: OrderState)` |
+| `path/to/file:34` | `if (status === OrderState.Pending)` |
+
+### Inferred Transitions
+
+| From | To | Evidence |
+|------|----|----------|
+| `Pending` | `Processing` | `order.ts:45` — `if (status === Pending) { status = Processing }` |
+| `Processing` | `Shipped` | `handler.ts:78` — assignment after `ship()` call |
+```
+
+**Transition inference:** scan the referencing files for patterns where an enum
+value is checked (`if (status === X)`, `case X:`) and the status variable is
+reassigned to another enum value in the same block. Record each distinct
+`{from, to, evidence file:line}` pair. Only include transitions backed by
+explicit code — do not fabricate implied transitions.
+
+**Output rules:**
+- One top-level `## State:` section per qualifying enum, sorted alphabetically.
+- Each enum section lists all defined values under `### States`.
+- `file:line` annotations must come from actual symbol table records — do not fabricate.
+- Existing `docs/state-machines.md` → skip unless `--force`.
+- No qualifying enum → skip generation entirely (no empty document).
+
+#### External Integrations
+
+**Detection rule:** scan `external_urls` from the symbol table —
+`fetch(...)` / `axios` / `http.get` (and `http.*`) calls, constants shaped like
+`API_ENDPOINT` / `*_URL` / `*_HOST`, and hardcoded `https?://` strings. Exclude
+matches inside comments and test fixtures (`*.test.*`, `*.spec.*`, `tests/`,
+`fixtures/`).
+
+**Threshold:** if no external integration is detected, skip generation entirely
+(no empty `docs/integrations.md`).
+
+**Output document structure** (`docs/integrations.md`):
+
+```markdown
+> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+
+# External Integrations
+
+## Integration: `{endpoint URL}`
+
+### Call Sites
+
+| File:Line | Timeout | Error Handling / Fallback |
+|-----------|---------|---------------------------|
+| `path/to/file:12` | `timeout: 5000` | `.catch` retry fallback |
+| `path/to/file:48` | — | try/catch |
+```
+
+**Per-integration fields:**
+- **endpoint URL** — the external URL / endpoint reached.
+- **call file:line** — every source location calling this endpoint.
+- **timeout config** — the value if the calling code carries a `timeout: N` field,
+  otherwise `—`.
+- **error handling / fallback** — recorded when the calling code has a `.catch`
+  handler or a `try` / `catch` block around the call, otherwise `—`.
+
+**Output rules:**
+- The same endpoint reached from multiple sites is merged into **one** integration
+  section that lists **all** its call sites — never one section per call.
+- One top-level `## Integration:` section per distinct endpoint, sorted alphabetically.
+- `file:line` annotations must come from actual symbol table records — do not fabricate.
+- Existing `docs/integrations.md` → skip unless `--force`.
+- No external integration detected → skip generation entirely (no empty document).
+
+#### Deployment Pipeline
+
+**Detection rule:** the project has at least one CI configuration file —
+`.github/workflows/*.yml` (or `*.yaml`) / `.gitlab-ci.yml` / `circle.yml` /
+`.circleci/config.yml` / `Jenkinsfile` — AND a deploy URL pattern appears in the
+code or CI config (vercel / netlify / cloudflare / firebase, or hostnames ending
+in `*.app` / `*.dev`). Pull deploy URLs from the `configs` and `external_urls`
+fields of the symbol table.
+
+**Threshold:** if no CI configuration file is detected, skip generation entirely
+(no empty `docs/deployment.md`).
+
+**Output document structure** (`docs/deployment.md`):
+
+```markdown
+> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+
+# Deployment
+
+## Pipeline: `{ci config file}`
+
+**CI Platform:** GitHub Actions
+**Trigger events:** push (main), pull_request, release
+
+### Key Jobs
+
+| Job | File:Line | Purpose |
+|-----|-----------|---------|
+| `test` | `.github/workflows/deploy.yml:18` | run test suite |
+| `build` | `.github/workflows/deploy.yml:25` | compile artifacts |
+| `deploy` | `.github/workflows/deploy.yml:33` | deploy to Vercel |
+
+### Deploy Targets
+
+| URL | File:Line |
+|-----|-----------|
+| `https://my-app.vercel.app` | `.github/workflows/deploy.yml:14` |
+
+### Environment Variables
+
+| Name | File:Line |
+|------|-----------|
+| `NODE_ENV` | `.github/workflows/deploy.yml:11` |
+| `VERCEL_TOKEN` | `.github/workflows/deploy.yml:12` |
+```
+
+**Per-pipeline fields:**
+- **CI platform** — inferred from which config file is present (GitHub Actions /
+  GitLab CI / CircleCI / Jenkins).
+- **trigger events** — the events that start the pipeline (`push` / `pull_request` /
+  `tag` / `release`), read from the CI config.
+- **key jobs** — each job / stage name with its `file:line` location.
+- **deploy target URL** — the deploy URL(s) matched by the detection rule.
+- **environment variable names** — every env var name referenced in the CI config,
+  listed **without values** (never emit secret values, only names).
+
+**Output rules:**
+- One top-level `## Pipeline:` section per CI configuration file, sorted alphabetically.
+- `file:line` annotations must come from actual symbol table / CI config records — do not fabricate.
+- Existing `docs/deployment.md` → skip unless `--force`.
+- No CI configuration detected → skip generation entirely (no empty document).
+
+#### Agent Entrypoint (AGENTS.md)
+
+This topic handles the **「文件不存在 → 创建」** case: when a project has no agent-facing
+convention file at all, generate a complete baseline `AGENTS.md`. It is complementary to the
+Phase 2 **"AGENTS.md Where to Look bootstrap"** rule, which handles the **「文件存在 → 补章节」**
+case (append a missing `## Where to Look` section to an existing `AGENTS.md`). The two rules
+never overlap — this one only fires when no `AGENTS.md` exists.
+
+**Detection rule:** project root has **no** `AGENTS.md` AND the source root (`src/`, or the
+equivalent — `lib/`, `app/`, `pkg/`, etc.) contains **≥ 3 subdirectories**. If `AGENTS.md`
+already exists, skip entirely (do not overwrite unless `--force`). If the source root has
+fewer than 3 subdirectories, skip — the project is too small to warrant a baseline doc.
+
+**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.
+
+# {Project Name}
+
+{One-sentence positioning: what this project is, inferred from README / package metadata.}
+
+## Where to Look
+
+- **Domain model**: `.roll/domain/context-map.md` — Contexts: {list, or "see file"}
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+- **Doc index**: `docs/INDEX.md` — generated documentation map
+
+## Source Layout
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/parser/` | tokenize and parse input (≤ 2 lines each) |
+| `src/codegen/` | emit output artifacts |
+| `src/cli/` | command-line entry and option wiring |
+```
+
+**Per-section rules:**
+- **Project positioning** — a single sentence describing what the project does, inferred from
+  the README / package metadata; never fabricate beyond what the source supports.
+- **`## Where to Look`** — pointer lines **only for directories that actually exist**
+  (`.roll/domain/`, `.roll/features/`, `docs/INDEX.md`, etc.); never fabricate pointers to
+  missing paths. If `.roll/domain/context-map.md` exists, read it for Bounded Context names.
+- **Source Layout** — one row per key source subdirectory, each description **≤ 2 lines**,
+  inferred from the files actually read in the symbol table.
+
+**Output rules:**
+- Existing `AGENTS.md` → skip unless `--force` (never overwrite a human-authored file).
+- Source root with < 3 subdirectories → skip generation entirely (no empty `AGENTS.md`).
+- All three sections must be present in the generated file.
+
+#### High Fan-in Directory (README)
+
+This topic complements the Phase 2 file-count threshold. A directory may hold only one or two
+source files yet be imported across the whole codebase (shared utils, a single-file core
+module). The file-count rule (≥ 3 files) alone skips such hot paths, so high fan-in widens the
+threshold to **「文件数 ≥ 3 OR 被 ≥ 5 个文件引用」**.
+
+**Detection rule:** using the symbol table's `imports` edges, count the **distinct source files
+that import any file in the directory**. If that count is **≥ 5**, the directory qualifies for a
+`<dir>/README.md` gap, **even when it contains < 3 source files**. Only count referencing files
+that are source files — exclude test files (`*.test.*`, `*.spec.*`, `tests/`) and files inside
+the directory itself. This rule operates **in addition to** the Phase 2 count ≥ 3 rule, never
+replacing it: directories meeting either condition get a README.
+
+**Output rules:**
+- Target file is `<dir>/README.md`, generated with the same Module README content as Phase 3
+  (purpose, key files, dependencies).
+- Existing `<dir>/README.md` → skip unless `--force` (never overwrite).
+- Directory imported by < 5 source files **and** holding < 3 source files → skip (no gap).
+- A directory already qualifying under the count ≥ 3 rule is not double-counted — one README.
+
+### Step 3 — Source Annotations
+
+Every topic document generated in Step 2 must cite `file:line` for each claim (function call,
+endpoint URL, state transition, CI job, import path). Annotations must come from actual
+symbol table records — do not fabricate line numbers. Follows the same "Do not fabricate"
+rule as Phase 3.
+
+**Mandatory `file:line` column** — each topic document's source-reference tables MUST carry a
+dedicated `file:line` column so the reader can jump straight to the code:
+- 「涉及文件」/ Files Involved table → one `file:line` per row.
+- 「引用文件」/ Referenced By table → one `file:line` per referencing site.
+- 「调用链」/ Complete Call Chain table → one `file:line` per hop.
+
+Do **not** fabricate a `file:line` value: every annotation MUST come from an actual symbol
+table record (the same "Do not fabricate" rule as above). If the symbol table has no line for
+a claim, omit the row rather than invent a location.
+
+---
+
+## Phase 4 — Report
+
+After all phases complete, output a summary:
+
+```
+📚 roll-doc complete
+
+Phase 1 — Index
+  N docs scanned, docs/INDEX.md updated
+  Categories: guide(N) domain(N) convention(N) module(N) stray(N)
+
+Phase 2 — Gaps
+  N undocumented module directories found
+  N special gaps (domain map / conventions)
+
+Phase 3 — Fill
+  N drafts generated: [list of paths]
+  N skipped (already exist; use --force to regenerate)
+
+Phase 3b — Deep Read
+  Symbol table: exports(N) imports(N) enums(N) external_urls(N) configs(N)
+  N topic documents generated:
+    - docs/dataflow.md       (data-flow)          source entries: N
+    - docs/state-machines.md (state-machine)       source entries: N
+    - docs/integrations.md   (external-integration) source entries: N
+  N topics skipped (no matches or already exist; use --force to regenerate)
+
+📋 Review priority (largest / most active modules first):
+  1. src/commands/README.md — 8 source files
+  2. docs/CONVENTIONS.md — 6 patterns detected
+```
+
+Each generated topic document is listed with its **path**, **type**, and **来源条目数 /
+source entries** (how many symbol-table records back the document). When Phase 3b produced no
+subject-level documents, print exactly one line and do **not** error:
+
+```
+Phase 3b: no subject-level drafts generated
+```
+
+If `--dry-run`, the `Phase 3b — Deep Read` section is shown the same way but every generated
+line is tagged `(plan)` — matching Phase 3's dry-run convention (nothing is written):
+
+```
+Phase 3b — Deep Read  (plan)
+  N topic documents would be generated:
+    - docs/dataflow.md (data-flow) source entries: N  (plan)
+```
+
+If no gaps were found:
+
+```
+✅ roll-doc: no gaps found. docs/INDEX.md updated.
+```
+
+If `--dry-run`:
+
+```
+🔍 roll-doc --dry-run: N drafts would be generated (nothing written).
+```
+
+## Rules
+
+- Never modify existing documentation files — only generate new drafts
+- `docs/INDEX.md` is the only existing file that may be overwritten (derived artifact)
+- Draft files are never committed by this skill — human reviews and commits them
+- Works on any project; always read project structure before acting
+- Do not fabricate module details — infer only from source files actually read

package/skills/roll-doctor/SKILL.md

@@ -2,11 +2,15 @@
 name: roll-doctor
 license: MIT
 allowed-tools: "Read, Bash, Edit"
-description: "Diagnose Roll toolchain health. Checks skill files, YAML frontmatter, symlinks, conventions sync, template integrity, and config validity."
+description: "Load when diagnosing Roll toolchain health, conventions sync, skill file health, templates, symlinks, config validity, or installation integrity."
 ---
-
 # Roll Doctor
 
+## Gotchas
+
+- Doctor diagnoses toolchain and convention health; it should fail loud on broken contracts rather than hiding drift.
+- Skill health checks belong here only as diagnostics; changing skill content still happens in roll-skills.
+
 诊断 Roll 工具链健康状态。快速定位 skill 不工作、convention 不同步、symlink 断裂等问题。
 
 ## When to Use
@@ -50,6 +54,21 @@ Check:
 - No duplicate `name` values across skills
 - File is readable markdown
 
+When diagnosing a roll-skills checkout, run the first-class skill audit:
+
+```bash
+node scripts/audit-skills.mjs
+node scripts/audit-skills.mjs --json
+node scripts/audit-skills.mjs --strict
+```
+
+Check:
+- Every description starts with `Load when...` and stays at 50 words or fewer
+- Every skill has positive and negative route cases in `route-cases/skills.json`
+- Every skill has Gotchas / Known Failure Modes coverage
+- Hub/spoke integrity has no missing or unreferenced `references/`, `assets/`, or `scripts/` files
+- Oversized hubs either split below 250 lines or carry an explicit reviewed waiver
+
 ### 3. Symlinks
 
 ```bash