小白实测审查：20 个问题全修（v0.4.0）

[KKKKhazix]

以完全不懂代码的新人身份从零实测走了两轮（空目录装到开并行任务、连 GitHub、私有仓库、已有项目接入、中文与带空格的文件夹），挖出 20 个问题，本 PR 全部修掉。每一条都有实测复现，改完又逐条实测验证。

会卡死或悄悄失效的（4）

• 新工作区没有依赖：boss task 现在自动补装（实测：之前第一条自检命令就 boss: command not found）。
• 守卫对没提交的文件睁眼瞎：全新项目里放一把明文密钥曾被报「9 项全部通过」。密钥守卫改扫工作区（已追踪＋未忽略），check 结论附上扫了多少文件。CI 检出没有未追踪文件，不会把任何人的 CI 改红。
• 短名 npx boss 会落到 npm 上陌生人的同名包（boss@1.0.5 真实存在，守卫因此静默不跑）：所有教用户敲的位置统一改为 npm run preflight。
• 私有仓库让 boss merge 必然失败：新增 gh auth token 兜底（实测本机可取到）。

框架自己教出来的死胡同（2）

• 本地阶段 → GitHub 的悬崖：本地已合进主干的提交推不上去，而旧提示教人「另开分支」根本不适用。pre-push 改为按处境给救援命令（git push origin main:refs/heads/rescue-…），并实测这条命令真能跑通。
• 已有项目装完必红：init 结尾不再在有待处理事项时承诺「守卫应当全绿」。

承诺与现实对齐（2）

• 没有任何测试：规则与 boss-flow 新增硬要求——每个项目必须有一条冒烟测试，框架不替写（裁决见 decisions）。
• 四阶梯对非 Claude 的 AI 不可见：四阶梯骨架内嵌进 AGENTS.md 模板，技能只留详细话术。

小白缺口（4）

新增 boss status（第六个命令，只读：在第几阶、环境齐不齐、下一步一条）；规则与技能补「改坏了怎么退回去」（用 revert，永不 reset --hard）；task／status 报告可回收的旧任务工作区；README 补卸载章节。

杂项（8）

中文文件夹名不再生成 ------- 这种非法包名；拒绝在家目录／桌面这类「东西堆」里开工并给出建文件夹的命令；技能改成真实副本（软链在 Windows 上克隆即失效，update 会就地迁移）；守卫报错不再重复文件名；README 补前置条件（Node 18.17+）；Gitee 等非 GitHub 远端改为说明并放行，不拿红叉挡住单干的人。

验证

• npm run preflight：86 项测试、9 项守卫全绿。
• 复跑实测：中文文件夹包名、未提交密钥被抓、status 输出、新工作区自检通过、直推救援提示与命令、家目录拒绝、老项目指引、gh 通行证取用——逐条确认。
• 四篇决策档案落档：守卫扫未提交文件／status 命令／冒烟测试要求／小白路径硬化。

发布

含版本号 0.3.0 → 0.4.0。合并不等于发布：合并后等老板确认，再由老板点头触发 gh workflow run publish.yml。

🤖 Generated with Claude Code