@seanyao/roll 3.620.1 → 3.624.1

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

@@ -1,323 +0,0 @@
-# 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 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. The v3 runner writes events natively; do not call the retired bash helper `_loop_event`.
-
-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.

package/skills/roll-propose/SKILL.md

@@ -1,155 +0,0 @@
----
-name: roll-propose
-license: MIT
-allowed-tools: "Read, Glob, Grep, Write, Bash(git:*)"
-description: "Load when the owner asks for product proposal drafts from project context that should go to .roll/proposals.md, not directly into backlog."
----
-# roll-propose
-
-## Gotchas
-
-- Proposals go to .roll/proposals.md for review; never write them directly into BACKLOG.
-- Keep product scenarios user-facing rather than turning every code smell into a feature proposal.
-
-> Follows the Architecture Constraints, Development Discipline, and Engineering
-> Common Sense defined in the project AGENTS.md.
-
-Human-triggered skill for product-level feature ideation. Generates structured
-User Story drafts from a product/user perspective and queues them in
-.roll/proposals.md for human approval before entering BACKLOG.
-
-## Distinct from roll-.dream
-
-| | roll-propose | roll-.dream |
-|---|---|---|
-| Triggered by | Human explicitly | Nightly schedule |
-| Perspective | User-facing / product scenarios | Code health / technical debt |
-| Output | .roll/proposals.md (pending approval) | BACKLOG (REFACTOR-XXX) |
-| Thinking style | "What would users want next?" | "What is the code telling us?" |
-
-## When to Use
-
-```
-$roll-propose                   # generate proposals from full context
-$roll-propose 用户反馈里提到了XX  # provide a focus hint
-```
-
-## When Not to Use
-
-- Describing a known defect or broken behavior (use `$roll-idea`)
-- A story is already well-defined and ready to build (use `$roll-build`)
-- Exploring technical architecture or design (use `$roll-design`)
-- Surfacing code-level technical debt (use `$roll-.dream`)
-
-## Behavior
-
-### Step 1 — Gather Context
-
-Read in parallel:
-
-1. `.roll/backlog.md` — all existing US-XXX, FIX-XXX, REFACTOR-XXX, IDEA-XXX entries (both Todo and Done) to avoid proposing duplicates
-2. `.roll/proposals.md` (if exists) — already-proposed items (avoid re-proposing rejected or pending ones)
-3. Recent 20 commits via `git log --oneline -20` — what has recently shipped
-4. `skills/` directory listing — what capabilities roll already has
-5. Optional: any focus hint passed by the user
-
-### Step 2 — Think from User Perspective
-
-Frame proposals from the **product engineer / end user** point of view:
-
-- What recurring friction do users of roll face that no current skill addresses?
-- What workflow is partially covered but has visible gaps?
-- What would make the autonomous loop more legible, controllable, or trustworthy to its human owner?
-
-Avoid technical-debt reasoning (that is roll-.dream's domain). Focus on:
-- New user-visible commands or behaviors
-- Improvements to existing UX (output clarity, discoverability, onboarding)
-- Integrations that extend reach (new AI tools, editor support, CI patterns)
-
-### Step 3 — Draft 1–3 Proposals
-
-Generate between 1 and 3 proposals. For each:
-
-```
-## PROPOSAL: {Short title}
-```
-
-`{Short title}` 写法：用户看得懂的一句话，说清楚"加什么"或"解决什么问题"。不用技术术语，不提内部实现。这句话批准后会直接成为 BACKLOG 里的描述。
-
-```
-**Motivation (why):**
-One to two sentences from the user's perspective explaining the pain or opportunity.
-
-**Target scenario:**
-Concrete usage example — what the user does, what they see, what they gain.
-
-**Acceptance Criteria (draft):**
-- [ ] AC 1
-- [ ] AC 2
-- [ ] AC 3
-
-**Suggested ID:** US-{EPIC}-{NNN}  (best-guess prefix; human assigns final ID)
-**Suggested Epic / Feature:** {name}
-**Estimated complexity:** {S | M | L}
-```
-
-Complexity guide: S = one skill file or small bin/roll change, M = skill + bin/roll + tests, L = multi-file + new infrastructure.
-
-### Step 4 — Write to .roll/proposals.md
-
-Append to `.roll/proposals.md` in the project root (create if absent):
-
-```markdown
----
-proposed: {YYYY-MM-DD HH:MM}
-status: pending
----
-
-{proposals from Step 3}
-```
-
-Use `---` as separator between proposal batches. Never overwrite existing content.
-
-### Step 5 — Report
-
-```
-✅ roll-propose: {N} proposal(s) written to .roll/proposals.md
-
-To approve: move the entry to .roll/backlog.md and assign a US-XXX ID.
-To reject:  annotate with "Rejected: {reason}" to suppress future re-proposals.
-```
-
-## Output Rules
-
-- Write proposals in the same language as the project's primary documentation (Chinese for this project).
-- Never write directly to .roll/backlog.md — .roll/proposals.md is the staging area.
-- If a similar proposal already exists in .roll/proposals.md (pending or rejected), note similarity and skip or merge rather than creating a duplicate.
-- Aim for 2 proposals by default; generate 1 if context is thin, 3 if focus hint suggests a rich area.
-
-## .roll/proposals.md Format
-
-```markdown
-# Roll Proposals
-
-> 待审批提案。批准后手工移入 .roll/backlog.md 并分配 US-XXX 编号。
-> 拒绝时在条目末尾注明拒绝原因，防止 Agent 重复提出相似提案。
-
----
-proposed: 2026-05-11 11:30
-status: pending
----
-
-## PROPOSAL: ...
-
-...
-
----
-proposed: 2026-05-08 09:00
-status: rejected
-rejected_reason: 与现有 roll-design 功能重叠，不需要单独技能
----
-
-## PROPOSAL: ...
-
-...
-```

package/skills/roll-review-pr/SKILL.md

@@ -1,62 +0,0 @@
----
-name: roll-review-pr
-license: MIT
-allowed-tools: "Read"
-description: "Load when reviewing a pull request diff and emitting APPROVE, REQUEST_CHANGES, or UNCERTAIN with file/line-grounded findings."
----
-# PR Review
-
-## Gotchas
-
-- Return a three-state verdict with concrete findings; do not approve by silence when evidence is missing.
-- This reviews PR diffs, not local TCR micro-steps or adversarial test design.
-
-> Follows the Architecture Constraints, Development Discipline, and Engineering
-> Common Sense defined in the project AGENTS.md.
-
-You are reviewing a pull request. Your job is to assess code quality,
-correctness, and adherence to project conventions.
-
-## Context
-
-**PR Title:** {{PR_TITLE}}
-
-**PR Body:**
-{{PR_BODY}}
-
-## Diff
-
-```diff
-{{PR_DIFF}}
-```
-
-## Review Instructions
-
-1. Read the diff carefully. Focus on:
-   - Correctness: logic errors, off-by-one, unhandled edge cases
-   - Security: injection, secrets exposure, unsafe operations
-   - Conventions: naming, structure, test coverage (as described in AGENTS.md)
-   - Scope: changes should match what the PR title/body claims
-
-2. Write your analysis in free text (2-10 sentences). Be specific — cite file
-   names and line numbers when pointing out issues.
-
-3. End your response with exactly ONE verdict footer on its own line:
-
-   - If the code is acceptable:
-     `<!--VERDICT:APPROVE-->`
-
-   - If changes are needed (cite the most important issue):
-     `<!--VERDICT:REQUEST_CHANGES:one-line reason-->`
-
-   - If you cannot confidently judge (e.g., missing context, domain-specific logic):
-     `<!--VERDICT:UNCERTAIN:one-line reason-->`
-
-## Rules
-
-- The verdict footer MUST appear on the last non-empty line of your response.
-- Choose exactly one verdict. Do not combine them.
-- REQUEST_CHANGES is for real issues — not style nitpicks or personal preferences.
-- When in doubt between APPROVE and UNCERTAIN, prefer UNCERTAIN.
-- If the PR body contains `[skip-ai-review]`, immediately output
-  `<!--VERDICT:APPROVE-->` with no analysis.

package/skills/roll-spar/SKILL.md

@@ -1,47 +0,0 @@
----
-name: roll-spar
-license: MIT
-allowed-tools: "Read, Edit, Write, Bash, Agent, Skill"
-description: "Load when high-risk logic needs adversarial TDD with attacker tests and defender implementation, such as auth, payments, data integrity, or state machines."
----
-# Roll Spar
-
-This hub keeps the routing boundary, hard gates, and execution skeleton in the initial context. Load the heavier runbook only when the task actually needs the detailed contract.
-
-## Load
-
-Load when high-risk logic needs adversarial TDD with attacker tests and defender implementation, such as auth, payments, data integrity, or state machines.
-
-## When Not to Use
-
-- Routine QA planning; load roll-.qa.
-- Ordinary peer review; load roll-peer.
-
-## Read On Demand
-
-- Read [the full contract](references/full-contract.md) before executing the workflow end to end, recovering from failures, or checking exact output templates.
-- Keep this hub in context for trigger boundaries and hard gates.
-
-## Workflow Skeleton
-
-1. Define the high-risk invariant.
-2. Attacker writes breaking tests first.
-3. Defender implements the minimal passing code.
-4. Iterate until the invariant is defended.
-5. Record adversarial evidence.
-
-## Hard Gates
-
-- Keep attacker/defender roles separate.
-- Use only when added cost matches risk.
-
-## Gotchas
-
-- Use spar only for high-risk logic where adversarial tests are worth the added cost.
-- Attacker and defender roles must stay separate; do not let implementation assumptions weaken the breaking tests.
-
-## Maintenance
-
-- Description changes require updates in `route-cases/skills.json`.
-- New observed failures should add a gotcha and the matching positive or negative route case.
-- Heavy examples, templates, recovery paths, and deterministic snippets belong in `references/`, `assets/`, or `scripts/`, not in this hub.