# 1) WSL 预置
sudo apt-get update
sudo apt-get install -y git jq bubblewrap
git config --global rerere.enabled true
git config --global rerere.autoupdate true
git config --global fetch.prune true

# 2) 在仓库根目录放入工作流文件
mkdir -p bugs bugspecs summaries scripts .claude/hooks .claude/agents .codex .codex/hooks .codex/agents .agents/skills

# 3) 每个缺陷准备说明和命令
# bugs/BUG-101.md
# bugspecs/BUG-101.env

# 4) 建立 worktree
./scripts/create-worktrees.sh BUG-101 BUG-102 BUG-103

# 5) 启动写入代理
./scripts/launch-agent.sh BUG-101 claude
./scripts/launch-agent.sh BUG-102 codex

# 6) 在各自 worktree 中跑检查并写总结
./scripts/run-checks.sh BUG-101
./scripts/run-checks.sh BUG-102
./scripts/aggregate-summaries.sh BUG-101 BUG-102

# 7) 回收前 rebase + 集成
git -C ../<repo>-wt/BUG-101 fetch origin && git -C ../<repo>-wt/BUG-101 rebase origin/main
git -C ../<repo>-wt/BUG-102 fetch origin && git -C ../<repo>-wt/BUG-102 rebase origin/main
git switch -c integration/defects-$(date +%F) origin/main
git merge --no-ff fix/BUG-101
git merge --no-ff fix/BUG-102

# 8) 可选：推送并创建 PR
./scripts/push-and-pr.sh origin/main

repo/
├─ AGENTS.md
├─ CLAUDE.md
├─ bugs/
│  ├─ BUG-101.md
│  └─ BUG-102.md
├─ bugspecs/
│  ├─ BUG-101.env
│  └─ BUG-102.env
├─ summaries/
├─ scripts/
├─ .claude/
│  ├─ settings.json
│  ├─ hooks/
│  ├─ agents/
│  └─ skills/
├─ .codex/
│  ├─ config.toml
│  ├─ hooks.json
│  ├─ hooks/
│  └─ agents/
└─ .agents/
   └─ skills/

# WSL shell
sudo apt-get update
sudo apt-get install -y git jq bubblewrap

git config --global rerere.enabled true
git config --global rerere.autoupdate true
git config --global fetch.prune true
git config --global pull.ff only

# BUG-101

## 来源
测试提交 / 缺陷平台 / 手工记录

## 现象
保存订单后页面显示成功，但后端实际未持久化。

## 复现
1. ...
2. ...
3. ...

## 预期
成功提示只能在持久化成功后出现。

## 约束
- 不要改动订单导出模块
- 优先最小修复
- 必须覆盖回归测试

TEST_CMD='pnpm vitest tests/order-persist.spec.ts'
LINT_CMD='pnpm lint'
TYPECHECK_CMD='pnpm tsc -p tsconfig.json --noEmit'
SMOKE_CMD='pnpm test:e2e --grep "order save"'

./scripts/create-worktrees.sh BUG-101 BUG-102 BUG-103

git fetch origin
git worktree add ../repo-wt/BUG-101 -b fix/BUG-101 origin/main
git worktree add ../repo-wt/BUG-102 -b fix/BUG-102 origin/main
git worktree add ../repo-wt/BUG-103 -b fix/BUG-103 origin/main

./scripts/launch-agent.sh BUG-101 claude
./scripts/launch-agent.sh BUG-102 codex
./scripts/launch-agent.sh BUG-103 claude

git worktree list
git worktree remove ../repo-wt/BUG-101
git worktree prune

{
  "worktree": {
    "baseRef": "fresh"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/protect_paths.py",
            "statusMessage": "Checking protected paths"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/guard_bash.py",
            "statusMessage": "Checking shell command policy"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/after_edit.sh",
            "statusMessage": "Formatting or lightweight checks"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Return valid JSON only. If the latest assistant output does not clearly include root cause, changed files/modules, validation results, remaining risk, and the path of the summary file to write, return {\"ok\": false, \"reason\": \"补全根因、验证、风险和摘要文件路径，然后再结束。\"}. Otherwise return {\"ok\": true}."
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
import json
import os
import sys
from pathlib import Path

PROTECTED = {
    "package-lock.json",
    "pnpm-lock.yaml",
    "yarn.lock",
    ".env",
    ".env.local",
    "migrations/",
    "db/migrations/"
}

def deny(reason: str):
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": reason
        }
    }))
    sys.exit(0)

payload = json.load(sys.stdin)
tool = payload.get("tool_name", "")
tool_input = payload.get("tool_input", {})

if tool in ("Edit", "Write"):
    p = tool_input.get("file_path", "")
    if any(p == x or p.startswith(x) for x in PROTECTED):
        deny(f"Protected path requires manual review: {p}")

sys.exit(0)

#!/usr/bin/env python3
import json
import re
import sys

payload = json.load(sys.stdin)
cmd = payload.get("tool_input", {}).get("command", "")

blocked = [
    r"\bgit\s+add\s+\.",
    r"\bgit\s+commit\b",
    r"\bgit\s+push\b",
    r"\brm\s+-rf\b"
]

for pattern in blocked:
    if re.search(pattern, cmd):
        print(json.dumps({
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": f"Blocked shell pattern: {pattern}"
            }
        }))
        sys.exit(0)

sys.exit(0)

#!/usr/bin/env bash
set -euo pipefail

INPUT="$(cat)"
FILE="$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')"

# 只做轻量操作，避免每次编辑都跑全量测试
case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx|*.json)
    if command -v prettier >/dev/null 2>&1; then
      prettier --write "$FILE" >/dev/null 2>&1 || true
    fi
    ;;
esac

---
name: bug-reviewer
description: Read-only local reviewer for a completed defect fix. Use proactively after code changes and before final summary.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 8
---

你是一个严格的本地代码评审者，只做只读检查，不改代码。

评审目标：
- 正确性回归
- 边界条件遗漏
- 缺少测试或测试过窄
- 配置/迁移/锁文件误改
- 并发与状态时序问题
- 与缺陷描述不匹配的“误修”

输出格式：
1. Findings（按 Critical / High / Medium / Low 排序）
2. Evidence（文件路径、符号、命令）
3. Decision（fix-required 或 lgtm-local）
4. Residual risk（即使通过也写一句）

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
review_model = "gpt-5.5"

[agents]
max_threads = 6
max_depth = 1

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/protect_bash.py",
            "statusMessage": "Checking Bash policy"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/stop_gate.py",
            "statusMessage": "Running completion gate"
          }
        ]
      }
    ],
    "SubagentStart": [
      {
        "matcher": "reviewer|explorer",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/subagent_context.py",
            "statusMessage": "Injecting reviewer context"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
import json
import re
import sys

payload = json.load(sys.stdin)
cmd = payload.get("tool_input", {}).get("command", "")

blocked = [
    r"\bgit\s+add\s+\.",
    r"\bgit\s+commit\b",
    r"\bgit\s+push\b",
    r"\brm\s+-rf\b",
]

for pattern in blocked:
    if re.search(pattern, cmd):
        print(json.dumps({
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": f"Blocked command pattern: {pattern}"
            }
        }))
        sys.exit(0)

sys.exit(0)

#!/usr/bin/env python3
import json
import subprocess
import sys
from pathlib import Path

payload = json.load(sys.stdin)

# 避免 Stop hook 连续 block 过多次
if payload.get("stop_hook_active"):
    sys.exit(0)

def run(cmd: str) -> str:
    return subprocess.check_output(cmd, shell=True, text=True).strip()

branch = run("git branch --show-current")
bug_id = branch.split("/")[-1] if "/" in branch else branch
summary = Path("summaries") / f"{bug_id}.md"
checks = Path(".meta") / f"checks-{bug_id}.log"
last_msg = payload.get("last_assistant_message") or ""

missing = []

if not summary.exists():
    missing.append(f"缺少总结文件: {summary}")

if not checks.exists():
    missing.append(f"缺少检查日志: {checks}")

required_markers = ["根因", "验证", "风险", "摘要文件"]
for marker in required_markers:
    if marker not in last_msg:
        missing.append(f"最终输出缺少字段: {marker}")

if missing:
    print(json.dumps({
        "decision": "block",
        "reason": "未满足收尾条件：\n- " + "\n- ".join(missing)
    }))
    sys.exit(0)

sys.exit(0)

name = "reviewer"
description = "Read-only reviewer for correctness, regression risk, and missing tests on defect-fix branches."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review like an owner.
Prioritize correctness, regression risk, missing tests, config drift, and accidental scope creep.
Lead with concrete findings. If no material issue exists, say LGTM-local and list residual risk in one sentence.
Do not make code changes.
"""

name = "explorer"
description = "Read-only codebase mapper for tracing the real execution path behind a reported defect."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Map the execution path for the reported defect.
Find the real entry point, state transitions, side effects, and the narrowest candidate fix area.
Do not propose broad refactors.
Do not write code.
"""

# 在每个 bug worktree 中先对齐最新主线
git fetch origin
git rebase origin/main

# 在主仓库创建集成分支
git switch -c integration/defects-$(date +%F) origin/main

# 顺序合并每个 bug branch
git merge --no-ff fix/BUG-101
git merge --no-ff fix/BUG-102
git merge --no-ff fix/BUG-103

# 发现冲突后
git diff
# 手工解决冲突
git add <resolved-file-1> <resolved-file-2>
git rebase --continue

# 要放弃这次 rebase
git rebase --abort

# 真要跳过当前冲突 commit
git rebase --skip

git mergetool
git status

Decision: fix-required | lgtm-local

Findings:
- [Severity] <summary>
  Evidence: <file/symbol/command>
  Why it matters: <impact>
  Suggested fix: <minimal change>

Coverage:
- Existing tests touched:
- Missing tests:

Residual risk:
- <one sentence>

你在 worktree fix/BUG-101 中工作。
先阅读 bugs/BUG-101.md、AGENTS.md、CLAUDE.md。
目标是先定位根因，再给出最小修复方案；除非必要，不要重构无关代码。
在动手修改之前，请先输出：
1. 根因假设
2. 受影响文件/模块
3. 最小修复计划
4. 需要补充的测试
确认计划后再实施，并在结束前写 summaries/BUG-101.md。

You are working in worktree fix/BUG-102.
Read bugs/BUG-102.md and AGENTS.md first.
Implement the smallest defensible fix only.
Update or add narrowly scoped regression tests.
Run ./scripts/run-checks.sh BUG-102.
When done, write summaries/BUG-102.md with sections:
- 根因
- 变更
- 验证
- 风险
- 后续建议
Then run a local review against origin/main and address material findings.

Review this branch against origin/main.
Focus only on correctness, regression risk, concurrency/race issues, config drift, and missing tests.
Ignore style-only nitpicks unless they hide a real bug.
If no material issues remain, say LGTM-local.
If issues exist, rank them by severity and cite exact files/symbols.

使用 bug-reviewer 子代理审查当前 worktree。
只做只读检查，不修改文件。
重点检查：实现是否真的对应缺陷描述、是否有漏掉的边界条件、是否缺少回归测试、是否误改锁文件/迁移/配置。
输出 Decision、Findings、Coverage、Residual risk。

# Agent operating contract

## Branch and worktree rules
- One bug -> one worktree -> one branch named fix/<BUG-ID>.
- One worktree may have only one writing agent session at a time.
- Reviewers must be read-only.

## Change scope
- Fix only the reported defect unless a wider change is strictly required.
- Prefer the smallest defensible patch.
- Do not modify lockfiles, migrations, or .env files unless the bug explicitly requires it.

## Validation
- Read bugs/<BUG-ID>.md before changing code.
- Read bugspecs/<BUG-ID>.env before running checks.
- Run ./scripts/run-checks.sh <BUG-ID> before claiming completion.

## Output contract
- Write summaries/<BUG-ID>.md.
- Final answer must include: 根因, 变更, 验证, 风险, 摘要文件.

@AGENTS.md

## Claude-specific additions
- Prefer planning before editing when the root cause is unclear.
- Use the bug-reviewer subagent before final closeout.
- If the fix touches billing, auth, or persistence, be extra conservative about scope.

---
name: bug-closeout
description: Close out a single defect fix by running checks, preparing the summary, and asking for review.
disable-model-invocation: true
allowed-tools: Bash(./scripts/run-checks.sh *) Read Grep Edit Write
---

Close out bug $ARGUMENTS.

Steps:
1. Read bugs/$ARGUMENTS.md and AGENTS.md.
2. Run ./scripts/run-checks.sh $ARGUMENTS.
3. If checks fail, stop and explain the failure clearly.
4. Write summaries/$ARGUMENTS.md with sections:
   - 根因
   - 变更
   - 验证
   - 风险
   - 后续建议
5. Ask to invoke bug-reviewer for a read-only review.
6. Do not commit, push, or merge.

---
name: bug-closeout
description: Finalize one bug-fix worktree by running the local validation commands, writing summaries/<BUG-ID>.md, and preparing a review handoff.
---

Inputs:
- BUG_ID

Workflow:
1. Read bugs/BUG_ID.md and AGENTS.md.
2. Read bugspecs/BUG_ID.env to discover project-specific commands.
3. Run ./scripts/run-checks.sh BUG_ID.
4. If checks fail, do not claim completion.
5. Write summaries/BUG_ID.md with:
   - 根因
   - 变更
   - 验证
   - 风险
   - 后续建议
6. Recommend a local review against origin/main.

Output:
- Short status
- Summary file path
- Whether review is still needed

#!/usr/bin/env bash
set -euo pipefail

REPO_ROOT="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "$REPO_ROOT")"
WT_ROOT="${WT_ROOT:-$(dirname "$REPO_ROOT")/${REPO_NAME}-wt}"
DEFAULT_BASE="${BASE_REF:-$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || echo origin/main)}"

mkdir -p "$WT_ROOT"
git fetch origin

for BUG_ID in "$@"; do
  BRANCH="fix/${BUG_ID}"
  WT_DIR="${WT_ROOT}/${BUG_ID}"

  if git worktree list --porcelain | grep -Fqx "worktree ${WT_DIR}"; then
    echo "[skip] worktree exists: ${WT_DIR}"
    continue
  fi

  git worktree add "${WT_DIR}" -b "${BRANCH}" "${DEFAULT_BASE}"

  mkdir -p "${WT_DIR}/.meta" "${WT_DIR}/summaries"

  if [[ -f "${REPO_ROOT}/bugs/${BUG_ID}.md" ]]; then
    cp -n "${REPO_ROOT}/bugs/${BUG_ID}.md" "${WT_DIR}/.meta/${BUG_ID}.md" || true
  fi

  echo "[ok] ${BUG_ID} -> ${WT_DIR} (${BRANCH})"
done

git worktree list

#!/usr/bin/env bash
set -euo pipefail

BUG_ID="${1:?BUG_ID required}"
AGENT="${2:?claude|codex}"

REPO_ROOT="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "$REPO_ROOT")"
WT_ROOT="${WT_ROOT:-$(dirname "$REPO_ROOT")/${REPO_NAME}-wt}"
WT_DIR="${WT_ROOT}/${BUG_ID}"

if [[ ! -d "$WT_DIR" ]]; then
  echo "worktree not found: $WT_DIR" >&2
  exit 1
fi

cd "$WT_DIR"

LOCKDIR=".agent-writer.lock"
if [[ -d "$LOCKDIR" ]]; then
  if [[ -f "$LOCKDIR/pid" ]] && kill -0 "$(cat "$LOCKDIR/pid")" 2>/dev/null; then
    echo "writer already active in $WT_DIR" >&2
    cat "$LOCKDIR/owner" 2>/dev/null || true
    exit 1
  else
    rm -rf "$LOCKDIR"
  fi
fi

mkdir -p "$LOCKDIR"
echo "$$" > "$LOCKDIR/pid"
{
  echo "agent=$AGENT"
  echo "bug=$BUG_ID"
  echo "pwd=$WT_DIR"
  echo "started=$(date -Is)"
} > "$LOCKDIR/owner"

cleanup() { rm -rf "$LOCKDIR"; }
trap cleanup EXIT INT TERM

case "$AGENT" in
  claude)
    claude
    ;;
  codex)
    codex --sandbox workspace-write --ask-for-approval on-request
    ;;
  *)
    echo "unknown agent: $AGENT" >&2
    exit 2
    ;;
esac

#!/usr/bin/env bash
set -euo pipefail

BUG_ID="${1:?BUG_ID required}"
REPO_ROOT="$(git rev-parse --show-toplevel)"
SPEC="${REPO_ROOT}/bugspecs/${BUG_ID}.env"

if [[ ! -f "$SPEC" ]]; then
  echo "missing spec: $SPEC" >&2
  echo "expected TEST_CMD / LINT_CMD / TYPECHECK_CMD / SMOKE_CMD in that file" >&2
  exit 1
fi

set -a
# shellcheck disable=SC1090
source "$SPEC"
set +a

mkdir -p .meta
LOG=".meta/checks-${BUG_ID}.log"
: > "$LOG"

run_step() {
  local name="$1"
  local cmd="${2:-}"
  [[ -z "$cmd" ]] && return 0

  {
    echo
    echo "===== ${name} ====="
    echo "\$ ${cmd}"
  } | tee -a "$LOG"

  if bash -lc "$cmd" 2>&1 | tee -a "$LOG"; then
    echo "[pass] ${name}" | tee -a "$LOG"
  else
    echo "[fail] ${name}" | tee -a "$LOG"
    exit 1
  fi
}

run_step TEST "${TEST_CMD:-}"
run_step LINT "${LINT_CMD:-}"
run_step TYPECHECK "${TYPECHECK_CMD:-}"
run_step SMOKE "${SMOKE_CMD:-}"

echo "[ok] checks complete -> $LOG"

#!/usr/bin/env bash
set -euo pipefail

mkdir -p summaries
OUT="summaries/_aggregate-$(date +%F-%H%M%S).md"

{
  echo "# Aggregate defect summary"
  echo
  echo "Generated: $(date -Is)"
  for BUG_ID in "$@"; do
    echo
    echo "## ${BUG_ID}"
    echo
    if [[ -f "summaries/${BUG_ID}.md" ]]; then
      cat "summaries/${BUG_ID}.md"
    else
      echo "_missing summary: summaries/${BUG_ID}.md_"
    fi
  done
} > "$OUT"

echo "$OUT"

#!/usr/bin/env bash
set -euo pipefail

BASE="${1:-origin/main}"
BRANCH="$(git branch --show-current)"

git push -u origin "$BRANCH"

if command -v gh >/dev/null 2>&1; then
  BODY_FILE=""
  BUG_ID="${BRANCH#fix/}"
  if [[ -f "summaries/${BUG_ID}.md" ]]; then
    BODY_FILE="--body-file summaries/${BUG_ID}.md"
  else
    BODY_FILE="--fill"
  fi

  # shellcheck disable=SC2086
  gh pr create --base "${BASE#origin/}" --head "$BRANCH" --title "$BRANCH" $BODY_FILE
else
  echo "gh not installed; branch pushed only."
fi

# BUG-101

## 背景
- 来源：
- 现象：

## 根因
- 

## 解决方案
- 

## 具体改动
- 文件：
- 关键逻辑：
- 是否新增/更新测试：

## 验证
- TEST：
- LINT：
- TYPECHECK：
- SMOKE：

## 评审结论
- Decision:
- 主要 findings:
- 是否已处理:

## 剩余风险
- 

## 后续建议
-