@accelerator-mzq/forge 1.4.0

package/dist/core/templates/commands/archive.md

@@ -0,0 +1,178 @@
+---
+description: 调 forge archive CLI 把 change 移到 archive/、内部 sync specs/、严格校验 verify+review 标记
+argument-hint: '<change-id> [--force] [--recover]'
+---
+
+You are about to handle `/forge:archive $ARGUMENTS`.
+
+## 步骤
+
+本命令是 CLI 的薄包装。直接执行:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" archive $ARGUMENTS
+```
+
+(plugin helper 内部 spawn npx 拉 forge CLI,避开 v0.2 P1 全局 PATH 问题。OpenCode/Codex 路径下 commands.md 不可用,走 skill 内嵌路径 — 见 Plan 3 Task 3.3 + skills/finishing-a-development-branch/SKILL.md。)
+
+## v1.0 三级分级行为(plan-9e1 落地)
+
+archive 阶段在 verify+review marker 严格校验之外,再叠加"三级业务行为"裁决(沿 design §2.4.2):
+
+| 状态                                                             | archive 行为                                                 |
+| ---------------------------------------------------------------- | ------------------------------------------------------------ |
+| 全 resolved=true                                                 | 通过                                                         |
+| CRITICAL resolved=false                                          | **拒签**(无 ack 出口,exit 1)                                 |
+| WARNING resolved=false + `severity_acked_by` 非空 + ack-log 匹配 | 通过(标 acked-warning archive,handoff 列入 `acked_warnings`) |
+| WARNING resolved=false + `severity_acked_by` 空                  | **拒签**(exit 1)                                             |
+| SUGGESTION resolved=false(无论 ack 与否)                         | **通过**(标 pending-suggestion archive,handoff to backlog)   |
+
+**强 fence 优势保留**:CRITICAL 永远拒签,无 `--force` 出口(`--force` 仍只覆盖 v0.4 那两类降级 — human-override / 非 git;不扩展到 CRITICAL,沿 design §2.4.6)。
+
+`review_outcomes` 端简码 S/C/L 迁移规则(v4 BLOCKER 1 + MAJOR 1 修订,沿 design §2.3.5 line 553-563):
+
+| v0.4 简码          | v1.0 映射             | archive 行为                                                                                                    |
+| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `S`(critical)      | `CRITICAL` 直接映射   | `S + resolved=false` 拒签;`S + resolved=true` 通过                                                              |
+| `L`(low)           | `SUGGESTION` 直接映射 | `L + resolved=false` 通过(进 pending_suggestions);`L + resolved=true` 通过                                      |
+| `C`(clarification) | **不自动映射**        | **任何状态**(resolved/accepted/rationale)**全拒签**;必须等 plan-9j 完成跑 `forge upgrade --resign-markers` 迁移 |
+
+**重要**:`review_outcomes` 端不存在"`accepted=true + rationale 非空` 等价 ack"路径(v2 文档错误,v4 MAJOR 1 修订删除)— ReviewOutcome 接口本身无 `severity_acked_by` 字段;WARNING ack 必须经 verify_findings 端 CLI ack-log 协议(沿 design §2.3.3)。
+
+## archive_summary 输出(plan-9e1 落地)
+
+archive 成功后,**新增产物**:`forge/changes/archive/YYYY-MM-DD-<id>/archive_summary.yaml`(给 v1.1 backlog index 入参)。
+
+完整 schema 见 [`src/core/schemas/archive-summary.ts`](../src/core/schemas/archive-summary.ts);9 顶级字段:
+
+- `schema` literal `forge-archive-summary/v1`
+- `version` semver
+- `archived_at` ISO 8601 UTC
+- `change_id` 字符串
+- `verify_passed` / `review_passed` 摘要
+- `process_evidence_summary`(9e1 placeholder → 9e2 真实统计,沿 plan-9g 14 不变量):
+  - `placeholder: false`
+  - `invariants_passed: number`(经 mapper 优先级筛选后仍为 status='pass' 的 invariant 数)
+  - `invariants_with_warning: number`(WARNING 经 fail/legacy-skip 优先级筛选后仍保留为 status='warning' 的数;legacy 路径下被豁免 invariant 的 WARNING 不计入,沿 master §3.4.4.1 精度损失)
+  - `invariants_failed: number`(v1.0 永远 = 0;fence.ok=false 时 archive 直接 exit 1,summary 不写入)
+  - `legacy_exempt: number`(`process_evidence_unavailable_legacy: true` 路径下被豁免的 invariant 数;legacy 路径恒 = 10,非 legacy 恒 = 0;flag 取自 verify || review 任一为 true)
+  - 不变式:`invariants_passed + invariants_with_warning + invariants_failed + legacy_exempt === 14`(沿 plan-9g FENCE_INVARIANT_NAMES.length)
+- `handoff_to_backlog` 三类聚合(SUGGESTION 持挂 + pause_decisions chosen_option=3 + scope-entries active)
+- `acked_warnings`(WARNING + ack 的引用,给用户回顾)
+- `pending_suggestions`(SUGGESTION + resolved=false 引用,handoff 子集)
+
+archive 成功后 stdout 渲染段(沿 design §2.4.4 模板):
+
+```
+## Archive Complete
+
+**Change:** <change-id>
+**Archived to:** forge/changes/archive/<archive-id>/
+**Specs:** ✓ Synced
+**Security:** [process_evidence:passed=3/warning=1/failed=0/legacy=10]
+
+### Acknowledged Warnings (N)
+- [WARNING] verify_findings#<id> (<dimension>/<check_type>)
+  Evidence: ...
+  Acked by: <user> at <iso>
+  Rationale: ...
+
+### Pending Suggestions (M) — recorded in archive_summary
+- [SUGGESTION] verify_findings#<id> (<dimension>/<check_type>)
+  Source: ...
+  Recommendation: ...
+
+Review handoff details: cat forge/changes/archive/<archive-id>/archive_summary.yaml
+Cross-change backlog: run `forge backlog list` (see forge/backlog/)
+```
+
+## --resume-summary 用法(plan-9e1 落地,罕见状态)
+
+设计语义:archive 流程"Move 完成 + 在 archive 目录把 `.tmp` rename 为正式名时失败"是极罕见状态(同目录 rename 几乎不会失败)。若发生:
+
+```bash
+forge archive --resume-summary 2026-05-12-add-x
+```
+
+行为:
+
+- archive 目录有 `.tmp` 无正式 `.yaml` → rename(exit 0)
+- 两者都存在(冲突,无法判断 ground truth)→ 拒签 exit 1(用户手动检查后删一个再重跑)
+- 两者都不存在 → 报错 exit 1(状态损坏 / 该 archive 从未生成 summary)
+
+`forge validate <change-id>` 会扫描 active change 目录是否残留孤立 `archive_summary.tmp.yaml`,残留时给 WARNING 提示走 `--resume-summary` 或手动 `rm`。
+
+## CLI 行为说明(给 AI 理解,不要重复实现)
+
+1. **加进程锁** `forge/.cache/archive.lock`(防止并发)
+2. **校验 verify-passed + review-passed 标记存在且合法**:
+   - YAML 解析成功 + `schema` 字段值 = `forge-verify/v1` 或 `forge-review/v1`
+   - 重算 `tasks_hash` / `content_hash` 必须等于 marker 字段值
+   - 重算 git.head + git.diff_hash 必须等于(`is_git_repo: true` 时)
+   - `verified_by`/`reviewed_by` 取值 ∈ `{ai-agent, human-override}`
+3. **`--force` 接受这两类降级**:
+   - `verified_by`/`reviewed_by` = `human-override`
+   - `is_git_repo: false`(非 git 项目)跳过 git 字段
+4. **`--force` 不覆盖**(任一不一致 archive 拒绝):
+   - tasks_hash/content_hash 不一致(标记过期或被篡改)
+   - evidence log 文件缺失 / log_hash 不匹配 / pass ≠ true
+   - review_outcomes 中 accepted=true 但 resolved=false
+   - **CRITICAL finding 未 resolve**(三级 fence 强不变量,无 ack 出口;沿 plan-9e1 §三级行为表)
+   - **WARNING finding 未 resolve 且缺 ack**(用户必须显式 ack `severity_acked_by`)
+5. **archive 顺序原子化**(沿 design §2.4.5 + spec §3.5):
+   - Move 前先写 `archive_summary.tmp.yaml` 到 source 目录
+   - Move(rename change → archive)
+   - rename `.tmp` → 正式 `archive_summary.yaml`
+   - Backup specs/
+   - Sync specs/
+   - 任一阶段失败按 §2.4.5 表回滚
+6. **`--recover` 子模式**:扫描半归档状态(case A/B/C)并修复(沿 v0.4)
+7. **`--resume-summary <archive-id>` 子模式**(plan-9e1):处理 archive 目录半完成 `.tmp` rename(rename ok / 双份冲突拒签 / 状态损坏报错)
+
+## 禁止行为
+
+- 不允许手工实现 Move/Sync/Rollback 原子化步骤(那是 CLI 内部实现;AI 只调 CLI,不重现 CLI 行为)
+- 不允许在 archive 失败时绕过 verify+review 标记直接 mv 文件
+- 不允许在 `--force` 不被允许的场景(如 hash 不匹配)主动加 `--force` 试图绕过
+
+## AI 后续行为
+
+archive 成功后,**调用 `forge:finishing-a-development-branch` skill** 提示用户做 git 层面的合并/PR/清理决策。
+
+## 与其他 sub-plan 合并点(参考 master plan §3.5)
+
+本文件由多个 sub-plan 共同维护:
+
+- **9e1**(本文件落地):三级分级行为表 + archive_summary 输出格式 + --resume-summary 用法
+- **9e2(已完成,plan-9e2)**:`process_evidence_summary` 字段从 placeholder 接 plan-9g 实施的 14 不变量真实统计(4 字段计数:passed / with_warning / failed / legacy_exempt;sum 不变式 = 14)
+- **9g**(process_evidence):在"archive 顺序原子化"步骤中加入 worktree 重跑 + 结构化 reporter parsing(注:9g 实施时 **不动** 9e1 的 .tmp / rename / 三级 fence 步骤,只在 verify markers 阶段之前插入 worktree 阶段)
+
+merge 顺序推荐:**9e1 → 9g → 9e2(已完成全链)** — 14 不变量真实统计已接入,placeholder 路径仅 plan-9e1 backward-compat 兼容保留
+
+## C 简码迁移协议(plan-9e1 v4 BLOCKER 1 落地 + plan-9j v2 解锁)
+
+`review_outcomes[i].severity = 'C'`(v0.4 clarification 简码)在 v1.0 三级体系中**不直接对应**;archive 阶段会**硬拒签**。
+
+**plan-9j 落地完成后**:用户工作流解锁路径:
+
+1. 跑 `forge upgrade --resign-markers <change-id>` — 若含 C 简码,exit 1 + 写 pending file
+2. 跑 `forge ack confirm <change-id> <findingId> --target-severity <WARNING|SUGGESTION>` — user 判定目标 severity
+3. 重跑 `forge upgrade --resign-markers <change-id>` — confirm 后 marker `severity` 字段改回全名,archive 通过
+
+**plan-9j 未完成时**(本 plan 实施期间):archive 含 C 简码 marker 仍是阻塞性硬墙(无 manual edit 出口,沿 v4 BLOCKER 1 三道墙)。
+
+## exit code 遗留声明(plan-9e1 v3 MAJOR 1 / v5 MINOR 3 修订:口径统一)
+
+`forge archive` 各路径 LockHeldError 的 exit code:
+
+| 路径                                                         | exit code | 说明                                                                                                                                                                                                               |
+| ------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `forge archive <id>`(主路径)                                 | 5         | v0.4 遗留 — **master §3.12.3 将由 plan-9e1 Task 6 Step 4-pre 加 known limitation 注脚**(实施时落地;plan v7 阶段 master 仍是 freeze 表无注脚);由后续 sub-plan(候选:9z release / 单独 cleanup plan)统一全路径 exit 2 |
+| `forge archive --recover`                                    | 5         | 同上 v0.4 遗留                                                                                                                                                                                                     |
+| `forge archive --resume-summary <archive-id>`(plan-9e1 新增) | **2**     | 对齐 master §3.12.3 freeze                                                                                                                                                                                         |
+
+**v5 口径统一(v10 措辞收干)**:不再说 "9e1 不修留 GH issue 跟进"(原 v3 措辞);改为 reflection **将由 Task 6 Step 4-pre 实施时落到** master plan(沿 v5 选项 C 修订;**实施 plan 阶段** master 仍是 freeze 表无注脚,Task 6 Step 4-pre 实施完成后 master 加 known limitation 注脚)。后续 sub-plan(9z release / cleanup plan)接 master notation 统一全路径 exit 2。
+
+## backlog 产物(plan-backlog-registry)
+
+archive 成功后,CLI 自动重生成项目级 backlog 注册表 `forge/backlog/{active.md,archived.md}`(跨所有 archived change 聚合未决 scope-entry;首次生成时附带 `README.md`)。backlog 生成失败**不回滚 archive**(archive 主流程已成功,backlog 是衍生产物),仅 stderr WARNING + 提示手动跑 `forge backlog`。详见 `forge backlog` 子命令(`forge backlog` 重生成 / `forge backlog list` 查询 / `forge backlog --check` CI staleness 守门)。

package/dist/core/templates/commands/brainstorm.md

@@ -0,0 +1,58 @@
+---
+description: 把模糊想法转化为 forge/drafts/ 下的结构化 draft,通过强制提问 + 设计探讨完成
+argument-hint: '<topic>'
+---
+
+You are about to handle a `/forge:brainstorm <topic>` invocation. The user typed:
+
+```
+/forge:brainstorm $ARGUMENTS
+```
+
+Follow these steps strictly. Do NOT skip any:
+
+1. **必须先调用 `forge:brainstorming` skill**(用 Skill 工具,skill 名 `forge:brainstorming`)。该 skill 强制提问 / 不允许直接给方案 / 不允许写代码。
+2. 完成 skill 内的全部 checklist(包括"探索项目上下文"、"逐个澄清问题"、"提 2-3 方案"、"分段呈现 design")。
+3. 确认 design 通过用户审阅后,把 draft **保存到 `forge/drafts/<YYYY-MM-DD>-<topic>.md`**(date 用今天,topic 来自用户参数,小写连字符化)。
+4. 若 `forge/drafts/` 目录不存在,先 `mkdir -p forge/drafts/`。
+5. 写完后,提示用户:"draft 保存到 `forge/drafts/<file>`,确认要推进就跑 `/forge:propose <change-id> --from-draft <date>-<topic>`"。
+
+## 禁止行为
+
+- 不允许直接产出 `forge/changes/<id>/` 任何文件(那是 `/forge:propose` 的工作)
+- 不允许跳过 `forge:brainstorming` skill 的提问环节,即使用户表示"我已经想清楚了"
+- 不允许在 `forge/specs/` 里写任何东西(specs/ 仅由 archive 内部 sync 写入)
+
+## (可选)Stage extensions hook — Tier 1 Claude Code only
+
+> codex review 集成。AI 主代理在本 stage(`brainstorming`)跑多轮收敛协议。
+> Tier 2/3(Codex/OpenCode)见 [`docs/stage-extensions.md §未来 Tier 2/3 集成`](../docs/stage-extensions.md#未来-tier-23-集成)。
+
+**Step A — 检查是否启用**:读 `forge/config.yaml#stage_extensions.brainstorming`。无该字段 / 数组为空 / 全部 entry `enabled: false` → **跳过本段,流程结束**。
+
+**Step B — 对每个 `enabled` entry 跑多轮收敛 loop**:
+
+初始化 `round = 1`、`threadId = ''`、`roundHistory = []`、`roundLimit = null`(F1-v8 fix:`roundLimit` **不从 config 文件读** —— effective convergence 由 runner 输出,见 Step 3。AI 协议不碰 config 文件解析 / deep-merge,单一数据源是 runner JSON)。循环:
+
+1. **跑单轮 runner**:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" stage-extensions run \
+     --stage brainstorming --change-id <change-id> --extension <entry-name> \
+     --round <round>${threadId:+ --thread-id $threadId}
+   ```
+2. **解析 stdout JSON 的 `kind`**:
+   - `converged` → 该 entry 收敛完成,**break loop**(codex 输出 verbatim 透传给用户)
+   - `failed` / `config_error` / `no_extension` → 该 entry 放弃,**break loop**(loose,不阻塞主流程)
+   - `unconverged` → 继续 3
+3. **从 unconverged JSON 取状态**(F1-v8 fix:effective config 来自 runner 输出,runner 内 `validateStageExtensionsConfig` 已 normalize):
+   - `roundHistory.push({ round, block_count: <blockFindings.length> })`;`threadId = <JSON.threadId>`;codex finding verbatim 透传给用户
+   - 首轮:`roundLimit = <JSON.effectiveConvergence.max_rounds>`(后续轮 `roundLimit` 已设,不覆盖 —— 选项①的 `roundLimit += N` 增量须保留)
+4. **若 `round >= roundLimit`**(F2-v7 fix:用可增长的 `roundLimit`):
+   - 若 `<JSON.effectiveConvergence.max_rounds_on_exceed>` 为 `force_end` → 把 blockFindings 写 `forge/changes/<id>/.evidence/codex-pending-findings.yaml`(backlog),**break loop**
+   - 否则跑 `node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" stage-extensions analyze-trend --history '<roundHistory JSON>'` 拿 TrendAdvice,再 `AskUserQuestion` 三选项(默认推 `TrendAdvice.recommended_option`):**①再跑 N 轮**(F2-v7 fix:读用户输入的 `N`,执行 `roundLimit += N`,然后 `round++` 继续 loop —— 后续 `round >= roundLimit` 判定按新上限走,不会立刻又进 Step 4)/ **②放弃 codex**(break loop)/ **③接受当前**(blockFindings 写 backlog,break loop)
+5. **否则(`round < roundLimit`)**:`AskUserQuestion` 三选项(默认推 `<JSON.userInteraction.block_unconverged>`):
+   - **①auto_fix** → 用 `Task` 工具 dispatch fresh fix subagent 修 blockFindings → `round++`,继续 loop
+   - **②manual_fix** → 等用户改完 → `round++`,继续 loop
+   - **③give_up** → break loop
+
+**Step C — loose**:本段任何步骤(runner 调用 / AskUserQuestion / fix dispatch)失败都**不阻塞主流程 fence**。runner 永远 exit 0;AskUserQuestion harness 不支持时降级终端 prompt。

package/dist/core/templates/commands/codex-adversarial.md

@@ -0,0 +1,95 @@
+---
+description: Run codex adversarial review on focus artifact (forge B-full wrapper - AI-invokable; bypasses /codex:adversarial-review disable-model-invocation lock)
+argument-hint: '[focus text or file path]'
+allowed-tools: Read, Bash(codex:*), Bash(node:*), Bash(git:*), Bash(mkdir:*), AskUserQuestion
+---
+
+You are about to handle `/forge:codex-adversarial $ARGUMENTS`.
+
+## What this command does
+
+Run a Codex adversarial review against the user-specified focus. Unlike `/codex:adversarial-review`
+(which has `disable-model-invocation: true` blocking AI auto-invoke), this forge wrapper IS
+invokable by AI agents — enabling automated codex review in forge workflows.
+
+**Wrapper status**:**临时(B-full)**。`plan-stage-extensions-framework` 实施完成后,完整
+runner (`forge stage-extensions run --stage <s>`) 会替换本 wrapper(沿 plan §3-§7)。
+
+## Step-by-step protocol
+
+### Step 1: 解析 $ARGUMENTS
+
+$ARGUMENTS 是用户给的 focus 文本或文件路径。例如:
+
+- `/forge:codex-adversarial review plan v1 in docs/plans/2026-05-15-plan-stage-extensions-framework.md`
+- `/forge:codex-adversarial`(空 — 默认 review 当前 branch)
+
+如果 $ARGUMENTS 包含一个 .md / .ts / .yaml 文件路径,这是 focus artifact;
+否则整个 $ARGUMENTS 作为 user focus 文本。
+
+### Step 2: 构造 prompt 文件
+
+跑 helper build-prompt 子命令:
+
+```bash
+PROMPT_FILE=$(mktemp -t forge-codex-adv-XXXXXX.md)
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-review-helper.mjs" build-prompt \
+  --template "${CLAUDE_PLUGIN_ROOT}/src/core/codex-review/prompts/adversarial-default.md" \
+  --output "$PROMPT_FILE" \
+  --user-focus "$ARGUMENTS" \
+  --target-label "$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'current state')"
+```
+
+### Step 3: 准备 output log 路径
+
+```bash
+LOG_DIR="${PWD}/.forge-codex-logs"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/codex-adversarial-$(date +%s).log"
+```
+
+### Step 4: 跑 codex(通过 helper)
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-review-helper.mjs" run \
+  --prompt-file "$PROMPT_FILE" \
+  --output-log "$LOG_FILE"
+```
+
+主代理需要把 codex 的 stdout **verbatim** 透传到会话(沿 codex 协议要求:
+"Return Codex's output verbatim. Do not paraphrase, summarize, or add commentary
+before or after it.")。
+
+### Step 5: 清理 + 报告
+
+```bash
+rm -f "$PROMPT_FILE"
+```
+
+告诉用户:
+
+- codex finding 已 verbatim 透传(上面)
+- log 文件位置 `$LOG_FILE`(用户可后续查)
+
+## 错误处理
+
+- codex CLI 未装(`codex --version` 失败)→ helper 报错 + 提示用户跑 `codex login` / 装 codex
+- prompt build 失败 → 检查 template 路径
+- codex exit !=0 → 错误透传给用户,**不**自动 retry(B-full 不实现 retry / 多轮 / 僵尸检测 —
+  这些是完整 framework 的事)
+
+## 禁止行为
+
+- ✗ 不允许 paraphrase / summarize codex 输出(沿 codex verbatim 协议)
+- ✗ 不允许自动修复 codex 找到的问题(本命令只跑 review,不动代码)
+- ✗ 不允许跳过 prompt 文件直接 inline prompt(B-full 接口约束)
+
+## 已知限制(B-full)
+
+- 单轮 review,无多轮收敛(完整 framework 加)
+- 同步阻塞(无 `--background`)— codex 跑完才返回
+- 无僵尸检测(codex 卡住 → 用户 Ctrl+C)
+- 无 `--resume` thread 复用(每次跑都新 thread)
+- 单一模板 `adversarial-default.md`(完整 framework 加 stage-specific 模板)
+
+完整能力见 plan `docs/plans/2026-05-15-plan-stage-extensions-framework.md` §3-§7。

package/dist/core/templates/commands/explore.md

@@ -0,0 +1,29 @@
+---
+description: 主动触发非线性思考空间 — 鼓励 ASCII diagram / 选项对比 / 反思 assumption;探索完必须显式收尾 + capture offer 含具体 forge 路径(沿 design §2.5)
+argument-hint: '[<topic> | --change <id>]'
+---
+
+You are about to handle a `/forge:explore [<topic> | --change <id>]` invocation. The user typed:
+
+```
+/forge:explore $ARGUMENTS
+```
+
+Follow these steps strictly. Do NOT skip any:
+
+1. **必须先调用 `forge:exploring` skill**(用 Skill 工具,skill 名 `forge:exploring`)。该 skill 强制显式收尾 + 可执行 capture offer + 禁止 explore 阶段直接写 artifacts(沿 design §2.5.6 反向加固三条)。
+2. **解析参数**:
+   - 无参数:开放探索,不绑定具体 change。
+   - `--change <id>`:绑定本 change,**读** `forge/changes/<id>/{proposal,design,tasks,specs/*}.md` 作上下文。
+   - `<topic>`(自由文本,非 `--` 开头):用户给的探索主题。
+   - 在 `/forge:apply` subagent 实施中、检测到唯一未归档 change 时,允许省略 `--change`(沿 v0.4 推断模式)。
+3. 完成 skill 内全部协议步骤(读上下文 → 探索阶段 → `## Exploration Summary` 显式收尾 → Capture offer 给具体 `file:section`)。
+4. **若 Capture offer 被用户明确确认**(明确"yes / 改吧 / capture 吧"),才走对应 capture decisions 表的落地位置(如 `design.md` / `proposal.md` / `tasks.md` / `forge/drafts/`);Write / Edit 前再次反确认具体段落改动。
+
+## 禁止行为
+
+- 不允许 explore turn 内直接 Write / Edit 修改 `forge/changes/*` artifacts(沿 design §2.5.6 反向加固第三条 + OpenSpec `explore.ts:132` "Don't auto-capture")— 读 Read 允许,写必须经 Capture offer + 用户明确确认两步
+- 不允许"探索完成无结论"— skill 末尾必须显式输出 `## Exploration Summary` 段(沿 §2.5.6 反向加固第一条)
+- 不允许 vague capture offer(如"也许更新 design")— 必须 `file:section` 具体(沿 §2.5.6 反向加固第二条)
+- 不允许触发对 archived change artifacts 的修改 — archived 冻结,引导起新 change supersede(沿 v0.4 archive 不变量 + design §2.5.5 桥接)
+- 不允许在用户已明示"我自己决定"的情况下直接替用户选(沿 OpenSpec `explore.ts:132` "The user decides — Offer and move on")

package/dist/core/templates/commands/index.d.ts

@@ -0,0 +1,12 @@
+/** 7 个 slash 命令名(spec §2.2 6 命令表 + plan-9f explore;实际 slash 名为 /forge:<name>) */
+export declare const COMMAND_NAMES: readonly ["brainstorm", "propose", "apply", "review", "verify", "archive", "explore"];
+export type CommandName = (typeof COMMAND_NAMES)[number];
+/** 单 command 内容加载 — 用 import.meta.url 定位,开发与生产路径自适应 */
+export declare function loadCommand(name: CommandName): Promise<string>;
+export interface LoadedCommand {
+    name: CommandName;
+    content: string;
+}
+/** 全量加载 7 个 slash 命令,失败抛错(说明某个 .md 漏建) */
+export declare function loadAllCommands(): Promise<LoadedCommand[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/templates/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/commands/index.ts"],"names":[],"mappings":"AAUA,iFAAiF;AACjF,eAAO,MAAM,aAAa,uFAQhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,uDAAuD;AACvD,wBAAsB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAEpE;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0CAA0C;AAC1C,wBAAsB,eAAe,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAIhE"}

package/dist/core/templates/commands/index.js

@@ -0,0 +1,26 @@
+// 7 个 slash 命令模板的 registry — Plan 4 + plan-9f
+// 文件实体 .md 由 Task C 逐个填实
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/** 7 个 slash 命令名(spec §2.2 6 命令表 + plan-9f explore;实际 slash 名为 /forge:<name>) */
+export const COMMAND_NAMES = [
+    'brainstorm',
+    'propose',
+    'apply',
+    'review',
+    'verify',
+    'archive',
+    'explore', // 9f 新增(沿 design §2.5 + plan-9f;非线性思考空间,非产物驱动)
+];
+/** 单 command 内容加载 — 用 import.meta.url 定位,开发与生产路径自适应 */
+export async function loadCommand(name) {
+    return readFile(join(__dirname, `${name}.md`), 'utf8');
+}
+/** 全量加载 7 个 slash 命令,失败抛错(说明某个 .md 漏建) */
+export async function loadAllCommands() {
+    return Promise.all(COMMAND_NAMES.map(async (name) => ({ name, content: await loadCommand(name) })));
+}
+//# sourceMappingURL=index.js.map

package/dist/core/templates/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/templates/commands/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,yBAAyB;AAEzB,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,iFAAiF;AACjF,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,YAAY;IACZ,SAAS;IACT,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,SAAS,EAAE,+CAA+C;CAClD,CAAC;AAIX,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAiB;IACjD,OAAO,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAOD,0CAA0C;AAC1C,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,OAAO,OAAO,CAAC,GAAG,CAChB,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAChF,CAAC;AACJ,CAAC"}

package/dist/core/templates/commands/propose.md

@@ -0,0 +1,90 @@
+---
+description: 把 draft(可选)转化为 forge/changes/<id>/ 下的 4 件套(proposal + specs + design + tasks)
+argument-hint: '<change-id> [--from-draft <date-topic>] [--light]'
+---
+
+You are about to handle `/forge:propose $ARGUMENTS`.
+
+解析参数:
+
+- 第一个 token 是 `<change-id>`(slug,小写连字符)
+- 可选 `--from-draft <date-topic>` 指定要消费的 draft 文件(对应 `forge/drafts/<date-topic>.md`)
+- **可选 `--light`**:强制 writing-plans skill 走 light mode(沿 v0.3 P3)
+
+## 前置 — Pending follow-ups 扫描(plan-9b §2.6.5)
+
+**在产 proposal/design/tasks 之前**,先扫 archived changes 的 out-of-scope / future-work / non-goal:
+
+1. 跑 `node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" scope scan-archived-followups <change-id>`(若 helper 不可用,fallback 调本地 `npx forge scope scan-archived-followups <change-id>`)
+2. 解析 stdout JSON;若 `entries` 为空 → 跳过本段直接进步骤 1
+3. 若非空 → 用 AskUserQuestion 渲染:
+   - 按 `category` 分组(future-work / out-of-scope / non-goal),沿 §2.6.5 优先级排序
+   - 标题:"## Pending follow-ups from archived changes (N active)"
+   - 每个 entry 显示:`[source_change] id — description`
+   - 每项 5 选项:`inherit`(本 change 做)/ `acknowledge but defer`(留 active)/ `mark obsolete` / `mark superseded by some other change` / `mark completed`(本 change 已实际完成该 backlog 项)
+4. 用户决策聚合并写入:
+   - **`inherit`**:写到本 change 自己的 `## Out of Scope/Future Work` YAML 块成为新 entry,archived 来源用 **`related_change: "<source_change>"`** 字段记录(change 粒度;entry 级精确来源由配套那条 superseding ref 的 `entry_id` 承载)(**勿**写 `triggered_by: {source: "from-archived", ...}` —— `from-archived` 不在 `TriggeredByRef.source` 枚举内,会被严格 validator 拒签);**并且**在 `superseding_entries` 数组写一条 `{source_change, entry_id, new_status: inherited, rationale}` —— 否则被继承的老 entry 不会从 backlog 注册表扣除,造成 double-count(plan-backlog-registry §9a/§9b)。此处 `rationale` 填「从 `<source_change>` 继承至本 change 实施」一类说明,勿留空
+   - **`mark obsolete` / `mark superseded` / `mark completed`**:各写一条 `superseding_entries` 项(`{source_change, entry_id, new_status, rationale}`,`new_status` 取 `obsolete` / `superseded` / `completed`)
+5. `acknowledge but defer` 不写(留原 archived entry 仍 active,下次再问)
+
+**不强制** — 用户可全跳过 / 部分处理。但**必须**显式提示,不能静默忽略。
+
+## 步骤(必须按序)
+
+1. **若提供了 `--from-draft <name>`**:
+   - 读 `forge/drafts/<name>.md`(若不存在,**报错并停止**:"draft 不存在: forge/drafts/<name>.md。可用 draft: " + 列出 `forge/drafts/*.md`)
+   - 把 draft 内容作为后续 writing 的输入上下文
+2. **读 `forge/config.yaml`** 提取 `context`(tech stack)和 `rules.{proposal,specs,design,tasks}`,把这些作为系统提示注入后续 skill。
+3. **必须调用 `forge:writing-plans` skill** 来产出 tasks。
+4. 产出文件到 `forge/changes/<change-id>/`(如目录已存在且非空,**报错并停止**:"change 已存在: forge/changes/<change-id>/。请改 change-id 或删除已有目录"):
+   - `proposal.md` — H1 标题 + Why + What + Scope
+     - **必须**含 `## Out of Scope {#forge-oos}` 段(沿 plan-9b §2.6.3);若本 change 没有 out-of-scope 项,该段仅占位 anchor 无 YAML 块(合法)
+     - **必须**含 `## Non-Goals {#forge-non-goals}` 段(同上)
+     - 若上面 §"前置"步骤 4 收集到 `inherit` / `superseding_entries` 决策 → 写入对应段的 `forge-scope-entries/v1` YAML 块(inherit 项带 `related_change`,且必配一条 `new_status: inherited` 的 superseding_entries 项 —— plan-backlog-registry §9a/§9b)
+   - `specs/<sub-area>.md` — 每个改动域一个文件,Given/When/Then 三段格式(spec deltas)
+   - `design.md` — H1 标题 + 技术方案 + 数据模型 + 接口设计;**必须**含 `## Future Work {#forge-future-work}` 段(同上,可仅占位)
+   - `tasks.md` — checkbox 任务列表,粒度 2-5 分钟一步,采用 forge:writing-plans skill 的 task 结构
+5. **若有 `--from-draft`**:把 draft 移到 `forge/drafts/.consumed/<name>.md`(filesystem chmod 444 只读)。
+6. 跑 `node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" validate <change-id>` 确认 4 件套完整 + scope YAML 合规(沿 plan-9b §2.6.8;若 helper 不可用 改用 skill 内嵌 fenced bash 调 helper,见 Plan 3 Task 3.3)。**若 validate 失败,根据错误回去补,不要把不完整产物留下**。
+
+## 禁止行为
+
+- 不允许跳过 `forge:writing-plans` skill 直接写 tasks.md(skill 内置 self-review,跳过会漏 placeholder 检查)
+- 不允许把任何东西写到 `forge/specs/`(那是 archive 内部 sync 的输出)
+- 不允许在 `forge/changes/<id>/` 之外创建产物文件
+- **不允许省略三段 anchor**(plan-9b §2.6.3):缺 `{#forge-oos}` / `{#forge-non-goals}` / `{#forge-future-work}` 会让 content_hash 把 follow-up 编辑算进 marker 失效,违反 §2.6.3 解耦
+- **不允许把 archived followups 决策静默丢弃**:若 scan 输出非空,必须走 AskUserQuestion 让用户做决策
+
+## (可选)Stage extensions hook — Tier 1 Claude Code only
+
+> codex review 集成。AI 主代理在本 stage(`propose`)跑多轮收敛协议。
+> Tier 2/3(Codex/OpenCode)见 [`docs/stage-extensions.md §未来 Tier 2/3 集成`](../docs/stage-extensions.md#未来-tier-23-集成)。
+
+**Step A — 检查是否启用**:读 `forge/config.yaml#stage_extensions.propose`。无该字段 / 数组为空 / 全部 entry `enabled: false` → **跳过本段,流程结束**。
+
+**Step B — 对每个 `enabled` entry 跑多轮收敛 loop**:
+
+初始化 `round = 1`、`threadId = ''`、`roundHistory = []`、`roundLimit = null`(F1-v8 fix:`roundLimit` **不从 config 文件读** —— effective convergence 由 runner 输出,见 Step 3。AI 协议不碰 config 文件解析 / deep-merge,单一数据源是 runner JSON)。循环:
+
+1. **跑单轮 runner**:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" stage-extensions run \
+     --stage propose --change-id <change-id> --extension <entry-name> \
+     --round <round>${threadId:+ --thread-id $threadId}
+   ```
+2. **解析 stdout JSON 的 `kind`**:
+   - `converged` → 该 entry 收敛完成,**break loop**(codex 输出 verbatim 透传给用户)
+   - `failed` / `config_error` / `no_extension` → 该 entry 放弃,**break loop**(loose,不阻塞主流程)
+   - `unconverged` → 继续 3
+3. **从 unconverged JSON 取状态**(F1-v8 fix:effective config 来自 runner 输出,runner 内 `validateStageExtensionsConfig` 已 normalize):
+   - `roundHistory.push({ round, block_count: <blockFindings.length> })`;`threadId = <JSON.threadId>`;codex finding verbatim 透传给用户
+   - 首轮:`roundLimit = <JSON.effectiveConvergence.max_rounds>`(后续轮 `roundLimit` 已设,不覆盖 —— 选项①的 `roundLimit += N` 增量须保留)
+4. **若 `round >= roundLimit`**(F2-v7 fix:用可增长的 `roundLimit`):
+   - 若 `<JSON.effectiveConvergence.max_rounds_on_exceed>` 为 `force_end` → 把 blockFindings 写 `forge/changes/<id>/.evidence/codex-pending-findings.yaml`(backlog),**break loop**
+   - 否则跑 `node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" stage-extensions analyze-trend --history '<roundHistory JSON>'` 拿 TrendAdvice,再 `AskUserQuestion` 三选项(默认推 `TrendAdvice.recommended_option`):**①再跑 N 轮**(F2-v7 fix:读用户输入的 `N`,执行 `roundLimit += N`,然后 `round++` 继续 loop —— 后续 `round >= roundLimit` 判定按新上限走,不会立刻又进 Step 4)/ **②放弃 codex**(break loop)/ **③接受当前**(blockFindings 写 backlog,break loop)
+5. **否则(`round < roundLimit`)**:`AskUserQuestion` 三选项(默认推 `<JSON.userInteraction.block_unconverged>`):
+   - **①auto_fix** → 用 `Task` 工具 dispatch fresh fix subagent 修 blockFindings → `round++`,继续 loop
+   - **②manual_fix** → 等用户改完 → `round++`,继续 loop
+   - **③give_up** → break loop
+
+**Step C — loose**:本段任何步骤(runner 调用 / AskUserQuestion / fix dispatch)失败都**不阻塞主流程 fence**。runner 永远 exit 0;AskUserQuestion harness 不支持时降级终端 prompt。

package/dist/core/templates/commands/review.md

@@ -0,0 +1,105 @@
+---
+description: 派 review subagent 审 [proposal + specs + design + diff],主代理处理反馈,满足三条件打 review-passed YAML
+argument-hint: '[--change-id <id>]'
+---
+
+You are about to handle `/forge:review $ARGUMENTS`.
+
+解析:`--change-id <id>` 默认 `forge/changes/` 下唯一未归档 change。
+
+## 步骤
+
+1.  **必须调用 `forge:requesting-code-review` skill**(主轨)。
+2.  **必须调用 `forge:receiving-code-review` skill**(收反馈环节)。
+3.  打包 review 输入:
+    - `forge/changes/<id>/proposal.md`
+    - `forge/changes/<id>/specs/*.md`
+    - `forge/changes/<id>/design.md`
+    - `git diff <since-tasks-start>..HEAD`(`since-tasks-start` 取 tasks.md 末尾 `applied_commits` 的第一个 commit 的 parent)
+4.  派 fresh review subagent,产出意见列表(每条带:[严重度:阻塞/关键/可改进/建议]、[文件路径]、[问题描述]、[期望修改])。
+5.  主代理对每条意见 **逐条判断接受/拒绝**(参考 forge:receiving-code-review skill 的"用证据反驳"原则,不机械接受)。
+6.  接受的意见 → append 到 `forge/changes/<id>/tasks.md` 末尾作为新 task 条目。
+7.  **仅当满足三条件,才打 `forge/changes/<id>/.review-passed`**:
+    a. 无"已用证据反驳但未存档"的拒绝意见
+    b. 接受的意见已**全部实现 + 测试通过**(本轮新接受的意见**不算本轮通过**,需下一轮 review)
+    c. 满足 a+b 时,本轮 review 无新增 task
+    7a. **(本 fix 补缺)调 forge evidence record-review 记录 review 事件证据到 staging**
+
+        主代理在写完 .review-passed YAML 后、freeze 之前,**必须**先调 record-review:
+
+        ```bash
+        forge evidence record-review <changeId> --task <ref> --implementer-commit <sha>
+        ```
+
+        这一步把 review 事件(子代理调用 + 主代理 accept/reject outcomes)写入 `.evidence/process-evidence.staging.yaml`(沿 `src/cli/commands/evidence.ts:474`;helper list 权威 `commands/apply.md:179-182`)。
+
+    7b. **(本 fix 补缺)调 forge evidence freeze 凝固 process_evidence**
+
+        7a record-review 后,**必须**调:
+
+        ```bash
+        forge evidence freeze <changeId> --kind review
+        ```
+
+        若漏调 record-review 直接 freeze → exit 1 + 提示 "staging file not found"(代码事实 `evidence.ts:639`)。若漏调 freeze → archive fence 拒签 "[review] v1.0 marker missing process_evidence"(代码事实 `src/core/archive/fence.ts:185`)。
+
+8.  `.review-passed` YAML schema(spec §3.4)— 含 `pause_decisions` 数组(本 fix 补 lifecycle 注):
+    ```yaml
+    schema: forge-review/v1
+    tasks_hash: <sha256(tasks.md 已勾段)>
+    content_hash: <sha256(proposal+specs+design)>
+    reviewed_by: ai-agent # 或 human-override(需 archive --force)
+    git:
+      is_git_repo: true
+      head: <git rev-parse HEAD>
+      diff_hash: <sha256(git diff against forge/config.yaml code_paths)>
+    review_outcomes:
+      - id: 1
+        severity: blocking
+        accepted: true
+        resolved: true
+        resolution_commit: <hash>
+    pause_decisions: # apply 阶段累积的 pause 决策在写本 marker 时一并迁移(沿 commands/apply.md "Marker 持久化" 段 lifecycle 说明)
+      - id: 1
+        # ... 完整 schema 见 commands/apply.md "Marker 持久化" 段
+    ```
+
+## 禁止行为
+
+- 不允许跳过 review subagent 直接打 review-passed
+- 不允许接受意见但不实现就打 review-passed(违反 b)
+- 非 git 项目跳过 git 字段时,review-passed YAML 必须 `is_git_repo: false`(archive --force 才接受)
+
+## (可选)Stage extensions hook — Tier 1 Claude Code only
+
+> codex review 集成。AI 主代理在本 stage(`review`)跑多轮收敛协议。
+> Tier 2/3(Codex/OpenCode)见 [`docs/stage-extensions.md §未来 Tier 2/3 集成`](../docs/stage-extensions.md#未来-tier-23-集成)。
+
+**Step A — 检查是否启用**:读 `forge/config.yaml#stage_extensions.review`。无该字段 / 数组为空 / 全部 entry `enabled: false` → **跳过本段,流程结束**。
+
+**Step B — 对每个 `enabled` entry 跑多轮收敛 loop**:
+
+初始化 `round = 1`、`threadId = ''`、`roundHistory = []`、`roundLimit = null`(F1-v8 fix:`roundLimit` **不从 config 文件读** —— effective convergence 由 runner 输出,见 Step 3。AI 协议不碰 config 文件解析 / deep-merge,单一数据源是 runner JSON)。循环:
+
+1. **跑单轮 runner**:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" stage-extensions run \
+     --stage review --change-id <change-id> --extension <entry-name> \
+     --round <round>${threadId:+ --thread-id $threadId}
+   ```
+2. **解析 stdout JSON 的 `kind`**:
+   - `converged` → 该 entry 收敛完成,**break loop**(codex 输出 verbatim 透传给用户)
+   - `failed` / `config_error` / `no_extension` → 该 entry 放弃,**break loop**(loose,不阻塞主流程)
+   - `unconverged` → 继续 3
+3. **从 unconverged JSON 取状态**(F1-v8 fix:effective config 来自 runner 输出,runner 内 `validateStageExtensionsConfig` 已 normalize):
+   - `roundHistory.push({ round, block_count: <blockFindings.length> })`;`threadId = <JSON.threadId>`;codex finding verbatim 透传给用户
+   - 首轮:`roundLimit = <JSON.effectiveConvergence.max_rounds>`(后续轮 `roundLimit` 已设,不覆盖 —— 选项①的 `roundLimit += N` 增量须保留)
+4. **若 `round >= roundLimit`**(F2-v7 fix:用可增长的 `roundLimit`):
+   - 若 `<JSON.effectiveConvergence.max_rounds_on_exceed>` 为 `force_end` → 把 blockFindings 写 `forge/changes/<id>/.evidence/codex-pending-findings.yaml`(backlog),**break loop**
+   - 否则跑 `node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" stage-extensions analyze-trend --history '<roundHistory JSON>'` 拿 TrendAdvice,再 `AskUserQuestion` 三选项(默认推 `TrendAdvice.recommended_option`):**①再跑 N 轮**(F2-v7 fix:读用户输入的 `N`,执行 `roundLimit += N`,然后 `round++` 继续 loop —— 后续 `round >= roundLimit` 判定按新上限走,不会立刻又进 Step 4)/ **②放弃 codex**(break loop)/ **③接受当前**(blockFindings 写 backlog,break loop)
+5. **否则(`round < roundLimit`)**:`AskUserQuestion` 三选项(默认推 `<JSON.userInteraction.block_unconverged>`):
+   - **①auto_fix** → 用 `Task` 工具 dispatch fresh fix subagent 修 blockFindings → `round++`,继续 loop
+   - **②manual_fix** → 等用户改完 → `round++`,继续 loop
+   - **③give_up** → break loop
+
+**Step C — loose**:本段任何步骤(runner 调用 / AskUserQuestion / fix dispatch)失败都**不阻塞主流程 fence**。runner 永远 exit 0;AskUserQuestion harness 不支持时降级终端 prompt。