@seanyao/roll 2026.508.2 → 2026.509.3

package/README.md

@@ -192,7 +192,7 @@ For larger changes, open an issue first to discuss the approach.
 
 Roll builds on ideas and inspiration from the open-source community:
 
-- **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)** by Digital Life Khazix — The HV Analysis (Horizontal-Vertical Analysis) deep research framework that powers `$roll-research` was adapted from this project.
+- **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)** by Digital Life Khazix — The HV Analysis (Horizontal-Vertical Analysis) deep research framework and schema used by `$roll-research` are derived from this project, used under the MIT License. Copyright (c) 2026 数字生命卡兹克.
 - **[superpowers](https://github.com/obra/superpowers)** by Jesse Vincent — A composable skills library for AI coding agents that informed several workflow patterns in Roll.
 
 ---

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.508.2"
+VERSION="2026.509.3"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -539,6 +539,11 @@ cmd_setup() {
   echo ""
   _sync_skills "$force"
 
+  echo ""
+  info "Setting up peer review state...  正在初始化 peer review 状态..."
+  _peer_ensure_state_dir
+  ok "Peer state directory ready.  Peer 状态目录已就绪。"
+
   echo ""
   ok "Setup complete.  初始化完成。"
 
@@ -1220,6 +1225,416 @@ check_sync_status() {
   fi
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# PEER REVIEW
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_PEER_STATE_DIR="${ROLL_HOME}/.peer-state"
+
+_peer_ensure_state_dir() {
+  mkdir -p "$_PEER_STATE_DIR"
+  mkdir -p "${_PEER_STATE_DIR}/logs"
+}
+
+_peer_state_file() {
+  local pair="$1"
+  local key="$2"
+  echo "${_PEER_STATE_DIR}/${pair}_${key}"
+}
+
+_peer_get_state() {
+  local pair="$1"
+  local key="$2"
+  local file
+  file="$(_peer_state_file "$pair" "$key")"
+  if [[ -f "$file" ]]; then
+    cat "$file"
+  else
+    echo ""
+  fi
+}
+
+_peer_set_state() {
+  local pair="$1"
+  local key="$2"
+  local val="$3"
+  _peer_ensure_state_dir
+  printf '%s\n' "$val" > "$(_peer_state_file "$pair" "$key")"
+}
+
+_peer_normalize_pair() {
+  local from="$1"
+  local to="$2"
+  printf '%s→%s\n' "$from" "$to"
+}
+
+_peer_detect_peers() {
+  local peers=""
+  for tool in claude kimi pi codex opencode cursor; do
+    if command -v "$tool" &>/dev/null; then
+      peers="${peers}${peers:+ }${tool}"
+    fi
+  done
+  printf '%s\n' "$peers"
+}
+
+_peer_route() {
+  local from="$1"
+  local tag="${2:-default}"
+
+  local map_val
+  map_val="$(config_get "peer_capability_map_${tag}" "")"
+  if [[ -z "$map_val" ]]; then
+    map_val="$(config_get "peer_capability_map_default" "kimi claude pi")"
+  fi
+
+  local installed
+  installed="$(_peer_detect_peers)"
+
+  local candidate
+  for candidate in $map_val; do
+    [[ "$candidate" == "$from" ]] && continue
+    if echo "$installed" | grep -qw "$candidate"; then
+      local pair status
+      pair="$(_peer_normalize_pair "$from" "$candidate")"
+      status="$(_peer_get_state "$pair" "status")"
+      if [[ "$status" != "abandoned" ]]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+    fi
+  done
+
+  printf '%s\n' ""
+  return 1
+}
+
+_peer_call() {
+  local to="$1"
+  local prompt="$2"
+  local output=""
+  local stderr_log
+  stderr_log="${_PEER_STATE_DIR}/logs/.last_stderr.log"
+  local call_timeout
+  call_timeout="$(config_get "peer_call_timeout" "180")"
+
+  info "Peer call timeout: ${call_timeout}s  Peer 调用超时: ${call_timeout}s"
+
+  case "$to" in
+    claude)
+      output="$(claude -p --output-format text "$prompt" 2>"$stderr_log" || true)"
+      ;;
+    kimi)
+      output="$(kimi --quiet -p "$prompt" 2>"$stderr_log" || true)"
+      ;;
+    pi)
+      output="$(pi -p --mode text "$prompt" 2>"$stderr_log" || true)"
+      ;;
+    *)
+      err "Unsupported peer: $to  不支持的 peer: $to"
+      return 1
+      ;;
+  esac
+
+  printf '%s\n' "$output"
+}
+
+_peer_parse_resolution() {
+  local output="$1"
+  local resolution
+  # Match AGREE/REFINE/OBJECT/ESCALATE near line start (only non-letters before it)
+  # Covers: **AGREE**, ### 结论：AGREE, - AGREE:, * REFINE, OBJECT — ...
+  resolution="$(printf '%s\n' "$output" | grep -oiE '^[^a-zA-Z]*\b(AGREE|REFINE|OBJECT|ESCALATE)\b' | head -1 | grep -oiE '\b(AGREE|REFINE|OBJECT|ESCALATE)\b' | tr '[:lower:]' '[:upper:]')"
+  printf '%s\n' "$resolution"
+}
+
+_peer_update_state() {
+  local pair="$1"
+  local outcome="$2"
+  local streak=0
+
+  local prev_streak
+  prev_streak="$(_peer_get_state "$pair" "streak")"
+  if [[ "$prev_streak" =~ ^[0-9]+$ ]]; then
+    streak="$prev_streak"
+  fi
+
+  if [[ "$outcome" == "AGREE" ]]; then
+    streak=0
+    _peer_set_state "$pair" "status" "active"
+  else
+    streak=$((streak + 1))
+    if [[ "$streak" -ge 3 ]]; then
+      _peer_set_state "$pair" "status" "abandoned"
+    else
+      _peer_set_state "$pair" "status" "degraded"
+    fi
+  fi
+
+  _peer_set_state "$pair" "streak" "$streak"
+  _peer_set_state "$pair" "last_outcome" "$outcome"
+  _peer_set_state "$pair" "last_time" "$(date -Iseconds)"
+}
+
+cmd_peer() {
+  local from_tool=""
+  local to_tool=""
+  local round=1
+  local tag="default"
+  local context_file=""
+  local yolo=false
+  local subcmd=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --from) from_tool="$2"; shift 2 ;;
+      --to) to_tool="$2"; shift 2 ;;
+      --round) round="$2"; shift 2 ;;
+      --tag) tag="$2"; shift 2 ;;
+      --context) context_file="$2"; shift 2 ;;
+      --yes|--yolo) yolo=true; shift ;;
+      status) subcmd="status"; shift ;;
+      reset) subcmd="reset"; shift; break ;;
+      help|--help|-h) subcmd="help"; shift ;;
+      *) err "Unknown option: $1  未知选项: $1"; exit 1 ;;
+    esac
+  done
+
+  case "$subcmd" in
+    status) cmd_peer_status; return ;;
+    reset) cmd_peer_reset "$@"; return ;;
+    help) cmd_peer_help; return ;;
+  esac
+
+  if [[ -z "$from_tool" ]]; then
+    err "--from is required.  必须指定 --from。"
+    echo ""
+    cmd_peer_help
+    exit 1
+  fi
+
+  if [[ -z "$to_tool" ]]; then
+    to_tool="$(_peer_route "$from_tool" "$tag")"
+    if [[ -z "$to_tool" ]]; then
+      err "No available peer found for tag '$tag'.  未找到 tag '$tag' 的可用 peer。"
+      echo ""
+      info "Installed peers: $(_peer_detect_peers)"
+      info "Capability map: $(config_get "peer_capability_map_${tag}" "$(config_get "peer_capability_map_default" "kimi claude pi")")"
+      exit 1
+    fi
+    info "Auto-selected peer: $to_tool  自动选择 peer: $to_tool"
+  fi
+
+  local pair
+  pair="$(_peer_normalize_pair "$from_tool" "$to_tool")"
+
+  local status
+  status="$(_peer_get_state "$pair" "status")"
+  if [[ "$status" == "abandoned" ]]; then
+    err "Peer pair $pair is abandoned. Run 'roll peer reset $from_tool $to_tool' to restore.  Peer 对 $pair 已废弃。运行 'roll peer reset $from_tool $to_tool' 恢复。"
+    exit 1
+  fi
+
+  if [[ "$yolo" != "true" ]]; then
+    local opt_out
+    opt_out="$(config_get "peer_opt_out_seconds" "10")"
+    info "Launching peer review: $from_tool → $to_tool (round $round, tag: $tag)"
+    info "Press Enter to proceed or type 'n' to abort. Auto-executing in ${opt_out}s..."
+    info "启动 peer review: $from_tool → $to_tool (第 $round 轮, tag: $tag)"
+    info "按 Enter 执行或输入 n 取消。${opt_out} 秒后自动执行..."
+
+    local answer=""
+    if IFS= read -r -t "$opt_out" answer 2>/dev/null; then
+      if [[ "$answer" == "n" || "$answer" == "N" ]]; then
+        info "Peer review aborted by user.  用户取消 peer review。"
+        exit 0
+      fi
+    fi
+  fi
+
+  local context=""
+  if [[ -n "$context_file" && -f "$context_file" ]]; then
+    context="$(cat "$context_file")"
+  fi
+
+  local prompt
+  prompt="[PEER_REVIEW round=${round} tool=${from_tool}→${to_tool}]\n\n${context}"
+
+  _peer_ensure_state_dir
+  local log_file
+  log_file="${_PEER_STATE_DIR}/logs/$(date +%Y%m%d_%H%M%S)_${from_tool}_${to_tool}.md"
+  {
+    echo "# Peer Review Log"
+    echo ""
+    echo "- **From**: $from_tool"
+    echo "- **To**: $to_tool"
+    echo "- **Round**: $round"
+    echo "- **Tag**: $tag"
+    echo "- **Time**: $(date -Iseconds)"
+    echo ""
+    echo "## Prompt"
+    echo ""
+    echo '```'
+    printf '%s\n' "$prompt"
+    echo '```'
+    echo ""
+    echo "## Response"
+    echo ""
+  } > "$log_file"
+
+  info "Calling $to_tool...  调用 $to_tool..."
+  local response
+  response="$(_peer_call "$to_tool" "$prompt")"
+
+  local stderr_log
+  stderr_log="${_PEER_STATE_DIR}/logs/.last_stderr.log"
+  if [[ -f "$stderr_log" && -s "$stderr_log" ]]; then
+    echo ""
+    echo -e "${BOLD}Peer stderr  Peer 标准错误:${NC}"
+    cat "$stderr_log"
+    echo ""
+  fi
+
+  printf '%s\n' "$response" >> "$log_file"
+
+  local resolution
+  resolution="$(_peer_parse_resolution "$response")"
+
+  if [[ -z "$resolution" ]]; then
+    warn "Could not parse resolution from peer response.  无法解析 peer 响应中的决议状态。"
+    resolution="UNKNOWN"
+  fi
+
+  _peer_update_state "$pair" "$resolution"
+
+  echo ""
+  echo -e "${BOLD}Peer Review Result  Peer Review 结果${NC}"
+  echo "  Pair: $pair"
+  echo "  Round: $round"
+  echo "  Resolution: $resolution"
+  echo ""
+
+  case "$resolution" in
+    AGREE)
+      ok "Consensus reached. Proceed with execution.  达成共识，继续执行。"
+      ;;
+    REFINE|OBJECT)
+      if [[ "$round" -ge 3 ]]; then
+        warn "Max rounds reached. Escalating to user.  达到最大轮数，升级给用户。"
+      else
+        info "Peer requests $resolution. Continue to round $((round + 1)).  Peer 请求 $resolution，继续第 $((round + 1)) 轮。"
+      fi
+      ;;
+    ESCALATE|UNKNOWN)
+      warn "Peer review escalated or failed. Human decision required.  Peer review 升级或失败，需要人类决策。"
+      ;;
+  esac
+
+  echo ""
+  info "Log: $log_file"
+
+  case "$resolution" in
+    AGREE) exit 0 ;;
+    REFINE|OBJECT) exit 2 ;;
+    *) exit 1 ;;
+  esac
+}
+
+cmd_peer_status() {
+  _peer_ensure_state_dir
+  echo -e "${BOLD}Peer Review Status  Peer Review 状态${NC}"
+  echo ""
+
+  local found=0
+  local status_file
+  for status_file in "$_PEER_STATE_DIR"/*_status; do
+    [[ -f "$status_file" ]] || continue
+    found=1
+    local pair status streak last_outcome last_time
+    pair="$(basename "$status_file" | sed 's/_status$//')"
+    status="$(_peer_get_state "$pair" "status")"
+    streak="$(_peer_get_state "$pair" "streak")"
+    last_outcome="$(_peer_get_state "$pair" "last_outcome")"
+    last_time="$(_peer_get_state "$pair" "last_time")"
+
+    local sc="$GREEN"
+    [[ "$status" == "degraded" ]] && sc="$YELLOW"
+    [[ "$status" == "abandoned" ]] && sc="$RED"
+
+    echo -e "  ${sc}${pair}${NC}"
+    echo "    Status: ${status:-active}"
+    echo "    Streak: ${streak:-0}"
+    echo "    Last: ${last_outcome:-none} @ ${last_time:-never}"
+    echo ""
+  done
+
+  if [[ "$found" -eq 0 ]]; then
+    info "No peer review history yet.  暂无 peer review 记录。"
+  fi
+
+  echo ""
+  info "Installed peers: $(_peer_detect_peers)"
+}
+
+cmd_peer_reset() {
+  local target_pair=""
+  local reset_all=false
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --all) reset_all=true; shift ;;
+      --from|--to|--round|--tag|--context|--yes|--yolo|status|reset|help|--help|-h) shift ;;
+      *)
+        if [[ -z "$target_pair" ]]; then
+          target_pair="$1"
+        fi
+        shift
+        ;;
+    esac
+  done
+
+  _peer_ensure_state_dir
+
+  if [[ "$reset_all" == "true" ]]; then
+    rm -f "$_PEER_STATE_DIR"/*_status
+    rm -f "$_PEER_STATE_DIR"/*_streak
+    rm -f "$_PEER_STATE_DIR"/*_last_outcome
+    rm -f "$_PEER_STATE_DIR"/*_last_time
+    ok "All peer states reset.  所有 peer 状态已重置。"
+    return
+  fi
+
+  if [[ -z "$target_pair" ]]; then
+    err "Usage: roll peer reset <from>→<to> | --all  用法: roll peer reset <from>→<to> | --all"
+    exit 1
+  fi
+
+  rm -f "$(_peer_state_file "$target_pair" "status")"
+  rm -f "$(_peer_state_file "$target_pair" "streak")"
+  rm -f "$(_peer_state_file "$target_pair" "last_outcome")"
+  rm -f "$(_peer_state_file "$target_pair" "last_time")"
+  ok "Peer state reset: $target_pair  Peer 状态已重置: $target_pair"
+}
+
+cmd_peer_help() {
+  echo -e "${BOLD}roll peer — Cross-Agent Peer Review${NC}"
+  echo ""
+  echo "Usage: roll peer [options]  用法: roll peer [选项]"
+  echo ""
+  echo "Options:"
+  echo "  --from <tool>       Originating agent (kimi, claude, pi)  发起方"
+  echo "  --to <tool>         Target peer (auto-detected if omitted)  对端 peer（省略则自动选择）"
+  echo "  --round <N>         Current round (default: 1)  当前轮数"
+  echo "  --tag <type>        Task type for routing (architecture, security, test...)  任务类型"
+  echo "  --context <file>    Context file to send to peer  上下文文件"
+  echo "  --yes, --yolo       Skip opt-out prompt  跳过确认提示"
+  echo ""
+  echo "Subcommands:"
+  echo "  status              Show peer review state  显示状态"
+  echo "  reset <pair|--all>  Reset peer state  重置状态"
+  echo "  help                Show this help  显示帮助"
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # MAIN
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1241,6 +1656,7 @@ usage() {
   echo "  update                 [Upgrade] npm install latest + re-sync             一键升级到最新版"
   echo "  init                   [Project] Create AGENTS.md + BACKLOG.md + docs/     初始化项目工作流文件"
   echo "  status                 [Diagnostic] Show current state                    显示当前状态"
+  echo "  peer                   [Peer Review] Cross-agent negotiation               跨 Agent 协商对审"
   echo ""
   echo "Examples / 示例:"
   echo "  roll setup                    # New machine: first-time install            新机器首次安装"
@@ -1258,6 +1674,7 @@ main() {
     update)        cmd_update "$@" ;;
     init)          cmd_init "$@" ;;
     status)        cmd_status "$@" ;;
+    peer)          cmd_peer "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h|"") usage ;;
     *)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.508.2",
+  "version": "2026.509.3",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"

package/skills/roll-build/SKILL.md

@@ -173,6 +173,33 @@ Proceed to the **Shared TCR Workflow** (Phase 4 onward).
 
 The following phases apply to both Story mode and Fly mode after planning is complete.
 
+### Phase 3.5: Peer Review Gate
+
+After planning is complete, before entering Test Design Review, assess whether the plan warrants peer review:
+
+**Auto-trigger `$roll-peer` when any of the following is true:**
+- Plan affects **>3 files** or **crosses modules**
+- **Architecture decisions** or non-obvious trade-offs are involved
+- **Destructive / irreversible operations** (deletions, migrations, production deploys)
+- **High-risk signal words** detected in user request ("critical / important / don't break / 关键 / 别搞砸")
+- User explicitly requests peer review ("/peer", "叫上 peer")
+
+**With 10s opt-out:**
+```
+Plan affects N files across M modules. Estimated peer review: 2–3 rounds, ~X tokens.
+Press Enter to launch peer review, or type 'n' to skip. Auto-executing in 10s...
+```
+
+**After peer review result:**
+- **AGREE** → proceed to Phase 4 (Test Design Review)
+- **REFINE** → incorporate feedback, regenerate plan, re-run Phase 3.5
+- **OBJECT** → consider alternative plan, re-run Phase 3.5 with revised proposal
+- **ESCALATE** → present both proposals to user for final decision before proceeding
+
+**Never trigger:**
+- Single-file changes or well-defined fixes
+- Plans with no cross-module impact and no architecture decisions
+
 ### Phase 4: Test Design Review
 
 Before writing implementation code:

package/skills/roll-doctor/SKILL.md

@@ -112,6 +112,30 @@ 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
 
 ```
@@ -123,6 +147,7 @@ Check:
 [✓/✗] Conventions sync
 [✓/✗] Templates integrity
 [✓/✗] Config
+[✓/✗] Peer Review
 
 ---
 Issues found: N

package/skills/roll-peer/SKILL.md

@@ -0,0 +1,241 @@
+---
+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.
+
+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**.
+
+### 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.
+
+## 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 `~/.shared/roll/peer/state.yaml`:
+
+```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>"` | ✅ High | Native, stable |
+| `deepseek` | `deepseek "<prompt>"` | ✅ Good | No TTY dependency |
+| `deepseek` (serve) | `curl localhost:<port>/v1/...` | ✅ High | Start with `deepseek serve --http`; preferred over direct CLI |
+| `kimi` | `kimi --quiet "<prompt>"` | ⚠️ Unverified | Verify non-interactive support before use |
+| `codex` | `codex exec --json --output-last-message "<prompt>"` | ⚠️ Unstable | Known CI failures due to Ink/TTY (issues [#1080](https://github.com/openai/codex/issues/1080), [#1340](https://github.com/openai/codex/issues/1340)); use only as fallback |
+| `pi` | `pi -p "<prompt>"` | ⚠️ Unverified | Verify non-interactive support before use |
+
+**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.
+
+## 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**: `~/.shared/roll/peer/logs/<timestamp>_<from>_<to>.md`
+- **State file**: `~/.shared/roll/peer/state.yaml`
+- **Decision record**: If AGREE, append summary to `docs/decisions/` or `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 (`~/.shared/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-research/SKILL.md

@@ -12,6 +12,13 @@ description: |
 
 > Follows the Architecture Constraints, Development Discipline, and Engineering Common Sense defined in the project AGENTS.md.
 
+## Credits
+
+The HV (Horizontal-Vertical) Analysis framework and the `references/schema.json`
+used by this skill are derived from **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)**
+by 数字生命卡兹克 (Digital Life Khazix), used under the MIT License.
+Copyright (c) 2026 数字生命卡兹克.
+
 You are executing an HV Analysis deep research session. The final deliverable is a **professionally formatted PDF research report**.
 
 ## Prerequisites

package/skills/roll-research/references/schema.json

@@ -1,3 +1,7 @@
+// Copyright (c) 2026 数字生命卡兹克 (Digital Life Khazix)
+// Released under the MIT License: https://github.com/KKKKhazix/khazix-skills/blob/main/LICENSE
+// This file contains substantial portions of the Horizontal-Vertical Analysis Framework
+// from khazix-skills (https://github.com/KKKKhazix/khazix-skills).
 {
   "$schema": "Horizontal-Vertical Analysis Framework",
   "version": "1.0",