@accelerator-mzq/forge 3.0.0 → 4.0.0

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

@@ -8,44 +8,44 @@ You are about to handle `/forge:apply $ARGUMENTS`.
 解析:
 
 - 默认:顺序模式(主工作区直接跑)
-- `--parallel`:并行模式(每个独立 task 一个 worktree;遵循 forge:dispatching-parallel-agents 的 cherry-pick 串行协议)
+- `--parallel`:并行模式(每个独立 task 一个 worktree;遵循 `forge:dispatching-parallel-agents` 的 cherry-pick 串行协议)
 - `--change-id <id>`:指定 change(默认为 `forge/changes/` 下唯一未归档的 change;若 >1,**报错并停止**列出选项)
 
 ## 步骤
 
-0. **前置 branch-check**(plan-9h §2.8.3 C):调 `forge preflight branch-check <change-id>`
+0. **前置 branch-check**(沿 §2.8.3 C):调 `forge preflight branch-check <change-id>`
    - exit 0 → 继续步骤 1
-   - exit 2 → **必须停下**,按 stderr 建议切 feature branch(`git checkout -b feature/<change-id>`)或显式传 `--allow-protected-branch`(后者需用户确认 build/CI 风险)
-   - 非 git 项目:helper 自动跳过 exit 0(沿 v0.4 graceful 降级)
+   - exit 2 → **必须停下**,按 stderr 建议切 feature branch(`git checkout -b feature/<change-id>`)或显式传 `--allow-protected-branch`(后者需用户确认风险)
+   - 非 git 项目:helper 自动跳过 exit 0
 1. **必须调用 `forge:subagent-driven-development` skill**(无 inline 模式)。
 2. **必须调用 `forge:test-driven-development` skill** 作为每个 subagent 的实施纲领。
 3. 若 `--parallel`,**追加调用 `forge:dispatching-parallel-agents` 和 `forge:using-git-worktrees`**。
 
-3.5. **Critical Plan Review**(主代理 dispatch subagent 前必做,沿 design §2.8.3 A):
+3.5. **Critical Plan Review**(主代理 dispatch subagent 前必做):
 
-主代理读 `forge/changes/<id>/{proposal, design, tasks, specs/*}.md` 全套,**按 4 类维度逐条检查**(不允许 vague pass-through,沿反向加固):
+主代理读 `forge/changes/<id>/{proposal, design, tasks, specs/*}.md` 全套,**按 4 类维度逐条检查**:
 
 | 维度   | 检查问题                                                            |
 | ------ | ------------------------------------------------------------------- |
 | 完整性 | tasks 是否覆盖 specs 所有 requirement?(对照 specs requirement 计数) |
 | 顺序   | tasks 依赖关系是否合理?(标 dependency 的 task 是否先于被依赖)       |
 | 清晰度 | 是否有 tasks 描述 vague(如"处理边界情况" / "加测试")?               |
-| scope  | 是否有 tasks 应该是 §2.6 out-of-scope 而非本 change?                |
+| scope  | 是否有 tasks 应该是 out-of-scope 而非本 change?                     |
 
 - **若有 concerns** → AskUserQuestion 列 concerns,等用户决策:
   - 改 plan(回 propose 修)
   - 接受当前 plan(继续 dispatch)
-  - 走 §2.5 explore 重新评估
+  - 走 explore 重新评估
 - **无 concerns** → 主代理**必须显式输出 4 类维度的结论**(可以是"无问题"但按维度逐条说),然后进步骤 4 dispatch
 
-**反向加固**:Critical Plan Review **不允许 vague pass-through** — 主代理必须显式输出 4 类检查结果(可以是"无问题"但必须按维度逐条说),不允许跳过整段 review。
+**Critical Plan Review 不允许 vague pass-through** — 必须显式输出 4 类检查结果,不允许跳过整段 review。
 
 4. 读 `forge/changes/<id>/tasks.md`,识别未勾选 tasks。
 5. **顺序模式**:
    - for each task:派 fresh subagent(主工作区),subagent 拿 [task + 相关 specs/<sub-area>.md + design.md] 启动
    - subagent 跑 TDD:red → green → refactor + git commit
    - 主代理 review subagent 的 commit + test 日志,通过则在主工作区 tasks.md 把 `[ ]` 改 `[x]`
-6. **--parallel 模式**:严格遵守 cherry-pick 串行协议(详 forge:dispatching-parallel-agents skill 的"forge --parallel 模式 cherry-pick 串行协议"段)
+6. **--parallel 模式**:严格遵守 cherry-pick 串行协议(详 `forge:dispatching-parallel-agents` skill 的"forge --parallel 模式 cherry-pick 串行协议"段)
 7. 全部 task 完成后,在 tasks.md 末尾追加(parallel 多 commit 用列表):
    ```yaml
    applied_commits:
@@ -54,40 +54,39 @@ You are about to handle `/forge:apply $ARGUMENTS`.
    final_head: <git rev-parse HEAD>
    ```
 
-## Fluid Pause Decision Point(v1.0,沿 design §2.1)
+## Fluid Pause Decision Point
 
-> **与 `/forge:explore` 边界提示**(沿 design §2.5.5 + plan-9f):Fluid Pause 是**被动**触发(subagent 报告阻塞型 issue 时主代理进入);若是**开放思考**(非阻塞 issue,如"实施途中想重新评估某个 design 决策"),应主动触发 `/forge:explore --change <id>` 而非 Fluid Pause。两者边界详见 `forge:exploring` skill 的"与 §2.1 Fluid Pause 边界"段。
+> **与 `/forge:explore` 边界**:Fluid Pause 是**被动**触发(subagent 报告阻塞型 issue 时主代理进入);若是**开放思考**(非阻塞 issue,如"实施途中想重新评估某个 design 决策"),应主动触发 `/forge:explore --change <id>` 而非 Fluid Pause。两者边界详见 `forge:exploring` skill。
 
 ### 触发条件
 
 subagent 在 apply 中段报告以下三档之一时,主代理**不直接处理**,改进 Fluid Pause:
 
-| Subagent 报告                                                                                                                         | 主代理行为                                                    |
-| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `DONE_WITH_CONCERNS`,concerns 类型 = "correctness or scope"(非 CRITICAL)                                                              | 进 Fluid Pause                                                |
-| `BLOCKED` 第 4 项 = "plan itself is wrong"                                                                                            | 进 Fluid Pause                                                |
-| `DESIGN_ISSUE_FOUND`(v1.0 新增第 5 档,沿 subagent-driven-development SKILL.md)— subagent 实施中发现属于本 change 但 spec 未覆盖的需求 | 进 Fluid Pause                                                |
-| **任一 CRITICAL 级问题**(测试 fail / hash mismatch / evidence 丢)                                                                     | **不进 Fluid Pause** — 走 forge 强 fence 拒签(保留 v0.4 行为) |
+| Subagent 报告                                                                | 主代理行为                            |
+| ---------------------------------------------------------------------------- | ------------------------------------- |
+| `DONE_WITH_CONCERNS`,concerns 类型 = "correctness or scope"                  | 进 Fluid Pause                        |
+| `BLOCKED` 第 4 项 = "plan itself is wrong"                                   | 进 Fluid Pause                        |
+| `DESIGN_ISSUE_FOUND` — subagent 实施中发现属于本 change 但 spec 未覆盖的需求 | 进 Fluid Pause                        |
+| **任一 CRITICAL 级问题**(测试 fail / 显式错误)                               | **不进 Fluid Pause** — abort 让用户修 |
 
 ### 协议流程
 
 ```
-subagent 报告 → 主代理判定 severity(CRITICAL / WARNING / SUGGESTION,沿 design §2.3)
+subagent 报告 → 主代理判定问题性质
               ↓
-              CRITICAL? → yes → 走 forge 强 fence 拒签(原 v0.4 行为)
-                       → no  → 主代理调 `forge pause-capture <change-id> --task <triggering-task-ref> --issue "<summary>"`
-                                (捕获 pause 时刻 tasks.md 状态进 ack-log hash-chain;记下 stdout 返回的 capture_id)
-                                ↓
-                                AskUserQuestion 四选项
+              CRITICAL? → yes → abort,让用户修代码 / 重派 subagent
+                       → no  → AskUserQuestion 四选项
                                 ↓
                                 用户选择
                                 ↓
-                                1=扩本 change scope → 更新 proposal `## What Changes` + subagent 重派
+                                1=扩本 change scope → 更新 proposal `## What` + subagent 重派
                                 2=加 task 进本轮 → 主代理 append 新 task 到 tasks.md + subagent 重派
-                                3=转 out-of-scope → 写到 proposal `## Out of Scope` / design `## Future Work` YAML 块(沿 §2.6)+ subagent 跳过 issue 继续
-                                4=Other → 用户自由文本描述(必须配 other_rationale + other_acked_by)
+                                3=转 out-of-scope → 写到 proposal `## Out of Scope` / design `## Future Work` YAML 块 + subagent 跳过 issue 继续
+                                4=Other → 用户自由文本描述
+                                ↓
+                                主代理在 session context 累积 PauseDecisionSimple
                                 ↓
-                                marker `pause_decisions` YAML 字段记录(沿 design §2.1.5)
+                                verify / review 阶段写 marker 时一并填 pause_decisions[]
 ```
 
 ### AskUserQuestion 模板
@@ -104,106 +103,54 @@ subagent 报告 → 主代理判定 severity(CRITICAL / WARNING / SUGGESTION,沿
 ### Issue Encountered
 <subagent 报告的 issue 描述,从 DONE_WITH_CONCERNS / BLOCKED concerns 字段或 DESIGN_ISSUE_FOUND payload 提取>
 
-**Severity:** WARNING | SUGGESTION(主代理初判,沿 design §2.3 分级;CRITICAL 不进本流程)
-
 **Options:**
-1. **扩本 change scope** — 把这个 issue 纳入本 change。更新 proposal `## What Changes` 段,重新派 subagent 实施。代价:本 change scope 增大,需要重 review
-2. **加 task 进本轮 tasks.md** — 当成新发现的本 change 必做项。主代理 append 新 task 到 tasks.md,subagent 重派实施。等同 v0.4 行为
-3. **转 out-of-scope**(仅限 issue 不阻断本 task 时可用) — 不在本 change 做,写到 proposal `## Out of Scope` 或 design `## Future Work` 段(YAML 结构化字段,沿 §2.6)。subagent 跳过该 issue 继续当前 task。**v1.1 backlog registry 会从这里读**
-4. **Other** — 自由文本描述。必须配 `other_rationale` + `other_acked_by`(用户在 marker 之外的某处确认)
+1. **扩本 change scope** — 把这个 issue 纳入本 change。更新 proposal `## What` 段,重新派 subagent 实施。代价:本 change scope 增大,需要重 review
+2. **加 task 进本轮 tasks.md** — 当成新发现的本 change 必做项。主代理 append 新 task 到 tasks.md,subagent 重派实施
+3. **转 out-of-scope**(仅限 issue 不阻断本 task 时可用) — 不在本 change 做,写到 proposal `## Out of Scope` 或 design `## Future Work` 段(YAML 结构化字段)。subagent 跳过该 issue 继续当前 task。**v1.1+ backlog registry 会从这里读**
+4. **Other** — 自由文本描述,主代理 notes 字段留底
 
 What would you like to do?
 ```
 
-### Marker 持久化(沿 design §2.1.5)
+### Marker 持久化(v4 简版)
 
-**Lifecycle 说明**(本 fix 补缺):pause 决策**实际写入** `.verify-passed` / `.review-passed` marker 是在 **verify / review 阶段**(那时 marker 才真正打;沿 `commands/verify.md` step 4.3 + `commands/review.md` step 7);apply **中段** marker 尚不存在,AI 主代理把每次 pause 决策**累积记录在本 change session context** 中,等到 verify / review 时一并迁移到对应 marker 的 `pause_decisions` 数组(沿 `src/cli/commands/archive.ts:411/422` archive fence 同时校验 verify-passed + review-passed 两个 marker 的 pause_decisions,确认这是 additive 模式)。
-
-主代理在 verify / review 写 marker 时,**必须**把本 change apply 阶段累积的所有 pause 决策按下面 schema 写入 `pause_decisions` 数组:
+apply **中段** marker 尚不存在,AI 主代理把每次 pause 决策**累积记录在本 change session context** 中,等到 verify / review 时一并迁移到对应 marker 的 `pause_decisions[]` 数组(`PauseDecisionSimple` schema,沿 `src/core/markers/types.ts`):
 
 ```yaml
 pause_decisions:
-  - id: 1 # 同一 marker 内唯一
-    paused_at: 2026-05-12T14:30:00Z # ISO 8601 UTC
-    task_ref: tasks.md#task-3 # 关联 task
+  - paused_at: 2026-05-21T14:30:00Z # ISO 8601 UTC,允许 ms 精度
+    task_ref: tasks.md#task-3
     issue_summary: 'subagent 发现 specs 没覆盖 OAuth refresh token 过期处理'
-    severity: WARNING # 主代理初判(CRITICAL 不进本流程)
-    severity_acked_by: msc # WARNING 必须;SUGGESTION 允许 null
-    severity_acked_at: 2026-05-12T14:32:00Z
-    chosen_option: 3 # 1=扩 scope / 2=加 task / 3=转 out-of-scope / 4=Other
-    added_task_ref: tasks.md#task-7 # option=2 必填:Fluid Pause 新增的 task(与 task_ref=触发 task 区分)
-    capture_id: <forge pause-capture 返回的 capture_id> # option=2 必填:关联 pause-capture entry
-    target_artifact: proposal.md # option=1=proposal.md;option=2=tasks.md;option=3=proposal.md|design.md
-    target_anchor: '## Out of Scope' # 记录写到哪个段(option=2 降为仅人类可读,fence 不据此校验)
-    non_blocking_rationale: 'subagent 可跳过该 issue 完成本 task 主体功能' # option=3 必填
-    other_rationale: null # option=4 必填
-    other_acked_by: null # option=4 必填
+    chosen_option: 3 # 1=扩scope/2=加task/3=转out-of-scope/4=Other
+    notes: 'subagent 可跳过该 issue 完成本 task 主体功能'
 ```
 
-### Fence 校验(`forge archive` 阶段,本协议反向加固点)
-
-`forge archive` 跑 `validatePauseDecisionsFence`(沿 design §2.1.5)— 任一违反拒签 exit 1:
-
-- CRITICAL severity → 拒签(CRITICAL 应走 forge 强 fence,不应进 pause)
-- WARNING + (severity_acked_by 空 ∨ severity_acked_at 空)→ 拒签
-- option=1:`target_artifact='proposal.md'` + `target_anchor` 含 `What Changes`
-- option=2:`added_task_ref` 指向的 task ∉ capture 快照、∈ 当前 tasks.md 且勾选 `[x]`;`capture_id` 匹配 ack-log pause-capture entry;链完整
-- option=3:proposal/design YAML 块含对应 entry.id + `non_blocking_rationale` 非空
-- option=4:`other_rationale` + `other_acked_by` 非空
-
-### option=2 capture 的已知边界(capture-input gap,design §9.2/§9.3)
-
-`forge pause-capture` 是轻量锚点,**不能**密码学证明 "task 是 pause 真新增的"。它能挡:无 capture 流程的 option=2、capture entry 事后被篡改、同 marker 内 capture 复用。它**挡不住**:capture 当下喂假输入(删旧 task → capture → 恢复)、AI 预先攒多条 capture 后选择性认领、AI 完全不记录 pause_decision。轻量 capture 对 "诚实但偷懒" 的 AI 有效,对蓄意构造假输入的攻击者无效 —— 此 gap 是当前 forge 架构下的已知限制。
-
-## 与其他 sub-plan 合并点
-
-本 §"Fluid Pause Decision Point" 段(plan-9c)与后续 sub-plan 在 apply.md 有合并点(参考 master plan §3.3 line 272):
-
-- **9h(SDD 实施前置纪律加固)**:将在步骤 0 加 `forge preflight branch-check` 调用 + 步骤 3.5 加 §"Critical Plan Review";9c 不动这些位置
-- **9g(process_evidence)**:将在每个 subagent task 完成后加 `forge evidence record-tdd` helper 调用;9c 不动这些位置
-- **推荐 merge 顺序**:9h → 9c → 9g
+**v4 BREAKING**:`PauseDecisionSimple` 只 5 个字段(`paused_at` / `task_ref` / `issue_summary` / `chosen_option` / `notes?`)。已删字段:`severity` / `severity_acked_by` / `severity_acked_at` / `added_task_ref` / `capture_id` / `target_artifact` / `target_anchor` / `non_blocking_rationale` / `other_rationale` / `other_acked_by`(v3 反加固 fence 字段全消亡)。**archive 阶段无 `validatePauseDecisionsFence` 校验**(v4 删 fence,marker 仅作 audit)。
 
 ## 禁止行为
 
 - 不允许主代理直接写代码 — 所有 task 实施必须通过 subagent
 - 不允许 subagent 改 tasks.md(写入是主代理单点串行职责)
-- 不允许跳过 TDD 的 red 步骤(verify 阶段会发现并 append 修复 task)
+- 不允许跳过 TDD 的 red 步骤(verify 阶段三维度 prose check 会发现)
 
-## 禁止行为(plan-9h §2.8.3 B 主代理 STOP 协议)
+## 禁止行为(主代理 STOP 协议)
 
-主代理 dispatch 阶段必须停下问用户的场景(不允许自动绕过 / 不允许重试,沿 `skills/subagent-driven-development/SKILL.md` §"Main Agent STOP Triggers"):
+主代理 dispatch 阶段必须停下问用户的场景(不允许自动绕过 / 不允许重试,沿 `forge:subagent-driven-development` skill 的"Main Agent STOP Triggers"):
 
 - ✗ **不允许"绕过失败 task 跑下一个"**(同 task BLOCKED 后必须 STOP)
-- ✗ **不允许"修改 task 描述让它能过"**(改 task 描述需经 §"Fluid Pause Decision Point" 走选项 1/2)
-- ✗ **不允许"重试同一 task ≥ 3 次不停下"**(verify 命令重试 ≥ 3 次仍失败 / subagent BLOCKED ≥ 2 次 → STOP 问用户,沿 SDD STOP triggers 表)
-
-## 禁止行为(plan-9g §2.7 process_evidence 协议)
-
-✗ **不允许绕过 forge evidence helper 直接写 process_evidence 字段**:
-
-- 不允许 `fs.writeFile .verify-passed` 或 `.review-passed` 含 process_evidence 字段
-- 不允许拼接 YAML 字面塞 process_evidence 到 marker
-- 不允许直接编辑 `.evidence/process-evidence.staging.yaml`
-
-✓ **必须**通过 helper 写入:
-
-- `forge evidence record-tdd <changeId> --task ... --red-commit ... --green-commit ... ...`(20 options)
-- `forge evidence record-verify <changeId> --task-refs ... --scope ... --report ...`
-- `forge evidence record-review <changeId> --task ... --implementer-commit ...`
-- `forge evidence freeze <changeId> --kind verify|review`(在 marker YAML 写完后调,统一凝固)
-
-详细 process_evidence 协议见 `skills/process-evidence/SKILL.md`。
+- ✗ **不允许"修改 task 描述让它能过"**(改 task 描述需经 Fluid Pause 走选项 1/2)
+- ✗ **不允许"重试同一 task ≥ 3 次不停下"**(verify 命令重试 ≥ 3 次仍失败 / subagent BLOCKED ≥ 2 次 → STOP 问用户)
 
 ## (可选)Stage extensions hook — Tier 1 Claude Code only
 
 > codex review 集成。AI 主代理在本 stage(`apply_critical_plan_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.apply_critical_plan_review`。无该字段 / 数组为空 / 全部 entry `enabled: false` → **跳过本段,流程结束**。
+**Step A — 检查是否启用**:读 `forge/config.yaml#stage_extensions.apply_critical_plan_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)。循环:
+初始化 `round = 1`、`threadId = ''`、`roundHistory = []`、`roundLimit = null`。循环:
 
 1. **跑单轮 runner**:
    ```bash
@@ -211,19 +158,9 @@ pause_decisions:
      --stage apply_critical_plan_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。
+2. **解析 stdout JSON 的 `kind`**:`converged` / `failed` / `config_error` / `no_extension` → break loop(loose);`unconverged` → 继续 3
+3. **从 unconverged JSON 取状态**:`roundHistory.push(...)`;`threadId = <JSON.threadId>`;首轮 `roundLimit = <JSON.effectiveConvergence.max_rounds>`
+4. **若 `round >= roundLimit`**:`force_end` → 写 backlog,break;否则 `analyze-trend` + AskUserQuestion 三选项(再跑 N 轮 / 放弃 / 接受当前)
+5. **否则**:AskUserQuestion 三选项(auto_fix dispatch fix subagent / manual_fix 等用户改 / give_up)
+
+**Step C — loose**:本段任何步骤失败都**不阻塞主流程**。

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

@@ -1,6 +1,6 @@
 ---
-description: 调 forge archive CLI 把 change 移到 archive/、内部 sync specs/、严格校验 verify+review 标记
-argument-hint: '<change-id> [--force] [--recover]'
+description: 调 forge archive CLI 把 change 移到 archive/、应用 spec deltas、写 archive_summary
+argument-hint: '[change-id] [--force] [--yes] [--skip-specs] [--api]'
 ---
 
 You are about to handle `/forge:archive $ARGUMENTS`.
@@ -13,181 +13,64 @@ You are about to handle `/forge:archive $ARGUMENTS`.
 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。)
+(plugin helper 内部 spawn npx 拉 forge CLI,避开 v0.2 P1 全局 PATH 问题。OpenCode/Codex 路径走 skill 内嵌 fenced bash 调本地 `npx forge archive`,见 `skills/using-forge/SKILL.md`。)
 
-## v1.0 三级分级行为(plan-9e1 落地)
+## flag 说明
 
-archive 阶段在 verify+review marker 严格校验之外,再叠加"三级业务行为"裁决(沿 design §2.4.2):
+| flag           | 行为                                                                  |
+| -------------- | --------------------------------------------------------------------- |
+| `[change-id]`  | 默认交互式列 active change(>1 时必选);唯一 active 时可省              |
+| `--force`      | 接受 `verified_by='human-override'` 或 `reviewed_by='human-override'` |
+| `--yes`        | CI 模式:跳过 incomplete-tasks confirm + spec deltas apply confirm     |
+| `--skip-specs` | 跳过 `forge/specs/` deltas 应用步                                     |
+| `--api`        | legacy-bridge sync-check 直连 Anthropic API(否则走 agent emit)        |
 
-| 状态                                                             | 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)   |
+## CLI 行为(给 AI 理解,不要重复实现)
 
-**强 fence 优势保留**:CRITICAL 永远拒签,无 `--force` 出口(`--force` 仍只覆盖 v0.4 那两类降级 — human-override / 非 git;不扩展到 CRITICAL,沿 design §2.4.6)。
+1. **legacy-bridge preflight**(若 `legacy_bridge.enforce_sync=true` 且 anchors 就绪)
+   - agent 模式 emit sync-check manifest 后 exit 2 暂停
+   - `--api` 模式直连跑 sync-check,有 critical pending 时 exit 2
+   - graceful skip 路径:config 缺 / anchors 缺 / allow_llm_calls=false / enforce_sync=false / 无受影响 anchor
+2. **Spec validate**(永远跑,blocking — sanity check 非 fence)
+3. **marker 存在性 + schema 校验**:`.verify-passed` schema=`forge-verify/v2`,`.review-passed` schema=`forge-review/v2`;human-override 需 `--force`
+4. **未完成 task confirm**(`- [ ] ` 计数 > 0 且非 `--yes`):dangerous-by-default 回车 = NO
+5. **Spec deltas 应用**(非 `--skip-specs`):`readDeltas` 列 create/replace/delete 操作 → 渲染 → 非 `--yes` 时 safe-by-default confirm 回车 = YES → `applyDeltas` 写 `forge/specs/`
+6. **mv `forge/changes/<id>/` → `forge/changes/archive/<YYYY-MM-DD>-<id>/`**(`getArchiveDate` 算一次,跨午夜防偏)
+7. **写 `archive_summary.yaml`** 到 archive 目录(schema `forge-archive-summary/v2`)
+8. **legacy-bridge posthook**(`enforce_sync=false` 时跑;`--api` 直接写报告,否则 emit manifest 非阻塞)
+9. **自动重生成 backlog**(`forge backlog active.md`;失败仅 warn,不回滚 archive)
+10. **emit monitor trace event**(`change_archived` 给 `forge monitor`)
 
-`review_outcomes` 端简码 S/C/L 迁移规则(v4 BLOCKER 1 + MAJOR 1 修订,沿 design §2.3.5 line 553-563):
+## archive_summary v2 输出
 
-| 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` 迁移 |
+`forge/changes/archive/<archive-name>/archive_summary.yaml` 顶层字段(沿 `src/core/schemas/archive-summary.ts`):
 
-**重要**:`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
+- `schema: forge-archive-summary/v2`
+- `version`(`2.0.0`)
 - `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 / 双份冲突拒签 / 状态损坏报错)
-
-## AI 编排步
-
-### 步骤 1:sync-check manifest fulfillment(若有)
-
-跑 `forge archive` 后,若输出提示 emit 了 sync-check manifest
-(`forge/.cache/legacy-bridge-task-sync-check.json` 存在):
-
-1. 按 `legacy-bridge-fulfillment` skill fulfill 该 manifest。
-2. 跑 `forge legacy-bridge sync-check --apply`。
-3. 跑 `forge archive --resume`:
-   - exit 2 → archive 被 critical 差异阻塞,先 `forge legacy-bridge resolve <change-id>`。
-   - exit 0 → archive 续跑完成。
-
-`enforce_sync=false` 时此步非阻塞;`enforce_sync=true` 时是硬 gate。
+- `change_id` / `archive_name` / `verified_by` / `reviewed_by`
+- `applied_commits?`(可选 — user/AI 自填)
+- `spec_updates_applied[]`:`{ capability, operation: create|replace|delete }`
+- `handoff_to_backlog[]`:两类来源(`scope_entries` 与 `pause_decisions` chosen_option=3)
 
 ## 禁止行为
 
-- 不允许手工实现 Move/Sync/Rollback 原子化步骤(那是 CLI 内部实现;AI 只调 CLI,不重现 CLI 行为)
-- 不允许在 archive 失败时绕过 verify+review 标记直接 mv 文件
-- 不允许在 `--force` 不被允许的场景(如 hash 不匹配)主动加 `--force` 试图绕过
+- 不允许在 archive 失败时绕过 marker 校验直接 mv 文件
+- 不允许伪造 `.verify-passed` / `.review-passed`(主代理必须真跑 `/forge:verify` + `/forge:review`)
+- 不允许在 schema 不是 v2 时手动改 schema 字段(用 `/forge:verify` 或 `/forge:review` 重写)
 
 ## 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:
+## v3 → v4 marker 升级
 
-| 路径                                                         | 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                                                                                                                                                                                         |
+v3 marker(`forge-verify/v1` / `forge-review/v1`)在 v4 archive 时会被 schema 校验拒。唯一升级路径:**重跑 `/forge:verify` + `/forge:review` 写 v2 marker**(沿 `docs/migration/v3-to-v4.md`)。`forge upgrade --resign-markers` flag 已在 v4 移除。
 
-**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。
+## sync-check manifest fulfillment
 
-## backlog 产物(plan-backlog-registry)
+archive 输出提示 emit 了 sync-check manifest(`forge/.cache/archive-pause-<id>.json` 存在):
 
-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 守门)。
+1. 按 `legacy-bridge-fulfillment` skill fulfill 该 manifest
+2. 跑 `forge legacy-bridge sync-check --apply`
+3. 重跑 `forge archive`(从头跑;v4 删了 `--resume` flag,直接重跑即可。preflight 看到 sync-state 已就绪不会重新暂停)