@flyin-ai/alloy 0.1.1 → 0.2.0-beta.1

package/commands/alloy/archive.md

@@ -1,6 +1,6 @@
 ---
 name: "Alloy: Archive"
-description: Alloy 归档——apply 完成后，锁定 Delta Spec 并归档 change
+description: Alloy 归档阶段 - apply 完成后进入
 category: Workflow
 tags: [alloy, workflow]
 ---
@@ -11,39 +11,50 @@ tags: [alloy, workflow]
 
 **核心原则：先锁定文档证据链，再合入代码。** archive 只负责 spec 归档，代码合入由后续的 `/alloy:finish` 完成。
 
+**调用外部命令或技能前，先输出标题和状态描述，再执行操作。不要只出标题然后沉默。**
+
+**捕获阶段启动时间**（命令调用后第一时间，前置检查之前，幂等——重入时返回已有值）：
+```bash
+PHASE_START=$(alloy _state timestamp ensure openspec/changes/<name> archive)
+```
+
+---
+
 **什么算"archive 操作不当"（反例）：**
 - verify.md 的 Overall Decision 是 FAIL 但仍然继续归档——阻塞问题被无视
 - 跳过 archive 直接手动 merge——Delta Spec 没有被同步，主 spec 落后于代码
 - openspec archive 返回错误但忽视警告继续——"反正代码对的，spec 后面再说"
 
+### Red Flags——STOP，不要继续
+
+以下任何一个念头出现，都意味着闸门正在被绕过：
+
+| 借口 | 现实 |
+|------|------|
+| "verify.md FAIL 是小问题，先归档再说" | FAIL = 阻塞问题。归档不可逆——带着 FAIL 归档意味着 spec 与代码的偏差被永久封存。 |
+| "跳过 archive 直接 merge，spec 后面补" | Delta Spec 不同步 = 主 spec 落后于代码。"后面补"的 spec 永远不会补。 |
+| "openspec archive 报错了，但代码是对的，忽略吧" | 归档报错意味着 Delta Spec 合并失败。忽略 = 主 spec 停留在旧版本，下次 change 基于过期 spec 做设计。 |
+| "worktree 合并冲突了，跳过清理吧" | 冲突不解决 = 代码丢失。worktree 中的变更没有合入 feature 分支就删除，等于白做。 |
+| "反正是个小 change，不用归档了吧" | 小 change 也需要 spec 同步。不归档 = 主 spec 和代码永久分叉。大小 change 的归档流程完全一样。 |
+
 ---
 
 ## 前置检查（HARD STOP）
 
 ### [Step 1/3] 前置检查
 
-**记录阶段开始时间：**
-```bash
-COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
-TIMINGS=$(alloy _state read openspec/changes/<name> phase_timings 2>/dev/null || echo "{}")
-echo "$TIMINGS" | python3 -c "
-import sys,json
-content = sys.stdin.read()
-d = json.loads(content) if content.strip() else {}
-p = d.setdefault('archive',{})
-if 'started_at' not in p:
-    p['started_at']='$COMPLETED_AT'
-print(json.dumps(d))
-" | while read -r val; do alloy _state write openspec/changes/<name> phase_timings "$val"; done
-```
-
 ```
 ┌──────────────────────────────────────┐
 │ Alloy [4/5] · Phase: Archive         │
-│ 启动时间: 从 phase_timings.archive.started_at 读取
+│ 启动时间: $PHASE_START
 └──────────────────────────────────────┘
 ```
 
+**0. Skill 预检：** 确认以下依赖可用：
+   cmd: opsx/archive
+
+   读取 `commands/alloy/references/skill-precheck.md` 了解检测方法。任一不可用 → 引导 `alloy init` → STOP。
+
 **1. phase 检查：**
 
 先通过 `alloy _guard` 做硬校验：
@@ -51,17 +62,7 @@ print(json.dumps(d))
 alloy _guard openspec/changes/<name> archived
 ```
 
-若 guard 报错（phase 不匹配），读取当前 phase，按以下规则自动路由：
-
-| 当前 phase | 行为 |
-|-----------|------|
-| started | "尚未 plan，自动进入 /alloy:plan" → 加载 alloy-plan 指令 |
-| planned | "尚未 apply，自动进入 /alloy:apply" → 加载 alloy-apply 指令 |
-| applied | precheck 通过，继续归档 |
-| archived | "已归档，自动进入 /alloy:finish" → 加载 alloy-finish 指令 |
-| finished | "工作流已完成" → STOP |
-
-**实现方式：** 输出对应命令文件的完整指令，将 change name 和当前进度信息作为上下文传入。
+若 guard 报错（phase 不匹配），读取 `commands/alloy/references/phase-routing.md` 按路由表自动跳转。当前 phase=applied 时 precheck 通过。
 
 **HARD STOP 保留场景：** change 目录不存在（前序阶段完全没做）→ 引导用户先运行 `/alloy:start`。
 
@@ -88,6 +89,22 @@ test -f openspec/changes/<name>/verify.md && ! grep -q '^- \[x\] ❌ FAIL' opens
 - `/opsx:archive` 返回错误（权限、冲突等）→ [HARD STOP]，不推进 phase
 - `/opsx:archive` 不可用（OpenSpec 未安装）→ 引导用户运行 `alloy init` 安装 OpenSpec
 
+**命令执行后立即记录：**
+```bash
+alloy _skill log openspec/changes/<name> archive opsx:archive
+```
+
+**归档变更提交（必须在 worktree 清理之前）：**
+
+`/opsx:archive` 执行 `mv` 移动目录，但不负责 git commit。如果当前在 worktree 中，变更必须先 commit 到 worktree 分支，否则 worktree 清理时 merge 会丢失归档操作。
+
+```bash
+git add -A openspec/specs/ openspec/changes/
+git diff --cached --quiet || git commit -m "chore(<name>): 归档目录移动"
+```
+
+`git diff --cached --quiet` 在无变更时跳过（`opsx:archive` 已自行 commit 的场景）。
+
 归档成功后，确定归档路径并处理后续步骤：
 
 ```bash
@@ -99,39 +116,85 @@ ARCHIVE_DIR="openspec/changes/archive/$(date +%Y-%m-%d)-<name>"
 
 > 这是 retrospective 从"死文档"变成"活反馈"的关键步骤——教训不跨 cycle 就不是教训。
 
-然后执行 git commit（确保归档变更被版本追踪）：
+**Worktree 清理（如果 apply 期间使用了 worktree）：**
+
 ```bash
-git add openspec/specs/ openspec/changes/archive/ 2>/dev/null
-git commit -m "chore(<name>): Delta Spec 已同步并归档" 2>/dev/null
+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)
+
+if [ "$WORKTREE_PATH" != "null" ] && [ -n "$WORKTREE_PATH" ] && [ "$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 "  ⚠ 无法检测 worktree 分支名（worktree_branch 为空且 git worktree list 未匹配）"
+      echo "  请手动指定: git merge <worktree-branch> && git worktree remove $WORKTREE_PATH"
+      exit 1
+    fi
+  fi
+
+  # 切回主仓库目录
+  MAIN_ROOT=$(cd "$WORKTREE_PATH" && git rev-parse --show-toplevel 2>/dev/null)
+
+  # 从 worktree 分支合并代码到 feature 分支
+  cd "$MAIN_ROOT"
+  git merge "$WORKTREE_BRANCH" --no-edit
+
+  if [ $? -eq 0 ]; then
+    # 删除 worktree 目录和分支
+    git worktree remove "$WORKTREE_PATH"
+    git branch -d "$WORKTREE_BRANCH"
+    # 标记已清理（保留 worktree/worktree_branch 原值不删除）
+    WORKTREE_MERGED_AT=$(date '+%Y-%m-%d %H:%M:%S')
+    alloy _state write "$ARCHIVE_DIR" worktree_merged_at "$WORKTREE_MERGED_AT"
+    echo "  ✓ worktree 已合并至 $FEATURE_BRANCH 分支并清理"
+  else
+    echo "  ⚠ merge 冲突，请手动解决后再继续"
+    echo "  先: git checkout $FEATURE_BRANCH && git merge $WORKTREE_BRANCH"
+    exit 1
+  fi
+fi
 ```
-（git commit 失败不阻断——可能没有变更或不在 git 仓库中）
 
-> ✓ Delta Spec 已合并到主 spec
-> ✓ Change 已归档到 $ARCHIVE_DIR
-> ✓ 归档变更已提交
+如果 apply 期间未使用 worktree（worktree 为 null 或 skipped），则跳过此步骤。
 
-### Step 3/3：完成
+**记录完成时间并提交（所有 .alloy.yaml 变更在 commit 之前完成）：**
 
-**记录阶段完成时间：**
 ```bash
-COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
-TIMINGS=$(alloy _state read "$ARCHIVE_DIR" phase_timings 2>/dev/null || echo "{}")
-echo "$TIMINGS" | python3 -c "
-import sys,json
-content = sys.stdin.read()
-d = json.loads(content) if content.strip() else {}
-p = d.setdefault('archive',{})
-if 'completed_at' not in p:
-    p['completed_at']='$COMPLETED_AT'
-print(json.dumps(d))
-" | while read -r val; do alloy _state write "$ARCHIVE_DIR" phase_timings "$val"; done
-git add "$ARCHIVE_DIR/"
-git commit -m "chore(<name>): 记录 archive 阶段完成时间"
+# 写入完成时间（:="${...:-...}" 兜底：防 Agent 漏 capture）
+COMPLETED_AT="${COMPLETED_AT:-$(date '+%Y-%m-%d %H:%M:%S')}"
+COMPLETED_AT_JSON=$(python3 -c "import json; print(json.dumps({'archive':{'completed_at': '$COMPLETED_AT'}}))")
+alloy _state merge "$ARCHIVE_DIR" phase_timings "$COMPLETED_AT_JSON"
+
+# commit：.alloy.yaml 变更（phase_timings + worktree_merged_at）
+# 归档目录移动已在 worktree 清理前提交（或无 worktree 时在上方提交）
+git add -A openspec/specs/ openspec/changes/
+git commit -m "chore(<name>): 归档阶段完成"
 ```
+commit 失败必须阻断——.alloy.yaml 变更未提交时，后续 finish 阶段状态不一致。
+
+> ✓ Delta Spec 已合并到主 spec
+> ✓ Change 已归档到 $ARCHIVE_DIR
+> ✓ 归档变更已提交（目录移动 + 阶段完成时间）
+
+### [Step 3/3] 完成
 
 **通过 `alloy _guard` 校验并推进 phase：**
 ```bash
 alloy _guard "$ARCHIVE_DIR" archived --apply
+git add -A openspec/specs/ openspec/changes/
+git commit -m "chore(<name>): phase → archived"
 ```
 
 ```
@@ -149,21 +212,14 @@ alloy _guard "$ARCHIVE_DIR" archived --apply
 ✓ Delta Spec 已合并到主 spec
 ✓ Change 已归档
 
-**根据 worktree 状态动态提示：**
-
-```bash
-alloy _state read "$ARCHIVE_DIR" worktree
-```
-
-- worktree 有值 → 代码在独立 worktree 分支上，尚未合入。运行 `/alloy:finish` 完成代码合入与现场清理。
-- worktree 为 `null` → 代码在当前分支上。运行 `/alloy:finish` 完成收尾。
+> → 代码合入由 `/alloy:finish` 处理
 
 ---
 
 ## 闸门规则
 
-- **git add 只用精确路径** — 永远不用 `-A`、`-a`、`.`。
-  archive 只 add `openspec/specs/` 和 `openspec/changes/archive/`，反例：`git add -A openspec/` 会把残留文件一起提交
+- **git add 只用精确路径** — 永远不用 `-a`、`.`。
+  archive 用 `git add -A openspec/specs/ openspec/changes/`（`-A` 限路径，只追踪这两个目录的新增/修改/删除），反例：`git add -A`（无路径限定，扫全仓）
 - **phase 必须为 applied** —— 只有 apply 完成的 change 才能归档
 - **verify.md 必须存在且非 FAIL** —— 阻塞问题必须先修复
 - **先归档后合入** —— spec 文档先锁定，代码后通过 `/alloy:finish` 合入，避免"代码合入了 spec 还没跟上"

package/commands/alloy/discard.md

@@ -1,6 +1,6 @@
 ---
 name: "Alloy: Discard"
-description: Alloy 放弃 change - 按 phase 分级清理
+description: Alloy 放弃 change - 需要放弃时调用
 category: Workflow
 tags: [alloy, workflow]
 ---
@@ -9,6 +9,10 @@ tags: [alloy, workflow]
 
 你是 Alloy 的放弃清理器。你的职责是：根据 change 的当前 phase 执行分级清理，确保用户明确确认后再删除。
 
+**核心原则：精确确认才能删除，残留必须清理。**
+
+每个 change 必须有独立的 feature 分支（start step 6 保证），discard 时可安全删除整个分支。
+
 ---
 
 ## 读取当前状态
@@ -18,24 +22,34 @@ Alloy · 放弃 Change
 ──────────────────────────────────────
 ```
 
-先通过 `alloy _state` 读取 phase 和 worktree：
+读取必要信息：
 ```bash
 alloy _state read openspec/changes/<name> phase
 alloy _state read openspec/changes/<name> worktree
+alloy _state read openspec/changes/<name> feature_branch
+alloy _config read . main_branch
 ```
 
 ---
 
 ## Phase 分级行为
 
-| phase | 行为 |
-|-------|------|
-| started / planned | 仅删除 `openspec/changes/<name>/` 目录（无 worktree 无分支） |
-| applied / archived | 删除 change 目录 + worktree + 分支 |
+| phase | 清理动作 |
+|-------|---------|
+| started / planned | `git checkout <main_branch>` + `git branch -D <feature_branch>` + `rm change 目录` |
+| applied / archived | `git worktree remove` + `git checkout <main_branch>` + `git branch -D <feature_branch>` + `rm change 目录` |
 | finished | **[HARD STOP] 已完成的 change 不可 discard。** finished 是终态 |
 
 ---
 
+## 安全兜底
+
+- `feature_branch` == `main_branch` → 不删分支（理论上不会发生，start step 6 已拦截）
+- `main_branch` 未记录 → 提示用户手动切回主分支，不执行 `git checkout`
+- `feature_branch` 未记录 → 仅删除 worktree 和 change 目录，不删分支
+
+---
+
 ## 确认提示
 
 清理前必须展示将要删除的内容并等待用户精确确认：
@@ -43,11 +57,12 @@ alloy _state read openspec/changes/<name> worktree
 ```
 将删除以下内容，不可恢复:
 
-  Change:     <name>
-  Phase:      <phase>
-  Worktree:   <path>（如有）
-  分支:       <name>（如有）
-  目录:       openspec/changes/<name>/
+  Change:        <name>
+  Phase:         <phase>
+  Feature 分支:  <feature_branch>（如有）
+  Worktree:      <path>（如有）
+  目录:          openspec/changes/<name>/
+  切回分支:      <main_branch>（如有）
 
 输入 'discard <name>' 确认，或输入其他任意内容取消。
 ```
@@ -56,16 +71,42 @@ alloy _state read openspec/changes/<name> worktree
 - 用户说"好"——不算，需要精确输入 `discard <name>`
 - 用户说"删吧"——不算，同上
 - 用户说"y"——不算，需要完整匹配
+- 用户说"嗯"——不算，中文里可以表示"知道了"而非"确认执行"
+- 用户说"删了吧"——不算，虽然语义明确但不够精确，仍需要完整匹配
 
 只有用户精确输入 `discard <name>` 后才执行清理。精确匹配是故意的——防止手滑删除。
 
+### Red Flags——STOP，不可跳过闸门
+
+| 借口 | 现实 |
+|------|------|
+| "就删个目录而已，y 就行了" | 删除是不可逆操作。`discard <name>` 的精确匹配是防手滑的最后一道防线。"y"、"好"、"删了吧"都不算。 |
+| "这个 change 已完成，直接删了吧" | finished 是终态——不可 discard。已完成的 change 有完整审计链，删除会破坏追溯性。 |
+| "不用列出清单了，我知道有什么" | 必须先展示六行删除清单（Change/Phase/分支/Worktree/目录/切回分支），让用户确认每个待删除项的完整性和正确性。 |
+| "不用按顺序清理，直接 rm -rf 就行了" | 清理必须按序：worktree remove → checkout main → branch -D → rm 目录。不按序可能留下孤儿 worktree 或残留分支。
+
 ---
 
 ## 确认后清理
 
-1. 若 worktree 存在：`git worktree remove <path> --force`
-2. 若分支存在且未合并：`git branch -D <name>`
-3. 删除 change 目录：`rm -rf openspec/changes/<name>/`
+**执行顺序（必须按序）：**
+
+```bash
+# 1. git worktree remove（如存在且 phase ≥ applied）
+git worktree remove <path> --force
+
+# 2. git checkout <main_branch>（切离要删的分支）
+git checkout <main_branch>
+
+# 3. git branch -D <feature_branch>
+git branch -D <feature_branch>
+
+# 4. rm -rf openspec/changes/<name>/
+rm -rf openspec/changes/<name>/
+```
+
+若 `main_branch` 未记录，跳过步骤 2，提示用户手动切回主分支。
+若 `feature_branch` 未记录，跳过步骤 3。
 
 ---
 
@@ -76,5 +117,6 @@ Alloy · 放弃 Change — DONE
 ──────────────────────────────────────
 
 ✓ <name> 已清理
-  已删除：<列出实际删除的内容>
+  已删除：<列出实际删除的内容（分支/worktree/目录）>
+  当前分支：<main_branch>（或提示用户手动切换）
 ```

package/commands/alloy/finish.md

@@ -1,6 +1,6 @@
 ---
 name: "Alloy: Finish"
-description: Alloy 收尾——archive 完成后，合入代码并清理现场
+description: Alloy 收尾阶段 - archive 完成后进入
 category: Workflow
 tags: [alloy, workflow]
 ---
@@ -9,42 +9,53 @@ tags: [alloy, workflow]
 
 你是 Alloy 的收尾命令。你的职责是：在 spec 已归档（phase=archived）的前提下，完成代码合入与现场清理，将 phase 推进到 `finished`。
 
-**finish 只做代码层面的收尾，不涉及 spec 变更。** 如果合入过程中（如 PR 审查）发现需要修改 spec，那是另一个 change 的事——当前 change 的 spec 已归档封存。
+**核心原则：只做代码合入，不碰 spec。** 如果合入过程中（如 PR 审查）发现需要修改 spec，那是另一个 change 的事——当前 change 的 spec 已归档封存。
+
+**交互风格：** 主分支确认、合并策略选择使用 `AskUserQuestion` 工具。**合并确认仍用精确文本匹配**（安全机制）。详见 `commands/alloy/references/interaction-style.md`。
+
+**调用外部命令或技能前，先输出标题和状态描述，再执行操作。不要只出标题然后沉默。**
+
+**捕获阶段启动时间**（命令调用后第一时间，前置检查之前，幂等——重入时返回已有值）：
+```bash
+PHASE_START=$(alloy _state timestamp ensure openspec/changes/<name> finish)
+```
+
+---
 
 **什么算"finish 使用不当"（反例）：**
 - phase 不是 archived 时调 finish——"反正就合个代码"——跳过了 archive，spec 没有同步
 - 分支已 merge 或删除后重复调 finish——浪费操作，应该直接告知用户无需再次 finish
 - finish 过程中试图修改 spec——spec 已归档，任何 spec 级变更应走新 change
 
+### Red Flags——STOP，不要继续
+
+以下任何一个念头出现，都意味着闸门正在被绕过：
+
+| 借口 | 现实 |
+|------|------|
+| "phase 不是 archived，但代码都已经写好了，直接合吧" | archive 不可跳过——spec 归档和代码合入是两件事。先归档再合入，顺序不可颠倒。 |
+| "分支已经删了，finish 白跑了" | finish 前置检查的第一步就是确认分支存在。分支不存在 = 无需再次 finish，直接告知用户。 |
+| "PR 审查说要改 spec，我在 finish 里顺手改了吧" | spec 已归档封存。任何 spec 级变更 = 新 change。当前 change 的 finish 不涉及 spec 修改。 |
+| "选'保持分支'就等于没做完，太麻烦了，直接 merge 吧" | 保持分支是合法选项——用户可能有后续计划。替用户选 merge 是越权。 |
+| "merge 确认太啰嗦了，用户说'好'就是同意了" | merge 确认必须精确文本匹配。`merge <branch> into <branch>` 是安全机制——防止手滑合入。 |
+
 ---
 
 ## 前置检查
 
-**记录阶段开始时间：**
-```bash
-COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
-TIMINGS=$(alloy _state read openspec/changes/<name> phase_timings 2>/dev/null || echo "{}")
-echo "$TIMINGS" | python3 -c "
-import sys,json
-content = sys.stdin.read()
-d = json.loads(content) if content.strip() else {}
-p = d.setdefault('finish',{})
-if 'started_at' not in p:
-    p['started_at']='$COMPLETED_AT'
-print(json.dumps(d))
-" | while read -r val; do alloy _state write openspec/changes/<name> phase_timings "$val"; done
-```
-
 ```
 ┌──────────────────────────────────────┐
 │ Alloy [5/5] · Phase: Finish          │
-│ 启动时间: 从 phase_timings.finish.started_at 读取
+│ 启动时间: $PHASE_START
 └──────────────────────────────────────┘
 ```
 
 ### [Step 1/3] 前置检查
 
-**0. Skill 预检：** 确认 `superpowers:finishing-a-development-branch` 技能可用。若不可用 → 引导 `alloy init` → STOP。
+**0. Skill 预检：** 确认以下依赖可用：
+   skill: finishing-a-development-branch
+
+   读取 `commands/alloy/references/skill-precheck.md` 了解检测方法。任一不可用 → 引导 `alloy init` → STOP。
 
 > phase 是否为 archived？ <检查结果>
 
@@ -55,25 +66,24 @@ print(json.dumps(d))
 alloy _guard openspec/changes/<name> finished
 ```
 
-若 guard 报错（phase 不匹配），读取当前 phase，按以下规则自动路由：
-
-| 当前 phase | 行为 |
-|-----------|------|
-| started | "尚未 plan，自动进入 /alloy:plan" → 加载 alloy-plan 指令 |
-| planned | "尚未 apply，自动进入 /alloy:apply" → 加载 alloy-apply 指令 |
-| applied | "尚未归档，自动进入 /alloy:archive" → 加载 alloy-archive 指令 |
-| archived | precheck 通过，继续收尾 |
-| finished | "工作流已完成" → STOP |
-
-**实现方式：** 输出对应命令文件的完整指令，将 change name 和当前进度信息作为上下文传入。
+若 guard 报错（phase 不匹配），读取 `commands/alloy/references/phase-routing.md` 按路由表自动跳转。当前 phase=archived 时 precheck 通过。
 
 **HARD STOP 保留场景：** 分支不存在（可能已 merge 或删除）→ 提示无需再次 finish。
 
 确认当前有对应的 git 分支存在：
 ```bash
-git branch --list <change-name>
+git branch --list <feature_branch>
+```
+分支不存在 → "分支 <feature_branch> 不存在，可能已 merge 或删除。无需再次 finish。"
+
+读取主分支作为默认合并目标：
+```bash
+alloy _config read . main_branch
+```
+若 `main_branch` 未记录（输出 `null`）→ 读取 `commands/alloy/references/main-branch-detection.md`，按 3 级优先级自动检测主分支。检测到后让用户确认（Y/n），确认后写入配置：
+```bash
+alloy _config write . main_branch <确认的主分支名>
 ```
-分支不存在 → "分支 <change-name> 不存在，可能已 merge 或删除。无需再次 finish。"
 
 ---
 
@@ -94,15 +104,20 @@ git branch --list <change-name>
 ```
 Change: <name>
 状态：phase=archived（spec 已归档，代码待合入）
-当前分支：<change-name>
-基础分支：<apply 阶段用户选择的分支>（merge 回合目标）
+当前分支：<feature_branch>
+基础分支：<main_branch>（从 openspec/config.yaml 读取）
+```
+
+**技能加载后立即记录：**
+```bash
+alloy _skill log openspec/changes/<name> finish superpowers:finishing-a-development-branch
 ```
 
 技能加载后，按其指引提供 3 个选项。
 
 ### 各选项的后续行为
 
-**选项 1：本地 merge**
+**选项 1：本地合并（squash）**
 
 在执行 merge 之前，必须展示确认信息并等待用户确认：
 
@@ -111,42 +126,64 @@ Change: <name>
 >
 > 即将执行本地合并：
 >
-> | | |
-> |---|---|
-> | 源分支 | <change-name> |
-> | 目标分支 | <base-branch> |
+> 源分支：<feature_branch>
+> 目标分支：<main_branch>
 >
 > 即将合入的提交：
 > ```
-> <git log base-branch..change-name --oneline 的输出>
+> <git log main_branch..feature_branch --oneline 的输出>
 > ```
 >
 > 合并后 worktree 将被清理，分支将被删除。
 >
-> 输入 merge <change-name> into <base-branch> 确认，或输入其他内容取消。
+> 输入 merge <feature_branch> into <main_branch> 确认，或输入其他内容取消。
 
 **必须等待用户精确输入确认语句。** "好"、"可以"、"y" 都不算确认。
 
-用户确认后执行 merge：
+用户确认后，记录完成时间、推进 phase，再 squash 合并：
 ```bash
-git checkout <base-branch>
+# 确定归档路径（archive 阶段已将目录移至 archive/ 下）
+ARCHIVE_DIR=$(ls -d openspec/changes/archive/*-<name> 2>/dev/null | sort -r | head -1)
+CHANGE_DIR="${ARCHIVE_DIR:-openspec/changes/<name>}"
+
+# 记录完成时间 + 推进 phase 到 finished（所有状态变更在 squash merge 之前完成）
+COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+alloy _state merge "$CHANGE_DIR" phase_timings "{\"finish\":{\"completed_at\":\"${COMPLETED_AT:-$(date '+%Y-%m-%d %H:%M:%S')}\"}}"
+alloy _guard "$CHANGE_DIR" finished --apply
+git add -A "$CHANGE_DIR" openspec/config.yaml
+git commit -m "chore(<name>): 记录 finish 阶段完成时间"
+
+git checkout <main_branch>
 git pull || echo "⚠️ git pull 失败（网络问题或冲突），请手动处理后再继续"
-git merge <change-name>
+git merge --squash <feature_branch>
+# 抓取被合入分支的完整 commit 列表，生成类似 GitHub squash merge 的 commit message
+COMMIT_LOG=$(git log <main_branch>..<feature_branch> --format="* %s")
+git commit -m "$(cat <<EOF
+chore(<name>): 合入 main（squash merge）
+
+${COMMIT_LOG}
+EOF
+)"
+# squash merge 不产生 merge commit，git 无法识别分支已合入，使用 -D 强删
+git branch -D <feature_branch>
 ```
 
-若 `git pull` 失败（网络不可达、认证失败），输出警告并暂停，让用户决定是否跳过 pull 直接 merge。若 `git merge` 冲突，输出冲突文件列表，让用户手动解决后继续。
-```bash
-alloy _guard openspec/changes/<name> finished --apply
-```
+若 `git pull` 失败（网络不可达、认证失败），输出警告并暂停，让用户决定是否跳过 pull 直接 merge。若 `git merge --squash` 冲突，输出冲突文件列表，让用户手动解决后继续。
 
-提示："代码已合入 <base-branch>。Alloy 工作流完成。"
+提示："代码已合入 <main_branch>。Alloy 工作流完成。"
 
 **选项 2：创建 PR**
-- PR 创建后，更新 phase：
+- 先记录完成时间并推进 phase，作为分支上最后一个提交（PR squash merge 后主分支仅 1 个 commit）：
   ```bash
-  alloy _guard openspec/changes/<name> finished --apply
+  ARCHIVE_DIR=$(ls -d openspec/changes/archive/*-<name> 2>/dev/null | sort -r | head -1)
+  CHANGE_DIR="${ARCHIVE_DIR:-openspec/changes/<name>}"
+  COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+  alloy _state merge "$CHANGE_DIR" phase_timings "{\"finish\":{\"completed_at\":\"${COMPLETED_AT:-$(date '+%Y-%m-%d %H:%M:%S')}\"}}"
+  alloy _guard "$CHANGE_DIR" finished --apply
+  git add -A "$CHANGE_DIR" openspec/config.yaml
+  git commit -m "chore(<name>): 记录 finish 阶段完成时间"
   ```
-- 提示："PR 已创建。审查通过后合并，Alloy 工作流即完成。"
+- 提示："PR 已创建。审查通过后 squash merge 即可完成。"
 - 当用户收到 PR 审查反馈并在对话中讨论时，遵循以下行为规范（来自 superpowers:receiving-code-review）：
   - **验证优先** —— 不要盲从审查意见。先验证 reviewer 指出的问题是否真实存在，再决定是否修改
   - **技术推理** —— 如果你的实现有技术理由，解释原因而不是被动接受。reviewer 可能缺少上下文
@@ -162,22 +199,7 @@ alloy _guard openspec/changes/<name> finished --apply
 
 ### [Step 3/3] 完成
 
-**记录阶段完成时间：**
-```bash
-COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
-TIMINGS=$(alloy _state read openspec/changes/<name> phase_timings 2>/dev/null || echo "{}")
-echo "$TIMINGS" | python3 -c "
-import sys,json
-content = sys.stdin.read()
-d = json.loads(content) if content.strip() else {}
-p = d.setdefault('finish',{})
-if 'completed_at' not in p:
-    p['completed_at']='$COMPLETED_AT'
-print(json.dumps(d))
-" | while read -r val; do alloy _state write openspec/changes/<name> phase_timings "$val"; done
-git add openspec/changes/<name>/
-git commit -m "chore(<name>): 记录 finish 阶段完成时间"
-```
+完成时间已在 Step 2 的记录 commit 中写入。finish 阶段不产生额外 commit——合入 commit（选项 1）或 PR（选项 2）本身就是终端动作。
 
 ```
 ┌──────────────────────────────────────┐
@@ -196,8 +218,8 @@ git commit -m "chore(<name>): 记录 finish 阶段完成时间"
 
 ## 闸门规则
 
-- **git add 只用精确路径** — 永远不用 `-A`、`-a`、`.`。
-  finish 阶段不主动 add 代码文件，只由外部技能处理合入
+- **git add 只用精确路径** — 永远不用 `-a`、`.`。
+  finish 阶段用 `git add -A "$CHANGE_DIR" openspec/config.yaml`（`$CHANGE_DIR` 为当前 change 的归档路径，`-A` 限路径，只追踪 change 目录和 openspec 配置的新增/修改/删除），代码合入由 git merge 处理
 - **phase 必须为 archived** —— spec 已归档的 change 才能 finish
 - **分支必须存在** —— 分支已 merge 或删除时无需再次 finish
 - **不涉及 spec 变更** —— spec 已归档封存，任何 spec 级修改应走新 change