v4.0.2 — wrapper Windows ^4.0.0 escape critical 修

critical hotfix:v4.0.1 通过 wrapper 调的 CLI Windows 用户永远是 v4.0.0(文件层 plugin 改动生效但 CLI 改动拿不到)。本 release 修。

根因(第 3 个同根 bug)

scripts/run-forge.mjs:24 --package @accelerator-mzq/forge@^4.0.0 + spawn { shell: true }(Windows 必须,Node 21+ CVE-2024-27980)
→ 走 cmd.exe 解析 → cmd.exe 把 ^ 当 escape character 吃掉
→ npx 收到 @accelerator-mzq/forge@4.0.0 精确版本(不是 semver range)→ 永远拉 4.0.0

修法(1 行 + 4 处版本号)

REQUIRED_RANGE: '^4.0.0' → '4.x'(等价 >=4.0.0 <5.0.0,字符全 cmd-safe 字母数字 + 点)。Linux/macOS 不受影响。跨 major bump(4→5)时改 5.x。

同根 3 bug 完整状态(v4.0.2 后)

Bug	shell:true → cmd.exe 干扰具体表现	状态
JSON 花括号被吃 → record_error	解析 {} 引号嵌套	✅ v4.0.1 workaround --json-file
Config build_prompt 引号嵌套乱 → codex 失焦	双重 escape 引号	✅ v4.0.1 workaround config + preflight
^4.0.0 被 escape → 永远拉 4.0.0	^ 当 escape char 吃掉	✅ v4.0.2 修(本 release)

三同根 bug 全部 covered。根因 shell: true 本身未根治(Node 21+ 强制要求),需重写 wrapper 走 spawn node + dist/cli/index.js 绕 .cmd 中间层 — 留 follow-up,scripts/build-bundled-plugin.mjs 已有 pattern 参考。

升级

• npm:npm i -g @accelerator-mzq/forge@4.0.2
• plugin:/plugin marketplace update accelerator-mzq-forge(plugin 文件层升级到 v4.0.2 后,wrapper 用新 REQUIRED_RANGE,下次 wrapper 调能拉到 latest 4.x)

完整改动见 CHANGELOG.md#402---2026-05-21。

v4.0.1 — Tier 2/3 onboarding + Windows monitor 修补

累积 5 PR 的 Tier 2/3 用户实测踩坑收敛 + Windows 兼容性修复。无功能新增,全 docs / bootstrap / onboarding / Windows compat 改进。

5 PR 主线

• #59(de17b0e)OpenCode 工具映射 + Codex/OpenCode 平台说明
• #60(9656f8e)CLAUDE.md/AGENTS.md 同步 v4 现状(v4.0.0 release 遗漏)
• #61(1f10db8)OpenCode 自动注入 workflow-monitor + injection harness-agnostic
• #62(aa6bf82)stage-extensions onboarding 三件套(preflight check + docs + migration doc)
• #63(42a30b3)monitor record --json-file flag 绕 Windows cmd.exe quoting

关键能力

• forge preflight stage-extensions-check 新子命令 — 扫 forge/config.yaml#stage_extensions 漏 --user-focus / --target-label 等常见漏洞(loose 模式不阻塞)
• forge monitor record --json-file <path> — Windows 用户绕 cmd.exe 引号嵌套,解 100% record_error bug
• docs/migration/setup-stage-extensions.md — 271 行 onboarding checklist(新项目 6-step setup + 已有项目检测 + 5 stage user-focus 文本设计 + FAQ)
• OpenCode workflow-monitor 自动注入 — .opencode/plugins/forge.js 加 monitor inject 逻辑,对齐 Tier 1 SessionStart hook 行为

升级说明

v4.0.0 → v4.0.1 是 patch release,无 BREAKING change:

• npm i -g @accelerator-mzq/forge 或 pnpm i -g @accelerator-mzq/forge
• 或 plugin 路径:/plugin install forge@accelerator-mzq-forge(marketplace 自动拉新版)

Release Gate

本地 7 步全绿:typecheck / lint / format / build / vitest(1082 pass / 1 skipped)/ pack(tarball 0.58 MB / 699 文件)/ dry-install(forge --version 4.0.1)/ brownfield。CI 双平台 ubuntu + windows 同样全绿。

完整改动见 CHANGELOG.md#401---2026-05-21。

v4.0.0 — OpenSpec alignment (BREAKING)

forge v4.0.0 是设计哲学整体转向 —— 从反向加固协议变为 OpenSpec 简洁对齐。

完整迁移指南:docs/migration/v3-to-v4.md
完整 CHANGELOG:CHANGELOG.md [4.0.0]

BREAKING(关键)

• 反加固协议整删:13 fence、三级 severity、ack 两步、process-evidence freeze、ack-log 完整性链、transaction 五阶段 atomic、resign-markers(净删 ~13000 行)
• CLI 子命令整删:forge ack / forge evidence / forge pause-capture / /forge:ack-confirm slash
• marker schema v1 → v2:VerifyMarker / ReviewMarker / archive_summary 全部 v2 极简
• forge archive flag 改造:新增 --yes / --skip-specs(沿 OpenSpec);删 --recover / --resume-summary / --resume
• forge upgrade 删 --resign-markers flag
• forge monitor:archive 事件名 fence_observed → archive_summary_observed;MonitorStage 删 'ack-confirm'

v3.x → v4.0 升级 checklist

# 1) 对每个 active change 清 v3 反加固残留
rm -rf forge/changes/<id>/.evidence/pending-acks/
rm -f forge/.cache/archive-pause-<id>.json
rm -f forge/changes/<id>/.evidence/process-evidence.staging.yaml

# 2) 升级 forge
pnpm update -g @accelerator-mzq/forge   # 或 plugin marketplace 升级

# 3) 重跑 verify/review 写 v2 marker
/forge:verify --change-id <id>
/forge:review --change-id <id>
/forge:archive --change-id <id>

详见 docs/migration/v3-to-v4.md §3。

Verification

• pnpm test:1074 pass / 0 fail / 1 skipped(测试从 192 简至 152 文件)
• pnpm release:gate:7 步全绿(typecheck/lint/format/build/vitest/pack/dry-install + tarball-size + tarball-content + brownfield)
• forge --version 输出含 4.0.0
• bundled tgz 0.68 MB

Plan

完整设计 plan + 11 轮 Codex 对抗 review:docs/plans/2026-05-20-plan-v4-openspec-alignment.md

Assets

• forge-bundled-v4.0.0.tgz — 离线分发 plugin 包(无需 npm 即可在 Claude Code 安装:/plugin install --from-tarball <path>)

🤖 Generated with Claude Code

v3.1.1 — 修发布包资产 / fence 段名 / FORGE_VERSION 漂移

Fixed

• npm 发布包补全 stage-extensions 运行时资产:package.json#files 此前仅含 dist/,导致 scripts/codex-review-helper.mjs 与 src/core/codex-review/prompts/adversarial-default.md 未进发布包,3.0.0 / 3.1.0 所有 npm 用户在 stage-extensions 5 个 stage 调 codex review / adversarial 都会因 helper 路径不存在或 prompt 模板缺失而失败。本版补齐两个资产到 files 字段;并在 release-gate 的 tarball 内容检查改用 npm pack --dry-run(跨平台),新增 helper + 模板必含断言,堵住「Windows 跳过」缺口。
• bundled plugin tgz 同步补齐 codex 资产:scripts/build-bundled-plugin.mjs 现额外拷 scripts/codex-review-helper.mjs 与 src/core/codex-review/ 到 staging,bundled 离线分发形态也能跑 stage-extensions。
• pause_decisions fence 与 proposal 段名对齐:src/core/archive/pause-decisions-fence.ts option=1(扩 scope)的 target_anchor 字段校验与 diff 段定位正则从 What Changes 改为 What,与 forge validate 要求的 ## What proposal 段名一致(此前 fence 死代码,marker 注释 / 模板 / fixture 仍用 OpenSpec 旧名 ## What Changes,option=1 扩 scope 路径在 forge 3.x 下无法通过 archive)。同步收尾 `commands/apply.md`、`skills/exploring/SKILL.md`、`docs/getting-started.md`、`src/core/markers/types.ts` 注释及 13 个 pause-decisions 测试 / fixture。
• `FORGE_VERSION` 漂移污染产物(release-gate 拦下):`src/index.ts:3` 此前硬编码 `FORGE_VERSION = '1.3.0'`,自 2026-05-16 漂移 —— 不仅 `forge --version` 显示错,更关键是被写进 archive marker / legacy-bridge handoff manifest 的 `forgeVersion` 字段(`legacy-bridge.ts:954`、`archive.ts:1006/1051`),v3.0.0 / v3.1.0 所有用户 archive 产物 / handoff manifest 写的 `forgeVersion: '1.3.0'` —— 数据完整性问题。本版改为动态读包根 `package.json#version`,根治漂移,版本号同步唯一源是 `package.json`。
• docs:`docs/codex-review.md` Quick Start 的 `codex-adversarial` 示例补 `build_prompt` + `command --prompt-file`(此前示例缺 `build_prompt`,helper `run --mode adversarial` 强制要求 `--prompt-file`,照抄示例直接报错)。
• docs:`docs/getting-started.md` 第 2 步加「4 件套格式速查」,展示 forge 3.x 的 `## What` proposal 段名、`## Scenario:` H2 spec scenario、`- [ ] :` tasks 行三种正确格式。

完整 changelog 见 CHANGELOG.md。

v3.0.0 — pause-fence 段级校验

BREAKING

• option=2(Fluid Pause 加 task)归档校验加固:archive fence 现要求 option=2 的 pause_decision 携带 added_task_ref + capture_id,并在 ack-log hash-chain 中匹配一条 forge pause-capture entry。发布前已 verify/review 但未 archive、且 apply 期未走过 forge pause-capture 的 option=2 change 会被 archive 拒签。 受影响 change 由用户人工处理(将该 pause_decision 改判为 option=4 Other 并补 other_rationale/other_acked_by,或人工接受后另行归档)—— fence 不开自动放行口子。

安装

npm i -g @accelerator-mzq/forge@3.0.0

Full Changelog: v2.0.0...v3.0.0

v2.0.0 — legacy-bridge 双路径执行模型

Added

• legacy-bridge Layer 3b:forge legacy-bridge extract —— 从老文档抽取需求条目并接入 backlog registry 第二数据源

Changed

• BREAKING forge legacy-bridge 的 map/index/regenerate/sync-check 四命令默认改为 agent 模式(emit Task manifest,需 fulfill 后跑 --apply)。--api flag 切回原进程内 SDK 行为。详见 docs/specs/2026-05-18-legacy-bridge-dual-path-exec-design.md。

Full Changelog: v1.4.0...v2.0.0

v1.4.0 — 文档补全与版本对齐

Fixed

• 文档:docs/cli-reference.md 补全到当前 16 个 CLI 子命令全集 —— 此前停留在 v0.3 的 7 命令快照,缺 migrate / ack / evidence / finding / scope / preflight / backlog;CLAUDE.md / AGENTS.md 的「14 子命令」与 getting-started.md 的「13 子命令」计数同步更正为 16,并清理 getting-started.md 内「v1.1 新 CLI 段待下轮补」的失效提示。
• 文档:docs/migration/from-openspec.md §2.3 与 docs/migration/from-superpowers.md §4.3 的 --dry-run 说明更正为占位 stub 的真实行为(此前描述的 plan 预览 / missing-preview / cost estimate 输出尚未实现)。
• 版本对齐:.claude-plugin/plugin.json / .codex-plugin/plugin.json / .claude-plugin/marketplace.json 的 plugin version 及 scripts/run-forge.mjs 的 REQUIRED_RANGE 此前停留在 plugin 形态引入时的 0.3,与 npm 包 / git tag 的 1.x 线脱节;现统一对齐到 1.4.0(REQUIRED_RANGE → ^1.4.0),修复 plugin helper 按 ^0.3 永远拉不到 1.x CLI 的问题。
• 文档:docs/getting-started.md 第 0 步补充 forge CLI 安装说明 —— plugin 安装不提供 PATH 上的 forge,而第 3 步 forge preflight 需在 shell 直接调用;补 pnpm dlx / npm i -g 两种获取方式。
• 文档:docs/claude-install.md / docs/codex-install.md / docs/opencode-install.md 与 skills/writing-plans 中过时的 @accelerator-mzq/forge@0.3.0 / @^0.3 引用更正 —— 全局安装命令改为不钉版本,helper 范围对齐 ^1.4.0。

Added

• 文档:docs/migration/from-openspec.md 新增 §7「项目同时含 OpenSpec 与 superpowers」—— 此前两份迁移文档均未覆盖双 source 项目;新节说明须串行跑两遍 forge migrate,并提示两遍之间备份 migrate-report.md / migrate-trace.json(固定文件名,第二遍会覆盖第一遍)。from-superpowers.md 加 §8.8 对应 FAQ 指针。
• 文档:新增 docs/migration/from-existing-project.md —— 已有 OpenSpec / superpowers 项目接入 forge 的端到端教程(安装 → forge migrate → 验收产物 → 从 /forge:apply 接入主流程 → cleanup)。补上 getting-started.md(从空目录起步)未覆盖的「已有项目」入口;getting-started.md 与两份 from-*.md 加交叉指针。§4.2 增「让 AI agent 补缺件代替 --regenerate」一节,说明 --no-regenerate + agent 手补的免 API key 路径及与 --regenerate 的 fidelity 校验差异。
• forge/config.yaml 新增 model_tiers 配置:把 forge:subagent-driven-discipline §1 的 haiku/sonnet model tier 重映射到实际派发模型(默认恒等、不改变现状)。forge config set model_tiers.<tier> <model> 写入。仅对直接传 model 参数的 harness(如 Claude Code)生效;把 haiku/sonnet 档映射到更强模型会抬高 token / 调用成本。opus 档不可重映射。

Changed

• forge:subagent-driven-development 的 model 选型不再内联 matrix,改为指向 forge:subagent-driven-discipline §1 + model_tiers 配置(消除两 skill 的 model tier 摘要漂移)。forge:subagent-driven-discipline 的 §1 haiku/sonnet/opus 明确为 tier 标签,## Platform Note 措辞修正(区分跨 harness 与跨模型 provider)。
• package.json 新增 prepublishOnly 脚本(npm publish 前自动 pnpm build),避免漏构建发出缺 dist/ 的包。

Full Changelog: v1.3.0...v1.4.0

v1.3.0 — workflow-monitor + subagent-driven-discipline

Added

• workflow-monitor:低耦合旁路工作流监控观察者。forge monitor enable 开启后,记录 forge 每阶段状态与动作选择,与 OpenSpec/superpowers 静态差异映射表对比做回归探测; forge monitor report 渲染 markdown 报告。详见 docs/specs/2026-05-15-workflow-monitor-design.md。
• subagent-driven-discipline:移植 superpowers:subagent-driven-development 的第三方 companion skill 为 forge plugin 第 17 个 skill forge:subagent-driven-discipline —— subagent 任务类型 taxonomy + cheap-model 可靠性 playbook + Trigger Type Matrix retrospect。净化掉 27+1 条项目锚点(§5 case study 全清、实证叙事删除、真实路径/变量/codex 命令占位符化、出处中性化),作为零项目信息的 generic 工作流初始技能。补全 subagent-driven-development / writing-plans 早已假定存在的依赖;并让 forge:subagent-driven-development 在 dispatch 前条件调用此 companion skill(配对闭环)。详见 docs/specs/2026-05-16-subagent-driven-discipline-port-design.md。

Full Changelog: v1.2.0...v1.3.0

v1.2.0 — stage-extensions framework

plan-stage-extensions-framework:forge core 通用 stage-level extension runner —— 预置 codex review/adversarial 作 default entries(Tier 1 Claude Code only;generic ExtensionContract 留 v2/v3 refactor)。plan 经 9 轮 Codex 对抗性 review 收敛(累计 21 finding:3 BLOCKER + 16 MAJOR + 2 MINOR 全独立核实为真问题、全 accept);实施(Task 5-9)经 superpowers:subagent-driven-development SDD —— 每 Task fresh implementer subagent → spec compliance reviewer → code quality reviewer 三阶段。

Added

• Stage Extensions Framework:stage_extensions config 段 —— forge core 通用 stage-level extension runner(v7 CLI/AI 职责分层:CLI 纯机械单轮执行,多轮收敛 / 交互 / 派 subagent 归 AI 主代理协议)。
• CLI:forge stage-extensions 子命令组 —— run(单轮执行器:spawn codex + watch + parse + judge + retry,显式 RoundOutcome 状态机,结构化 JSON 输出)+ analyze-trend(收敛趋势分析)。runner 永远 exit 0(loose,不阻塞主流程 fence)。
• Core:src/core/stage-extensions/ 6 模块(severity-mapper / convergence-judge / thread-map / trend-analyzer / output-watcher / state-machine)+ src/core/schema/ config schema + validator + src/core/codex-review/prompts/adversarial-default.md 通用模板(B-full Task 0 已 ship)。
• Commands:commands/*.md 5 处末尾段(brainstorm / propose / apply / review / verify)—— AI 主代理多轮收敛协议(反复调单轮 runner + AskUserQuestion 介入 + Task dispatch fix subagent);新 slash 命令 commands/codex-adversarial.md(B-full Task 0 已 ship)。
• Helper:scripts/codex-review-helper.mjs 扩展 —— --thread-id resume / mode 多分支(code-review / adversarial / rescue);harness-agnostic。
• Docs:docs/stage-extensions.md(framework 协议)+ docs/codex-review.md(codex 预置 extension 用户指南)+ docs/getting-started.md 嵌入 deep-dive + README.md 更新。
• Tests:全 suite 1115 tests pass / 0 fail(Task 0-4 基线 1069 + Task 5 runner +21 integration + Task 6 commands sync +25 integration)。

Notes

• forge 协议层 SKILL.md 0 改动:stage-extensions framework 不触碰 forge 协议层 skills(skills/*/SKILL.md)—— 多轮收敛 / askUser / fix dispatch 落在 commands 末尾段(v7 CLI/AI 职责分层),协议层纯净。
• loose 语义:codex 集成任何失败(spawn 失败 / retry 耗尽 / config 非法 / markdown 解析失败)都不阻塞 forge 主流程 fence;runner 永远 exit 0。

Codex Review 收敛

plan 经 9 轮 Codex 对抗性 review 收敛,首轮(v2)7 个 finding 全 accept 修订:

• F1(BLOCKER):runner 变量作用域 + 控制流隐患 → §7 重写为显式 RoundOutcome 状态机。
• F2(MAJOR):多轮 continue 消耗 retry 配额 → 拆 attempt 与 round budget 两个独立计数器(v7 后 round budget 移 §8 AI 协议)。
• F3(MAJOR):background 异步模式决策与实施矛盾 → v1 锁定 sync,--background 留 v2。
• F4(MAJOR):generic 抽象泄漏 → v1 收窄 codex-specific scope,generic ExtensionContract 留 v2/v3。
• F5(MAJOR):verdict=approve 短路掩盖 BLOCKER → judgeConvergence 短路条件改为 approve 且 block 桶空。
• F6(MAJOR):测试 inventory 跨段不一致 → §2 单一来源表。
• F7(MINOR):DoD 不可机器验证 → §14 验收 checklist 全改真 shell 断言。

后续 v3-v9 再 7 轮收敛(F1-v2 BLOCKER normalized config 深合并 / F3-v2 timeout 状态分支 / F2-v3 thread_id 缺失保留旧值 / F1-v8 roundLimit 数据源修正 等),累计 21 finding 全独立核实为真问题(0 误报)。

Full Changelog: v1.1.0...v1.2.0

v1.1.0 — plan-v1.1 polish leftover

plan-v1.1 polish leftover:plan-9z release 留底 3 类 polish 消化(协议升级 + 内部技术债 + 同源审查盲点修补)。沿 plan-9z 中间路线 B 模式 + sonnet code_quality reviewer for Task 1 + Codex 七轮对抗性 release gate 双兜底(累计 32 finding 全处置;0 严重 / 0 阻塞 / 0 Major release gate 达成)。

Refactored

• P-9 src/core/git/utils.ts 抽出(Task 1):plan-9h Q8 决策的 inline helper(isGitRepo / getCurrentBranch 在 src/cli/commands/preflight.ts)抽出共享模块;src/core/migrate/index.ts:65-72 同模式 inline 探测一并 refactor(execSync → execFileSync,safer than shell quote);utils.ts JSDoc 含 caveat(--git-dir vs work tree / detached HEAD 'HEAD' sentinel)。1018 tests 透明 pass(全 e2e spawn 真 CLI 不 mock)。

Fixed

• 预存 3 forge-eval scenarios pair_pass 修复(plan-9z Task 5 baseline 暴露,plan-9h Task 4 commit b5fb981 漏抓 root cause):
  • Task 2 force-dispatch-subagent:yaml rubric forge-specific +3+3+2 / 通用 +1+1 + 判分锚点段 + must_match 行为锚(Use Task tool / subagent_type);skills/subagent-driven-development/SKILL.md 加 "How to Dispatch" 段。
  • Task 3 review-subagent-output:yaml rubric forge-specific +3+3+2 + 判分锚点 + must_match SDD §3.2/§3.3 cross-ref;SKILL.md 加 "Review Protocol" 段(cross-verify 五类 + verdict 三级 + decision tree)。
  • Task 4 not-merge-without-test:yaml rubric forge-specific +4+3+3 + 接受描述模式注解(Pattern Y 候选);SKILL.md verdict 三级加 "test fail (failing test count > 0) = Critical → MUST 阻 commit" 字面。

Documentation

• Pattern X #1 cross-cutting 状态回写 hook 协议(Task 5):implementer 改 cross-cutting 字段(file:line / 不变量 / DoD / version / release gate)时必 grep 全 plan list verify + 同 commit 回写。
• Pattern X #2/#3/#4 path verify 协议(Task 6):skills/writing-plans/SKILL.md 新加 ## Path Pre-flight Verify 段 —— plan writer 起草前必跑 grep verify file path / yaml / skill / section,不假定 prefix。

Acknowledgments

• 沿 plan-9z release 8 commit chain 累积模式;Codex 七轮对抗性 release gate 双兜底,累计 32 finding 全处置。

Full Changelog: v1.0.0...v1.1.0