@accelerator-mzq/forge 1.4.0

package/dist/core/stage-extensions/trend-analyzer.js

@@ -0,0 +1,60 @@
+// trend-analyzer.ts — finding 数量趋势分析
+// plan-stage-extensions Task 2.4
+// 分析最近 3 轮的 block_count 变化趋势,给出中文建议与推荐选项
+/**
+ * 分析收敛轮次历史,判断 finding 数量变化趋势。
+ *
+ * 规则(按优先级顺序):
+ * 1. 历史 < 3 轮 → data_insufficient,推选项 1
+ * 2. 最后 3 轮严格递减(a > b > c) → strict_decrease,推选项 1
+ * 3. 最后 3 轮近平(任意相邻差 ≤ 1) → stable,推选项 2
+ * 4. 最后 3 轮有上升(任意后轮 > 前轮) → increase,推选项 2
+ * 5. 其他(波动) → fluctuate,推选项 3
+ *
+ * @param roundHistory  按 round 升序排列的历史记录
+ */
+export function analyzeTrend(roundHistory) {
+    // 数据不足:历史轮次 < 3
+    if (roundHistory.length < 3) {
+        return {
+            trend: 'data_insufficient',
+            recommendation: '数据不足,建议再跑几轮',
+            recommended_option: 1,
+        };
+    }
+    // 取最后 3 轮
+    const last3 = roundHistory.slice(-3);
+    const [a, b, c] = last3;
+    // 严格递减:a.block_count > b.block_count > c.block_count
+    if (a.block_count > b.block_count && b.block_count > c.block_count) {
+        return {
+            trend: 'strict_decrease',
+            recommendation: '收敛中,建议继续',
+            recommended_option: 1,
+        };
+    }
+    // 近平(stable):所有相邻差 ≤ 1(优先于 increase 判断)
+    if (Math.abs(b.block_count - a.block_count) <= 1 &&
+        Math.abs(c.block_count - b.block_count) <= 1) {
+        return {
+            trend: 'stable',
+            recommendation: '已停滞,建议放弃 codex 介入',
+            recommended_option: 2,
+        };
+    }
+    // 上升:任意后轮 > 前轮
+    if (b.block_count > a.block_count || c.block_count > b.block_count) {
+        return {
+            trend: 'increase',
+            recommendation: 'finding 数上升,建议放弃',
+            recommended_option: 2,
+        };
+    }
+    // 波动(其他情况)
+    return {
+        trend: 'fluctuate',
+        recommendation: '波动,建议接受当前状态计入 backlog',
+        recommended_option: 3,
+    };
+}
+//# sourceMappingURL=trend-analyzer.js.map

package/dist/core/stage-extensions/trend-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trend-analyzer.js","sourceRoot":"","sources":["../../../src/core/stage-extensions/trend-analyzer.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,iCAAiC;AACjC,yCAAyC;AAezC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,YAA2D;IAE3D,gBAAgB;IAChB,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,KAAK,EAAE,mBAAmB;YAC1B,cAAc,EAAE,aAAa;YAC7B,kBAAkB,EAAE,CAAC;SACtB,CAAC;IACJ,CAAC;IAED,UAAU;IACV,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAIjB,CAAC;IAEF,qDAAqD;IACrD,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QACnE,OAAO;YACL,KAAK,EAAE,iBAAiB;YACxB,cAAc,EAAE,UAAU;YAC1B,kBAAkB,EAAE,CAAC;SACtB,CAAC;IACJ,CAAC;IAED,wCAAwC;IACxC,IACE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC;QAC5C,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,EAC5C,CAAC;QACD,OAAO;YACL,KAAK,EAAE,QAAQ;YACf,cAAc,EAAE,mBAAmB;YACnC,kBAAkB,EAAE,CAAC;SACtB,CAAC;IACJ,CAAC;IAED,eAAe;IACf,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QACnE,OAAO;YACL,KAAK,EAAE,UAAU;YACjB,cAAc,EAAE,kBAAkB;YAClC,kBAAkB,EAAE,CAAC;SACtB,CAAC;IACJ,CAAC;IAED,WAAW;IACX,OAAO;QACL,KAAK,EAAE,WAAW;QAClB,cAAc,EAAE,uBAAuB;QACvC,kBAAkB,EAAE,CAAC;KACtB,CAAC;AACJ,CAAC"}

package/dist/core/stage-extensions/types.d.ts

@@ -0,0 +1,39 @@
+import type { StageExtensionsDefaults } from '../schema/types.js';
+/** codex severity → forge 4 级映射类型(从 StageExtensionsDefaults 取) */
+export type SeverityMap = StageExtensionsDefaults['severity_map'];
+/**
+ * codex review JSON 输出中的单个 finding。
+ * 字段与 codex review-output.schema.json 对齐。
+ */
+export interface CodexFinding {
+    /** codex 原始 severity */
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    title: string;
+    body: string;
+    file: string;
+    line_start: number;
+    line_end: number;
+    /** 置信度 0-1 */
+    confidence: number;
+    recommendation: string;
+}
+/**
+ * codex review 完整输出。
+ * `thread_id` 不在 codex JSON schema 中 — 由 helper (Task 3) 从 codex session id 附加,可选。
+ */
+export interface CodexReviewOutput {
+    verdict: 'approve' | 'needs-attention';
+    summary: string;
+    findings: CodexFinding[];
+    next_steps: string[];
+    /** codex session id,由 helper 附加;首轮可能缺失 */
+    thread_id?: string;
+}
+/**
+ * CodexFinding + forge 内部 4 级 severity。
+ * convergence-judge 分桶后产出此类型。
+ */
+export interface ForgeFinding extends CodexFinding {
+    forge_severity: 'BLOCKER' | 'MAJOR' | 'MINOR' | 'NIT';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/stage-extensions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/stage-extensions/types.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAElE,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,uBAAuB,CAAC,cAAc,CAAC,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,SAAS,GAAG,iBAAiB,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,cAAc,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;CACvD"}

package/dist/core/stage-extensions/types.js

@@ -0,0 +1,5 @@
+// types.ts — stage-extensions 共用辅助类型
+// plan-stage-extensions Task 2.0
+// 定义 CodexReviewOutput / CodexFinding / ForgeFinding / SeverityMap 等共用类型
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/stage-extensions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/stage-extensions/types.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,iCAAiC;AACjC,yEAAyE"}

package/dist/core/staging-lock.d.ts

@@ -0,0 +1,36 @@
+/** lock 文件内容 */
+interface StagingLockData {
+    pid: number;
+    acquired_at: string;
+}
+/** 当 staging lock 被另一活进程持有时抛出 */
+export declare class StagingLockHeldError extends Error {
+    readonly holder: StagingLockData;
+    constructor(holder: StagingLockData);
+}
+/** acquireStagingLock 选项 */
+export interface AcquireStagingLockOptions {
+    /** 等待 lock 释放的总超时毫秒(默认 5000) */
+    timeoutMs?: number;
+    /** 重试间隔毫秒(默认 100) */
+    retryIntervalMs?: number;
+}
+/**
+ * acquireStagingLock — 获取 staging 文件锁
+ *
+ * 路径:<changeRoot>/.evidence/.staging.lock(独立于 archive lock)
+ *
+ * 流程:
+ *   1. O_CREAT|O_EXCL 原子创建 lock 文件
+ *   2. 若已存在 — isPidAlive 检测:
+ *      - dead(stale)→ 删 lock 重试
+ *      - alive → 等 retryInterval 重试,直到 timeoutMs 超时抛 StagingLockHeldError
+ *   3. 成功 → 写 {pid, acquired_at}
+ *
+ * @param changeRoot change 根目录
+ * @param options { timeoutMs, retryIntervalMs }
+ * @returns release 函数(幂等)
+ */
+export declare function acquireStagingLock(changeRoot: string, options?: AcquireStagingLockOptions): Promise<() => Promise<void>>;
+export {};
+//# sourceMappingURL=staging-lock.d.ts.map

package/dist/core/staging-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging-lock.d.ts","sourceRoot":"","sources":["../../src/core/staging-lock.ts"],"names":[],"mappings":"AAeA,gBAAgB;AAChB,UAAU,eAAe;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,iCAAiC;AACjC,qBAAa,oBAAqB,SAAQ,KAAK;aACjB,MAAM,EAAE,eAAe;gBAAvB,MAAM,EAAE,eAAe;CAMpD;AAED,4BAA4B;AAC5B,MAAM,WAAW,yBAAyB;IACxC,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAiE9B"}

package/dist/core/staging-lock.js

@@ -0,0 +1,122 @@
+// src/core/staging-lock.ts — plan-9g Task 3.2
+// staging 文件并发保护(brainstorm spec §9.10)
+// 仿 archive lock.ts 模式 — O_CREAT|O_EXCL + isPidAlive stale detection
+//
+// 用途:helper(record-tdd/verify/review)写 staging.yaml 是"读 YAML + 改 array +
+//       重算 hash + 覆写"非原子操作;主代理多 helper 并发(per-task 并行)会 lost update。
+//       wrapper read-modify-write 在 acquireStagingLock → releaseStagingLock 内。
+//
+// 语义差异:archive lock 是 fail-immediately;staging lock 是 wait-retry-timeout
+// (合理因 staging 是 short-lived per-call)
+import { readFile, rm } from 'node:fs/promises';
+import { existsSync, openSync, closeSync, writeSync, mkdirSync, constants } from 'node:fs';
+import { join, dirname } from 'node:path';
+/** 当 staging lock 被另一活进程持有时抛出 */
+export class StagingLockHeldError extends Error {
+    holder;
+    constructor(holder) {
+        super(`another evidence helper is writing staging (pid ${holder.pid}, acquired ${holder.acquired_at})`);
+        this.holder = holder;
+        this.name = 'StagingLockHeldError';
+    }
+}
+/**
+ * acquireStagingLock — 获取 staging 文件锁
+ *
+ * 路径:<changeRoot>/.evidence/.staging.lock(独立于 archive lock)
+ *
+ * 流程:
+ *   1. O_CREAT|O_EXCL 原子创建 lock 文件
+ *   2. 若已存在 — isPidAlive 检测:
+ *      - dead(stale)→ 删 lock 重试
+ *      - alive → 等 retryInterval 重试,直到 timeoutMs 超时抛 StagingLockHeldError
+ *   3. 成功 → 写 {pid, acquired_at}
+ *
+ * @param changeRoot change 根目录
+ * @param options { timeoutMs, retryIntervalMs }
+ * @returns release 函数(幂等)
+ */
+export async function acquireStagingLock(changeRoot, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const retryIntervalMs = options.retryIntervalMs ?? 100;
+    const lockPath = join(changeRoot, '.evidence', '.staging.lock');
+    // 确保 .evidence 目录存在
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const deadline = Date.now() + timeoutMs;
+    let lastHolder = null;
+    while (Date.now() < deadline) {
+        let fd;
+        try {
+            // O_CREAT|O_EXCL 原子创建:若文件已存在则抛 EEXIST
+            fd = openSync(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o644);
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                // lock 已存在;检测 stale
+                try {
+                    const data = JSON.parse(await readFile(lockPath, 'utf8'));
+                    lastHolder = data;
+                    if (!isPidAlive(data.pid)) {
+                        // stale → 删 lock 重试
+                        await rm(lockPath, { force: true });
+                        continue;
+                    }
+                }
+                catch {
+                    // 坏 lock 文件 → 删除重试
+                    await rm(lockPath, { force: true });
+                    continue;
+                }
+                // alive → 等 retryInterval
+                await new Promise((r) => setTimeout(r, retryIntervalMs));
+                continue;
+            }
+            throw err;
+        }
+        // 创建成功 → 通过 fd 写内容(round 2 fix I1):
+        //   - 避免 path-write race window:openSync 后立即用 fd 写,无 empty 中间态
+        //   - 避免 fd leak:try/finally 保证 closeSync 必走;writeSync 抛错 fd 仍关闭
+        const data = {
+            pid: process.pid,
+            acquired_at: new Date().toISOString(),
+        };
+        try {
+            writeSync(fd, JSON.stringify(data, null, 2));
+        }
+        finally {
+            closeSync(fd);
+        }
+        // 返回幂等 release 函数
+        return async () => {
+            if (existsSync(lockPath)) {
+                await rm(lockPath, { force: true });
+            }
+        };
+    }
+    // 超时 → 抛错(用最后一次读到的 holder 数据)
+    if (lastHolder) {
+        throw new StagingLockHeldError(lastHolder);
+    }
+    throw new StagingLockHeldError({ pid: -1, acquired_at: new Date(deadline).toISOString() });
+}
+/**
+ * isPidAlive — 沿 archive lock.ts 同函数
+ *
+ * process.kill(pid, 0) 向进程发信号 0(不实际发信号),仅验证进程是否存在。
+ * - pid <= 0 永远视为 stale(防御性)
+ * - ESRCH:进程不存在 → stale
+ * - EPERM:进程存在但无权限 → 视为 alive
+ */
+function isPidAlive(pid) {
+    if (pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0); // 不发实际信号,仅验证存活
+        return true;
+    }
+    catch (err) {
+        // ESRCH = 进程不存在;其他错误(EPERM)= 进程存在但无权限
+        return err.code !== 'ESRCH';
+    }
+}
+//# sourceMappingURL=staging-lock.js.map

package/dist/core/staging-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging-lock.js","sourceRoot":"","sources":["../../src/core/staging-lock.ts"],"names":[],"mappings":"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"}

package/dist/core/templates/commands/ack-confirm.md

@@ -0,0 +1,32 @@
+---
+description: 主代理读 pending ack file + AskUserQuestion 确认 + 调 forge ack confirm/reject 真正写 marker
+argument-hint: '<change-id> <finding-id>'
+---
+
+You are about to handle `/forge:ack-confirm $ARGUMENTS`。
+
+## 步骤(必须按序)
+
+1. 解析 `$ARGUMENTS` 为 `<change-id>` `<finding-id>` 两参数(若缺,**报错并停止**)
+2. 列出 `forge/changes/<change-id>/.evidence/pending-acks/<finding-id>-*.yaml`(可能多份,取最新)。**若 0 份,报错**:"No pending ack for finding <finding-id>"
+3. 读 pending file 内容,提取 `action / rationale / target_severity` 等字段
+4. **必须用 AskUserQuestion** 让用户确认:
+   - 题目:`Confirm AI ack proposal for finding #<id>`
+   - 选项:
+     - `confirm`(执行 ack action)
+     - `reject`(拒绝 + 让用户写 rationale)
+     - `modify-rationale`(用户改 rationale 后再 confirm)
+5. 根据用户选择:
+   - `confirm` → 调 `forge ack confirm <change-id> <finding-id>`(CLI 写 marker + ack-log + 删 pending)
+   - `reject` → 用 AskUserQuestion 让用户输入 `rejection rationale` → 调 `forge ack reject <change-id> <finding-id> --rationale "<text>"`
+   - `modify-rationale` → 用 AskUserQuestion 让用户输入新 rationale → 重写 pending file → 回到 step 4
+
+## 禁止行为
+
+- 不允许跳过 AskUserQuestion 直接调 confirm(违反 §2.3.3 B 两步协议核心 — user 必须实际看到 + 确认)
+- 不允许在 CI 模式下调用本 slash(CI 应该早在 propose 阶段就被 forge ack propose 拒绝)
+- 不允许直接修改 marker 字段(必须经 forge ack confirm CLI)
+
+## 与其他 forge 协议的关系
+
+本 slash 是 §2.3.3 B 两步 propose/confirm 协议的第二步;第一步由 AI 在 receiving-code-review / verifying-three-dimensions / Fluid Pause Decision Point 等场景 invoke `forge ack propose`(写 pending file + exit 1)触发。

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

@@ -0,0 +1,220 @@
+---
+description: 读 tasks.md 派子代理实施每个 task,顺序模式或 --parallel 模式
+argument-hint: '[--parallel] [--change-id <id>]'
+---
+
+You are about to handle `/forge:apply $ARGUMENTS`.
+
+解析:
+
+- 默认:顺序模式(主工作区直接跑)
+- `--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>`
+   - 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 降级)
+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):
+
+主代理读 `forge/changes/<id>/{proposal, design, tasks, specs/*}.md` 全套,**按 4 类维度逐条检查**(不允许 vague pass-through,沿反向加固):
+
+| 维度   | 检查问题                                                            |
+| ------ | ------------------------------------------------------------------- |
+| 完整性 | tasks 是否覆盖 specs 所有 requirement?(对照 specs requirement 计数) |
+| 顺序   | tasks 依赖关系是否合理?(标 dependency 的 task 是否先于被依赖)       |
+| 清晰度 | 是否有 tasks 描述 vague(如"处理边界情况" / "加测试")?               |
+| scope  | 是否有 tasks 应该是 §2.6 out-of-scope 而非本 change?                |
+
+- **若有 concerns** → AskUserQuestion 列 concerns,等用户决策:
+  - 改 plan(回 propose 修)
+  - 接受当前 plan(继续 dispatch)
+  - 走 §2.5 explore 重新评估
+- **无 concerns** → 主代理**必须显式输出 4 类维度的结论**(可以是"无问题"但按维度逐条说),然后进步骤 4 dispatch
+
+**反向加固**: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 串行协议"段)
+7. 全部 task 完成后,在 tasks.md 末尾追加(parallel 多 commit 用列表):
+   ```yaml
+   applied_commits:
+     - <task-id-1>: <commit-hash>
+     - <task-id-2>: <commit-hash>
+   final_head: <git rev-parse HEAD>
+   ```
+
+## Fluid Pause Decision Point(v1.0,沿 design §2.1)
+
+> **与 `/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 边界"段。
+
+### 触发条件
+
+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 报告 → 主代理判定 severity(CRITICAL / WARNING / SUGGESTION,沿 design §2.3)
+              ↓
+              CRITICAL? → yes → 走 forge 强 fence 拒签(原 v0.4 行为)
+                       → no  → AskUserQuestion 四选项
+                                ↓
+                                用户选择
+                                ↓
+                                1=扩本 change scope → 更新 proposal `## What Changes` + 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)
+                                ↓
+                                marker `pause_decisions` YAML 字段记录(沿 design §2.1.5)
+```
+
+### AskUserQuestion 模板
+
+主代理调 AskUserQuestion(harness 不支持时降级为终端 [1]/[2]/[3]/[4] prompt):
+
+```
+## Implementation Paused
+
+**Change:** <change-id>
+**Task:** <task-id>(<task-summary>)
+**Progress:** N/M tasks complete
+
+### 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 之外的某处确认)
+
+What would you like to do?
+```
+
+### Marker 持久化(沿 design §2.1.5)
+
+**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` 数组:
+
+```yaml
+pause_decisions:
+  - id: 1 # 同一 marker 内唯一
+    paused_at: 2026-05-12T14:30:00Z # ISO 8601 UTC
+    task_ref: tasks.md#task-3 # 关联 task
+    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
+    target_artifact: proposal.md # option=1=proposal.md;option=2=tasks.md;option=3=proposal.md|design.md
+    target_anchor: '## Out of Scope' # marker 记录写到哪个段
+    non_blocking_rationale: 'subagent 可跳过该 issue 完成本 task 主体功能' # option=3 必填
+    other_rationale: null # option=4 必填
+    other_acked_by: null # option=4 必填
+```
+
+### 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:tasks.md 中 `task_ref` 末段对应的行已勾选 `[x]`
+- option=3:proposal/design YAML 块含对应 entry.id + `non_blocking_rationale` 非空
+- option=4:`other_rationale` + `other_acked_by` 非空
+
+## 与其他 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
+
+## 禁止行为
+
+- 不允许主代理直接写代码 — 所有 task 实施必须通过 subagent
+- 不允许 subagent 改 tasks.md(写入是主代理单点串行职责)
+- 不允许跳过 TDD 的 red 步骤(verify 阶段会发现并 append 修复 task)
+
+## 禁止行为(plan-9h §2.8.3 B 主代理 STOP 协议)
+
+主代理 dispatch 阶段必须停下问用户的场景(不允许自动绕过 / 不允许重试,沿 `skills/subagent-driven-development/SKILL.md` §"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`。
+
+## (可选)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 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 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。