@seanyao/roll 2026.529.5 → 2026.601.2

package/skills/roll-doc/SKILL.md

@@ -95,12 +95,13 @@ 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**: directories with ≥ 3 source files (default). Tune by editing the skill.
+**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.
 
@@ -177,9 +178,12 @@ Pure documentation-only projects (no source code gaps, no code characteristics)
 
 ### Step 1 — Build Symbol Table
 
-Read every source file **in full** (no truncation). The existing Phase 3 "up to 20 source files"
-limit does not apply — Phase 3b builds a complete project symbol table for downstream topic
-detection to reason across files without missing logic.
+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):
 
@@ -272,6 +276,236 @@ If no chain meets the ≥ 3 directory threshold, skip generation entirely (no em
 
 **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,
@@ -279,6 +513,16 @@ endpoint URL, state transition, CI job, import path). Annotations must come from
 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
@@ -302,15 +546,34 @@ Phase 3 — Fill
 
 Phase 3b — Deep Read
   Symbol table: exports(N) imports(N) enums(N) external_urls(N) configs(N)
-  N topic documents generated: [list of paths and types]
+  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)
-  (if no topics generated: "no subject-level drafts generated")
 
 📋 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:
 
 ```

package/skills/roll-fix/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: roll-fix
 license: MIT
+allowed-tools: "Read, Edit, Write, Glob, Grep, Bash, Skill"
 description: Execute bugfix/hotfix from backlog. Reads FIX/BUG from .roll/backlog.md, delivers via TCR workflow. Lighter than roll-build, focused on single-issue fixes.
 ---
 
@@ -89,24 +90,29 @@ Before creating any file or directory:
 
 ### 0. Pre-flight self-check (US-AGENT-007)
 
-Before locking the issue, read the FIX's Agent profile (est_min / risk_zone / chain_depth) from the linked feature md and decide whether this cycle should attempt the fix:
+Before locking the issue, read the FIX's Agent profile (est_min / chain_depth) from the linked feature md and decide whether this cycle should attempt the fix:
 
 ```
 inputs:
   fix.est_min       (from **Agent profile:** block on the FIX row's feature md)
-  fix.risk_zone     (low / medium / high)
   fix.chain_depth   (0 unless already a downgrade product)
-  agent.max_est_min (from .roll/agent-routes.yaml for the current agent)
-  history.prefer_threshold + history.hit_rate (FIX history for this agent)
 
 verdict:
-  too_big when ANY:
-    1. fix.est_min > agent.max_est_min
-    2. fix.risk_zone not in agent.risk
-    3. history.hit_rate < prefer_threshold AND fix.chain_depth == 0
+  too_big when:
+    fix.est_min > 20   (lands in the `hard` complexity tier)
   ok otherwise
 ```
 
+Routing is a single axis now (US-AGENT-022): `est_min` maps to one of three
+complexity tiers — `easy` (≤8), `default` (8<x≤20), `hard` (>20) — and each
+tier binds to a locally-installed agent slot in `.roll/agents.yaml` (model =
+the agent's own default; a `fallback` slot mechanically covers an unavailable
+agent). The retired v1 model (three-dimension type/est/risk_zone matching
+against `agent-routes.yaml`, soft history hit-rate preference, per-agent
+`max_est_min`/`risk`) no longer applies. The pre-flight verdict here is just
+the `hard`-tier boundary: a FIX estimated past it is a sanity signal that the
+"single small fix" assumption may be wrong.
+
 Emit `verdict: ok` or `verdict: too_big` (with `reason:`) as the first cycle output line.
 
 - `ok` → continue with step 1 below normally
@@ -369,7 +375,7 @@ Change the Status of the corresponding row from `📋 Todo` or `🔨 In Progress
 
 ### 12. Update Changelog
 
-**Mandatory** — release notes depend on this step. Do not skip.
+**Mandatory** — the release (GitHub Release body = this version's changelog section) depends on this step. Do not skip.
 
 ```bash
 $roll-.changelog

package/skills/roll-loop/SKILL.md

@@ -247,7 +247,7 @@ Together these mean: only one loop runs at a time per project (LOCK), and within
 > 2. Read its Agent profile (est_min / risk_zone) and routed an agent via `_loop_pick_agent_for_story` (hard rules from `.roll/agent-routes.yaml` + soft preference from `runs.jsonl`)
 > 3. Exported `ROLL_LOOP_ROUTED_STORY` / `ROLL_LOOP_ROUTED_AGENT` / `ROLL_LOOP_ROUTED_RULE` and printed `[loop] story <id> routed to <agent> via <rule_kind>` to cron.log
 >
-> When `ROLL_LOOP_ROUTED_STORY` is set, prefer it as `US_ID` for this cycle. The story has already been chosen by hard+soft routing rules — do not re-pick a different one unless that story can no longer be found in BACKLOG (e.g. status changed concurrently).
+> When `ROLL_LOOP_ROUTED_STORY` is set, prefer it as `US_ID` for this cycle. The story has already been chosen by hard+soft routing rules — and, per FIX-146, the runner re-validates it against the authoritative backlog right before handing it to you (re-picking the next eligible Todo if it went ✅ Done / In Progress / ineligible between pick and handoff, emitting a `story_stale` event). So treat `ROLL_LOOP_ROUTED_STORY` as already-eligible and just work it. Only if you still find at cycle start that it is no longer 📋 Todo in BACKLOG (a residual concurrent flip), re-pick the next eligible Todo via `_loop_pick_next_story` rather than idling the whole cycle.
 >
 > Old single-agent fallback (`primary_agent` from `~/.roll/config.yaml`) still applies when:
 > - no story is pickable (empty Todo / all manual-only)
@@ -344,12 +344,14 @@ After each item completes:
 
    **Path B — heal exhausted (≥`ROLL_LOOP_HEAL_MAX`, default 2) or disabled (`ROLL_LOOP_NO_HEAL=1`) (exit 1):**
 
-   1. Do NOT force ✅ Done here. CI red means the PR will not merge, and
-      FIX-140's merge gate (in `bin/roll`, after `publish_wait_merge`) is the
-      single authority on final status: if the PR actually merges, the story
-      stays ✅ Done; if it does not merge, the gate reverts it ✅ Done → 📋 Todo
-      so BACKLOG never shows a false Done for code that isn't on main. (FIX-141
-      then stops the next cycle re-opening a duplicate PR while this one is open.)
+   1. Do NOT force ✅ Done here. CI red means the PR will not merge. Under
+      **US-AUTO-044** the main loop no longer waits for merge — it publishes the
+      PR and exits; the dedicated PR Loop (`com.roll.pr.<slug>`, every 5 min)
+      merges / rebases / closes it asynchronously. There is no false-Done risk:
+      with worktree isolation the ✅ Done lives only in the unmerged PR, never on
+      the loop's main checkout, and the story is not re-picked meanwhile via the
+      open-PR eligibility gate (`_loop_story_is_eligible`, FIX-146). The story's
+      ✅ Done lands on main only when the PR Loop actually merges the PR.
    2. Write ALERT to `~/.shared/roll/loop/ALERT-<slug>.md` with:
       - story ID, time, commit SHA
       - heal attempts made (read `heal_count:` from `state-<slug>.yaml`)

package/skills/roll-notes/SKILL.md

@@ -24,7 +24,7 @@ $roll-notes 今天的 code review 给了很好的反馈
 ## When Not to Use
 
 - Capturing a bug or feature idea into BACKLOG (use `$roll-idea`)
-- Generating user-facing release notes (use `$roll-.changelog`)
+- Generating the user-facing changelog (use `$roll-.changelog`)
 - Writing design documents or AC (use `$roll-design`)
 
 ## Behavior

package/skills/roll-onboard/SKILL.md

@@ -55,6 +55,58 @@ Walk the repo. Identify:
 - **domains**: top business/technical domains (e.g., "auth", "billing", "search")
 - **key_modules**: top 3-5 modules that hold most of the logic
 
+### Step 1b — Phase 2 analysis: business model, tech, tests (US-ONBOARD-016)
+
+A single onboard now produces three structured analysis sections in the plan
+(`domain_model`, `tech_analysis`, `test_assessment`). Build them here so Step 4
+can serialise them.
+
+**`domain_model`** — from the code you read, identify the bounded contexts. For
+each: a `name`, its `aggregates` (the entities that own consistency), and its
+`ubiquitous_language` (the domain terms the code/docs actually use). If you
+genuinely cannot infer contexts from the code, emit an empty
+`bounded_contexts: []` — do NOT invent contexts that aren't in the code.
+
+**`tech_analysis`** — `stack` (languages/frameworks evidenced by manifests),
+`dependencies` (from `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml`
+etc.), `architecture_notes` (observed structure, not aspirational), and `risks`
+(each a mapping with a `description`; optionally `severity: LOW|MEDIUM|HIGH` and
+an `evidence: detected|inferred` tag).
+
+**`test_assessment`** — this section is under a **hard anti-hallucination
+constraint** (next sub-step). Do NOT write it from intuition.
+
+#### The verifiable test scan (ANTI-HALLUCINATION HARD CONSTRAINT)
+
+Every `test_assessment` claim must be backed by a real filesystem scan you run
+here — never by "what a project like this usually needs". Run these probes and
+record the raw counts/paths:
+
+1. **Count test files** by the conventional patterns:
+   - `*.test.*` / `*.spec.*` (JS/TS), `*_test.go` (Go), `test_*.py` / `*_test.py` (Python), `*_spec.rb` (Ruby), `*Test.java` (Java)
+   - e.g. `git ls-files | grep -cE '\.(test|spec)\.[jt]sx?$'` and similar per pattern
+2. **Probe for runner configs**: `jest.config.*`, `pytest.ini` (or `[tool.pytest]` in `pyproject.toml`), `.mocharc.*`, `vitest.config.*`, `karma.conf.*`, `phpunit.xml`, `go test` (implied by `*_test.go`)
+3. **Probe for a `coverage/` directory** (and `.coverage` / `coverage.xml` artifacts)
+
+Then turn the raw findings into claims, each a **mapping** carrying a `claim`
+string plus an `evidence` tag:
+
+- `evidence: detected` — the scan directly found it (e.g. "42 `*.test.ts` files detected", "vitest.config.ts present", "coverage/ directory present").
+- `evidence: inferred` — a judgement you derived FROM the detected facts (e.g. "unit layer present but no E2E config — integration coverage likely thin"). The inference must trace back to something the scan detected.
+
+**"none detected" rule**: when a probe finds nothing, you MUST say so explicitly
+with a tagged claim — `{claim: "none detected", evidence: detected}` (a scan that
+ran and returned zero is a genuine `detected` finding). You must NOT silently
+omit the dimension, and you must NOT invent generic filler like "needs more E2E
+tests" / "consider adding integration tests" with no detected basis. The plan
+validator (`lib/roll-plan-validate.py`) rejects any untagged free-text claim, so
+filler will fail `roll init --apply`.
+
+Map the findings into the three buckets:
+- `current_layers`: what test layers actually exist (each tagged `detected`)
+- `gaps`: dimensions where the scan found nothing (`none detected`, tagged `detected`) or thin coverage you can justify (`inferred`)
+- `recommended_actions`: actions that trace to a detected gap (tag `inferred`); if nothing is missing, this bucket may be `[]`
+
 ### Step 2 — Get gap report
 
 Run `roll-doc --dry-run` (READ-ONLY mode). This reports:
@@ -121,6 +173,39 @@ agent_routes_template: default                # user's Q10 — agent routing pre
                                               # minimal = single agent (pi), no history
                                               # heavy   = pi/deepseek/claude/kimi + larger window
                                               # skip    = don't seed .roll/agent-routes.yaml
+
+# ── US-ONBOARD-016: Phase 2 analysis sections (optional, but emit all three) ──
+# All three are validated only when present, so they are backward-compatible,
+# but a normal onboard should produce them from Step 1b.
+
+domain_model:
+  bounded_contexts:                          # [] if none can be inferred — never invent
+    - name: auth
+      aggregates: [User, Session]
+      ubiquitous_language: [login, token, refresh]
+
+tech_analysis:
+  stack: [bash, python3]                     # evidenced by manifests
+  dependencies: [pyyaml]                     # from package.json / pyproject / go.mod / ...
+  architecture_notes: ["single-binary CLI + python helpers in lib/"]
+  risks:
+    - description: "no automated test run on macOS bash 3.2"
+      severity: HIGH                         # optional: LOW | MEDIUM | HIGH
+      evidence: detected                     # optional: detected | inferred
+
+# test_assessment — ANTI-HALLUCINATION: every claim is a mapping with an
+# `evidence` tag (detected | inferred). A zero-result scan is `none detected`
+# tagged `detected`. Untagged free-text is REJECTED by the validator.
+test_assessment:
+  current_layers:
+    - claim: "112 bats files detected under tests/"   # evidence: a real scan count
+      evidence: detected
+  gaps:
+    - claim: "none detected"                 # e.g. no coverage/ dir found
+      evidence: detected
+  recommended_actions:                       # [] if nothing is missing
+    - claim: "add a macOS CI runner (inferred from launchd-only test skips)"
+      evidence: inferred                     # an inference traceable to a detected fact
 ```
 
 Then tell the user:

package/skills/roll-peer/SKILL.md

@@ -180,7 +180,7 @@ Running
 
 ### Per Peer Pair (e.g., kimi→claude)
 
-Stored in `~/.shared/roll/peer/state.yaml`:
+Stored in `~/.roll/.peer-state/` (flat key files per pair):
 
 ```yaml
 kimi→claude:
@@ -269,7 +269,7 @@ When peer review is manually triggered by a human (via `/peer`, "叫上 peer", e
 - Relay the peer's response **verbatim** before adding your own analysis.
 - After the peer's reply, the reviewer's own analysis block must explicitly state whether the peer's root cause and fix direction match the reviewer's own (independent) conclusion — that comparison is what determines the next round's action.
 - If a peer call fails or times out, report it immediately inline and either retry or ESCALATE.
-- Negotiation log is still written to `~/.shared/roll/peer/logs/` as usual.
+- Negotiation log is written to `<project>/.roll/peer/logs/` as usual.
 
 **Why inline, not tmux:** When a human manually triggers peer review inside an agent's interactive session, the conversation IS the visible interface. tmux auto-attach is only relevant for CLI-launched background sessions (`bin/roll peer`), not for skill invocations.
 
@@ -300,8 +300,9 @@ When Attacker and Defender reach a stalemate (both tests pass but interpretation
 
 ## Output Artifacts
 
-- **Negotiation log**: `~/.shared/roll/peer/logs/<timestamp>_<from>_<to>.md`
-- **State file**: `~/.shared/roll/peer/state.yaml`
+- **Negotiation log**: `<project>/.roll/peer/logs/<timestamp>_<from>_<to>.md`
+- **Structured record**: `<project>/.roll/peer/runs.jsonl`
+- **State file**: `~/.roll/.peer-state/`
 - **Decision record**: If AGREE, append summary to `docs/decisions/` or `.roll/backlog.md` (optional)
 
 ## Configuration
@@ -327,7 +328,7 @@ peer:
 
 ## Limitations
 
-1. **Reverse link reliability**: Direct CLI calls are preferred. Reliability varies by tool — see Peer Invocation Reference table. If a peer fails consistently, the adaptive streak tracker marks it `abandoned` and falls back to the next candidate. File mailbox (`~/.shared/roll/peer/mailbox/`) is the last-resort fallback.
+1. **Reverse link reliability**: Direct CLI calls are preferred. Reliability varies by tool — see Peer Invocation Reference table. If a peer fails consistently, the adaptive streak tracker marks it `abandoned` and falls back to the next candidate. File mailbox (`<project>/.roll/peer/mailbox/`) is the last-resort fallback.
    - `deepseek serve --http` is the most reliable option when available — prefer it over direct `deepseek` CLI invocation.
    - `codex exec` has known TTY/Ink issues in non-interactive environments; treat as low-priority fallback.
 2. **Cost**: Every peer review consumes tokens on both sides. Only trigger for tasks where the cost of a wrong decision exceeds the cost of peer review. DeepSeek is the most cost-effective peer for general use.