onboard

/onboard — Legacy Project Onboarding Protocol (v3.2.0)

参数：$ARGUMENTS

本包是 Skill 形式发布（.claude/skills/onboard/）。 包含预制的 4 个 hook 脚本作为 supporting files：

• hooks/guard-bash.sh — PreToolUse on Bash，拦截危险命令
• hooks/guard-edit.sh — PreToolUse on Edit|Write|MultiEdit，拦截禁区编辑
• hooks/post-edit-check.sh — PostToolUse on Edit|Write|MultiEdit，记录触及文件 + 轻量检查
• hooks/stop-verify.sh — Stop hook，按 mode 跑增量验证

Phase 7 不再动态生成脚本，而是直接在 .claude/settings.json 中引用 ${CLAUDE_PROJECT_DIR}/.claude/skills/onboard/hooks/<name>.sh。

兼容 Command 形式：把 SKILL.md 重命名为 .claude/commands/onboard.md，Phase 7 改回动态生成脚本到 .claude/hooks/。

关于 disable-model-invocation: true 防止 Claude 自动触发。已知 Skill 形式有兼容性 bug，若异常移除该字段或改用 Command 形式。

关于 allowed-tools 故意限制为只读工具。Bash/Write/Edit 走正文授权流程。会话开始时若希望连续执行，请在首个权限弹窗选择"允许本会话"；否则保持逐次确认。两种节奏都安全。

---

0. 总则（贯穿全流程）

文件四分类

• PROJECT：仓库已有内容。默认不得修改；仅当 Phase 2 plan 列入 touches 并经授权后可改。
• RUNTIME：本命令运行期状态与日志：.claude/onboarding-state.json、.claude/onboarding-logs/、.claude/tmp/。
• OUTPUT：本流程新增/维护的 Claude 产物：CLAUDE.md、.claude/settings.json、.claude/hooks/*、.gitignore 修订等。
• LOCAL-SIDE-EFFECT：不入仓但改变本机环境的写入目标：.git/hooks/*、.git/info/exclude、专用 onboarding 分支。不参与 touch_budget。

工作区"干净"仅针对 PROJECT。

Iron Laws（19 条，与 v2.3 同；Iron Law 3 / 14 措辞精化）

1. Read-before-write：未读取现状不得写入；现状报告未生成不得进入 Phase 1.5/2。
2. No silent overwrite：覆盖任何已存在配置文件前必须 diff + 用户确认。
3. Respect existing stack(s)：同一语言栈内禁止引入冲突工具（如 Node 内同时 ESLint + JSHint）。允许多语言项目并存多套工具栈——按栈分别应用。
4. Idempotent：可重复执行；已完成阶段须基于状态文件跳过或验证而非重做。
5. Verifiable：每个阶段必须有可执行验证步骤，失败不得标记为完成。
6. Stateful：所有阶段决策、产出、验证结果写入状态文件。
7. No auto-install：任何安装/升级动作必须先列清单 + 显式授权。凡 installs != []，对应 lockfile 自动追加到该 item 的 touches。（v2.7 注释）：Phase 2.5 引入的 batch AUTH（approve dev-tools-all）满足"显式授权"语义——用户看过清单后给出的一次性授权 = N 次单批授权之和，颗粒度变粗但约束未弱化。绝不允许"只要是 dev-only 就跳过 AUTH"的无差别豁免。
8. No business logic changes：onboarding 不得修改业务代码；唯一例外是 Phase 5 中用户批准的最小 smoke test。
9. No dependency upgrades：不得升级已有依赖版本；只允许新增经授权的开发依赖。
10. Prefer existing task runner：若项目已有 Makefile / justfile / package scripts，不新增平行入口；新增 script 前必须先做任务运行器健康检查。
11. Cross-platform awareness：hook 脚本默认 POSIX shell；Windows-first 项目必须提示兼容性风险并给替代或 defer。
12. CI alignment：本地 lint/test/typecheck 命令必须优先复用 CI 中已有命令。
13. Touch budget：实际改动文件集合若超出 Phase 2 计划中 touches 并集（含自动追加的 lockfile），立即中止并重新进入 Phase 2。local_side_effects 不计入。
14. No file-level reset on PROJECT：禁止对 PROJECT 文件执行 git reset --hard / git checkout -- <file> / git restore <file>。git checkout -b <new-branch>（创建新分支）不在此限——配合 --isolate-branch 模式使用。测试改动一律走 .claude/tmp/。
15. Exit code or JSON, never both：hook 脚本必须明确选择 exit 0 + stdout JSON 或 exit 2 + stderr；混用时 JSON 被忽略。
16. Forbidden zones are global：Phase 1 探测出的禁区是 candidates；只有 Phase 1.5 用户确认的 confirmed forbidden zones 才进入全流程消费——CLAUDE.md / lint ignore / hook env / guard-edit 必须保持一致。
17. New-check first failure is deferred, not blocking：Phase 4 首次引入的检查若首次跑失败，标 deferred: pre_existing_violations，不阻塞。
18. Mutex group authorization：同一 mutex_group 最多批准一个 plan item；Phase 2 即刻拒绝冲突。
19. warn-only must exit 0：标 warn-only 的检查必须输出 warning 但 exit 0，绝不返回非零退出码导致推送阻断。