feat: add install-codebuddy for CodeBuddy Code CLI

[ZiyiXingYao]

修改内容

新增 install-codebuddy 安装脚本，支持将 spec-superflow 部署到 CodeBuddy Code CLI（~/.codebuddy/skills/ + hooks）。

新增文件

• scripts/install-codebuddy.mjs — 独立入口脚本
• scripts/lib/cmd-install-codebuddy.mjs — 安装命令模块

修改文件

• scripts/spec-superflow.mjs — 注册 install-codebuddy 命令、help 描述、使用示例
• INSTALL.md — 新增 ## CodeBuddy Code CLI 章节（安装/升级/卸载/验证/部署结构）

功能特点

• 从 GitHub release 或本地源码部署 spec-superflow 到 CodeBuddy Code CLI
• skills 安装到 ~/.codebuddy/skills/，不覆盖其他 skill（如 project-init）
• 运行时依赖安装到 ~/.codebuddy/spec-superflow/
• phase-guard 规则安装到 ~/.codebuddy/rules/phase-guard.md
• SessionStart hook 自动配置到 ~/.codebuddy/hooks/hooks.json
• canonical recovery commands 部署到 ~/.codebuddy/commands/ssf/
• 支持 --local、--tag、--config-dir、--dry-run 参数

[MageByte-Zero]

感谢贡献 CodeBuddy 安装器，整体方向是对的：skills、runtime、commands 的部署流程已经跑通，CI 也保持绿色，基础实现质量不错。

当前建议先补几处兼容性问题，再合并：

1. SessionStart Hook 需要写入 ~/.codebuddy/settings.json，或完整按 CodeBuddy 插件方式生成并启用插件。目前写入 ~/.codebuddy/hooks/hooks.json，用户级配置不会自动加载。
2. session-start 需要输出 CodeBuddy 要求的 hookSpecificOutput 格式；当前 standalone 模式下可能只输出顶层 additionalContext。
3. 全局 phase-guard.md 可能影响所有普通项目。建议增加作用域控制，避免没有 spec-superflow 变更时也强制进入 workflow。
4. --local 模式下，recovery commands 仍调用 npx，建议统一改为使用已部署的本地 runtime。
5. 卸载时只删除 spec-superflow 自己注入的 Hook，不能直接删除整个 hooks 配置文件。
6. 建议补充 CodeBuddy 专项测试和 CI installer smoke test，并同步 README、平台矩阵和 CHANGELOG。

推荐至少覆盖：首次安装、重复安装、已有用户 Hook、保留其它 skill、--local、--dry-run，以及卸载安全性。

这些问题主要集中在 CodeBuddy 配置约定和边界场景，不影响整体设计方向。修复后直接 push 到当前分支即可自动更新 PR，期待下一版！

[MageByte-Zero]

建议暂缓合并。当前安装器已能复制 runtime、skills、rules 与 commands，但仍未可靠完成“可用且安全地部署到 CodeBuddy Code CLI”的目标。

合并前请修复

1. --local recovery commands 必须使用已部署 runtime（P1）
   copyValidatedCommands() 当前原样复制 commands/ssf/*.md，导致 /ssf:resume、/ssf:save、/ssf:switch 仍运行固定版本的 npx --package spec-superflow@0.12.1，而非 <config-dir>/spec-superflow/scripts/spec-superflow.mjs。请在复制 command adapter 时同时重写命令与 allowed-tools，并新增 --local 回归测试。

2. 按 CodeBuddy 的真实配置契约启用 SessionStart（P1）
   当前写入 ~/.codebuddy/hooks/hooks.json，且 hooks/session-start 在该环境输出顶层 additionalContext。请依据 CodeBuddy 官方配置方式写入/启用（例如 settings.json 或完整插件流程），并确保输出符合其要求的 hookSpecificOutput 格式。请用真实 CLI 或可复现的契约测试验证“重启后自动加载”。

3. 卸载不得删除用户所有 hooks（P1）
   INSTALL.md 目前建议删除整个 ~/.codebuddy/hooks/hooks.json，这与“保留非 spec-superflow hooks”的安装承诺冲突。请提供精确移除 spec-superflow 条目的卸载流程/命令，并覆盖已有用户 Hook 的场景。

4. 限制全局 phase-guard 的影响范围（P2）
   用户级 rules/phase-guard.md 写入后会要求所有项目从 workflow-start 开始，与普通任务直接执行的预期冲突。请增加项目范围限制或显式 opt-in，并补充相应说明与测试。

5. 补齐测试、CI 和发布文档（P1）
   新增安装器需要覆盖：首次/重复安装、保留其他 skill 与 hook、--local command 重写、--dry-run 零写入、异常配置、卸载安全性。CI 的 platform-install smoke 也应纳入 CodeBuddy。同步 README、docs/README_en.md、docs/platform-matrix.md、CHANGELOG.md 和 release checklist。

我已在隔离目录复现：安装会复制 9 个 skills 和 runtime，但 --local 安装后的三个 command adapter 仍使用固定 npx 版本。现有 CI 全绿，但尚未覆盖 CodeBuddy installer，因此不足以作为合并依据。

[ZiyiXingYao]

修复说明（针对评审意见）

已按 MageByte-Zero 的评审意见修复以下问题，并 push 到本分支（commit 7c22560）：

P1-① --local recovery commands 使用已部署 runtime

copyValidatedCommands 现在重写 commands/ssf/*.md：npx --yes --package spec-superflow@0.12.1 ssf <sub> → node <pluginRoot>/scripts/spec-superflow.mjs <sub>，allowed-tools: Bash(npx:*) → Bash(node:*)。

P1-② 按 CodeBuddy 配置契约启用 SessionStart

• SessionStart hook 改为写入 ~/.codebuddy/settings.json（CodeBuddy 用户级 hooks/hooks.json 不会自动加载，依据 CodeBuddy 官方 hook 文档）
• hooks/session-start 新增 CODEBUDDY_PROJECT_DIR 分支，输出 hookSpecificOutput:{hookEventName:"SessionStart",additionalContext:...} 格式
• settings.json 采用合并策略：保留 permissions/enabledPlugins/其他事件 hook

P1-③ 卸载不删用户 hooks

新增 ssf uninstall-codebuddy 命令：从 settings.json 精确移除 spec-superflow 的 SessionStart 条目，删除 spec-superflow/、commands/ssf/、phase-guard.md、9 个 skill 目录，保留其他 skill/rule/hook/字段。INSTALL.md 的 rm -f ~/.codebuddy/hooks/hooks.json 已替换。

P2-④ phase-guard 作用域限制

phase-guard.md 加 frontmatter alwaysApply:false + 内容说明"仅在检测到 spec-superflow 变更工件时应用"。普通项目不再被强制走 workflow。

P1-⑤ 测试/CI/文档

• 新增 tests/lib/cmd-install-codebuddy.test.mjs（13 用例，全通过）：首次/重复安装、保留其他 skill 与 hook、--local command 重写、--dry-run 零写入、异常配置、卸载安全性、session-start 输出格式
• CI platform-install-smoke 8→9 平台，新增 CodeBuddy 验证（settings.json SessionStart、command 重写、phase-guard frontmatter）
• 同步 README/docs/platform-matrix/CHANGELOG/release-checklist/INSTALL

端到端验证

• ssf uninstall-codebuddy → ssf install-codebuddy --local → ssf doctor All checks passed
• session-start 在 CODEBUDDY_PROJECT_DIR 下输出 hookSpecificOutput
• 卸载保留 project-init skill 与 settings.json 其他字段（trustedDirectories/language/model/enabledPlugins）

workbuddy 的 command adapter 仍用 npx（未在本 PR scope，如需同步修复可单独处理）。

[MageByte-Zero]

CI/CD 工作流运行未通过，详见 https://github.com/MageByte-Zero/spec-superflow/actions/runs/30334309842/job/90200454887?pr=86 @ZiyiXingYao

[ZiyiXingYao]

补充：CI Build & Test 失败已修复（commit 6a1c920）

之前 Build & Test (22) 失败在 closing-terminal-semantics.test.mjs:191 — "keeps the #64 terminal closing repair in its v0.11.0 release record"。

根因：该测试行 196 断言 [Unreleased] section 必须完全空（assert.equal(unreleased.trim(), '## [Unreleased]')），这是 v0.11.0 发布后的临时约束，与新增 CodeBuddy 变更条目冲突。

修复：更新断言为只确保 #64 修复不泄漏到 [Unreleased]（assert.doesNotMatch(unreleased, /#64/)），保留核心约束（#64 留在 v0.11.0 record），允许 [Unreleased] 承载其他未发布内容——符合 Keep a Changelog 惯例。

本地验证（40/40 通过）

• closing-terminal-semantics 8 ✅
• cmd-install-codebuddy 13 ✅
• execution-control-plane 6 ✅
• minimality-discipline 2 ✅
• marketplace-release-docs 2 ✅
• codebuddy-manifest 1 ✅
• token-baseline 4 ✅

CI 整体

• Platform Install Smoke (9 platforms) 之前已 ✅（含新增 CodeBuddy smoke）
• Build & Test 仅 closing-terminal 一个失败，已修复
• 跨平台验证：测试用 pathToFileURL + 路径正则 [\\/]+，Windows/Linux 均通过

CI 现在应一把绿。

[MageByte-Zero]

复核了最新提交（1434ac2）：此前阻塞项中的 --local runtime 重写、settings.json SessionStart、hookSpecificOutput、phase-guard 作用域、专项测试与 9 平台 CI 均已修复；Node 20/22 CI 也已全绿。

不过仍有一个数据安全阻塞项，暂不能批准：uninstallCodeBuddy() 会递归删除整个共享目录 ~/.codebuddy/commands/ssf（cmd-uninstall-codebuddy.mjs 第 129–133 行），而不是只删除本安装器创建的 resume.md、save.md、switch.md。

我已在隔离目录复现：先安装，再在 commands/ssf/custom.md 放入用户自建 command，运行 ssf uninstall-codebuddy 后该文件被删除。共享命名空间中的用户数据不应被卸载命令删除。

请改为仅删除三个受管 command 文件（或用安装清单精确识别）；仅当目录为空时才移除目录，并新增“保留 commands/ssf/custom.md”的回归测试。另请同步 docs/README_en.md 与 README 的平台/命令表，INSTALL 的部署树也不应声称 runtime 下含 commands/ssf，实际路径在共享 ~/.codebuddy/commands/ssf。

[ZiyiXingYao]

修复：uninstall 数据安全阻塞项（commit eff4637）

MageByte-Zero 指出 uninstallCodeBuddy() 递归删除整个 ~/.codebuddy/commands/ssf 目录会误删用户自建 command。已修复：

1. 精确删除 command 文件（cmd-uninstall-codebuddy.mjs）

改为只删除 resume.md/save.md/switch.md 三个受管文件；仅当目录为空（过滤 .DS_Store 等隐藏文件后）时才移除 commands/ssf 目录。用户自建的 custom.md 等不受影响。

2. 文档同步

• INSTALL.md 部署树修正：移除 spec-superflow/ 下的 commands/ssf（实际在共享 ~/.codebuddy/commands/ssf），标注可含用户自建 command
• README.md + docs/README_en.md：平台表 + 命令表加 CodeBuddy Code CLI（install-codebuddy/uninstall-codebuddy）

3. 新增测试

• preserves user-created commands/ssf/custom.md and only removes managed files：卸载保留 custom.md，删 3 受管文件，目录保留
• rewrites npx invocations in deployed skills to use the local runtime：skills 的 npx→node 重写（补充覆盖）
• removes all 9 spec-superflow skill directories on uninstall：9 个 skill 全删

验证

• 本地 43/43 测试通过（含 model-profiles-docs / execution-control-plane / closing-terminal 等）
• 端到端：放 custom.md → 卸载 → custom.md 保留 + 3 受管文件删 → 重装 → custom.md 仍在 + ssf doctor All checks passed

跨平台：readdirSync/rmSync 跨平台，隐藏文件过滤（.DS_Store）macOS 友好。

[MageByte-Zero]

@ZiyiXingYao 合并前还需修复一个 P1 数据安全问题：ssf uninstall-codebuddy 当前会递归删除整个共享目录 ~/.codebuddy/commands/ssf，会误删用户自建的 /ssf command。

我已复现：安装后新增 commands/ssf/custom.md，执行卸载后该文件不存在。

请调整为：

• 仅删除本安装器管理的 resume.md、save.md、switch.md（或通过安装清单精确识别）；
• 仅在目录为空时删除 commands/ssf；
• 新增“保留 commands/ssf/custom.md”的回归测试。

另外请同步 README.md、docs/README_en.md 的 CodeBuddy 平台/命令表，并修正 INSTALL 部署树中 commands 的实际共享路径。修复后 push 到当前 PR，我会复核并在通过后批准。

[MageByte-Zero]

已复核最新提交 36faa92，批准合并。

此前阻塞的卸载数据安全问题已修复：卸载仅删除受管的 resume.md、save.md、switch.md，并保留用户的 commands/ssf/custom.md；相应回归测试已加入。README、docs/README_en.md 与 INSTALL 部署路径也已同步。

验证通过：隔离副本 npm run build、完整 npm test、以及 CodeBuddy 专项 16/16 测试；GitHub Node 20/22 CI 与 9 平台 installer smoke 均为绿色。

非阻塞后续建议：目录是否为空的判断不要忽略 dotfile，避免仅含 .gitkeep 等隐藏用户文件时被删除。