@seanyao/roll 0.5.0 → 2.602.1

package/skills/roll-onboard/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: roll-onboard
+license: MIT
+description: Interactive onboarding for legacy projects. Reads existing code, understands the project, asks 9 questions in 3 groups (cognition / scope / privacy), and writes .roll/onboard-plan.yaml as the contract for `roll init --apply` to execute.
+---
+
+# Roll Onboard
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering Common Sense defined in the project AGENTS.md.
+
+Interactive onboarding flow for **legacy projects**: existing code that needs to adopt the Roll convention without disrupting how the team already works.
+
+## Trigger
+
+This skill runs when:
+
+- `roll init` detected a legacy project (≥10 source files, no `AGENTS.md`)
+- The CLI told the user to open an AI agent and run `$roll-onboard`
+- The user has now invoked you here
+
+## Hard responsibility boundary
+
+You are the **认知 (cognition) layer**. Your job ends with writing a plan file.
+
+| You do | You do NOT |
+|--------|------------|
+| Read project code, infer type/domains/modules | Modify any source file |
+| Call `roll-doc --dry-run` to get a gap report | Call `roll-doc` (write mode) |
+| Ask the user 9 questions across 3 groups | Decide for the user |
+| Produce `.roll/onboard-plan.yaml` | Write `.gitignore` |
+| Produce `.roll/onboard-plan.yaml` | Run `roll init --apply` |
+
+Hard constraint: **AI cannot create files in the user's project other than `.roll/onboard-plan.yaml`.** Anything else is `bash`'s job (`roll init --apply`).
+
+## Inputs you must read
+
+1. The repository tree (use the project's own structure to infer technologies)
+2. Any existing `README.md` / `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` etc. as evidence
+3. `roll-doc --dry-run` output → identifies what documentation gaps exist
+4. The path-audit pattern: scan for legacy structure markers (`BACKLOG.md`, `docs/features/`, etc.) — if any are present, REFUSE and tell the user to run `roll migrate` first
+
+## Workflow
+
+### Step 0 — Pre-flight
+
+1. Check that you're in a legacy project root (no `AGENTS.md`, has source code)
+2. If `BACKLOG.md` or `docs/features/` already present → STOP, tell user to run `roll migrate` first (this is a partial-migration project, not legacy)
+3. Check `.roll/onboard-plan.yaml` doesn't already exist; if it does, ask user whether to overwrite
+
+### Step 1 — Read code, build understanding
+
+Walk the repo. Identify:
+- **type**: one of `backend-service` / `frontend-only` / `fullstack` / `cli`
+- **description**: 1-2 sentence summary of what this project does
+- **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:
+- Which standard Roll artifacts (BACKLOG, features, domain models) are missing
+- Which existing docs Roll could `include` rather than regenerate
+
+### Step 3 — Three groups of nine questions
+
+Present these in chat. **Aim for total time ≤ 3 minutes.** Group 1 confirms your understanding; group 2 scopes the work; group 3 handles privacy and next steps.
+
+**$(msg onboard.questions_group1)**
+
+1. $(msg onboard.q1 "[type]" "[description]")
+2. $(msg onboard.q2 "[domain A, domain B, …]")
+3. $(msg onboard.q3 "[X, Y, Z]")
+
+**$(msg onboard.questions_group2)**
+
+4. $(msg onboard.q4) Multi-select:
+   - `backlog` — initial BACKLOG with seeded stories
+   - `features` — features index + per-feature spec stubs
+   - `domain` — DDD context map
+   - `briefs` — directory for `$roll-brief` outputs
+5. Of these existing docs, which should I `include` rather than regenerate?
+   - (list candidates: README.md, docs/architecture.md, etc.)
+6. Put drafts inside `.roll/`? (default: yes; "no" means use the legacy `docs/` layout — not recommended for new adoption)
+
+**Group 3 — Privacy & next steps**
+
+7. Add `.roll/` to `.gitignore`? (yes = keep project management private; no = commit it like Roll itself does)
+8. Sync Roll conventions to which AI tools? Multi-select from detected agents (claude / cursor / codex / kimi / deepseek / pi / opencode / agy / trae)
+9. Enable `roll loop` autonomous execution after init?
+
+### Step 4 — Write plan file
+
+Write `.roll/onboard-plan.yaml` with this exact schema (validated by `lib/roll-plan-validate.py`):
+
+```yaml
+version: 1
+generated_at: "2026-05-19T14:30:00+08:00"   # current ISO 8601, your timezone OK
+
+project_understanding:
+  type: cli                                  # one of: backend-service / frontend-only / fullstack / cli
+  description: "..."
+  domains: [...]
+  key_modules: [...]
+
+scope:
+  approved: [backlog, features, domain]      # user's Q4 multi-select
+  declined: [briefs]                         # what they said no to
+
+include_existing:
+  - README.md                                # user's Q5 selections
+  - docs/architecture.md
+
+privacy:
+  gitignore_dot_roll: true                   # user's Q7
+
+sync_targets: [claude, cursor]               # user's Q8
+enable_loop: false                            # user's Q9
+agent_routes_template: default                # user's Q10 — agent routing preset
+                                              # one of: default / minimal / heavy / skip
+                                              # default = pi/deepseek/claude + history (US-AGENT-002)
+                                              # 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:
+
+> Onboard conversation done. Plan saved to `.roll/onboard-plan.yaml`.
+> Return to your terminal and run:
+>
+>     roll init --apply
+>
+> The plan expires in 24 hours.
+
+### Step 5 — Stop
+
+Do NOT run `roll init --apply` yourself. Do NOT modify other project files. Your job is done.
+
+## When NOT to use
+
+- **Not a legacy project**: empty dir or fresh project → use plain `roll init` instead
+- **Has BACKLOG.md or docs/features/**: this is a pre-2.0 Roll project → run `roll migrate` first
+- **Has .roll/ already**: already onboarded → don't re-run
+
+## Failure modes
+
+- User aborts mid-conversation → don't write partial plan; tell user to re-run from scratch
+- User answers contradict the gap report (e.g., declines `features` but has lots of code) → ask the contradictory question once more before accepting; if they confirm, respect the choice
+- You can't read enough code to fill `project_understanding` (e.g., binary repo) → write a placeholder plan but ask user to fill in `type` and `description` manually before applying

package/skills/roll-peer/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: roll-peer
+license: MIT
+allowed-tools: "Read, Bash, Write, Edit"
+description: |
+  Cross-agent peer review skill. When a task enters a decision phase (planning,
+  high-risk, ambiguous, destructive), triggers a bidirectional negotiation with
+  another AI agent via a unified protocol. Up to 3 rounds. If consensus is not
+  reached, escalates to the human user. Includes adaptive peer routing based on
+  task type and historical success rate.
+  Trigger: /peer, "叫上 peer", "peer review", or auto-triggered at workflow gates.
+---
+
+# Roll Peer (Cross-Agent Peer Review)
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+## Credits
+
+Cross-agent consultation protocol inspired by
+[friend-skill](https://github.com/fpyluck/friend-skill) (MIT) by fpyluck.
+Independent implementation for the Roll toolchain.
+
+## Trigger
+
+**Manual:**
+- `/peer`
+- "叫上 peer"
+- "peer review 一下"
+- "和 peer 商量"
+
+**Auto-triggered (with 10s opt-out):**
+- `roll-build` enters Plan Mode (executable plans / architecture decisions)
+- `roll-spar` Attacker and Defender disagree
+- High context pressure (large number of files read / tools executed)
+- Destructive / irreversible operations (`rm -rf`, production deploy, global config changes)
+- High-risk signal words ("重要 / 关键 / 别搞砸 / important / critical")
+- Cross-repository / cross-toolchain / ambiguous permission boundaries
+
+**Never trigger:**
+- Single-file changes
+- Clear, well-defined fixes
+- Simple refactoring
+
+## Protocol: `[PEER_REVIEW]`
+
+### Marker Format
+
+The marker **must** appear on the first non-empty line of the message:
+
+```markdown
+[PEER_REVIEW round=N tool=<from>→<to>]
+```
+
+- `round=N`: Current round number (1–3)
+- `tool=<from>→<to>`: Direction of this message (e.g., `kimi→claude`)
+
+### Three-State Resolution + Escape
+
+Allowed states only. No invented words.
+
+- **AGREE**: Accept the current proposal. Proceed to execution.
+- **REFINE**: Direction is correct, but specific changes are needed. Proceed to next round.
+- **OBJECT**: The proposal is wrong. Provide an alternative. Proceed to next round.
+- **ESCALATE**: Round 3 reached without AGREE, or a round fails due to API/token error. Hand off to the human user.
+
+After each round decision, emit a `peer` event to the cycle event stream:
+
+```bash
+# $round = current round number, $total = max rounds, $verdict = AGREE/REFINE/OBJECT/ESCALATE
+# $agents = e.g. "claude→deepseek"
+_loop_event peer "${round}/${total}" "$verdict" "$agents" 2>/dev/null || true
+```
+
+If information is insufficient:
+```
+REFINE: Need to confirm X/Y/Z with the user first.
+```
+
+### Context Handoff Card (required for round=1)
+
+When the task involves a local project, the first message must include:
+
+```markdown
+## Project Handoff (round=1 required)
+- Project root: <absolute path>
+- Execution environment: <shell / container / devcontainer / remote / N/A>
+- Project type: <language + framework>
+- Virtual environment: <absolute path / conda env / container name / N/A>
+- Activation command: <one-line executable string, or N/A>
+- Key tool calls:
+  - test: <one-line command or N/A>
+  - build: <one-line command or N/A>
+  - run: <one-line command or N/A>
+  - lint: <one-line command or N/A>
+- Key conventions / constraints: <2–3 items, or N/A>
+- Related file pointers: <absolute paths or @references, or N/A>
+```
+
+Rules:
+- Paths must be **absolute**.
+- Commands must be **one-line executable strings**, not descriptions.
+- Prefer commands that do **not** require an activated environment (absolute interpreter paths, `uv run`, `docker compose exec`).
+- Do not copy README text. List file pointers only.
+- Never include secrets, tokens, credentials, or `.env` content.
+- Even if logically a continuation, treat as round=1 if the peer has **no prior context**.
+- **Do NOT** prefill the peer with your own root-cause analysis, proposed fix, or leading questions — see the *Independent Judgment Rule* below. The handoff card is for context, not conclusions.
+
+### Anti-Hallucination Rule
+
+When mentioning specific paths, function names, commands, line numbers, or tool results, **must cite the source** ("I read X at line Y"). If unverified, state "unverified" explicitly.
+
+### Independent Judgment Rule (round=1)
+
+The whole point of peer review is to surface a **second, independent** read. If
+the reviewer's own root-cause analysis, fix diff, and leading questions are sent
+to the peer up front, the peer can only AGREE inside the reviewer's frame — and
+that AGREE carries no signal. The reviewer **must complete their own analysis
+before opening round=1**; skipping that step turns peer review into a search for
+endorsement.
+
+Round=1 message **must NOT include**:
+
+- The reviewer's own root-cause analysis ("the bug is in function X at line Y because…").
+- The reviewer's own proposed fix, patch, or diff.
+- Leading questions of the form "do you agree with my conclusion on X?" / "is the change I made on Y safe?" — these lock the peer into the reviewer's framing.
+- Specific line numbers, function names, or branch points the reviewer has already identified as relevant — let the peer locate them.
+
+Round=1 message **should include**:
+
+- The Project Handoff Card (above).
+- Symptoms exactly as observed: the user's reported error, terminal output verbatim, the precise commands that triggered it.
+- Necessary external context: the goal of the work, the date / version under test, anything the peer cannot infer from the repo alone.
+- Key file pointers as **entry points** (paths only — let the peer choose what to read and how deep).
+- An open invitation: "independently identify the root cause, propose a fix, and call out any test gaps."
+
+After receiving the peer's round=1 reply, the reviewer **compares** their own
+conclusion to the peer's and routes the next action:
+
+| Reviewer's own conclusion vs. peer's conclusion | Next action |
+|---|---|
+| Same root cause + same fix direction | High confidence — AGREE and proceed to execution |
+| Same root cause, different fix direction | REFINE — open round=2 to reconcile the fix |
+| Different root cause | OBJECT — open round=2; at least one of the two analyses is wrong |
+| Peer asks for more context | REFINE — supply the missing context, then re-evaluate |
+
+#### Example (bad — endorsement-seeking)
+
+```
+Bug is in `cmd_init` at line 932 — the v2 demo renderer fires unconditionally.
+My fix: gate it behind `--demo`. Q1: is this over-killed? Q2: should I
+refactor the renderer instead? Q3: are the tests strong enough?
+```
+
+The peer can only AGREE or quibble inside the reviewer's framing.
+
+#### Example (good — independent analysis)
+
+```
+Symptoms: user ran `roll init` on /path/X and saw [verbatim terminal output A];
+then ran `roll backlog` and saw [verbatim terminal output B]. Project background:
+[project shape]. Entry points: `bin/roll`, `lib/roll-init.py`, `tests/`.
+Independently identify the root cause and propose a fix.
+```
+
+The peer reads, locates, and proposes on its own. The reviewer then compares.
+
+## State Machine
+
+### Per Negotiation (Single Task)
+
+```
+Running
+  ├── AGREE (any round)     → Execute proposal
+  ├── Round == 3, no AGREE  → ESCALATE (failed_max_rounds)
+  ├── API/token error        → ESCALATE (failed_api_error)
+  └── User aborts            → ESCALATE (user_abort)
+```
+
+### Per Peer Pair (e.g., kimi→claude)
+
+Stored in `~/.roll/.peer-state/` (flat key files per pair):
+
+```yaml
+kimi→claude:
+  status: active        # active | degraded | abandoned
+  streak: 0             # consecutive failure count
+  last_outcome: agreed
+  history:
+    - { time: "2026-05-08T23:30:00+08:00", outcome: agreed, rounds: 2, tag: architecture }
+```
+
+Rules:
+- `streak >= 3` → automatically mark as `abandoned`
+- `abandoned` peer pairs are skipped by the bridge script
+- Human can reset via `roll peer reset <from> <to>` or `roll peer reset --all`
+- If a peer pair is abandoned, the bridge falls back to the next candidate in the capability map
+
+## Peer Routing (Adaptive)
+
+### Capability Map (Task Type → Preferred Peer Order)
+
+```yaml
+peer:
+  capability_map:
+    architecture: [claude, deepseek, kimi, pi]
+    security: [claude, deepseek, pi, kimi]
+    test: [codex, kimi, deepseek, claude]
+    refactor: [deepseek, kimi, claude, pi]
+    default: [deepseek, kimi, claude, pi]
+```
+
+### Adaptive Adjustment
+
+After each negotiation, record:
+- `outcome`: agreed / failed_max_rounds / failed_api_error
+- `rounds`: number of rounds consumed
+- `tag`: task type
+
+If `streak` for a peer pair reaches the configured threshold (default: 3 consecutive failures), mark as `abandoned`. The next task of the same type will try the next candidate in `capability_map`.
+
+### Peer Detection
+
+The bridge script detects installed peers via `command -v <tool>`. Only installed tools are considered. The current running tool is excluded (`exclude_self: true`).
+
+For `deepseek`, also check if serve mode is available as a more reliable alternative:
+```bash
+command -v deepseek && { deepseek serve --help 2>/dev/null; true; } | grep -q "\-\-http" && echo "serve_mode"
+```
+If serve mode is available, prefer HTTP transport over direct CLI invocation.
+
+### Peer Invocation Reference
+
+| Peer | Non-interactive command | Reliability | Notes |
+|------|------------------------|-------------|-------|
+| `claude` | `claude -p "<prompt>"` | ✅ Verified | Native, stable |
+| `deepseek` | `deepseek "<prompt>"` | ✅ Verified | No TTY dependency |
+| `deepseek` (serve) | `curl localhost:<port>/v1/...` | ✅ High | Start with `deepseek serve --http`; preferred over direct CLI |
+| `kimi` | `kimi --quiet -p "<prompt>"` | ✅ Verified | `--quiet` is alias for `--print --output-format text --final-message-only`; prompt via `-p` |
+| `pi` | `pi -p "<prompt>"` | ✅ Verified | Clean non-interactive output |
+| `opencode` | `opencode run "<prompt>"` | ✅ Verified | Works non-interactively |
+| `codex` | `codex exec "<prompt>"` | ⚠️ Auth required | Token must be valid; re-login with `codex login` if expired |
+
+**CLI vs. API Key**: `claude`, `deepseek`, `kimi`, `codex` CLIs authenticate via existing subscription accounts — no separate API key required. This is the primary advantage of CLI transport over the MCP/HTTP approach.
+
+## Inline Display Mode (Manual Triggers)
+
+When peer review is manually triggered by a human (via `/peer`, "叫上 peer", etc.), the executing agent **must display each round inline in the current conversation**. This applies regardless of which agent is executing — Claude, DeepSeek, Kimi, PI, or any other.
+
+**Per-round display format:**
+
+```
+─── Peer Review · Round N ───────────────────────────────
+→ Sending to [peer]:
+{full message sent to peer}
+
+← [peer] responds:
+{peer's full response, verbatim}
+
+◆ My analysis: {Claude/executing agent's reaction and position for this round}
+─────────────────────────────────────────────────────────
+```
+
+**Rules:**
+- Peer CLI calls must be **synchronous** (do NOT use background/async execution).
+- The outgoing round=1 message must follow the *Independent Judgment Rule* above — no root-cause analysis, no fix diff, no leading questions.
+- Show the outgoing message **before** calling the peer, so the user sees what's being asked.
+- 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 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.
+
+## Workflow Integration
+
+### `roll-build` Plan Mode
+
+After generating an executable plan, before proceeding to TCR:
+
+1. Assess plan complexity (file count, cross-module impact, risk level)
+2. If complexity > threshold, prompt user:
+   ```
+   This plan affects 5 files across 3 modules. Estimated peer review: 2–3 rounds, ~X tokens.
+   Press Enter to launch peer review, or type 'n' to skip. Auto-executing in 10s...
+   ```
+3. If user does not abort within 10s, invoke `roll peer` with `--tag architecture`
+4. Wait for result:
+   - AGREE → proceed to TCR
+   - REFINE/OBJECT → incorporate feedback and regenerate plan
+   - ESCALATE → present both proposals to user for final decision
+
+### `roll-spar`
+
+When Attacker and Defender reach a stalemate (both tests pass but interpretations differ):
+
+1. Auto-invoke `roll peer` with `--tag test`
+2. Use the peer's verdict as tie-breaker
+
+## Output Artifacts
+
+- **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
+
+User overrides in `~/.roll/config.yaml`:
+
+```yaml
+peer:
+  max_rounds: 3
+  opt_out_seconds: 10
+  call_timeout: 180        # seconds per round; configure based on your API latency
+  fallback: file_mailbox    # direct_cli | file_mailbox | auto
+  capability_map:
+    architecture: [claude, deepseek, kimi, pi]
+    security: [claude, deepseek, pi, kimi]
+    test: [codex, kimi, deepseek, claude]
+    refactor: [deepseek, kimi, claude, pi]
+    default: [deepseek, kimi, claude, pi]
+  adaptive:
+    streak_threshold: 3
+    min_samples: 3
+```
+
+## 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 (`<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.
+3. **Context window**: Large project handoff cards may consume significant context. Keep file pointers concise.
+4. **Tool differences**: Claude, DeepSeek, Kimi, Codex, and Pi interpret skills and AGENTS.md differently. The peer may apply the protocol slightly differently. This is expected and acceptable — the protocol is designed to tolerate variation.