@seanyao/roll 0.5.0 → 2.602.1

package/skills/roll-doctor/SKILL.md

@@ -0,0 +1,192 @@
+---
+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."
+---
+
+# Roll Doctor
+
+诊断 Roll 工具链健康状态。快速定位 skill 不工作、convention 不同步、symlink 断裂等问题。
+
+## When to Use
+
+- "roll 怎么不工作了"
+- "skill 找不到了"
+- "convention 没有同步"
+- "$roll-debug 不响应"
+- 任何 Roll 相关功能异常
+
+## Checks
+
+### 1. Roll Installation
+
+```bash
+# Verify ROLL_HOME structure
+ls -la ~/.roll/
+ls -la ~/.roll/skills/
+ls -la ~/.roll/conventions/
+```
+
+Expected:
+- `~/.roll/` exists
+- `~/.roll/skills/` has roll-* directories
+- `~/.roll/conventions/global/` has AGENTS.md, CLAUDE.md, etc.
+- `~/.roll/conventions/templates/` has backend-service, cli, frontend-only, fullstack
+
+### 2. Skill Health
+
+```bash
+# List all skills and check YAML frontmatter
+for f in ~/.roll/skills/*/SKILL.md; do
+  echo "=== $(basename $(dirname $f)) ==="
+  head -5 "$f"
+done
+```
+
+Check:
+- Each skill directory has `SKILL.md`
+- YAML frontmatter has `name:` and `description:`
+- No duplicate `name` values across skills
+- File is readable markdown
+
+### 3. Symlinks
+
+```bash
+# Claude Code
+ls -la ~/.claude/skills/roll-*
+
+# Antigravity (agy — reuses ~/.gemini/, if exists)
+ls -la ~/.gemini/skills/roll-* 2>/dev/null
+
+# Trae (if exists)
+ls -la ~/.trae/skills/roll-* 2>/dev/null
+```
+
+Check:
+- Each symlink exists
+- Each symlink points to valid target in `~/.roll/skills/`
+- No broken symlinks (red in ls output)
+
+### 4. Conventions Sync
+
+```bash
+# Check roll.md sync
+diff ~/.roll/conventions/global/CLAUDE.md ~/.claude/roll.md
+
+# Check CLAUDE.md includes @roll.md
+grep "@roll.md" ~/.claude/CLAUDE.md
+```
+
+Check:
+- `~/.claude/roll.md` exists and matches `~/.roll/conventions/global/CLAUDE.md`
+- `~/.claude/CLAUDE.md` contains `@roll.md` reference
+- `~/.claude/CLAUDE.md` is not missing or stale
+
+### 5. Template Integrity
+
+```bash
+# Global conventions
+ls ~/.roll/conventions/global/
+
+# Project type templates
+for t in backend-service cli frontend-only fullstack; do
+  ls ~/.roll/conventions/templates/$t/
+done
+
+# New project template
+ls ~/.roll/template/
+```
+
+Check:
+- All expected files present in each directory
+- No missing AGENTS.md, CLAUDE.md, or GEMINI.md
+
+### 6. Config
+
+```bash
+cat ~/.roll/config.yaml
+```
+
+Check:
+- File exists and is valid YAML
+- Has required `ai_tool_name` or `ai_claude` entries
+
+### 7. Peer Review
+
+```bash
+# Peer state directory
+ls -la ~/.roll/.peer-state/ 2>/dev/null || echo "missing"
+
+# Peer config in config.yaml
+grep "peer_" ~/.roll/config.yaml 2>/dev/null || echo "no peer config"
+
+# Available peer CLIs
+for tool in claude kimi pi codex; do
+  command -v "$tool" &>/dev/null && echo "✓ $tool" || echo "✗ $tool"
+done
+
+# roll-peer skill
+ls ~/.roll/skills/roll-peer/SKILL.md 2>/dev/null || echo "missing"
+```
+
+Check:
+- `~/.roll/.peer-state/` exists and is writable
+- `~/.roll/config.yaml` contains `peer_call_timeout` (default: 180)
+- At least one peer CLI (claude / kimi / pi) is installed
+- `roll-peer` skill exists
+
+## Report Format
+
+```
+🔬 Roll Doctor Report
+
+[✓/✗] Roll installation
+[✓/✗] Skills (N skills checked)
+[✓/✗] Symlinks (N tools checked)
+[✓/✗] Conventions sync
+[✓/✗] Templates integrity
+[✓/✗] Config
+[✓/✗] Peer Review
+
+---
+Issues found: N
+
+1. [severity] description → fix command
+2. [severity] description → fix command
+
+Recommendation: ...
+```
+
+## Severity Levels
+
+| Level | Meaning | Example |
+|-------|---------|---------|
+| 🔴 Critical | Skill completely broken | Broken symlink, missing SKILL.md |
+| 🟡 Warning | Partial functionality | Stale convention, outdated roll.md |
+| 🟢 Info | Recommendations | Missing optional tool symlink |
+
+## Auto-Fix
+
+If user confirms, automatically fix safe issues:
+
+- **Broken/missing symlinks** → `roll setup` (recreates all)
+- **Stale conventions** → `roll sync conventions`
+- **Missing template files** → warn user to re-install
+
+Never auto-fix without user confirmation for:
+- Overwriting `~/.claude/CLAUDE.md` (may have user customizations)
+- Deleting files
+
+## Quick Fix Commands
+
+```bash
+# Recreate all symlinks and sync conventions
+roll setup
+
+# Sync only conventions
+roll sync conventions
+
+# Reinstall (nuclear option)
+curl -fsSL https://raw.githubusercontent.com/seanyao/roll/main/install.sh | bash
+```

package/skills/roll-fix/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: roll-fix
-description: Execute bugfix/hotfix from backlog. Reads FIX/BUG from BACKLOG.md, delivers via TCR workflow. Lighter than story-build, focused on single-issue fixes.
+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.
 ---
 
 # Fix Ship (TCR Edition)
@@ -18,10 +20,10 @@ Use when:
 - It does not need to be split into multiple Stories / Actions to deliver
 
 **Workflow:**
-1. Read BACKLOG.md index → Find FIX/BUG row → Follow link to `docs/features/<feature>.md`
+1. Read .roll/backlog.md index → Find FIX/BUG row → Follow link to `.roll/features/<feature>.md`
 2. Single Action (no splitting)
 3. Execute via TCR workflow
-4. Write back: update BACKLOG.md status column + update FIX section in Feature file
+4. Write back: update .roll/backlog.md status column + update FIX section in Feature file
 
 Do not use for:
 
@@ -30,7 +32,7 @@ Do not use for:
 - Requirements that need planning and splitting first
 - Roadmap work that should be tracked as Stories
 
-If the issue expands beyond a single bounded change, switch to `roll-story`.
+If the issue expands beyond a single bounded change, switch to `roll-build`.
 
 ## Project Context Rule
 
@@ -86,6 +88,51 @@ Before creating any file or directory:
 
 ## TCR Workflow
 
+### 0. Pre-flight self-check (US-AGENT-007)
+
+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.chain_depth   (0 unless already a downgrade product)
+
+verdict:
+  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
+- `too_big` → self-downgrade per US-AGENT-008, **gated by US-AGENT-009 cap check**:
+
+```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
+```
+
+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.
+
+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.
+
 ### 1. Lock the issue
    - state the user-visible issue or requested enhancement
    - define the scope boundary and non-goals
@@ -95,17 +142,26 @@ Before creating any file or directory:
    - define the online verification target
    - for hotfixes: include regression test to prevent recurrence
    - reference `$roll-.qa` for appropriate test type (unit/integration/E2E)
+   - **Test-quality self-check (US-QA-011)** — for any new test the fix adds:
+     1. The test must call project functions / public command entry points,
+        not inline `sed`/`awk`/`grep -o`/`find`/`cut` pipelines that
+        re-implement what `lib/` or `bin/` already does — rubric ❼.
+     2. The test must sandbox filesystem state via `BATS_TMPDIR` or an
+        equivalent helper; never assert on or write to paths outside this
+        repo (`~/.codex`, `~/.kimi`, `~/.roll/`, system paths) — rubric ❽.
+     3. If you can't satisfy (1) or (2), extract a project helper or
+        redirect the env var to a tmp dir before writing the test.
 
 ### 3. Test Design Review (TCR Core)
 
 ```
-🧪 Test Design for Fix:
+🧪 $(msg fix.test_design):
    
-   Verification Approach: {unit test | integration test | manual check}
+   $(msg fix.verification_approach): {unit test | integration test | manual check}
    
-   Test Scenarios:
-   ├── Fix verification: {how to confirm the fix works}
-   └── Regression check: {how to ensure we didn't break anything}
+   $(msg fix.test_scenarios):
+   ├── $(msg fix.fix_verification): {how to confirm the fix works}
+   └── $(msg fix.regression_check): {how to ensure we didn't break anything}
 ```
 
 **Reference `$roll-.qa` for test strategy:**
@@ -121,10 +177,10 @@ Before creating any file or directory:
 
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
-│ TCR CYCLE FOR FIX                                                    │
+│ $(msg fix.tcr_cycle)                                                 │
 └─────────────────────────────────────────────────────────────────────┘
 
-MICRO-STEP 1: {description of the fix}
+$(msg fix.micro_step 1 "{description of the fix}")
 
    Step 1: Write/Update Test
       └── Run test → Confirm RED (bug reproduced or test fails)
@@ -197,12 +253,12 @@ $roll-.review staged
 
 **Review Output:**
 ```
-🔍 Self Review Report
-├── Scope: X files (+Y/-Z lines)
-├── 🔴 Critical: N issues (must fix)
-├── 🟡 Warnings: N issues (should fix)
-├── 🟢 Suggestions: N items (optional)
-└── ✅ Passed dimensions: [...]
+🔍 $(msg fix.self_review)
+├── $(msg fix.scope): X files (+Y/-Z lines)
+├── 🔴 $(msg fix.critical): N issues (must fix)
+├── 🟡 $(msg fix.warnings): N issues (should fix)
+├── 🟢 $(msg fix.suggestions): N items (optional)
+└── ✅ $(msg fix.passed_dimensions): [...]
 ```
 
 **Review Dimensions** (correctness guaranteed by TCR):
@@ -268,17 +324,17 @@ Verify the shipped fix on the deployed target:
 **Fresh evidence** must be provided — claiming completion based on assumptions is not acceptable.
 
 ```
-🚦 Verification Gate
+🚦 $(msg build.verification_gate)
    
-   Evidence checklist (each item must have actual output):
-   ├── [ ] Tests pass: paste actual test run output
-   ├── [ ] Build succeeds: paste build output
-   ├── [ ] Issue resolved: screenshot / curl output / log excerpt as proof
-   └── [ ] No regression: verify at least one existing feature still works
+   $(msg build.evidence_checklist):
+   ├── [ ] $(msg build.tests_passed)
+   ├── [ ] $(msg build.build_succeeded)
+   ├── [ ] $(msg fix.issue_resolved): screenshot / curl output / log excerpt as proof
+   └── [ ] $(msg build.no_regression)
    
-   Gate Decision:
-   ├── ✅ All items have evidence → Can mark as DONE
-   └── ❌ Any item lacks evidence → Provide evidence before passing the gate
+   $(msg build.gate_decision):
+   ├── ✅ $(msg build.gate_pass)
+   └── ❌ $(msg build.gate_fail)
 ```
 
 **Hard Rule**: "I confirm tests passed" does not count as evidence. It must be **freshly run** command output from this session.
@@ -289,15 +345,15 @@ Only update when Hard Rule #6 conditions are met (user requested, affects roadma
 
 Both locations must be updated — neither can be skipped:
 
-**① Update BACKLOG.md index row (Status column):**
+**① Update .roll/backlog.md index row (Status column):**
 
 ```markdown
-| [FIX-{ID}](docs/features/<feature>.md#fix-{id}) | {Title} | ✅ Done |
+| [FIX-{ID}](.roll/features/<feature>.md#fix-{id}) | {Title} | ✅ Done |
 ```
 
-Change the Status of the corresponding row from `📋 Todo` to `✅ Done`.
+Change the Status of the corresponding row from `📋 Todo` or `🔨 In Progress` (whichever the row currently shows) to `✅ Done`. When invoked by `roll-loop`, the row will already be `🔨 In Progress` — that is the expected starting state.
 
-**② Update `docs/features/<feature>.md` FIX section:**
+**② Update `.roll/features/<feature>.md` FIX section:**
 
 ```markdown
 ## FIX-{ID} {description} ✅
@@ -317,7 +373,15 @@ Change the Status of the corresponding row from `📋 Todo` to `✅ Done`.
 - Change AC (if any) from `[ ]` to `[x]`
 - Update Files to reflect actual changed files
 
-### 12. Report
+### 12. Update Changelog
+
+**Mandatory** — the release (GitHub Release body = this version's changelog section) depends on this step. Do not skip.
+
+```bash
+$roll-.changelog
+```
+
+### 13. Report
 
 Summarize:
 - shipped fix/enhancement
@@ -325,7 +389,8 @@ Summarize:
 - quality review outcome
 - verification results
 - any residual risk
-- **BACKLOG.md updated** ✅
+- **.roll/backlog.md updated** ✅
+- **CHANGELOG.md updated** ✅
 
 ## Required Artifacts
 
@@ -356,6 +421,58 @@ A minor change is only "done" when all are true:
 - [ ] Deployment completed
 - [ ] Online verification performed
 - [ ] **Verification Gate passed** (fresh evidence for tests, build, fix confirmation, no regression)
+- [ ] **Self-score note written (US-SKILL-010 / 011)** — before exit, the agent
+      writes a structured score note via `_skill_write_self_score` so trend
+      analysis (US-SKILL-014) and skill-self-scoring docs (US-SKILL-015) have
+      data to read.
+
+### Self-score (US-SKILL-011)
+
+Before exiting the cycle, write one self-score note. The helper validates
+inputs and lands the note under `.roll/notes/<date>-roll-fix-<FIX-id>-<epoch>.md`:
+
+```bash
+bash -c 'source "$(command -v roll)"; \
+  _skill_write_self_score roll-fix FIX-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>"'
+```
+
+Score guidance (integer 1..10):
+- **9..10** — clean root-cause fix; regression test added; TCR cycle smooth.
+- **6..8** — fix shipped but with caveats (e.g. workaround, partial coverage,
+  or repeated TCR red iterations); rationale explains the trade-off.
+- **1..5** — fix landed but quality is below the bar (test coverage missing,
+  fix only narrows blast radius, repeated agent re-tries). Verdict should be
+  `ok` or `regression` if a related test broke.
+
+Verdict values:
+- `good` — fix is the proper root-cause fix; no caveats.
+- `ok` — shipped but with documented trade-offs (use rationale to explain).
+- `regression` — the fix re-broke something else (rare; consider re-opening).
+
+## Rubric
+
+Quality evaluation for a completed fix. Score each dimension independently.
+
+| 维度 | ❌ Miss (0) | ⚠️ Partial (1) | ✅ Hit (2) |
+|------|------------|----------------|-----------|
+| **根因定位** | 只修了表象，未说明根因 | 描述了直接原因 | 追溯根本原因并有代码/日志证据 |
+| **最小范围** | 改动超出 fix 边界，含机会主义修改 | 范围合理但有冗余改动 | 最小改动，非 fix 相关代码零触碰 |
+| **回归测试** | 无测试，或测试与 bug 无关 | 有测试但未复现原始 bug | 先写复现测试（RED）再修复（GREEN） |
+| **验证证据** | 仅声称通过，无实际输出 | 有部分截图/日志但不完整 | 贴出完整命令输出，覆盖 fix + 回归 |
+| **无新破坏** | CI 红，或已知回归未处理 | CI 绿但有 warning 未说明 | CI 全绿，覆盖率不降，warning 清零 |
+
+**评分解读**
+
+| 总分 | 结论 |
+|------|------|
+| 9–10 | Exemplary — 可作为参考案例 |
+| 7–8 | Acceptable — 可交付，有小瑕疵 |
+| 5–6 | Needs Work — 需补充证据或补测试 |
+| ≤ 4 | Redo — 根因或验证存在根本缺失 |
+
+> 用法：fix 完成后由 `$roll-eval`（或人工）对照此表打分，结果写入 `roll-notes`。
+
+---
 
 ## TCR Patterns for Common Fixes
 

package/skills/{roll-jot → roll-idea}/SKILL.md

@@ -1,32 +1,40 @@
 ---
-name: roll-jot
-description: "Fast backlog capture. Analyzes a short description, classifies it as bug or idea, and appends it to BACKLOG.md with an auto-incremented ID."
+name: roll-idea
+license: MIT
+allowed-tools: "Read, Edit"
+description: "Fast backlog capture. Analyzes a short description, classifies it as bug or idea, and appends it to .roll/backlog.md with an auto-incremented ID."
 ---
 
-# roll-jot
+# roll-idea
 
 > One-liner in, backlog entry out. No questions asked.
 
 ## Trigger
 
-User explicitly invokes `roll-jot` with a free-text description.
+User explicitly invokes `roll-idea` with a free-text description.
 
 ```
-$roll-jot 评价页面的星星也要纳入到 draft 的 scope 里
-$roll-jot 手机端星星指标一行一个从上往下排
-$roll-jot 给 HOD 加一个批量导出 PDF 的功能
+$roll-idea 评价页面的星星也要纳入到 draft 的 scope 里
+$roll-idea 手机端星星指标一行一个从上往下排
+$roll-idea 给 HOD 加一个批量导出 PDF 的功能
 ```
 
+## When Not to Use
+
+- Requirement needs discussion or splitting into Stories (use `$roll-design`)
+- A US-XXX / FIX-XXX is ready to execute (use `$roll-build` / `$roll-fix`)
+- Recording a development moment or feeling (use `$roll-notes`)
+
 ## Behavior
 
-1. **Read** `BACKLOG.md` from the project root.
+1. **Read** `.roll/backlog.md` from the project root.
 2. **Classify** the input:
    - If it describes a defect, regression, broken behavior, or "也要/没/不/bug" → **bug**
    - Otherwise → **idea**
 3. **Assign ID**:
    - Bug → next `FIX-NNN`
    - Idea → next `IDEA-NNN`
-4. **Append** a new row to the appropriate table in `BACKLOG.md`:
+4. **Append** a new row to the appropriate table in `.roll/backlog.md`:
    - Bug → `## 🐛 Bug Fixes` table
    - Idea → `## 💡 Ideas` table (create the section if it doesn't exist)
 5. **Update stats** line if present (e.g. `Bug Fixes: N`, `Ideas: N`).
@@ -47,4 +55,4 @@ Text:   {description}
 - Do **not** ask the user for clarification.
 - If the description is vague, record it verbatim and append `(细节待确认)`.
 - Never modify existing entries — only append new rows.
-- If `BACKLOG.md` does not exist, report an error and stop.
+- If `.roll/backlog.md` does not exist, report an error and stop.