@flyin-ai/alloy 0.2.0-beta.0 → 0.2.0-beta.2

package/commands/alloy/references/apply-precheck.md

@@ -0,0 +1,21 @@
+# apply 多 change 并行检测（前置 Step 0/5 用）
+
+apply 单 change 串行（subagent 内部并行 OK）——同期多个 change 同时 apply 会导致 git 操作竞争（branch 切换、worktree 创建、commit 写入相互干扰）。
+
+## 检测 bash
+
+```bash
+PARALLEL=$(find openspec/changes -maxdepth 2 -name .alloy.yaml \
+  -exec grep -l "phase: apply\|phase: applied" {} \; 2>/dev/null \
+  | grep -v "/<name>/" | wc -l)
+if [ "$PARALLEL" -gt 0 ]; then
+  echo "⚠️ [WARN] 检测到 $PARALLEL 个其他 change 处于 apply/applied 状态："
+  find openspec/changes -maxdepth 2 -name .alloy.yaml \
+    -exec grep -l "phase: apply\|phase: applied" {} \; 2>/dev/null | grep -v "/<name>/"
+  echo ""
+  echo "  apply 串行更安全——多 change 并行 apply = worktree/branch/commit 竞争。"
+  echo "  继续当前 apply 前请确认其他 change 已暂停。"
+fi
+```
+
+不阻断——仅提示。

package/commands/alloy/references/apply-rationalizations.md

@@ -0,0 +1,18 @@
+# apply Red Flags 完整表（第三层防御——任一借口出现即 STOP）
+
+主文件保留 5 条核心，完整 12 条在此。
+
+| 借口 | 现实 |
+|------|------|
+| "用户说了跳过 worktree" | 隔离是软闸门——`/alloy:apply` 允许 worktree=skipped；但模糊回复（"嗯"/"好"）不算同意，必须 USER_GATE 明确选择。 |
+| "先写代码再补测试" | TDD 次序不可颠倒。提速靠并行子任务，不靠砍测试（Iron Law 第一层）。 |
+| "用户要改需求，直接改" | 需求变更必须走 tasks.md checkbox 闸门。已编码→开新 change，未编码→回溯，禁直接改 plans.md。 |
+| "技能缺失没关系" | 技能是闸门不是加速器。缺失 = ⛔ PRECONDITION_FAIL。引导 `alloy init`，不存在降级。 |
+| "用户很急，跳过 review" | 跳过 review = 跳过质量闸门。急不是绕过流程的理由（Iron Law 第二层）。 |
+| "先建 worktree 再问用户" | consent 必须在创建前。加载 using-git-worktrees Step 0 后停手，等用户明确回复。 |
+| "verify.md 措辞不太顺，直接编辑改一下" | 制品禁直接编辑——任何变更必须重新生成 + 重新 hash-lock。违反字面 = 违反精神。 |
+| "verify FAIL 是小问题，retro 写'已知 FAIL'继续" | FAIL 必须修复回到 Step 2。带 FAIL 进 archive 阶段 = spec 与代码偏差永久封存。 |
+| "single-commit 修复不需要 retrospective，自动跳过" | retrospective 跳过判定必须 USER_GATE，agent 不得自动选"跳过"（task #17）。 |
+| "worktree 内分支看起来对，应该没问题吧" | worktree-<name> 是硬约束。子 agent 在错误分支编辑 = 用户主分支被污染（task #18）。 |
+| "git stash list 有内容，但这是之前的不影响 commit" | stash 残留 = 未完成工作。commit 前必须 ⚠️ WARN 让用户确认（task #19）。 |
+| "另一个 change 也在 apply，并行做完更快" | apply 单 change 串行（subagent 内部并行 OK）。多 change 同时 apply = git 操作竞争。 |

package/commands/alloy/references/apply-subagent-commit.md

@@ -0,0 +1,49 @@
+# apply 子 agent commit 三规则（SDD/EP 共享）
+
+apply Step 2/5 内每个子 agent 任务的 commit 必须满足以下三条硬规则——任一违反即拒绝合入。
+
+## 1. 分支再校验（⛔ PRECONDITION_FAIL，task #18）
+
+子 agent 任务开始时再次校验当前分支 = `worktree-<name>`，防 subagent 中途被 `git checkout` 切换：
+
+```bash
+EXPECTED_BRANCH="worktree-<name>"
+ACTUAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [ "$ACTUAL_BRANCH" != "$EXPECTED_BRANCH" ] && [ "$(alloy _state read openspec/changes/<name> worktree)" != "skipped" ]; then
+  echo "⛔ [PRECONDITION_FAIL] 子 agent 当前分支 ($ACTUAL_BRANCH) ≠ 预期 ($EXPECTED_BRANCH)"
+  echo "  禁止：agent 自动 git checkout 切回 worktree-<name>。"
+  echo "  必须：退出子 agent 让用户检查，可能上一个子 agent 切换了分支或 worktree 失效。"
+  exit 1
+fi
+```
+
+## 2. git add 规则（⛔ HARD_STOP，§5.2.1）
+
+只用精确路径，不用 `-A`/`-a`/`.`。违反字面 = 违反精神：哪怕"反正只有这一个文件"，也禁止 `-A`——agent 看不到的副作用文件可能被一并提交。commit 前检查 untracked 文件：
+
+- 构建产物（`.vite/`、`dist/`、`node_modules/` 等）追加 `.gitignore`
+- 项目源码按精准路径 add（如 `git add src/foo.ts tests/foo.test.ts`）
+- 判断不准时 🔴 USER_GATE 询问用户
+
+```bash
+# 反例（禁用）：git add -A / git add . / git add -a
+# 正例：git add <精确路径列表>
+git add src/<具体文件>.ts tests/<具体测试>.test.ts
+```
+
+## 3. stash 残留检查（⚠️ WARN，task #19）
+
+commit 前必须运行：
+
+```bash
+if [ -n "$(git stash list)" ]; then
+  echo "⚠️ [WARN] 检测到 stash 残留："
+  git stash list
+  echo ""
+  echo "  stash 残留可能是用户之前未完成的工作。继续 commit 不会丢失 stash，"
+  echo "  但用户可能需要先 git stash pop 或 drop。"
+  echo "  禁止：agent 自动 git stash drop / git stash clear（§3.5.1）。"
+fi
+```
+
+WARN 不阻断 commit，但提醒 agent 在 commit 完成后向用户播报 stash 列表，让用户决定后续处理。

package/commands/alloy/references/apply-worktree.md

@@ -0,0 +1,130 @@
+# apply-worktree.md
+
+apply Step 1 worktree 路径占用检查、创建后状态记录、分支锁定校验。
+
+## 路径占用检查（⛔ PRECONDITION_FAIL，task #10）
+
+`git worktree add` 在目标路径已存在时会失败；agent 不得用 `git worktree remove --force` 或 `rm -rf` 自动清理——目标路径可能是用户之前未归档的工作（被 alloy 早期版本遗留 / 用户手动创建 / 同名 change 重启）。
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+TARGET_PATH="$REPO_ROOT/.claude/worktrees/<name>"
+TARGET_BRANCH="worktree-<name>"
+
+if [ -e "$TARGET_PATH" ] || git worktree list --porcelain | grep -qF "worktree $TARGET_PATH"; then
+  echo "⛔ [PRECONDITION_FAIL] worktree 目标路径已被占用："
+  echo "  路径: $TARGET_PATH"
+  echo "  目录存在: $([ -e "$TARGET_PATH" ] && echo 是 || echo 否)"
+  echo "  已注册为 git worktree: $(git worktree list --porcelain | grep -qF "worktree $TARGET_PATH" && echo 是 || echo 否)"
+  echo ""
+  echo "  禁止：agent 自动运行 git worktree remove --force / rm -rf $TARGET_PATH /"
+  echo "        git worktree prune 强行清理。这些路径可能是用户之前未归档的工作。"
+  echo "  违反字面 = 违反精神：哪怕看似\"覆盖一下让 apply 继续\"，也算违反禁令——"
+  echo "  必须 USER_GATE 让用户决策。"
+fi
+```
+
+路径已占用 → 🔴 USER_GATE：
+
+> 目标路径 `.claude/worktrees/<name>` 已被占用。
+> 选项：
+> (a) 复用现有 worktree——直接 `EnterWorktree(path=...)` 进入，跳过创建（要求该路径已是有效 git worktree 且分支为 `worktree-<name>`，否则降级到 (b)）
+> (b) 重命名当前 change——退出 skill，让用户用 `/alloy:start <new-name>` 重新发起，或手动重命名 change 目录
+> (c) 中止 apply——`alloy _state write openspec/changes/<name> worktree blocked` 后退出，待用户清理后重新运行
+
+- 选 (a)：检测分支匹配后 `EnterWorktree(path=".claude/worktrees/<name>")`，跳到"创建后状态记录"
+- 选 (b)：退出 skill 并提示用户重命名后重跑
+- 选 (c)：写入 worktree=blocked 后退出 skill
+
+路径未占用 → 执行创建：
+
+```bash
+git worktree add .claude/worktrees/<name> -b worktree-<name> <feature_branch>
+```
+
+再用 `EnterWorktree(path=".claude/worktrees/<name>")` 进入。路径偏好 `.claude/worktrees/<name>`（`.claude/` 是 alloy 固定目录），分支命名 `worktree-<name>`（与 EnterWorktree 内置一致，archive 清理时无需猜测）。
+
+## 创建后状态记录
+
+worktree 创建完成后，检测实际位置并写入状态文件：
+
+```bash
+echo "  正在检测 worktree 实际状态..."
+
+# 判断是否已在 worktree 中：GIT_DIR != GIT_COMMON 表示在 linked worktree 中
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+
+if [ "$GIT_DIR" != "$GIT_COMMON" ]; then
+  # 已在 worktree 中，获取实际路径和分支名
+  WORKTREE_PATH=$(cd "$(git rev-parse --show-toplevel)" 2>/dev/null && pwd -P)
+  WORKTREE_BRANCH=$(cd "$WORKTREE_PATH" && git branch --show-current)
+  alloy _state write openspec/changes/<name> worktree "$WORKTREE_PATH"
+  alloy _state write openspec/changes/<name> worktree_branch "$WORKTREE_BRANCH"
+  alloy _state write openspec/changes/<name> worktree_created_at "$(date '+%Y-%m-%d %H:%M:%S')"
+  echo "  ✓ worktree 已记录: 分支=$WORKTREE_BRANCH  路径=$WORKTREE_PATH"
+  # commit 确保断点恢复时 state 不丢失
+  git add openspec/changes/<name>/.alloy.yaml
+  git diff --cached --quiet || git commit -m "chore(<name>): record worktree state"
+else
+  # EnterWorktree 失败后的 git worktree fallback
+  # 优先检测 .claude/worktrees/（EnterWorktree 原生路径），回退 .worktrees/
+  WT_PATH=""
+  for CANDIDATE in ".claude/worktrees/<name>" ".worktrees/<name>"; do
+    if [ -d "$CANDIDATE" ]; then
+      WT_PATH=$(cd "$CANDIDATE" 2>/dev/null && pwd -P)
+      break
+    fi
+  done
+  if [ -n "$WT_PATH" ]; then
+    WORKTREE_BRANCH=$(cd "$WT_PATH" && git branch --show-current 2>/dev/null)
+    alloy _state write openspec/changes/<name> worktree "$WT_PATH"
+    alloy _state write openspec/changes/<name> worktree_branch "$WORKTREE_BRANCH"
+    alloy _state write openspec/changes/<name> worktree_created_at "$(date '+%Y-%m-%d %H:%M:%S')"
+    echo "  ✓ worktree fallback 已记录: 分支=$WORKTREE_BRANCH  路径=$WT_PATH"
+    # 提交 source repo 的 state
+    git add openspec/changes/<name>/.alloy.yaml
+    git diff --cached --quiet || git commit -m "chore(<name>): record worktree state"
+    # worktree 内也写入并提交——bash cd 不跨工具调用持久化
+    cd "$WT_PATH" && \
+      alloy _state write openspec/changes/<name> worktree "$WT_PATH" && \
+      alloy _state write openspec/changes/<name> worktree_branch "$WORKTREE_BRANCH" && \
+      alloy _state write openspec/changes/<name> worktree_created_at "$(date '+%Y-%m-%d %H:%M:%S')" && \
+      git add openspec/changes/<name>/.alloy.yaml && \
+      git diff --cached --quiet || git commit -m "chore(<name>): record worktree state (worktree)"
+  else
+    echo "  ℹ 未检测到 worktree，按用户选择记录"
+    alloy _state write openspec/changes/<name> worktree skipped
+  fi
+fi
+```
+
+## 状态记录字段
+
+| 字段 | 值 | 写入时机 |
+|------|-----|---------|
+| `worktree` | 有效路径 / `skipped` / `null` | 创建后或用户跳过时 |
+| `worktree_branch` | 分支名（如 `worktree-<name>`） | 创建后 |
+| `worktree_created_at` | `%Y-%m-%d %H:%M:%S` | 创建后 |
+
+这些数据是断点恢复的关键——Agent 重入时通过 `alloy _guard worktree-status` 读取。
+
+## Worktree 内分支锁定（⛔ PRECONDITION_FAIL，task #18）
+
+进入 worktree 后必须验证当前分支与状态记录一致——子 agent 后续在错误分支编辑 = 用户主分支被污染。
+
+```bash
+WORKTREE_PATH=$(alloy _state read openspec/changes/<name> worktree)
+EXPECTED_BRANCH="worktree-<name>"
+
+if [ "$WORKTREE_PATH" != "skipped" ] && [ "$WORKTREE_PATH" != "blocked" ] && [ -d "$WORKTREE_PATH" ]; then
+  ACTUAL_BRANCH=$(git -C "$WORKTREE_PATH" rev-parse --abbrev-ref HEAD 2>/dev/null)
+  if [ "$ACTUAL_BRANCH" != "$EXPECTED_BRANCH" ]; then
+    echo "⛔ [PRECONDITION_FAIL] worktree 内分支 ($ACTUAL_BRANCH) 与预期 ($EXPECTED_BRANCH) 不一致"
+    echo "  可能原因：用户在 worktree 内手动切换了分支 / 旧 worktree 残留 / 复用 (a) 进入了错误 worktree"
+    echo "  禁止：agent 自动 git checkout 切换分支——可能丢弃用户未提交的工作（§3.5.1）。"
+    echo "  必须：USER_GATE 让用户决策修复方式（手动切回 / 退出 skill 重建 worktree / 复用前确认分支）。"
+    exit 1
+  fi
+fi
+```

package/commands/alloy/references/archive-rationalizations.md

@@ -0,0 +1,16 @@
+# archive Red Flags 完整表（第三层防御——任一借口出现即 STOP）
+
+主文件保留 5 条核心，完整 11 条在此。
+
+| 借口 | 现实 |
+|------|------|
+| "verify.md FAIL 是小问题，先归档再说" | FAIL = 阻塞问题。归档不可逆——带着 FAIL 归档意味着 spec 与代码偏差被永久封存。 |
+| "跳过 archive 直接 merge，spec 后面补" | Delta Spec 不同步 = 主 spec 落后。"后面补"的 spec 永远不会补。 |
+| "openspec archive 报错了，但代码是对的" | 归档报错 = Delta Spec 合并失败。忽略 = 主 spec 停留在旧版本。 |
+| "spec 合并看起来没问题，直接继续" | 没看过的 spec 变更 = 代码与规格可能已分叉。审查只需 1 分钟，修复分叉需要 1 小时。 |
+| "worktree 合并没问题，直接清理吧" | merge 结果必须审查——未审查的合并可能引入意外变更或冲突残留。确认只需 30 秒，修复遗漏需要 1 小时。 |
+| "memory 条目都挺合理的，直接写入" | memory 影响所有后续会话。写入不当"经验"污染全局行为。确认只需 1 分钟。 |
+| "worktree 合并冲突了，跳过清理吧" | 冲突不解决 = 代码丢失。worktree 变更没合入 feature 就删除 = 白做。 |
+| "merge 冲突了，git merge --abort 一下让流程继续" | 冲突 = 代码状态未达预期，自动 abort = 隐藏真问题。退出 skill 让用户处理是唯一合法路径（§3.5.1）。 |
+| "memory 候选都对，全部写入吧" | 单次确认承担不了全局污染风险。每条独立 USER_GATE，无例外（§5.2.2）。 |
+| "另一个 change 也在 archive，等一下吧" | 多 change 并行 archive = Delta Spec 合并顺序敏感。先归档晚开始的 = 主 spec 状态错乱。必须串行。 |

package/commands/alloy/references/archive-worktree-cleanup.md

@@ -0,0 +1,94 @@
+# archive worktree 清理
+
+archive Step 2 末段：把 worktree 分支合入 feature 分支后清理 worktree 目录。包括 silent fallback 检测、遗留 change 兼容、merge 冲突处理三段。
+
+> **§3.5.1 git 自救禁令（HARD_STOP）：** 整段流程任何 git 失败都禁止 agent 自动 `git merge --abort` / `git reset --hard` / `git checkout .` / `git restore .` / `git stash` / `git clean -fd` / `git push --force` 任何一个。冲突现场必须报告并 USER_GATE 让用户决策。违反字面 = 违反精神。
+
+## 完整 bash 流程
+
+```bash
+WORKTREE_PATH=$(alloy _state read "$ARCHIVE_DIR" worktree 2>/dev/null)
+FEATURE_BRANCH=$(alloy _state read "$ARCHIVE_DIR" feature_branch 2>/dev/null)
+WORKTREE_BRANCH=$(alloy _state read "$ARCHIVE_DIR" worktree_branch 2>/dev/null)
+
+# task #21: silent fallback 检测——区分"遗留 change"（state 字段未写但 worktree 存在）
+# vs "state 缺失"（apply 阶段 state 写入失败）。后者必须 PRECONDITION_FAIL。
+if [ -z "$WORKTREE_PATH" ] || [ "$WORKTREE_PATH" = "null" ]; then
+  # state 中无 worktree 字段——检查 git 实际状态
+  ACTUAL_WT=$(git worktree list --porcelain | awk -v p=".claude/worktrees/<name>" '
+    /^worktree / { wt = substr($0, 10) }
+    wt ~ p { print wt; exit }
+  ')
+  if [ -n "$ACTUAL_WT" ]; then
+    echo "⛔ [PRECONDITION_FAIL] 检测到 git worktree 但 .alloy.yaml 未记录："
+    echo "  实际 worktree: $ACTUAL_WT"
+    echo "  状态字段:    worktree=$WORKTREE_PATH"
+    echo ""
+    echo "  可能原因：apply 阶段 state 写入失败，archive 不能 silent fallback。"
+    echo "  请用户检查 openspec/changes/<name>/.alloy.yaml 后手动修复 worktree 字段，"
+    echo "  或直接 git worktree remove $ACTUAL_WT（确认无未提交工作时）。"
+    exit 1
+  fi
+  # 真无 worktree → 跳过本段
+elif [ "$WORKTREE_PATH" != "skipped" ]; then
+  echo "  ℹ 检测到 worktree（$WORKTREE_PATH），正在合并回 feature 分支..."
+
+  # 遗留 change 兼容：FEATURE_BRANCH 缺失 → 退回到 feature/<name>
+  if [ -z "$FEATURE_BRANCH" ] || [ "$FEATURE_BRANCH" = "null" ]; then
+    FEATURE_BRANCH="feature/<name>"
+  fi
+
+  # 遗留 change 兼容：WORKTREE_BRANCH 缺失 → 从 worktree 实际状态检测
+  if [ -z "$WORKTREE_BRANCH" ] || [ "$WORKTREE_BRANCH" = "null" ]; then
+    WORKTREE_BRANCH=$(git worktree list --porcelain | awk -v path="$WORKTREE_PATH" '
+      /^worktree / { wt = substr($0, 10) }
+      /^branch / && wt == path { gsub(/^refs\/heads\//, "", $2); print $2; exit }
+    ')
+    if [ -z "$WORKTREE_BRANCH" ]; then
+      echo "⛔ [PRECONDITION_FAIL] 无法检测 worktree 分支名（state 缺失且 git 也无法定位）"
+      echo "  请用户手动指定 worktree_branch 后重试。"
+      exit 1
+    fi
+  fi
+
+  # 从 worktree 分支合并代码到 feature 分支
+  MAIN_ROOT=$(cd "$WORKTREE_PATH" && git rev-parse --show-toplevel 2>/dev/null)
+  cd "$MAIN_ROOT"
+  git merge "$WORKTREE_BRANCH" --no-edit
+
+  if [ $? -eq 0 ]; then
+    # worktree 合并审查（USER_GATE）
+    : <<'USER_GATE_TEMPLATE'
+    🔴 USER_GATE（必须 AskUserQuestion）：
+    > worktree 合并完成：
+    > [展示 merge 的 commit 列表：git log --oneline <FEATURE_BRANCH>..HEAD]
+    > 选项：
+    > (a) 确认并清理 worktree
+    > (b) 需要检查——退出 skill 让用户审查
+USER_GATE_TEMPLATE
+
+    # 用户选 (a) 后执行清理：
+    git worktree remove "$WORKTREE_PATH"
+    git branch -d "$WORKTREE_BRANCH"
+    # worktree_merged_at 由 archive.md 主流程内联记录，此处仅做清理
+    echo "  ✓ worktree 已合并至 $FEATURE_BRANCH 分支并清理"
+  else
+    # [HARD_STOP] merge 冲突时禁止运行 git merge --abort 或任何 git 自救命令。
+    # 必须报告冲突现场后调用 USER_GATE 让用户决定。
+    echo "⛔ merge 冲突——worktree 工作未合入 feature 分支"
+    echo ""
+    echo "  冲突现场："
+    git status --short
+    echo ""
+    echo "  合法路径："
+    echo "    1) 用户手动解决冲突后 git add + git commit，再重新运行 /alloy:archive"
+    echo "    2) 用户决定放弃 worktree 工作（注意：放弃前确认无未保存改动）"
+    echo ""
+    echo "  禁止：agent 自动运行 git merge --abort / git reset --hard /"
+    echo "        git checkout . / git restore . / git stash 任何一个。"
+    exit 1
+  fi
+fi
+```
+
+未使用 worktree 时跳过本段。

package/commands/alloy/references/artifact-hash-commit.md

@@ -0,0 +1,49 @@
+# artifact-hash-commit.md
+
+制品审批后的 hash 锁定 + commit 标准序列。
+
+## 标准流程
+
+用户在审查窗口选 (a) 确认后执行：
+
+```bash
+HASH=$(alloy _record compute openspec/changes/<name> <artifact>)
+APPROVED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+APPROVER=$(alloy _record approver openspec/changes/<name>)
+alloy _record write openspec/changes/<name> <artifact> "$HASH" "$APPROVED_AT" "$APPROVER"
+git add openspec/changes/<name>/
+git commit -m "docs(<name>): <artifact> 已确认"
+```
+
+## 阶段最后一个制品
+
+阶段最后一个制品审批时，phase_timings.completed_at + hash 锁定合并为一个 commit——禁止拆成两次提交：
+
+```bash
+COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+alloy _state merge openspec/changes/<name> phase_timings "{\"<phase>\":{\"completed_at\":\"${COMPLETED_AT:-$(date '+%Y-%m-%d %H:%M:%S')}\"}}"
+HASH=$(alloy _record compute openspec/changes/<name> <artifact>)
+APPROVED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+APPROVER=$(alloy _record approver openspec/changes/<name>)
+alloy _record write openspec/changes/<name> <artifact> "$HASH" "$APPROVED_AT" "$APPROVER"
+git add openspec/changes/<name>/
+git commit -m "docs(<name>): <artifact> 已确认"
+```
+
+phase_timings 作为元数据附着在制品提交上，不单独 commit。
+
+## commit message 格式
+
+`docs(<change-name>): <artifact> 已确认`（Conventional Commits `docs` type）。
+
+`<artifact>` 为 draft / proposal / design / specs / tasks / plans / verify / retrospective。
+
+## 生成下一制品前
+
+校验上游依赖制品的 hash 未被篡改：
+
+```bash
+alloy _record check openspec/changes/<name> <upstream-artifact>
+```
+
+check 返回非零 → HARD STOP，hash 不匹配意味着有未审批的篡改。

package/commands/alloy/references/branch-naming.md

@@ -0,0 +1,65 @@
+# branch-naming.md
+
+Alloy 分支命名白名单与 PRECONDITION_FAIL 校验。`start` 创建 feature 分支、`fix` 创建热修分支、用户自定义分支名时统一引用本文件。
+
+## 白名单（与 `CLAUDE.md` 同源）
+
+允许的 prefix（kebab-case 后缀）：
+
+| prefix | 用途 | 示例 |
+|--------|------|------|
+| `feature/` | 新功能 change（start 默认） | `feature/user-auth` |
+| `fix/` | Bug 修复 / 热修 | `fix/login-redirect` |
+| `docs/` | 文档变更 | `docs/api-reference` |
+| `refactor/` | 重构（无行为变更） | `refactor/extract-validator` |
+| `test/` | 测试补全 / 验证分支 | `test/phase-5-validation` |
+| `chore/` | 构建 / 配置 / 杂项 | `chore/bump-deps` |
+
+**禁用 prefix**：`hotfix/`（用 `fix/` 替代）、`bugfix/`（用 `fix/`）、`master/` `main/` `dev/`（与主分支同名）、无 prefix 裸分支名（`wip` `tmp` 等）。
+
+## PRECONDITION_FAIL 校验 bash
+
+调用方在分支创建/确认前嵌入：
+
+```bash
+# 输入：$BRANCH_NAME（待创建或用户自定义的分支名）
+# 输出：通过则 echo "✓ 分支命名合法"；不合法则 exit 1
+
+ALLOY_BRANCH_PREFIXES="feature|fix|docs|refactor|test|chore"
+
+if ! echo "$BRANCH_NAME" | grep -Eq "^(${ALLOY_BRANCH_PREFIXES})/[a-z0-9][a-z0-9._-]*$"; then
+  echo "⛔ [PRECONDITION_FAIL] 分支名 \"$BRANCH_NAME\" 不在白名单："
+  echo "  允许的 prefix: feature/ fix/ docs/ refactor/ test/ chore/"
+  echo "  分支后缀须 kebab-case（小写字母数字 . _ -，不以 . _ - 开头）"
+  echo ""
+  echo "  禁止：agent 自动改写分支名后继续——分支命名是 PR / merge / 审计链入口，"
+  echo "  必须 USER_GATE 让用户选择合法名称。"
+  echo ""
+  echo "  违反字面 = 违反精神：哪怕 \"hotfix/ 历史上能用\" 或 \"分支名只是临时\"，"
+  echo "  也算违反白名单——历史 hotfix/ 名应在本次重新走 fix/ 路径。"
+  exit 1
+fi
+
+echo "✓ 分支命名合法: $BRANCH_NAME"
+```
+
+## 与主分支同名校验（叠加约束）
+
+白名单通过后仍需校验不与 `main_branch` 重合——`feature/main` 这种名称合法但语义混乱，建议另外校验。该校验由调用方（start.md 步骤 3）在白名单后追加：
+
+```bash
+if [ "$BRANCH_NAME" = "$MAIN_BRANCH" ]; then
+  echo "⛔ [PRECONDITION_FAIL] 分支名与主分支同名: $BRANCH_NAME"
+  exit 1
+fi
+```
+
+## 调用方
+
+- `start.md` 步骤 3 ②：默认 `feature/<change-name>`，用户自定义时强制走白名单校验
+- `fix.md` 场景 3：固定 `fix/<desc>`（不再用 `hotfix/`）。用户自定义时同样校验
+- `apply.md` worktree 路径占用 (b) 重命名分支：用户输入新分支名后校验
+
+## Why
+
+CLAUDE.md 规定的 6 个 prefix 是 squash merge 时 Conventional Commits 的语义来源，分支名 prefix 直接影响 PR 标题模板和归档审计链。`hotfix/` 不在白名单 = `fix/` 与 `hotfix/` 双轨并存导致 changelog 工具无法识别。**白名单是闸门型约束，不是建议。**

package/commands/alloy/references/branch-validation.md

@@ -0,0 +1,36 @@
+# branch-validation.md
+
+`alloy _guard branch-position` 返回异常时的修复选项。
+
+**交互规则：** 所有选项确认点均为 🔴 STOP——必须用 AskUserQuestion 等用户选择，不可自行决定。
+
+## 异常结果与修复路径
+
+### feature-missing
+
+`.alloy.yaml` 未记录 feature_branch。这通常是 start 阶段数据写入失败——null 是状态异常，不是设计的容错。
+
+🔴 STOP: 选择修复方式——(a) 手动指定分支名 (b) 使用当前分支作为 feature_branch (c) 放弃，回退 start 阶段修复
+
+用户选择后：`alloy _state write openspec/changes/<name> feature_branch <用户确认的分支>`
+
+**不允许静默回退**——回退值可能与实际分支不一致。
+
+### on-other:\<current\>
+
+当前分支与 feature_branch 记录不一致：
+
+🔴 STOP: 选择处理方式——(a) 切换到 feature_branch（推荐） (b) 使用当前分支（更新 feature_branch 记录）
+
+选 (a)：`git checkout <feature_branch>` → 重新运行 `alloy _guard branch-position`
+选 (b)：`alloy _state write openspec/changes/<name> feature_branch <current_branch>` → 继续
+
+### feature-lost:\<feature\>
+
+feature_branch 记录在 .alloy.yaml 但本地不存在：
+
+🔴 STOP: 选择修复方式——(a) 从远程拉取 (b) 手动指定其他分支 (c) 放弃，回退 start 阶段修复
+
+## 跨文件复用
+
+此文件供 apply.md 和 start.md 的分支验证步骤引用。start.md 的分支选择逻辑更复杂（包含新建分支选项），此文件只处理 apply 阶段的修复场景。

package/commands/alloy/references/fix-precommit-check.md

@@ -0,0 +1,58 @@
+# fix-precommit-check.md
+
+fix 场景 1/2/3 在 commit / merge 前的 TDD + verification 校验门。**目的：阻止"跳诊后跳验证"——commit 前必须证明已加载 test-driven-development + verification-before-completion 两个 skill。**
+
+## 场景 1/2（有归属 change）：skill_usage[] 校验
+
+调用方在 commit 前嵌入。校验对象：`.alloy.yaml` 的 `skill_usage[]`，匹配 `stage=fix` 且 `skill ∈ {test-driven-development, verification-before-completion}`，`action=log`（不是 skip）。
+
+```bash
+# 输入：$NAME（change name），$CHANGE_DIR=openspec/changes/$NAME
+
+REQUIRED_SKILLS="test-driven-development verification-before-completion"
+MISSING=""
+
+for SKILL in $REQUIRED_SKILLS; do
+  COUNT=$(alloy _state read "$CHANGE_DIR" skill_usage 2>/dev/null \
+    | python3 -c "
+import sys, json
+data = json.load(sys.stdin) if sys.stdin.readable() else []
+hits = [e for e in (data or []) if e.get('stage')=='fix' and e.get('skill')=='$SKILL' and e.get('action')=='log']
+print(len(hits))
+" 2>/dev/null || echo 0)
+  if [ "${COUNT:-0}" -eq 0 ]; then
+    MISSING="$MISSING $SKILL"
+  fi
+done
+
+if [ -n "$MISSING" ]; then
+  echo "⛔ [HARD_STOP] commit 前缺失必需 skill 调用记录："
+  echo "  缺失:$MISSING"
+  echo "  原因：fix 场景 1/2 commit 前必须先加载 test-driven-development + verification-before-completion"
+  echo "        并通过 alloy _skill log <change-dir> fix <skill> 记录调用。"
+  echo ""
+  echo "  禁止：agent 自动补 _skill log 后继续——记录必须反映真实加载。"
+  echo "  违反字面 = 违反精神：哪怕\"测试已经写过了\"或\"diff 看起来明显是修复\"，"
+  echo "  也算违反——跳过验证 = 跳过修复闸门。"
+  exit 1
+fi
+
+echo "✓ pre-commit 校验通过：$REQUIRED_SKILLS 均已加载"
+```
+
+## 场景 3（无归属 change）：USER_GATE 物理确认
+
+热修无 change 上下文，无法读 skill_usage。改用 🔴 USER_GATE 在 merge 精确字符串确认前追加：
+
+> 已加载 superpowers:test-driven-development（写失败测试 → 修代码）？
+> 已加载 superpowers:verification-before-completion（独立验证修复结果）？
+>
+> 选项：
+> (a) 已加载两个 skill，继续 merge 确认
+> (b) 未加载——返回 Step 3 重做
+
+**[HARD_STOP]** agent 不得基于"diff 包含测试代码"或"自己已经测过"自动选 (a)——必须用户物理选择。否则违反 interaction-style.md "沉默 ≠ 授权"通用禁令。
+
+## Why
+
+systematic-debugging（已在 Step 2 强制）只解决"修对位置"——TDD 解决"修法正确"，verification 解决"修完没回归"。三者缺一就把 bug 搬家而不是修复。L4 漏洞场景：用户压力下 agent 直接 `git diff` + `git commit` 跳过 Step 3 子步骤 1-2，闸门必须在 commit 前物理拦截。

package/commands/alloy/references/interaction-style.md

@@ -51,10 +51,43 @@ AskUserQuestion: {
 > 请输入 a 或 b：
 ```
 
-**硬规则：凡是技能文件中出现 `AskUserQuestion` JSON 块的，同一位置必须附带降级文本格式。** Agent 执行时先检测当前平台是否支持 `AskUserQuestion` 工具——支持则用原生交互组件，不支持则自动降级为文本选项。两个格式给出相同选项、相同数量，确保不同平台上用户看到的选项一致。
+**硬规则：技能文件中用 `🔴 STOP` 标记确认点，不写 JSON 块。** Agent 遇到 🔴 STOP 时自动用 AskUserQuestion（支持的平台）或降级为结构化文本选项（不支持的平台）。两个格式给出相同选项、相同数量。
 
 **反例：** 审查窗口只用文本 "(a) 确认 (b) 调整" 而不给明确的输入提示——用户不知道是要打字、复制粘贴还是直接说"确认"。
 
+## 🔴 STOP 标记规则
+
+技能文件中的 `🔴 STOP` 表示硬交互确认点——**必须使用 AskUserQuestion（或平台等价工具），不可跳过、不可用文本替代、不可自行决定。**
+
+遇到 `🔴 STOP: <确认事项>` 时：
+1. 用 AskUserQuestion 展示选项，**等用户选择后才继续**
+2. 选项从确认事项的上下文推导（通常是"确认/调整"或"选项A/选项B"）
+3. 跳过任何 🔴 STOP = 违反技能 Iron Law
+
+**Why:** 纯文本确认（"Y/n"、"(a)/(b)"）是软交互——agent 可自行判断"用户大概同意"后跳过。AskUserQuestion 是硬交互——agent 必须等用户物理选择才能继续。
+
+## 沉默 ≠ 授权（USER_GATE 通用禁令，跨 skill 适用）
+
+**[HARD_STOP]** 所有 🔴 USER_GATE / 🔴 STOP **必须**单独调用 AskUserQuestion 等用户物理选择，下列行为全部禁止：
+
+| 反模式 | 现实 |
+|--------|------|
+| **批量打包**：N 条候选 → 1 个"全部确认"问题 | 单次确认承担不了 N 项独立的污染风险（典型：archive memory 候选必须逐条问，§5.2.2） |
+| **基于内容跳过**：diff 短 / 无 conflict / "看起来明显合理" → 自动跳过 USER_GATE | 内容质量不是授权来源，用户的 (a) 选择才是。哪怕 1 行 diff 也必须问 |
+| **沉默推断**：用户长时间不回复 → 选默认项继续 | USER_GATE 没有默认项；超时不算授权，必须等到物理选择 |
+| **改写选项**：把"(a) 确认 / (b) 调整"改成"(a) 确认（推荐）"后默认选 (a) | 推荐文案不等于已选，必须用户主动确认 |
+| **降级为文本**：在支持 AskUserQuestion 的平台用纯文本提示自循环判断 | 平台支持时强制 AskUserQuestion，降级仅限不支持的平台（见上方对照表） |
+
+**违反字面 = 违反精神：** 哪怕"用户上次同意过"、"内容看起来无争议"、"流程已经很顺了"，也算违反 Iron Law。**USER_GATE 的物理实现是 AskUserQuestion 工具调用本身——没调用就是没问。**
+
+### 精确字符串确认特例
+
+部分破坏性操作要求用户输入精确字符串（discard、热修 merge），见上方"不能使用 AskUserQuestion 的场景"章节。此时禁令仍适用：
+
+- **agent 不得回填精确字符串**：用户必须自己输入 `discard <name>` / `merge <branch> into <branch>`，禁 agent 在工具调用中预填、模拟、或基于"用户回复了'好'"自行判定
+- **模糊回复不算确认**："好"、"可以"、"y"、"go ahead" 全部不算精确确认，必须等到字面匹配的字符串
+- **跨 skill 适用**：fix 场景 3 热修合并、discard 命令均按此规则
+
 ## 不能使用 AskUserQuestion 的场景
 
 以下场景**保持精确文本确认**，因为它们是安全机制而非便利功能：

package/commands/alloy/references/main-branch-detection.md

@@ -2,6 +2,8 @@
 
 start 和 fix 命令共享的主分支自动检测逻辑。
 
+**交互规则：** 确认点为 🔴 STOP——必须用 AskUserQuestion 等用户选择，不可自行决定。
+
 ## 检测优先级（3 级）
 
 ```bash
@@ -19,12 +21,7 @@ DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|
 
 ## 确认步骤
 
-检测到主分支后，必须让用户确认（Y/n）：
-```
-主分支: $DEFAULT_BRANCH。使用此分支作为基础分支？[Y/n]
-```
-
-选 Y 或直接回车 → 使用检测结果。选 n → 让用户输入自定义名称。
+检测到主分支后，🔴 STOP: 确认主分支（检测值 / 自定义名称）。
 
 确认后写入项目级配置：
 ```bash

package/commands/alloy/references/phase-downgrade-path.md

@@ -0,0 +1,27 @@
+# §5.2.3 phase 推进降级路径
+
+各 skill 在推进 phase 后，如果后续阶段失败，agent 不得自动 `git reset --hard` / `git checkout .` 清场。降级路径如下：
+
+## 通用降级 3 步（apply / archive 适用）
+
+若推进后续阶段失败，用户须手动按以下 3 步回退：
+
+```bash
+alloy _state set <CHANGE_DIR> phase <previous-phase>
+git checkout HEAD~1 -- <CHANGE_DIR>/.alloy.yaml  # 撤销 phase commit 中的状态变更
+git reset HEAD~1                                 # 退回 phase commit
+```
+
+`<previous-phase>` 对应：
+- apply 阶段降级 → `planned`
+- archive 阶段降级 → `applied`
+- finish 阶段降级 → `archived`
+
+## 禁令
+
+- 禁止 agent 自动 `git reset --hard` / `git checkout .` 清场（详见 §3.5.1 git 自救禁令）
+- 违反字面 = 违反精神：哪怕"清理一下让流程重启"，也算违反禁令——退出 skill 让用户决策是唯一合法路径
+
+## 边界
+
+- start 是 phase 推进起点（无前序 phase），phase=started 写入失败时降级路径只有"重跑 /alloy:start"——不存在 phase 回退场景。本阶段无 §5.2.3 适用空间。