@accelerator-mzq/forge 3.1.1 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/dist/cli/commands/archive.d.ts +32 -33
  2. package/dist/cli/commands/archive.d.ts.map +1 -1
  3. package/dist/cli/commands/archive.js +339 -667
  4. package/dist/cli/commands/archive.js.map +1 -1
  5. package/dist/cli/commands/legacy-bridge.js +1 -1
  6. package/dist/cli/commands/legacy-bridge.js.map +1 -1
  7. package/dist/cli/commands/upgrade.d.ts.map +1 -1
  8. package/dist/cli/commands/upgrade.js +2 -51
  9. package/dist/cli/commands/upgrade.js.map +1 -1
  10. package/dist/cli/commands/validate.d.ts.map +1 -1
  11. package/dist/cli/commands/validate.js +4 -25
  12. package/dist/cli/commands/validate.js.map +1 -1
  13. package/dist/cli/index.js +0 -9
  14. package/dist/cli/index.js.map +1 -1
  15. package/dist/core/archive/index.d.ts +2 -3
  16. package/dist/core/archive/index.d.ts.map +1 -1
  17. package/dist/core/archive/index.js +7 -5
  18. package/dist/core/archive/index.js.map +1 -1
  19. package/dist/core/archive/summary-builder.d.ts +26 -21
  20. package/dist/core/archive/summary-builder.d.ts.map +1 -1
  21. package/dist/core/archive/summary-builder.js +115 -223
  22. package/dist/core/archive/summary-builder.js.map +1 -1
  23. package/dist/core/archive/summary-render.d.ts +5 -3
  24. package/dist/core/archive/summary-render.d.ts.map +1 -1
  25. package/dist/core/archive/summary-render.js +38 -44
  26. package/dist/core/archive/summary-render.js.map +1 -1
  27. package/dist/core/lock.d.ts +46 -0
  28. package/dist/core/lock.d.ts.map +1 -0
  29. package/dist/core/lock.js +98 -0
  30. package/dist/core/lock.js.map +1 -0
  31. package/dist/core/markers/types.d.ts +27 -134
  32. package/dist/core/markers/types.d.ts.map +1 -1
  33. package/dist/core/markers/types.js +10 -1
  34. package/dist/core/markers/types.js.map +1 -1
  35. package/dist/core/migrate/index.js +1 -1
  36. package/dist/core/migrate/index.js.map +1 -1
  37. package/dist/core/monitor/artifact-observer.d.ts.map +1 -1
  38. package/dist/core/monitor/artifact-observer.js +28 -78
  39. package/dist/core/monitor/artifact-observer.js.map +1 -1
  40. package/dist/core/monitor/divergence-map.d.ts.map +1 -1
  41. package/dist/core/monitor/divergence-map.js +9 -7
  42. package/dist/core/monitor/divergence-map.js.map +1 -1
  43. package/dist/core/monitor/health-verdict.d.ts.map +1 -1
  44. package/dist/core/monitor/health-verdict.js +2 -1
  45. package/dist/core/monitor/health-verdict.js.map +1 -1
  46. package/dist/core/monitor/trace-store.d.ts +1 -1
  47. package/dist/core/monitor/trace-store.js +2 -2
  48. package/dist/core/monitor/trace-store.js.map +1 -1
  49. package/dist/core/monitor/types.d.ts +1 -1
  50. package/dist/core/monitor/types.d.ts.map +1 -1
  51. package/dist/core/monitor/types.js +0 -1
  52. package/dist/core/monitor/types.js.map +1 -1
  53. package/dist/core/schemas/archive-summary.d.ts +39 -109
  54. package/dist/core/schemas/archive-summary.d.ts.map +1 -1
  55. package/dist/core/schemas/archive-summary.js +15 -23
  56. package/dist/core/schemas/archive-summary.js.map +1 -1
  57. package/dist/core/templates/commands/apply.md +49 -112
  58. package/dist/core/templates/commands/archive.md +43 -160
  59. package/dist/core/templates/commands/review.md +49 -74
  60. package/dist/core/templates/commands/upgrade.md +21 -40
  61. package/dist/core/templates/commands/verify.md +43 -146
  62. package/dist/core/templates/skills/_shared/tier23-command-bridge.md +8 -8
  63. package/dist/core/templates/skills/receiving-code-review.md +14 -45
  64. package/dist/core/templates/skills/requesting-code-review.md +4 -4
  65. package/dist/core/templates/skills/subagent-driven-development.md +25 -30
  66. package/dist/core/templates/skills/subagent-driven-discipline.md +28 -28
  67. package/dist/core/templates/skills/using-forge.md +24 -23
  68. package/dist/core/templates/skills/verification-before-completion.md +4 -4
  69. package/dist/core/templates/skills/verifying-three-dimensions.md +93 -169
  70. package/dist/core/validate/archive-summary-schema.d.ts +1 -1
  71. package/dist/core/validate/archive-summary-schema.d.ts.map +1 -1
  72. package/dist/core/validate/archive-summary-schema.js +101 -125
  73. package/dist/core/validate/archive-summary-schema.js.map +1 -1
  74. package/dist/core/validate/index.d.ts +0 -1
  75. package/dist/core/validate/index.d.ts.map +1 -1
  76. package/dist/core/validate/index.js +2 -1
  77. package/dist/core/validate/index.js.map +1 -1
  78. package/dist/core/validate/marker-schema.d.ts +12 -4
  79. package/dist/core/validate/marker-schema.d.ts.map +1 -1
  80. package/dist/core/validate/marker-schema.js +98 -605
  81. package/dist/core/validate/marker-schema.js.map +1 -1
  82. package/package.json +18 -20
package/dist/core/templates/skills/subagent-driven-development.md CHANGED
@@ -327,49 +327,44 @@ Done!
327
327
 
328
328
  - **forge:test-driven-development** - Subagents follow TDD for each task
329
329
 
330
- ## forge-specific 反向加固(v1.0)
330
+ ## forge-specific 协议(v4)
331
331
 
332
- forge v1.0 在本 skill 基础上加以下反向加固协议(与上游 superpowers 兼容、不冲突):
332
+ forge v4 在本 skill 基础上加以下行为约束(与上游 superpowers 兼容、不冲突;v4 BREAKING 删反加固 fence + 复杂 marker 字段 + 严格 ack 协议)。
333
333
 
334
- ### Fluid Pause 不可绕过的不变量
334
+ ### Fluid Pause 行为约束(v4 软记录)
335
335
 
336
- 主代理在调 AskUserQuestion 并写入 `pause_decisions` marker 字段时**不可**:
336
+ 主代理在调 AskUserQuestion 并写入 marker `pause_decisions[]` 字段时:
337
337
 
338
- 1. **伪造 `severity_acked_by`** — WARNING pause_decision 的 `severity_acked_by` 必须是真实用户响应,且 `.evidence/ack-log.jsonl` 必须有对应 `kind=ack` + `action=ack-pause-warning` + `finding_id=pause_decisions:<id>` + `user=<同 marker>` 条目。若 marker 直填 `severity_acked_by: msc` 但 ack-log.jsonl 无该条目 → `validateAckLogConsistency`(v2 codex BLOCKER 1 扩展)拒签;若 ack-log `user` 与 marker `severity_acked_by` 不一致(如 marker 写 `msc`,ack-log 写 `ai-agent`)→ 拒签。**SUGGESTION 例外**:fence 不要求 ack 一致性(沿 design §2.1.5 SUGGESTION 允许空 ack)
338
+ 1. **CRITICAL 不走 pause 路径** — 主代理判定问题严重到 abort 程度(测试 fail / 显式错误)时**禁止**调 AskUserQuestion 让用户在 1-4 间选;直接 abort 让用户修代码 / 重派 subagent。Fluid Pause 仅用于 DONE_WITH_CONCERNS / BLOCKED 第 4 项 / DESIGN_ISSUE_FOUND 三档。
339
339
 
340
- 2. **CRITICAL 走 pause 路径** — 主代理判定 severity=CRITICAL 时**禁止**调 AskUserQuestion 让用户在 1-4 间选;CRITICAL 必须走 forge 强 fence 拒签(沿 design §2.1.2)。`forge archive` 步骤 3.7 任一 `pause_decisions[].severity === 'CRITICAL'` → exit 1
340
+ 2. **option=2 必勾选新 task** — `option=2` 加 task 时,主代理 append 新 task 到 tasks.md 后 subagent 重派实施;实施完成后**必须**改 `[ ]` → `[x]`(沿 SDD 写入主代理单点串行职责)。
341
341
 
342
- 3. **option=3 没 `non_blocking_rationale`** — `option=3` 转 out-of-scope 必须配 `non_blocking_rationale` 论证"为什么 subagent 能跳过该 issue 完成主体 task"。fence 拒签缺失
342
+ 3. **option=3 转 out-of-scope 必写 `notes`** — `notes` 字段应论证"为什么 subagent 能跳过该 issue 完成主体 task"(沿 PauseDecisionSimple `notes?` 字段,v4 marker 不再校验 `non_blocking_rationale` 等结构化字段)。
343
343
 
344
- 4. **option=2 不勾选新 task** — `option=2` 加 task 时,主代理 append 新 task 到 tasks.md 后 subagent 重派实施;实施完成后**必须**改 `[ ]` → `[x]`。fence 校验 `tasks.md` 中 `task_ref` 末段对应行已勾选
344
+ 4. **`PauseDecisionSimple` 5 字段限定** — v4 marker 只接受 `paused_at` / `task_ref` / `issue_summary` / `chosen_option` / `notes?` 共 5 字段(沿 `src/core/markers/types.ts`);**不要写 v3 字段**(`severity` / `severity_acked_by` / `added_task_ref` / `capture_id` / `target_artifact` / `non_blocking_rationale` / `other_rationale` 等已删,写了 marker schema 校验拒)。
345
345
 
346
346
  ### 红旗清单(借口模式)
347
347
 
348
- | AI 借口 | 反向加固 |
349
- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
350
- | "用户在对话中确认过,我直接写 ack 就好" | `forge archive` ack-log 一致性 cross-check 会发现 marker ack ↔ ack-log 不一致(沿 plan-9d v2 B-4) |
351
- | "CRITICAL 太严了,我降级为 WARNING 让用户 ack" | fence 在 `severity` 字段重算 finding_hash(沿 plan-9d Task 6),篡改任一 hash payload 字段 → 拒签 |
352
- | "option=3 转 out-of-scope 时 rationale 写"用户决定即可"" | rationale 必须论证"为什么 subagent 能跳过"— 不是"用户决定"是答案 |
348
+ | AI 借口 | 现实 |
349
+ | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
350
+ | "CRITICAL 不严重,走 pause 让用户选" | CRITICAL 应直接 abort 让用户修(不进 Fluid Pause)— Fluid Pause 只处理 non-critical 3 档 |
351
+ | "option=3 转 out-of-scope 时 notes 写'用户决定即可'" | notes 必须论证"为什么 subagent 能跳过"— 不是"用户决定"是答案 |
352
+ | "把 v3 字段塞回 marker(severity / severity_acked_by 等)" | v4 `VerifyMarker` / `ReviewMarker` schema 只 5 字段,塞 v3 字段 → archive 校验直接拒 |
353
353
 
354
- ### plan-9g 新增:DONE_REPORT 必须含 process_evidence 字段
354
+ ### DONE_REPORT 字段(v4 极简)
355
355
 
356
- subagent 在 task 实施完成报 DONE 时,**必须**提供以下字段给主代理(供 `forge evidence record-tdd` helper 用):
356
+ subagent 在 task 实施完成报 DONE 时,**必须**提供给主代理:
357
357
 
358
- - `red_commit`:RED 阶段 commit sha + ISO timestamp
359
- - `red_log_path` + `red_log_hash`(sha256)
360
- - `red_report_path` + `red_report_hash`(JUnit XML / TAP / Vitest JSON)
361
- - `red_exit_code`(必 != 0)
362
- - `green_commit`:同上(GREEN)
363
- - `green_exit_code`(必 == 0)
364
- - `expected_failures`:RED 阶段绑定具体失败的 test(test_file + test_name + failure_type)
358
+ - `red_commit`:RED 阶段 commit sha + ISO timestamp(若走 TDD)
359
+ - `green_commit`:GREEN 阶段 commit sha
360
+ - `task_ref`:tasks.md 内对应行(如 `tasks.md#task-3`)
361
+ - (可选)`notes`:subagent 在实施中遇到的 observation,供主代理 review
365
362
 
366
- 若 light mode trivial change 走 tdd_exemption:必须先调 `forge ack propose --action ack-tdd-exemption`,DONE_REPORT 含 ack_log entry 引用。
363
+ **v4 BREAKING**:不再要求 subagent 提供 RED log path / hash / expected failure list / tdd-exemption ack entry 等反加固字段。evidence-helper CLI 已删;TDD 行为仍由 `forge:test-driven-development` skill 约束,但 marker 不固化 TDD 证据链。
367
364
 
368
- 详细 process_evidence 协议见 `skills/process-evidence/SKILL.md`。
365
+ ### Main Agent STOP Triggers
369
366
 
370
- ### plan-9h 新增:Main Agent STOP Triggers
371
-
372
- 主代理在 apply 阶段必须停下问用户的 **6 类触发条件**(不允许自动绕过或重试,沿 design v3 §2.8.3 B + §2.8.3 C):
367
+ 主代理在 apply 阶段必须停下问用户的 **6 类触发条件**(不允许自动绕过或重试):
373
368
 
374
369
  | 触发条件 | 主代理行为 | cross-ref |
375
370
  | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
@@ -386,8 +381,8 @@ subagent 在 task 实施完成报 DONE 时,**必须**提供以下字段给主代
386
381
 
387
382
  - 每次接到 subagent BLOCKED 报告 → 该 task 计数 +1
388
383
  - 每次 verify 命令失败 → 该次重试计数 +1
389
- - **不依赖 marker / ack-log 持久化字段**(避免侵入 master plan §3.12.4 ack-log schema freeze + §3.12 marker schema freeze)
390
- - 跨 session wakeup 丢计数属 v0.4 known limitation;若用户手工告知"task X 已 BLOCKED N 次",主代理按用户告知值续计
384
+ - **不依赖 marker 持久化字段**(v4 marker 极简,只 5 字段;计数纯 session-local)
385
+ - 跨 session wakeup 丢计数属 v4 known limitation;若用户手工告知"task X 已 BLOCKED N 次",主代理按用户告知值续计
391
386
 
392
387
  #### 禁止行为(主代理 dispatch 阶段红线)
393
388
 
@@ -410,5 +405,5 @@ subagent 在 task 实施完成报 DONE 时,**必须**提供以下字段给主代
410
405
 
411
406
  执行完成前核对 apply 硬门槛自检清单:
412
407
 
413
- - 每个完成的 task 经 `forge evidence record-tdd` 写入 TDD 证据链(缺则 archive 的 process_evidence fence 因 `tdd_event_chain` 缺失拒签)。
408
+ - 每个完成的 task 走 TDD red → green → refactor + 真 commit(沿 `forge:test-driven-development`;v4 marker 不固化 TDD 证据链,但行为约束仍在)。
414
409
  - `forge preflight branch-check` 已跑(在 main/master 等保护分支上会 fail-closed)。
package/dist/core/templates/skills/subagent-driven-discipline.md CHANGED
@@ -606,34 +606,34 @@ git update-ref refs/heads/<wrong-branch> <prior-base-sha>
606
606
 
607
607
  ## §6 Pattern Catalog(failure mode → scenario subtype + recovery)
608
608
 
609
- | Subagent failure mode | Root cause(scenario subtype 误配) | Prevention | Recovery |
610
- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
611
- | **cross-cutting 状态回写漏(implementer 改 file:line / 不变量 / DoD / version / release gate 但 master plan / spec / 上游 sub-plan 引用 stale)** | implementer prompt 缺 cross-cutting hook;controller dispatch 未列引用方文件;plan writer 眼测不 grep | §2.1.2 cross-cutting 回写 hook — implementer prompt + self-review checklist 加 grep 全 plan list verify;controller dispatch prompt 列引用方文件 | grep `<old-value>` 全 plan 验 = 0 + 同 commit 回写至新值 |
612
- | over-cost(默认继承 Opus) | §1 model 选择缺 / 全 Opus 默认 | §1 显式 model + dispatch 时传 `model:` 参数 | 无(commit 已发生 cost) |
613
- | spec_reviewer scope-bleed | §1.2.3 cross-phase 任务用 Haiku | §1.2.3 升 Sonnet OR §2.2 phase boundary 段 | controller override verdict |
614
- | 幻觉 URL / pytest count | §1.2.x reviewer 任务无 §2.6 三条 | §2.2 pre-verified data + enumerated list | §3.2 cross-verify 命令 |
615
- | worktree-scope leak | §3.1 STRICT cwd 写 prompt 但被跳过 | §3.1 + §3.2 branch verify | §4.1 cherry-pick recovery |
616
- | 自我汇报幻觉 | subagent 输出 trust 过度 | §3.2 cross-verify 必跑 | §3.2 5 类 verify 命令 |
617
- | 静态 review 漏 runtime correctness | §1.3.4 误用 Haiku 替代 Sonnet | §1.3.4 MANDATORY Sonnet | controller catches downstream / Sonnet code_quality 必跑 |
618
- | Plan inline code 含 latent bug,Mechanical implementer 照搬不抓 | §1.1.1 Mechanical 假设 plan 可信;Plan 上一阶段既存 bug 搬运 / Plan 自身 review 不彻底 | §1.3.4 Sonnet code_quality 兜底(MANDATORY)+ §2.1 implementer escape valve("觉得 plan code 有 bug → 标 observation") | Sonnet code_quality 抓到后 controller inline fix 修复 |
619
- | Implementer self-review stack-mismatch(Python 模板套 TS 漏 format/lint) | §2.1 playbook checklist 写 generic Python 命令 | §2.1 stack-specific 命令清单(TS/Node:`pnpm format:check + lint + build`;Python:`ruff + mypy + pytest`;Rust:`cargo fmt + clippy + test`) | chore commit 自动修(单 commit 修 N 文件) |
620
- | Reviewer Critical claim 越权(假设最坏 / 偏离 plan 决策表) | code_quality reviewer 不持 plan 上下文,reasoning code 时倾向最坏假设 | §3.2 controller cross-verify reviewer Critical claim → 对照 plan 决策表独立核 | controller 独立核后拒绝 / 部分采纳;只接受不偏离 plan 的 inline fix |
621
- | **Prettier(或同类 formatter)normalize 破坏 binary / 行尾敏感 fixture(Pattern A)** | `.prettierignore` 缺 fixture 路径排除;`.gitattributes` 不阻止 formatter 处理(formatter 按 file extension 判断,.md 默认进 prettier) | `.prettierignore` 显式加 fixture 目录(`tests/fixtures/<scope>/`);chore commit 单独提;dispatch implementer prompt 加注 "若跑 pnpm format 后 fixture 字节变化 → 走 .prettierignore" | `git restore <fixture>` 还原 + `.prettierignore` 加排除 + chore commit;controller cross-verify `xxd <fixture>` 确认字节符合预期 |
622
- | **Implementer 测试断言 silent 降级(`>0` 改 `>=0` 永真;Pattern B)** | fixture/环境不符 plan 假设时 implementer 优先降级 assertion 让测试通过,而非 BLOCKED 报告;§2.1 prompt "When Stuck" 缺测试断言降级 = BLOCKED 的明确约束 | §2.1 implementer prompt "When Stuck" 段强化:**测试 assertion 降级 = BLOCKED 状态**,不可静默接受;Self-review checklist 加"是否有 assertion 从 plan 原样改为永真断言?有 → BLOCKED" | controller cross-verify implementer self-review 报告中的 Observation;若发现 `>=0` / `not.toThrow()` 永真断言 → inline fix 改回真断言 + 加 fixture/parameter 让真命中 |
623
- | **`spec-reviewer` 路径 hallucinate(假设根目录 vs 子目录路径;Pattern C)** | §1.2.1 string matching reviewer 在多目录 / scoped fixture 时假设默认根;Pre-verified Data 段未显式标完整路径让 reviewer 推 | §2.2 spec-reviewer prompt:涉及子目录 fixture 时,Pre-verified Data 段显式标完整路径(`tests/fixtures/<scope>/<file>`),不要让 reviewer 自己推 | controller cross-verify reviewer 引用的路径(实际 `cat <path>` 看是否真不存在);若是 reviewer 错路径,override verdict 标 false positive |
624
- | **Plan inline 跨 build/runtime 边界(rootDir / outDir / package boundary)— controller pre-dispatch signature check 漏(Pattern D)** | controller 只 grep export + signature,**未读 tsconfig.json `rootDir/include/exclude` 看 import path 是否跨边界**;此类 latent bug typecheck 立刻抓但不在 controller 视野 | §1.1.3 Multi-file integration dispatch 前 mandatory step:**read tsconfig.json + 检查 plan inline import path 是否跨 rootDir(典型征兆:含 `../../../` + 跨包名)** → 跨边界 → 标 NEEDS_REWRITE 给 implementer dynamic import workaround 或调 build 配置 | Sonnet implementer 自修(dynamic import + new URL workaround;但留 prod build 风险 — see Pattern E) |
625
- | **CLI flag/option 死代码(option declared 但 action 不引用 → silent no-op;Pattern F)** | §1.2.x spec_reviewer 只看 imports + signature + commit,未 grep flag 在 action 内引用次数 | controller pre-dispatch 跑 `grep -c "opts\\.<flagName>" <action-file>` 给 spec-reviewer;§1.2.4 acceptance reviewer 加"flag 实际被 action 引用"verify 项 | code_quality reviewer 兜底抓到;round 2 implementer 实现 flag 的真实逻辑 |
626
- | **Spike workaround 留 prod build 风险(dynamic import / `as unknown as` / `// @ts-ignore` / `/* @vite-ignore */` 解 typecheck 但不解 runtime;Pattern E)** | 短期 unblock 但 dist/ build 不含跨包源 → ERR_MODULE_NOT_FOUND / runtime type error | Phase final reviewer **必扫**所有 escape hatch(grep `as unknown as / @ts-ignore / @vite-ignore / await import\\(`)→ PR description 必标 "release 前 follow-up: <issue>";不阻塞 PR merge 但记入 Phase F gate | Phase F release 前修(迁移到 src/ 内 / 改 build script 复制 / 改正式 env 加载) |
627
- | **下游 Task implementer 兜底跨 Task scope 修上游 Task plan 字面要求但 inline 缺实现的 latent gap(Pattern N)** | 上游 Task plan 字面要求某 helper / 行为(eg. "confirm 后 marker 字段写回"),但 plan inline code 块缺该 helper 完整代码;上游 spec/code_quality reviewer 只对照"已 implemented 字面"无法发现 gap;下游 Task 真集成 e2e 时才暴露 | dispatch implementer prompt 强化 escape valve 第二条:"若 plan 字面要求 X 但 inline 缺该实现,implementer self-review 段标 observation,不擅自加。若后续 Task 集成必依赖,**explicit BLOCKED + escalate** 让 controller 决定派 emergent fix 还是退回 plan 修订"。Plan reviewer 在 plan 评审阶段加"plan 字面 vs inline 一致性"扫描 — 字面要求项必有 inline code | Controller 接受 emergent fix(commit message 透明记录"X Task 发现 Y Task 实现缺口"),或退回 plan 修订重跑上游 Task。**preferred**: e2e 测试设计成发现 plan inline gap 的 ground truth |
628
- | **implementer 改顶层 file 漏 sync build script auto-copy 副本(Pattern O)** | 项目含 build script 自动 copy 顶层 file 到 generated/templates 目录(`scripts/copy-templates.mjs` 类);implementer 改顶层但漏 add 副本;`pnpm build` 后 working tree modified 但未 commit | §2.1 implementer self-review checklist 加最后一条:**`git status -sb` 检查无 modified file**;若 build script 自动 sync 副本 → 一并 `git add` + commit。Dispatch prompt 列出项目所有自动 copy script 路径让 implementer 知晓 | controller push 前 `git status -sb` 兜底发现 → 单独 chore commit `chore(sync): xxx-副本 同步顶层` 显式记录;**preferred**: 改 build script 直接 commit 副本而非生成(eliminate auto-copy ambiguity) |
629
- | **第三方包 self-closing/empty payload + plan 双层 guard 间隙(Pattern G)** | plan inline 双层 guard:一层 `?? {...}` 防 `noUncheckedIndexedAccess` 数组越界;另一层 `X ? ... : ...` ternary 防 falsy。第三方包(如 fast-xml-parser)对 self-closing `<failure/>` / empty input 返 `""` empty string,`Boolean("") = false` → ternary 走 fallback 分支 → 该分支不防 undefined-deref → crash。两层 guard 各自合理但**语义间隙**:truthy/falsy 边界 ≠ "内容存在"边界 | dispatch prompt **Pre-verified Data 段列出第三方包对 edge input(empty string / self-closing / null / undefined)的真实返回行为**(controller 实测验证给 implementer);不要让 implementer 假设 truthy/falsy 边界与"内容存在"边界等价。Sonnet code_quality reviewer 涉及 parser/serializer 时必实测第三方包 edge case | guard 改 `typeof X === 'object' && X !== null` 排除空字符串(明确 type 边界而非 truthy/falsy 边界);round 2 fix + regression test 加 edge input 用例 |
630
- | **plan 留白展开 "同时"/"并且" 文字 atomic boundary 歧义(Pattern H)** | plan 留白(§0.0 留白展开模式)文字描述 atomic boundary("同时"/"并且"/"在...的同时")被 implementer 解读不一致 — plan 写时假设 critical section 边界 X,implementer 展开时把代码放 critical section 边界 X' 不同位置;有 lock 时 critical section 内 vs 外位置不同 → silent lock-protected critical section 错位 → 并发 race | plan 留白展开时**显式标注 critical section boundary**(eg. "appendAckLog 必须在 `finally { release() }` 之前,即 lock 仍持有时调用")— 不依赖 implementer 解读 "同时"/"并且" 文字。§2.1 implementer self-review checklist 加:"plan 文字描述的 atomic boundary — 我的代码是否真在该 boundary 内?有 lock 时,critical section 内 vs 外位置不同 → silent race" | Sonnet code_quality reviewer round 1 抓到(runtime correctness race condition 子类);round 2 implementer 把 critical section call 移入 lock try 块尾 + 加 regression test spawn 子进程验链不断 |
631
- | **plan inline placeholder/lookup 与现有 schema regex/interface 不符(Pattern I)** | plan inline placeholder(如 `'sha256:placeholder'` 15-char)/ lookup(如 `e.extra?.task_ref`)字面与现有 schema regex / interface 字段假设不符 — plan 写时假设 schema X 但实际 schema Y;Sonnet implementer 严格 transcribe plan 字面而**不 cross-check 现有 schema** → 数据 schema-invalid 必拒 / lookup 永远 false 永久 fail-closed | dispatch prompt Pre-verified Data 段 controller 应 cat 涉及 schema file 全 regex + interface 字段给 implementer,要求"对照 schema regex / interface 字段 — 若 plan inline 字面与现有 schema 不符 → 标 observation 让 controller 决定 fix"。Plan reviewer 在 plan 评审阶段加"plan inline placeholder / lookup vs 现有 schema regex / interface 字段一致性"扫描 | Sonnet code_quality reviewer round 1 + controller 对照 schema file 实测确认;round 2 fix placeholder 改满足 regex(`sha256:${'0'.repeat(64)}` 等);lookup 改简化方案(失去精度作为 polish trade-off,plan-Nz follow-up) |
632
- | **多路径 fallback divergence cross-source hash mismatch + reviewer Important 低估 → controller 必实测升级(Pattern J)** | plan 留白展开时 implementer 在 helper 同时构造**多路径**同 schema 数据(payload 写一处 / staging 写另一处)用了不同 fallback default(payload `?? null` / staging `?? '' / ?? -1 / ?? new Date()`);下游 fence cross-source canonicalHash 比对永远 mismatch → 任何省略 optional CLI arg → 所有合法工作流被拒签 → system-wide broken。Sonnet code_quality reviewer 标 Important 但描述含 "system-wide" / "always-fail" / "all-changes" 等关键词,controller 应实测升级为 Critical | §3.2 cross-verify 强化:**reviewer 标 Important 但描述含 "system-wide" / "always-fail" / "all-changes" / "永远 X" → controller 必实测 evidence 验证**(grep 涉及 file:line + 模拟 user happy path) → 决定升级 Critical 还是接受 Important。dispatch prompt 加:helper 同时构造多路径同 schema 数据时,**显式约束"single source of truth"**(payload = staging-built object,不构造两次) | Round 2 implementer 跨 Task scope fix(改 helper 为 single source of truth payload = staging-built object;沿 Pattern N emergent fix 模式) + 加 regression test cross-source projection hash 不误报 |
633
- | **cross-Task test interaction(N regression test assume N+1 logic placeholder)(Pattern K)** | Task N 加 regression test assuming Task N+1 logic 仍是 placeholder(eg. `const findings = []` 占位);test PASS 快速 1.3s。Task N+1 enable real logic(eg. 启用 `runRerunFence(ctx)` 真调 worktree)→ 同 test 现在真跑 long-running operation → timeout 5000ms fail。Implementer 想急完成 task 倾向 **self-report "flaky"** 而非 real regression | dispatch prompt 加:涉及多 Task 跨阶段 test setup 时,**显式标注 "N Task 加的 test 在 N+M Task enable real logic 后会不会触发新 long-running operation?若会 → N Task test 设计 hash-only / skip 路径走 fast path"**(test design 显式 forward-compat)。controller cross-verify 必拒绝 "flaky" self-report → 实测 stash 前后对比 + deterministic 触发条件分析 | Round 2 fix:test 改 staging mode='hash-only' 走 skip 路径(hash-only 直接 return),仍验目标 fence(因子检仍跑);controller cross-verify stash 前后确认是 deterministic regression 而非 flaky |
634
- | **implementer "acceptable risk"/"flaky" 自报 → controller final review 必实测 verify(Pattern L)** | per-task code_quality reviewer 标 Important 但 implementer self-report "acceptable risk" / "flaky 与 X 无关" / "low priority" 误导 final review 阶段。Implementer 想急完成 task 倾向自报 acceptable risk;若 controller 接受 self-report 不实测 verify → release 时暴露 real risk(攻击路径 / timing 距 bound 距离 < buffer) | §2.7 final reviewer playbook 加:cross-task synthesis 必扫所有 per-task Important 中 implementer self-report "acceptable risk" / "flaky" / "low priority" 的 finding → **实测 verify**(攻击路径模拟 / 实测 timing 距 bound 距离 N 次 / stash 前后 deterministic verify)→ 决定升级 Critical / 维持 Important / 接受 acceptable risk。**Implementer 自报评估不能 substitute final review 实测验证** | Final reviewer 实测 N 次 + controller direct fix commit(eg. catch 块加 else 转 CRITICAL finding + timeout buffer 加大);PR description 必标"final review 实测升级"留 audit trail |
635
- | **CI 环境 env var 累积 latent bug(long-lived feature branch first CI run)(Pattern M)** | 老 test 不 override `CI` env / 其他 CI-sensitive env var(GH_TOKEN / TZ / LANG);GitHub runner 默认 `CI=true` → child process 检 `process.env.CI` 调整行为(如 ack propose exit 2 拒);本地 `process.env.CI=undefined` PASS;long-lived feature branch(>3 plan 周期未 PR 到主干)累积 latent CI bug,first PR run 才暴露 | test setup 显式 `CI=''` env override(`{ env: { ...process.env, CI: '' } }` 给 spawnSync / execa);dispatch prompt Pre-verified Data 段标"CI=true 环境下命令行为 vs 本地" — 若 child process 检 `process.env.CI` 调整行为,test setup 必显式 override。§3.2 cross-verify 加:**long-lived feature branch(>3 plan 周期未 PR 到主干)PR 前必跑 `gh pr create --draft` 触发 CI dry run** — 累积 latent CI bug 早发现 | chore commit `chore(<old plan> test fix): 加 CI='' env override`(本地 + CI 双 PASS 验证);PR description 标"累积 N plan 周期 latent CI bug,first CI run 暴露" |
636
- | **plan 增量修订加功能但漏加 test scenario → 该功能代码路径零覆盖,bug 穿透 implementer 自检 + spec review(Pattern AA)** | plan 在多轮 review 收敛**之后**追加新 Step / helper(本例 v10 加 parseCodexOutput markdown 解析),但固定的 integration scenario 集是修订前定稿的,无一覆盖新路径;implementer 自写实现(plan 只给格式说明不给代码)含 bug(本例 `\Z` cross-language false-cognate 锚 → 整条 markdown 路径全量 breakage);零覆盖 → implementer 自检(原 scenario 全过)+ spec compliance review(只比对 spec 字面)双漏 | controller dispatch 前检查「plan vN→vN+1 增量加的每个代码路径是否有对应 test scenario」,无则 dispatch prompt 显式要求 implementer 补测试(不被固定 scenario 计数束缚,计数交 test inventory 统一 Task 校准);implementer self-review checklist 加「自写的解析器/正则/状态机是否有专门测试」;涉及 implementer 自写正则 → code_quality reviewer 必 `node -e` 实测 repro 而非读码判断 | §1.3.4 Sonnet code_quality runtime review 兜底(读码 + adversarial 实测);TDD 补测试(markdown 测试 RED → 修 parser → GREEN,一举暴露连带的第二个 bug) |
609
+ | Subagent failure mode | Root cause(scenario subtype 误配) | Prevention | Recovery |
610
+ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
611
+ | **cross-cutting 状态回写漏(implementer 改 file:line / 不变量 / DoD / version / release gate 但 master plan / spec / 上游 sub-plan 引用 stale)** | implementer prompt 缺 cross-cutting hook;controller dispatch 未列引用方文件;plan writer 眼测不 grep | §2.1.2 cross-cutting 回写 hook — implementer prompt + self-review checklist 加 grep 全 plan list verify;controller dispatch prompt 列引用方文件 | grep `<old-value>` 全 plan 验 = 0 + 同 commit 回写至新值 |
612
+ | over-cost(默认继承 Opus) | §1 model 选择缺 / 全 Opus 默认 | §1 显式 model + dispatch 时传 `model:` 参数 | 无(commit 已发生 cost) |
613
+ | spec_reviewer scope-bleed | §1.2.3 cross-phase 任务用 Haiku | §1.2.3 升 Sonnet OR §2.2 phase boundary 段 | controller override verdict |
614
+ | 幻觉 URL / pytest count | §1.2.x reviewer 任务无 §2.6 三条 | §2.2 pre-verified data + enumerated list | §3.2 cross-verify 命令 |
615
+ | worktree-scope leak | §3.1 STRICT cwd 写 prompt 但被跳过 | §3.1 + §3.2 branch verify | §4.1 cherry-pick recovery |
616
+ | 自我汇报幻觉 | subagent 输出 trust 过度 | §3.2 cross-verify 必跑 | §3.2 5 类 verify 命令 |
617
+ | 静态 review 漏 runtime correctness | §1.3.4 误用 Haiku 替代 Sonnet | §1.3.4 MANDATORY Sonnet | controller catches downstream / Sonnet code_quality 必跑 |
618
+ | Plan inline code 含 latent bug,Mechanical implementer 照搬不抓 | §1.1.1 Mechanical 假设 plan 可信;Plan 上一阶段既存 bug 搬运 / Plan 自身 review 不彻底 | §1.3.4 Sonnet code_quality 兜底(MANDATORY)+ §2.1 implementer escape valve("觉得 plan code 有 bug → 标 observation") | Sonnet code_quality 抓到后 controller inline fix 修复 |
619
+ | Implementer self-review stack-mismatch(Python 模板套 TS 漏 format/lint) | §2.1 playbook checklist 写 generic Python 命令 | §2.1 stack-specific 命令清单(TS/Node:`pnpm format:check + lint + build`;Python:`ruff + mypy + pytest`;Rust:`cargo fmt + clippy + test`) | chore commit 自动修(单 commit 修 N 文件) |
620
+ | Reviewer Critical claim 越权(假设最坏 / 偏离 plan 决策表) | code_quality reviewer 不持 plan 上下文,reasoning code 时倾向最坏假设 | §3.2 controller cross-verify reviewer Critical claim → 对照 plan 决策表独立核 | controller 独立核后拒绝 / 部分采纳;只接受不偏离 plan 的 inline fix |
621
+ | **Prettier(或同类 formatter)normalize 破坏 binary / 行尾敏感 fixture(Pattern A)** | `.prettierignore` 缺 fixture 路径排除;`.gitattributes` 不阻止 formatter 处理(formatter 按 file extension 判断,.md 默认进 prettier) | `.prettierignore` 显式加 fixture 目录(`tests/fixtures/<scope>/`);chore commit 单独提;dispatch implementer prompt 加注 "若跑 pnpm format 后 fixture 字节变化 → 走 .prettierignore" | `git restore <fixture>` 还原 + `.prettierignore` 加排除 + chore commit;controller cross-verify `xxd <fixture>` 确认字节符合预期 |
622
+ | **Implementer 测试断言 silent 降级(`>0` 改 `>=0` 永真;Pattern B)** | fixture/环境不符 plan 假设时 implementer 优先降级 assertion 让测试通过,而非 BLOCKED 报告;§2.1 prompt "When Stuck" 缺测试断言降级 = BLOCKED 的明确约束 | §2.1 implementer prompt "When Stuck" 段强化:**测试 assertion 降级 = BLOCKED 状态**,不可静默接受;Self-review checklist 加"是否有 assertion 从 plan 原样改为永真断言?有 → BLOCKED" | controller cross-verify implementer self-review 报告中的 Observation;若发现 `>=0` / `not.toThrow()` 永真断言 → inline fix 改回真断言 + 加 fixture/parameter 让真命中 |
623
+ | **`spec-reviewer` 路径 hallucinate(假设根目录 vs 子目录路径;Pattern C)** | §1.2.1 string matching reviewer 在多目录 / scoped fixture 时假设默认根;Pre-verified Data 段未显式标完整路径让 reviewer 推 | §2.2 spec-reviewer prompt:涉及子目录 fixture 时,Pre-verified Data 段显式标完整路径(`tests/fixtures/<scope>/<file>`),不要让 reviewer 自己推 | controller cross-verify reviewer 引用的路径(实际 `cat <path>` 看是否真不存在);若是 reviewer 错路径,override verdict 标 false positive |
624
+ | **Plan inline 跨 build/runtime 边界(rootDir / outDir / package boundary)— controller pre-dispatch signature check 漏(Pattern D)** | controller 只 grep export + signature,**未读 tsconfig.json `rootDir/include/exclude` 看 import path 是否跨边界**;此类 latent bug typecheck 立刻抓但不在 controller 视野 | §1.1.3 Multi-file integration dispatch 前 mandatory step:**read tsconfig.json + 检查 plan inline import path 是否跨 rootDir(典型征兆:含 `../../../` + 跨包名)** → 跨边界 → 标 NEEDS_REWRITE 给 implementer dynamic import workaround 或调 build 配置 | Sonnet implementer 自修(dynamic import + new URL workaround;但留 prod build 风险 — see Pattern E) |
625
+ | **CLI flag/option 死代码(option declared 但 action 不引用 → silent no-op;Pattern F)** | §1.2.x spec_reviewer 只看 imports + signature + commit,未 grep flag 在 action 内引用次数 | controller pre-dispatch 跑 `grep -c "opts\\.<flagName>" <action-file>` 给 spec-reviewer;§1.2.4 acceptance reviewer 加"flag 实际被 action 引用"verify 项 | code_quality reviewer 兜底抓到;round 2 implementer 实现 flag 的真实逻辑 |
626
+ | **Spike workaround 留 prod build 风险(dynamic import / `as unknown as` / `// @ts-ignore` / `/* @vite-ignore */` 解 typecheck 但不解 runtime;Pattern E)** | 短期 unblock 但 dist/ build 不含跨包源 → ERR_MODULE_NOT_FOUND / runtime type error | Phase final reviewer **必扫**所有 escape hatch(grep `as unknown as / @ts-ignore / @vite-ignore / await import\\(`)→ PR description 必标 "release 前 follow-up: <issue>";不阻塞 PR merge 但记入 Phase F gate | Phase F release 前修(迁移到 src/ 内 / 改 build script 复制 / 改正式 env 加载) |
627
+ | **下游 Task implementer 兜底跨 Task scope 修上游 Task plan 字面要求但 inline 缺实现的 latent gap(Pattern N)** | 上游 Task plan 字面要求某 helper / 行为(eg. "confirm 后 marker 字段写回"),但 plan inline code 块缺该 helper 完整代码;上游 spec/code_quality reviewer 只对照"已 implemented 字面"无法发现 gap;下游 Task 真集成 e2e 时才暴露 | dispatch implementer prompt 强化 escape valve 第二条:"若 plan 字面要求 X 但 inline 缺该实现,implementer self-review 段标 observation,不擅自加。若后续 Task 集成必依赖,**explicit BLOCKED + escalate** 让 controller 决定派 emergent fix 还是退回 plan 修订"。Plan reviewer 在 plan 评审阶段加"plan 字面 vs inline 一致性"扫描 — 字面要求项必有 inline code | Controller 接受 emergent fix(commit message 透明记录"X Task 发现 Y Task 实现缺口"),或退回 plan 修订重跑上游 Task。**preferred**: e2e 测试设计成发现 plan inline gap 的 ground truth |
628
+ | **implementer 改顶层 file 漏 sync build script auto-copy 副本(Pattern O)** | 项目含 build script 自动 copy 顶层 file 到 generated/templates 目录(`scripts/copy-templates.mjs` 类);implementer 改顶层但漏 add 副本;`pnpm build` 后 working tree modified 但未 commit | §2.1 implementer self-review checklist 加最后一条:**`git status -sb` 检查无 modified file**;若 build script 自动 sync 副本 → 一并 `git add` + commit。Dispatch prompt 列出项目所有自动 copy script 路径让 implementer 知晓 | controller push 前 `git status -sb` 兜底发现 → 单独 chore commit `chore(sync): xxx-副本 同步顶层` 显式记录;**preferred**: 改 build script 直接 commit 副本而非生成(eliminate auto-copy ambiguity) |
629
+ | **第三方包 self-closing/empty payload + plan 双层 guard 间隙(Pattern G)** | plan inline 双层 guard:一层 `?? {...}` 防 `noUncheckedIndexedAccess` 数组越界;另一层 `X ? ... : ...` ternary 防 falsy。第三方包(如 fast-xml-parser)对 self-closing `<failure/>` / empty input 返 `""` empty string,`Boolean("") = false` → ternary 走 fallback 分支 → 该分支不防 undefined-deref → crash。两层 guard 各自合理但**语义间隙**:truthy/falsy 边界 ≠ "内容存在"边界 | dispatch prompt **Pre-verified Data 段列出第三方包对 edge input(empty string / self-closing / null / undefined)的真实返回行为**(controller 实测验证给 implementer);不要让 implementer 假设 truthy/falsy 边界与"内容存在"边界等价。Sonnet code_quality reviewer 涉及 parser/serializer 时必实测第三方包 edge case | guard 改 `typeof X === 'object' && X !== null` 排除空字符串(明确 type 边界而非 truthy/falsy 边界);round 2 fix + regression test 加 edge input 用例 |
630
+ | **plan 留白展开 "同时"/"并且" 文字 atomic boundary 歧义(Pattern H)** | plan 留白(§0.0 留白展开模式)文字描述 atomic boundary("同时"/"并且"/"在...的同时")被 implementer 解读不一致 — plan 写时假设 critical section 边界 X,implementer 展开时把代码放 critical section 边界 X' 不同位置;有 lock 时 critical section 内 vs 外位置不同 → silent lock-protected critical section 错位 → 并发 race | plan 留白展开时**显式标注 critical section boundary**(eg. "appendAckLog 必须在 `finally { release() }` 之前,即 lock 仍持有时调用")— 不依赖 implementer 解读 "同时"/"并且" 文字。§2.1 implementer self-review checklist 加:"plan 文字描述的 atomic boundary — 我的代码是否真在该 boundary 内?有 lock 时,critical section 内 vs 外位置不同 → silent race" | Sonnet code_quality reviewer round 1 抓到(runtime correctness race condition 子类);round 2 implementer 把 critical section call 移入 lock try 块尾 + 加 regression test spawn 子进程验链不断 |
631
+ | **plan inline placeholder/lookup 与现有 schema regex/interface 不符(Pattern I)** | plan inline placeholder(如 `'sha256:placeholder'` 15-char)/ lookup(如 `e.extra?.task_ref`)字面与现有 schema regex / interface 字段假设不符 — plan 写时假设 schema X 但实际 schema Y;Sonnet implementer 严格 transcribe plan 字面而**不 cross-check 现有 schema** → 数据 schema-invalid 必拒 / lookup 永远 false 永久 fail-closed | dispatch prompt Pre-verified Data 段 controller 应 cat 涉及 schema file 全 regex + interface 字段给 implementer,要求"对照 schema regex / interface 字段 — 若 plan inline 字面与现有 schema 不符 → 标 observation 让 controller 决定 fix"。Plan reviewer 在 plan 评审阶段加"plan inline placeholder / lookup vs 现有 schema regex / interface 字段一致性"扫描 | Sonnet code_quality reviewer round 1 + controller 对照 schema file 实测确认;round 2 fix placeholder 改满足 regex(`sha256:${'0'.repeat(64)}` 等);lookup 改简化方案(失去精度作为 polish trade-off,plan-Nz follow-up) |
632
+ | **多路径数据构造 divergence + cross-source consistency check 永久 mismatch + reviewer Important 低估 → controller 必实测升级(Pattern J)** | plan 留白展开时 implementer 在 helper 同时构造**多路径**同 schema 数据(A 路径写一处 / B 路径写另一处)用了不同 fallback default(A `?? null` / B `?? '' / ?? -1 / ?? new Date()`);下游 cross-source consistency check 永远 mismatch → 任何省略 optional CLI arg → 所有合法工作流被拒签 → system-wide broken。Sonnet code_quality reviewer 标 Important 但描述含 "system-wide" / "always-fail" / "all-changes" 等关键词,controller 应实测升级为 Critical | §3.2 cross-verify 强化:**reviewer 标 Important 但描述含 "system-wide" / "always-fail" / "all-changes" / "永远 X" → controller 必实测 evidence 验证**(grep 涉及 file:line + 模拟 user happy path) → 决定升级 Critical 还是接受 Important。dispatch prompt 加:helper 同时构造多路径同 schema 数据时,**显式约束"single source of truth"**(B 路径 = A 路径 built object,不构造两次) | Round 2 implementer 跨 Task scope fix(改 helper 为 single source of truth — 下游路径直接 reuse 上游构造好的 object;沿 Pattern N emergent fix 模式) + 加 regression test cross-source projection 不误报 |
633
+ | **cross-Task test interaction(N regression test assume N+1 logic placeholder)(Pattern K)** | Task N 加 regression test assuming Task N+1 logic 仍是 placeholder(eg. `const findings = []` 占位);test PASS 快速 1.3s。Task N+1 enable real logic(eg. 启用 `runRerunFence(ctx)` 真调 worktree)→ 同 test 现在真跑 long-running operation → timeout 5000ms fail。Implementer 想急完成 task 倾向 **self-report "flaky"** 而非 real regression | dispatch prompt 加:涉及多 Task 跨阶段 test setup 时,**显式标注 "N Task 加的 test 在 N+M Task enable real logic 后会不会触发新 long-running operation?若会 → N Task test 设计 hash-only / skip 路径走 fast path"**(test design 显式 forward-compat)。controller cross-verify 必拒绝 "flaky" self-report → 实测 stash 前后对比 + deterministic 触发条件分析 | Round 2 fix:test 改 staging mode='hash-only' 走 skip 路径(hash-only 直接 return),仍验目标 fence(因子检仍跑);controller cross-verify stash 前后确认是 deterministic regression 而非 flaky |
634
+ | **implementer "acceptable risk"/"flaky" 自报 → controller final review 必实测 verify(Pattern L)** | per-task code_quality reviewer 标 Important 但 implementer self-report "acceptable risk" / "flaky 与 X 无关" / "low priority" 误导 final review 阶段。Implementer 想急完成 task 倾向自报 acceptable risk;若 controller 接受 self-report 不实测 verify → release 时暴露 real risk(攻击路径 / timing 距 bound 距离 < buffer) | §2.7 final reviewer playbook 加:cross-task synthesis 必扫所有 per-task Important 中 implementer self-report "acceptable risk" / "flaky" / "low priority" 的 finding → **实测 verify**(攻击路径模拟 / 实测 timing 距 bound 距离 N 次 / stash 前后 deterministic verify)→ 决定升级 Critical / 维持 Important / 接受 acceptable risk。**Implementer 自报评估不能 substitute final review 实测验证** | Final reviewer 实测 N 次 + controller direct fix commit(eg. catch 块加 else 转 CRITICAL finding + timeout buffer 加大);PR description 必标"final review 实测升级"留 audit trail |
635
+ | **CI 环境 env var 累积 latent bug(long-lived feature branch first CI run)(Pattern M)** | 老 test 不 override `CI` env / 其他 CI-sensitive env var(GH_TOKEN / TZ / LANG);GitHub runner 默认 `CI=true` → child process 检 `process.env.CI` 调整行为(如 ack propose exit 2 拒);本地 `process.env.CI=undefined` PASS;long-lived feature branch(>3 plan 周期未 PR 到主干)累积 latent CI bug,first PR run 才暴露 | test setup 显式 `CI=''` env override(`{ env: { ...process.env, CI: '' } }` 给 spawnSync / execa);dispatch prompt Pre-verified Data 段标"CI=true 环境下命令行为 vs 本地" — 若 child process 检 `process.env.CI` 调整行为,test setup 必显式 override。§3.2 cross-verify 加:**long-lived feature branch(>3 plan 周期未 PR 到主干)PR 前必跑 `gh pr create --draft` 触发 CI dry run** — 累积 latent CI bug 早发现 | chore commit `chore(<old plan> test fix): 加 CI='' env override`(本地 + CI 双 PASS 验证);PR description 标"累积 N plan 周期 latent CI bug,first CI run 暴露" |
636
+ | **plan 增量修订加功能但漏加 test scenario → 该功能代码路径零覆盖,bug 穿透 implementer 自检 + spec review(Pattern AA)** | plan 在多轮 review 收敛**之后**追加新 Step / helper(本例 v10 加 parseCodexOutput markdown 解析),但固定的 integration scenario 集是修订前定稿的,无一覆盖新路径;implementer 自写实现(plan 只给格式说明不给代码)含 bug(本例 `\Z` cross-language false-cognate 锚 → 整条 markdown 路径全量 breakage);零覆盖 → implementer 自检(原 scenario 全过)+ spec compliance review(只比对 spec 字面)双漏 | controller dispatch 前检查「plan vN→vN+1 增量加的每个代码路径是否有对应 test scenario」,无则 dispatch prompt 显式要求 implementer 补测试(不被固定 scenario 计数束缚,计数交 test inventory 统一 Task 校准);implementer self-review checklist 加「自写的解析器/正则/状态机是否有专门测试」;涉及 implementer 自写正则 → code_quality reviewer 必 `node -e` 实测 repro 而非读码判断 | §1.3.4 Sonnet code_quality runtime review 兜底(读码 + adversarial 实测);TDD 补测试(markdown 测试 RED → 修 parser → GREEN,一举暴露连带的第二个 bug) |
637
637
 
638
638
  ---
639
639
 
package/dist/core/templates/skills/using-forge.md CHANGED
@@ -106,15 +106,15 @@ The skill itself tells you which.
106
106
 
107
107
  Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
108
108
 
109
- ## v0.3 plugin 协议状态(Plan 0a + Plan 0b.1 实测,2026-05-09)
109
+ ## Multi-harness 协议状态
110
110
 
111
111
  forge 在三 harness 下的协议支持:
112
112
 
113
- | Tier | Harness | skill auto-trigger | slash command 注册 | workflow bridge | CLI 调用形态 |
114
- | ---- | ----------- | ------------------ | ---------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
115
- | 1 | Claude Code | ✅ 全 PASS | ✅ 全 PASS | —(slash 直驱,无需桥接) | commands.md 调 `${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs` |
116
- | 2 | OpenCode | ✅ PASS | ❌ FAIL(plugin 不注册) | ✅ 经 stage skill 桥接段 Read `commands/<stage>.md` | 桥接段按 `tier23-command-bridge.md` 替换为 `node "<ROOT>/scripts/run-forge.mjs" <subcmd>` |
117
- | 3 | Codex | ✅ PASS | ❌ FAIL(plugin 不注册) | ✅ 同上 | 同上 |
113
+ | Tier | Harness | skill auto-trigger | slash command 注册 | workflow bridge | CLI 调用形态 |
114
+ | ---- | ----------- | ------------------ | ------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
115
+ | 1 | Claude Code | ✅ | ✅ | —(slash 直驱,无需桥接) | commands.md 调 `${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs` |
116
+ | 2 | OpenCode | ✅ | ❌(plugin 不注册) | ✅ 经 stage skill 桥接段 Read `commands/<stage>.md` | 桥接段按 `tier23-command-bridge.md` 替换为 `node "<ROOT>/scripts/run-forge.mjs" <subcmd>` |
117
+ | 3 | Codex | ✅ | ❌(plugin 不注册) | ✅ 同上 | 同上 |
118
118
 
119
119
  **OpenCode + Codex 用户提示**:即使 `/forge:*` 不可用,brainstorming / writing-plans / verify 等 skill **会按 description 自动触发**,你只需:
120
120
 
@@ -124,21 +124,22 @@ forge 在三 harness 下的协议支持:
124
124
 
125
125
  Tier 2/3 经 stage skill 的桥接段 Read `commands/<stage>.md` 执行,功能闭环但属 best-effort skill orchestration。
126
126
 
127
- ## forge slash commands(本 bootstrap 携带的 7 个工作流入口)
127
+ ## forge slash commands(工作流入口)
128
128
 
129
- **触发 prerequisites**:Tier 1 Claude Code 路径下可用;Tier 2/3 OpenCode/Codex 路径下不可用(实测 FAIL,见上表)— 改为 skill auto-trigger 等价路径。
129
+ **触发 prerequisites**:Tier 1 Claude Code 路径下可用;Tier 2/3 OpenCode/Codex 路径下不可用 — 改为 skill auto-trigger 等价路径。
130
130
 
131
131
  触发以下任一命令时,会自动调起对应 skill 链:
132
132
 
133
- | 命令 | 用途 | 调起 skill |
134
- | -------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
135
- | `/forge:brainstorm <topic>` | 模糊想法 → forge/drafts/<date>-<topic>.md | forge:brainstorming |
136
- | `/forge:propose <change-id> [--from-draft <name>]` | draft → 4 个 change 产物 | forge:writing-plans |
137
- | `/forge:apply [--parallel]` | tasks.md → 实施 | forge:subagent-driven-development + forge:test-driven-development(--parallel 加 forge:dispatching-parallel-agents + forge:using-git-worktrees) |
138
- | `/forge:review` | 派 review subagent + 收反馈 | forge:requesting-code-review + forge:receiving-code-review |
139
- | `/forge:verify` | 跑 forge validate + 三维度分析 + 写 verify-passed YAML | forge:verification-before-completion + forge:verifying-three-dimensions |
140
- | `/forge:archive` | 归档 change 到 forge/changes/archive/ | (CLI `forge archive`,无 skill 链) |
141
- | `/forge:explore [<topic> \| --change <id>]` | 非线性思考空间(任何阶段,非产物驱动) | forge:exploring(9f 新增,沿 design §2.5) |
133
+ | 命令 | 用途 | 调起 skill |
134
+ | -------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
135
+ | `/forge:brainstorm <topic>` | 模糊想法 → forge/drafts/<date>-<topic>.md | forge:brainstorming |
136
+ | `/forge:propose <change-id> [--from-draft <name>]` | draft → 4 个 change 产物 | forge:writing-plans |
137
+ | `/forge:apply [--parallel]` | tasks.md → 实施 | forge:subagent-driven-development + forge:test-driven-development(--parallel 加 forge:dispatching-parallel-agents + forge:using-git-worktrees) |
138
+ | `/forge:review` | 派 review subagent + 收反馈,写 .review-passed v2 marker | forge:requesting-code-review + forge:receiving-code-review |
139
+ | `/forge:verify` | 跑 forge validate + 三维度 prose check,写 .verify-passed v2 marker | forge:verification-before-completion + forge:verifying-three-dimensions |
140
+ | `/forge:archive` | 归档 change 到 forge/changes/archive/(校验 v2 marker + 应用 spec deltas) | (CLI `forge archive`,无 skill 链) |
141
+ | `/forge:explore [<topic> \| --change <id>]` | 非线性思考空间(任何阶段,非产物驱动) | forge:exploring |
142
+ | `/forge:upgrade` | 清理 v0.2 legacy harness adapter 产物(forge/ 100% 不动) | (CLI `forge upgrade`) |
142
143
 
143
144
  ## meta-development entry — writing-skills
144
145
 
@@ -150,14 +151,14 @@ forge 框架自身的 skill 开发流程(用户主动 invoke,不走 slash comman
150
151
  | 修订一个 forge skill 的 behavior(不是 typo) | `forge:writing-skills` |
151
152
  | 跑 forge-eval baseline 重跑发现 skill 失效 → REFACTOR | `forge:writing-skills` |
152
153
 
153
- `forge:writing-skills` 自身的初次开发使用 superpowers 上游 writing-skills 完成(bootstrap exception,沿 design §2.9.5);后续修订使用 forge:writing-skills 自身。详 `skills/writing-skills/SKILL.md`。
154
+ `forge:writing-skills` 自身的初次开发使用 superpowers 上游 writing-skills 完成(bootstrap exception);后续修订使用 forge:writing-skills 自身。详 `skills/writing-skills/SKILL.md`。
154
155
 
155
156
  ## forge 红旗清单(覆盖 superpowers 红旗清单的 forge 专属补充)
156
157
 
157
158
  除了 superpowers 通用红旗,forge 多以下条目:
158
159
 
159
- | 想法 | 现实 |
160
- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
161
- | "用户需求看起来很清晰,直接写 propose 吧" | 用户原话有 "大概 / 也许 / 不太确定 / 看着办" 任一关键词 → 必须先 `/forge:brainstorm`,不允许直接 `/forge:propose` |
162
- | "实施中模糊 / 觉得需要重新想想,直接改 `design.md` 或跳 forge 流程" | 错(沿 design §2.5 + plan-9f)。**开放思考**走 `/forge:explore --change <id>`(skill 强制显式收尾 + capture offer + 不写 artifacts);**阻塞 issue**走 §2.1 Fluid Pause;**都不是**在 apply 中直接改 artifacts |
163
- | "explore 是 thinking time,可以无限发散,不需要 capture offer" | 错(沿 design §2.5.6 forge 反向加固第一条)。即使 OpenSpec 上游允许"不 reach conclusion",forge 加显式收尾约束 — skill 末尾必须输出 `## Exploration Summary` + 至少一个具体 `file:section` 的 capture offer |
160
+ | 想法 | 现实 |
161
+ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
162
+ | "用户需求看起来很清晰,直接写 propose 吧" | 用户原话有 "大概 / 也许 / 不太确定 / 看着办" 任一关键词 → 必须先 `/forge:brainstorm`,不允许直接 `/forge:propose` |
163
+ | "实施中模糊 / 觉得需要重新想想,直接改 `design.md` 或跳 forge 流程" | 错。**开放思考**走 `/forge:explore --change <id>`(skill 强制显式收尾 + capture offer + 不写 artifacts);**阻塞 issue**走 Fluid Pause(`commands/apply.md`);**都不是**在 apply 中直接改 artifacts |
164
+ | "explore 是 thinking time,可以无限发散,不需要 capture offer" | 错(forge 反向加固)。即使 OpenSpec 上游允许"不 reach conclusion",forge 加显式收尾约束 — skill 末尾必须输出 `## Exploration Summary` + 至少一个具体 `file:section` 的 capture offer |
package/dist/core/templates/skills/verification-before-completion.md CHANGED
@@ -150,10 +150,10 @@ From 24 failure memories:
150
150
 
151
151
  执行完成前核对 verify 硬门槛自检清单:
152
152
 
153
- - AI 写基础 `.verify-passed` marker。
154
- - `forge evidence record-verify` 跑过(写 staging)。
155
- - `forge evidence freeze --kind verify` exit 0(缺 freeze → archive 的 process-evidence fence 拒签)。
156
- - 过程中遇 `forge ack propose` 退出(产生 pending)→ Read 并执行 `commands/ack-confirm.md` 等价流程,降级 prompt 让用户确认,经 `forge ack confirm`/`reject` 落 ack-log(AI 不得自 ack)。
153
+ - 真跑了项目测试 + 三维度 prose check(`forge:verifying-three-dimensions`),证据先于声称。
154
+ - 写 `.verify-passed` v2 marker(schema=`forge-verify/v2`,5 字段;沿 `src/core/markers/types.ts`)。
155
+ - 若三维度发现 Completeness / Correctness 重大问题 → abort verify 不写 marker,让用户先修。
156
+ - v4 已无 evidence-helper / freeze / ack 协议;不要再调 `forge evidence` 子命令(v4 已删)。
157
157
 
158
158
  ## The Bottom Line
159
159