@accelerator-mzq/forge 3.1.1 → 4.0.1

package/dist/cli/commands/archive.d.ts

@@ -1,16 +1,27 @@
 import { Command } from 'commander';
 import type { SyncCheckInput } from '../../core/legacy-bridge/sync-check.js';
+/**
+ * Forge archive 命令工厂 — v4 简版(沿 plan §6.1 v9 伪代码)
+ *
+ * 9 步主流程:
+ *   1. forgeRoot + changeId selection
+ *   2. legacy-bridge preflight(可 graceful skip)
+ *   3. spec validate(blocking,永远跑)
+ *   4. marker check + v2 schema validate
+ *   5. task progress confirm(--yes 跳过)
+ *   6. spec deltas(--skip-specs 跳;否则 readDeltas + confirm + applyDeltas)
+ *   7. mv change → archive/<archiveDate>-<changeId>(算一次 archiveDate)
+ *   8. buildArchiveSummary + 写 archive_summary.yaml
+ *   9. legacy-bridge posthook + generateBacklog + appendTraceEvent
+ */
 export declare function buildArchiveCommand(): Command;
 /**
- * preflight 结果 union — caller 在 try 块内根据 kind 手动 release + exit,
- * 与 archive.ts 现有"business-rule fail 处理"convention 一致(line 154 / 160 等)。
+ * preflight 结果 union — caller 根据 kind 退出
  *
  * kind 'ok':可继续 archive(graceful skip / 无 affected anchor / --api 跑完无 critical)
- * kind 'ack-missing':ack 未就绪,caller 应 await release + exit 2
- * kind 'critical-pending':**仅 --api 模式产生** —— 进程内跑 sync-check 后发现
- *   critical pending 差异,sync-state 已写,caller 应 await release + exit 2
- * kind 'halted-for-fulfillment':**仅 agent 模式产生** —— emit manifest +
- *   暂停态文件已写,archive 应 halt,caller await release + exit 2
+ * kind 'ack-missing':ack 未就绪,exit 2
+ * kind 'critical-pending':**仅 --api 模式** —— 进程内跑 sync-check 后发现 critical pending
+ * kind 'halted-for-fulfillment':**仅 agent 模式** —— emit manifest + 暂停态文件已写,exit 2
  */
 export type PreflightResult = {
     kind: 'ok';
@@ -35,27 +46,20 @@ export type PreflightResult = {
  *   4. legacy_bridge.enforce_sync != true
  *   5. 无受影响 anchor / 全部读取失败(buildSyncCheckTask 返 null)
  *
- * 双模式(ack 就绪后):
- *   - **agent 模式(默认,不带 --api)**:emit sync-check manifest 到 .cache +
- *     写暂停态文件 → 返 {kind:'halted-for-fulfillment'},archive halt 等 agent fulfill。
- *   - **--api 模式**:进程内直连 Anthropic API 跑 sync-check + 写 sync-state →
- *     含 critical pending 返 {kind:'critical-pending'};否则返 {kind:'ok'} 续跑 archive。
+ * 双模式:
+ *   - **agent 模式(默认)**:emit sync-check manifest + 暂停态 → halted-for-fulfillment
+ *   - **--api 模式**:进程内直连 API 跑 sync-check + 写 sync-state → critical-pending 或 ok
  *
- * ack 不就绪(两模式共有)→ 返 {kind:'ack-missing'}。
- *
- * **不再调 process.exit / console.error**:caller(archive 命令)负责打印消息 +
- * release archive.lock + exit,避免本函数内 process.exit 跳过 caller finally
- * 导致 archive.lock 文件残留。
+ * ack 不就绪 → ack-missing。
  */
 export declare function runArchivePreflight(forgeRoot: string, changeId: string, opts?: {
     api: boolean;
 }): Promise<PreflightResult>;
 /**
- * Plan 7 §2.5 + Task 6.3:post-archive hook — 不阻塞,仅在 enforce_sync=false 时跑(产报告)。
- * enforce_sync=true 已由 preflight 跑过;graceful skip 路径同 preflight。
+ * Plan 7 §2.5 + Task 6.3:post-archive hook — 不阻塞,enforce_sync=false 时跑(产报告)。
  *
- * agent 模式:emit sync-check manifest(非阻塞,archive 已完成,fulfill 后跑 --apply 出报告)。
- * --api 模式:进程内直连 API 跑 sync-check + 写 sync-state(非阻塞,直接出报告)。
+ * agent 模式:emit sync-check manifest(非阻塞,archive 已完成)
+ * --api 模式:进程内直连 API 跑 sync-check + 写 sync-state(非阻塞)
  *
  * I-2:archiveDate 由 archive 主流程透传(不自己算 new Date(),避免跨午夜偏一天)。
  */
@@ -75,28 +79,23 @@ export declare function emitPreflightSyncCheck(forgeRoot: string, changeId: stri
     kind: 'halted-for-fulfillment' | 'skip';
 }>;
 /**
- * agent 模式:enforce_sync=false 时 post-archive emit sync-check manifest(非阻塞,无暂停态)(Task 6.3)。
+ * agent 模式:enforce_sync=false 时 post-archive emit sync-check manifest(非阻塞)。
  *
  * archive 已完成;fulfill 后跑 forge legacy-bridge sync-check --apply 出报告。
- * 调用前 gate 检查由 runArchivePostHook 负责。
- *
- * @param ctx 已拼好的 SyncCheckInput(可选;不传则内部自拼,供测试直接调用)
  */
 export declare function emitPostHookSyncCheck(forgeRoot: string, changeId: string, ctx?: SyncCheckInput): Promise<{
     kind: 'emitted' | 'skip';
 }>;
 /**
- * Task 6.4:forge archive --resume 的 gate 复核。
+ * Task 6.4:forge archive --resume 的 gate 复核(legacy 留存 — v4 archive 主流程已无 --resume,
+ * 但 tests/cli/legacy-bridge/archive-dualpath.test.ts 直接 import 测试此 gate 逻辑,需保留)。
  *
  * 复核两项:
- * ① 产物绑定 — sync-state 的 produced_from 必须等于暂停态文件的 manifest_hash,
- *              确保 sync-check --apply 产出的 sync-state 确实来自本次 preflight emit 的 manifest。
- * ② critical 幂等重评 — sync-state 中不得有 severity=critical + status=pending 的差异;
- *                       若有,说明 agent 未完全 resolve,不可续跑 archive。
+ * ① 产物绑定 — sync-state.produced_from 必须等于暂停态文件的 manifest_hash
+ * ② critical 幂等重评 — sync-state 中不得有 severity=critical + status=pending 的差异
  *
- * @param forgeRoot forge/ 根目录路径
- * @param changeId  change id(e.g. 'add-pay')
- * @returns { ok: true } 表示 gate 通过;{ ok: false, reason } 表示拒绝并附原因
+ * v4 备注:archive 命令本身不再调用此函数;legacy-bridge sync-check 命令(若有 resume 路径)
+ * 可调用此函数验证 sync-state 绑定。本函数留存为 sync-check 子系统的 building block。
  */
 export declare function resumeArchiveGateCheck(forgeRoot: string, changeId: string): Promise<{
     ok: true;

package/dist/cli/commands/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/archive.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAyD7E,wBAAgB,mBAAmB,IAAI,OAAO,CA6mB7C;AAkBD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,GAAG,EAAE,OAAO,CAAA;CAAmB,GACtC,OAAO,CAAC,eAAe,CAAC,CAiF1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CA6Df;AA0DD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,cAAc,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,wBAAwB,GAAG,MAAM,CAAA;CAAE,CAAC,CAgCtD;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,cAAc,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,CAAC,CAevC;AA8BD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+DvD"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/archive.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAwI7E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAuN7C;AAMD;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,GAAG,EAAE,OAAO,CAAA;CAAmB,GACtC,OAAO,CAAC,eAAe,CAAC,CAuE1B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAwDf;AAkDD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,cAAc,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,wBAAwB,GAAG,MAAM,CAAA;CAAE,CAAC,CA0BtD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,cAAc,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,CAAC,CAUvC;AA8BD;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAqDvD"}