sillyspec 3.20.1 → 3.20.3

package/docs/sillyspec/file-lifecycle/worktree-and-guard.md

@@ -1,193 +0,0 @@
----
-author: qinyi
-created_at: 2026-06-04 16:25:42
----
-
-# Worktree 与 Hook 门禁
-
-## 命令入口
-
-`src/index.js` 暴露：
-
-```text
-sillyspec worktree create <change-name> [--base <branch>]
-sillyspec worktree apply <change-name> [--check-only]
-sillyspec worktree list
-sillyspec worktree cleanup <change-name>
-```
-
-实现分别调用：
-
-- `WorktreeManager.create()`
-- `applyWorktree()`
-- `WorktreeManager.list()`
-- `WorktreeManager.cleanup()`
-
-## `create`
-
-默认路径：
-
-```text
-.sillyspec/.runtime/worktrees/<change-name>/
-```
-
-默认分支：
-
-```text
-sillyspec/<change-name>
-```
-
-关键校验与分支：
-
-1. `changeName` 不能为空，不能包含 `..`、`/`、`\`。
-2. 如果当前目录是 git submodule，直接报错。
-3. 如果当前目录已经是 linked worktree，创建 `native-worktree` meta，复用当前目录。
-4. 普通主工作区必须先确认 `.sillyspec/.runtime/worktrees` 被 `.gitignore` 忽略，否则报错。
-5. 如果 worktree 目录存在但没有 `meta.json`，视为幽灵目录并自动删除。
-6. 如果目标 branch 已存在，报错。
-7. 默认 base 是当前 `HEAD`；传 `--base` 时使用指定 ref。
-8. `git worktree add` 失败时：
-   - 如果 git 版本低于 2.15 或不可用，报错。
-   - 其他失败降级为 `in-place-fallback`，在主工作区记录 meta。
-9. 创建普通 worktree 后，会 best-effort `fetch origin` 并尝试 fast-forward 到默认远端分支。
-10. 主工作区已有 staged/unstaged/untracked 变更时，会 overlay 到 worktree，并创建 baseline checkpoint commit。
-
-## `meta.json`
-
-普通 worktree 的 `meta.json` 位于 worktree 目录内：
-
-```text
-.sillyspec/.runtime/worktrees/<change>/meta.json
-```
-
-`native-worktree` 和 `in-place-fallback` 下，meta 仍写到 `.sillyspec/.runtime/worktrees/<change>/meta.json`，其中 `worktreePath` 可能指向当前工作目录。
-
-主要字段：
-
-| 字段 | 说明 |
-|---|---|
-| `changeName` | 变更名 |
-| `branch` | worktree 分支 |
-| `baseBranch` | 基准分支或 ref |
-| `baseHash` | 创建时基准 commit |
-| `actualBaseHash` | worktree 当前 HEAD |
-| `createdAt` | 创建时间 |
-| `worktreePath` | 实际执行目录 |
-| `mode` | `worktree` / `native-worktree` / `in-place-fallback` |
-| `baselineFiles` | 从主工作区 overlay 的未提交文件 |
-| `baselineCommit` | baseline checkpoint commit |
-| `baselineHash` | execute 前主工作区 dirty baseline hash |
-
-## `apply`
-
-`applyWorktree(changeName, { checkOnly })` 的真实流程：
-
-1. 读取 `meta.json`。
-2. diff base 使用 `baselineCommit || baseHash`。
-3. 收集 tracked diff 和 untracked 新文件。
-4. 从 `.sillyspec/changes/<change>/design.md` 解析“文件变更清单”作为 allow list。
-5. 如果 allow list 非空，要求 changed files 都在清单内。
-6. 如果 meta 有 `baselineHash`，重新计算主工作区 dirty hash；不同则拒绝 apply。
-7. 检查主工作区和 apply 文件有无未提交冲突。
-8. 比较主工作区 `HEAD` 与 worktree `baseHash` 的目标文件 blob。
-9. `--check-only` 到这里返回。
-10. 生成临时 patch。
-11. 在主工作区执行 `git apply --check`。
-12. 执行 `git apply --3way`。
-13. 成功后自动调用 `WorktreeManager.cleanup()`。
-
-无变更时，如果不是 check-only，也会 cleanup。
-
-## `cleanup`
-
-`cleanup(changeName, { force })`：
-
-| mode | 非 force 行为 |
-|---|---|
-| `worktree` | 尝试 `git worktree remove --force`，删除目录，删除分支，删除 meta 目录 |
-| `native-worktree` | 抛错，避免删除用户自己的 worktree |
-| `in-place-fallback` | 返回 `skipped` |
-| 无 meta 且目录不存在 | 返回 `skipped` |
-
-如果 `git worktree remove` 失败但目录可删，结果是 `force-cleaned`。
-
-## execute 阶段
-
-`execute.js` 的固定前缀第 3 步是“创建 worktree”，prompt 要求运行：
-
-```text
-sillyspec worktree create <change-name>
-```
-
-后续 Wave prompt 要求把子代理 cwd 设置为 worktree 路径。完成确认 step 根据 mode 分别处理：
-
-- `worktree`：check-only，用户确认后 apply，再 cleanup。
-- `native-worktree`：可以 apply，但不要 cleanup。
-- `in-place-fallback`：跳过 apply/cleanup。
-- 无 worktree：只展示 diff 摘要。
-
-注意：`buildExecuteSteps()` 有 `noWorktree` 参数，但当前 `runCommand()` 没有解析 `--no-worktree` flag，CLI help 也没有列出该 flag。文档不要把 `--no-worktree` 写成已接通的公开流程。
-
-## quick 阶段
-
-quick 当前不创建 worktree。
-
-`quick.js` 第 2 步明确写的是“直接在主工作区实现任务”。`worktree-guard.js` 在 stage 为 `quick` 时，对 Write/Edit/MultiEdit 直接放行；Bash 仅拦截危险命令。quick 作为辅助阶段完成后，`run.js` 会重置 quick 步骤并清空 `currentStage`，从而删除 gate 状态。
-
-因此旧文档中“quick 创建 worktree/meta.json”的描述不符合当前代码。
-
-## Hook 门禁
-
-入口：`src/hooks/claude-pre-tool-use.cjs`
-
-输入：Claude Code PreToolUse hook 的 JSON。它只映射这些工具：
-
-- `Write`
-- `Edit`
-- `MultiEdit`
-- `Bash`
-
-实际判断：`src/hooks/worktree-guard.js`
-
-### 文件白名单
-
-以下写入直接放行：
-
-- 路径中包含 `.sillyspec`，但 `.sillyspec/.runtime/worktrees/` 例外
-- 路径中包含 `.git`
-- 扩展名为 `.md`
-- 文件名为 `package.json`、`tsconfig.json`、`local.yaml`、`local.yml`
-
-`.sillyspec/.runtime/worktrees/` 下的写入不会仅因路径包含 `.sillyspec` 而放行；它必须命中当前 gate 中 active change 对应的 `meta.json.worktreePath`。
-
-### 阶段门禁
-
-阶段读取顺序：
-
-1. `.sillyspec/.runtime/gate-status.json`
-2. `sqlite3` CLI 查询 `.sillyspec/.runtime/sillyspec.db`
-
-只有 `execute` 和 `quick` 被视为允许源码写入的阶段。
-
-### execute 写入
-
-execute 阶段的源码写入必须位于已登记 worktree 内：
-
-1. hook 读取 `.sillyspec/.runtime/gate-status.json` 或 SQLite，得到当前 active changes。
-2. 对每个 active change 读取 `.sillyspec/.runtime/worktrees/<change>/meta.json`。
-3. 只有目标路径位于 `meta.json.worktreePath` 内时才允许写入。
-
-这意味着随便构造一个包含 `.sillyspec/.runtime/worktrees/` 字符串的路径不会被放行。主工作区写源码仍会被拦截。
-
-### quick 写入
-
-quick 阶段写文件直接放行，不要求 worktree。
-
-### Bash 命令
-
-- 已登记 worktree 内 cwd：全部 Bash 放行。
-- 非 execute/quick：只读白名单放行。
-- quick：危险黑名单拦截，其余放行。
-- execute 主工作区：危险黑名单拦截；只读白名单放行；其他不确定命令当前放行。
-
-`worktree-guard.js` 的本地扩展白名单优先读取 `.sillyspec/local.yaml` / `.sillyspec/local.yml`，并兼容项目根 `local.yaml` / `local.yml`。

package/docs/sillyspec/file-lifecycle.md

@@ -1,125 +0,0 @@
----
-author: qinyi
-created_at: 2026-05-31 11:00:00
-updated_at: 2026-06-19 15:00:00
----
-
-# SillySpec 文件生命周期
-
-> 本文档按当前代码重写。它描述的是仓库里已经实现或运行时会暴露的行为，不描述期望设计。
-
-## 文档拆分
-
-| 文件 | 说明 |
-|---|---|
-| [storage-and-state.md](file-lifecycle/storage-and-state.md) | `.sillyspec/.runtime/`、SQLite、gate、artifact、history、local 配置口径 |
-| [stage-artifacts.md](file-lifecycle/stage-artifacts.md) | 各阶段的运行时步骤、变更目录产物、归档和 quicklog |
-| [worktree-and-guard.md](file-lifecycle/worktree-and-guard.md) | `sillyspec worktree`、`meta.json`、apply、cleanup、Claude hook 门禁 |
-| [platform-workflows-sync.md](file-lifecycle/platform-workflows-sync.md) | 平台模式、workflow check、manifest、SillyHub sync |
-| [known-implementation-gaps.md](file-lifecycle/known-implementation-gaps.md) | 当前代码与提示文案/旧文档不一致的地方 |
-
-## 代码依据
-
-本组文档主要对照以下实现：
-
-- `src/init.js`
-- `src/db.js`
-- `src/scan-postcheck.js`
-- `src/knowledge-match.js`
-- `src/progress.js`
-- `src/run.js`
-- `src/stages/*.js`
-- `src/worktree.js`
-- `src/worktree-apply.js`
-- `src/hooks/worktree-guard.js`
-- `src/workflow.js`
-- `src/sync.js`
-- `src/modules.js`
-- `src/index.js`
-
-运行时阶段列表以导入 `src/stages/index.js` 后得到的对象为准。当前导入结果：
-
-| 阶段 | 当前步骤数 | 备注 |
-|---|---:|---|
-| scan | 11 | 辅助阶段；step 2 后会按项目动态展开 `perProject` 步骤；第 10 步「Extract Project Knowledge」写入 `knowledge/` |
-| brainstorm | 11 | 独立包含“写设计文档并自审”和“用户确认并生成规范文件” |
-| propose | 7 | 包含“生成规范文件”与“自检门控”，四件套是该阶段预期产物 |
-| plan | 动态 | 默认 8 步；`plan.md` 解析到任务后插入任务蓝图协调器 |
-| execute | 动态 | 默认 12 步；Wave 来自 `plan.md`，解析失败时默认 3 个 Wave |
-| verify | 7 | 只读校验 + 写 `verify-result.md` |
-| archive | 5 | 辅助阶段；第 4 步必须带 `--confirm`，由 `run.js` 移动目录并注销 active change |
-| quick | 3 | 辅助阶段；直接在主工作区实现，不创建 worktree |
-| explore | 1 | 只读探索 |
-| status | 3 | 状态展示 |
-| doctor | 5 | 环境和项目自检 |
-
-## 顶层目录口径
-
-当前 `sillyspec init` 会创建或维护以下目录：
-
-| 路径 | tracked | 创建/维护方 | 当前生命周期 |
-|---|---|---|---|
-| `.sillyspec/projects/` | 是 | `init.js`、scan prompt 人工确认后 | 项目注册表，`*.yaml` 描述项目名、路径、状态 |
-| `.sillyspec/docs/<project>/scan/` | 是 | `init.js` 建目录；scan 阶段生成文档 | 代码扫描产物，workflow `scan-docs` 会检查 |
-| `.sillyspec/docs/<project>/modules/` | 是 | scan 可选步骤、archive sync、`modules` 子命令 | 模块索引和模块卡片 |
-| `.sillyspec/changes/<change>/` | 是 | `ProgressManager.initChange()` 确保目录；阶段 prompt 写入 | 单个变更包文档和验收产物 |
-| `.sillyspec/changes/archive/` | 是 | archive `确认归档 --confirm` 分支 | 已归档变更目录 |
-| `.sillyspec/knowledge/` | 是 | `init.js` 建目录；scan「Extract Project Knowledge」步骤产出 | `INDEX.md`、`uncategorized.md`，以及 scan 提取的 `conventions.md`/`patterns.md`/`known-issues.md` |
-| `.sillyspec/workflows/` | 是 | `init.js` 从模板复制 | workflow check 定义 |
-| `.sillyspec/quicklog/` | 是 | quick prompt | 无 `--change` quick 任务记录 |
-| `.sillyspec/shared/` | 是 | `init.js` | 共享目录，当前无核心生命周期逻辑 |
-| `.sillyspec/workspace/` | 是 | `init.js` | 工作区目录，当前无核心生命周期逻辑 |
-| `.sillyspec/.runtime/` | 否 | `init.js`、`ProgressManager`、运行时命令 | DB、gate、artifacts、history、workflow-runs、worktrees、knowledge-hit-report.json、postcheck-result.json |
-
-`init.js` 会把 `.sillyspec/.runtime/`、`.sillyspec/local.yaml`、`.sillyspec/codebase/SCAN-RAW.md` 追加到 `.gitignore`。
-
-## 主要文件流
-
-```text
-sillyspec init
-  -> .sillyspec/projects/<project>.yaml
-  -> .sillyspec/docs/<project>/scan/.gitkeep
-  -> .sillyspec/workflows/*.yaml
-  -> .sillyspec/knowledge/{INDEX.md,uncategorized.md}
-  -> .sillyspec/.runtime/{sillyspec.db,user-inputs.md,artifacts,history,logs,templates}
-
-sillyspec run scan
-  -> .sillyspec/docs/<project>/scan/*.md
-  -> .sillyspec/docs/<project>/modules/_module-map.yaml      (optional prompt)
-  -> .sillyspec/docs/<project>/modules/<module>.md           (optional prompt)
-  -> .sillyspec/knowledge/{conventions,patterns,known-issues}.md  (Extract Project Knowledge)
-  -> .sillyspec/knowledge/INDEX.md                           (索引更新)
-  -> .sillyspec/.runtime/scan-projects.json                  (step expansion state)
-  -> .sillyspec/.runtime/postcheck-result.json              (scan-postcheck 结构化结果)
-
-brainstorm / propose / plan / execute / verify / archive
-  -> .sillyspec/changes/<change>/...
-  -> .sillyspec/.runtime/sillyspec.db
-  -> .sillyspec/.runtime/user-inputs.md
-  -> .sillyspec/.runtime/artifacts/*.txt                     (long step output)
-
-execute
-  -> .sillyspec/.runtime/worktrees/<change>/meta.json
-  -> .sillyspec/.runtime/knowledge-hit-report.json           (启动时按 taskContext 匹配 knowledge)
-  -> worktree branch sillyspec/<change>
-  -> apply patch back to main workspace, then cleanup
-
-quick
-  -> .sillyspec/quicklog/QUICKLOG-<git-user>.md              (without --change)
-  -> or append checkbox to .sillyspec/changes/<change>/tasks.md
-  -> code changes are made in the main workspace
-```
-
-## 核心修正
-
-这版文档相对旧版长文档做了几项关键修正：
-
-- `quick` 不走 worktree 生命周期。hook 在 quick 阶段对写文件放行，只拦截危险 Bash 命令。
-- `scan` 当前定义是 10 步，并且 step 2 后会动态展开项目级步骤，不是固定 12 步。
-- `brainstorm` 和 `propose` 的重复 object key 已拆成独立步骤，运行时步骤数分别是 11 和 7。
-- `.sillyspec/local.yaml` 是当前主配置口径；scan prompt 写这里，sync 读写这里，hook 优先读这里并兼容根目录 fallback。
-- 平台模式的 `manifest.json` 已接入 scan 完成回调；`workflow-runs` 的 runtimeRoot 路径支持在 `workflow.js` 中存在，但 `run.js` 当前调用没有传入 `runtimeRoot`。
-- `archive` 的目录移动已经由 `run.js` 在第 4 步 `--confirm` 时执行；未带 `--confirm` 会回退该步骤并提示补参。
-- scan 第 10 步「Extract Project Knowledge」把长期有效的项目知识写入 `.sillyspec/knowledge/`（`conventions.md`/`patterns.md`/`known-issues.md` + 更新 `INDEX.md`）；`scan-postcheck.js` 校验产物（INDEX.md 存在、引用文件真实存在）。
-- execute 启动时由 `knowledge-match.js` 按 plan.md 的 task 关键词匹配知识库，命中报告注入 prompt 并写 `.runtime/knowledge-hit-report.json`。
-- Revision v1：`stages` 表新增 `revision`/`reopened_from_step`/`reopened_at`/`stale_reason` 列；阶段新增 `revising`/`stale` 状态；`sillyspec run <stage> --reopen --from-step <n>` 重开已完成阶段、级联标记下游 stale；`.runtime/postcheck-result.json` 由 `scan-postcheck.js` 的 `writeStructuredResult` 落盘（本地写 `specDir/.runtime`，平台写 `runtimeRoot/scan-runs/<id>`）。

package/docs/workflow-contract-regression.md

@@ -1,106 +0,0 @@
-# Workflow Contract Regression Audit
-
-> 日期：2026-06-19  
-> 范围：16 commits (f52e670..977ad0a)  
-> 结论：**全绿，0 bug，274 个断言全部通过**
-
-## 审计目标
-
-确认今晚 16 个 commit 引入的 contract/revision/stale safety 改动没有误伤现有主链路。
-
-## 审计范围
-
-### 新增功能
-1. **Revision v1** — 阶段重开 + 步骤级修订控制
-2. **Revision v1.1** — 可观测性与状态自检
-3. **Revision v1.2** — progress repair 安全修复状态元数据
-4. **Execute stale safety v1** — 防止基于旧 plan 继续执行
-5. **Verify/Archive stale safety** — 8 个测试固化安全链
-6. **Plan→Execute contract v1** — 校验 + 文档 + 测试
-7. **Plan postcheck contract v1** — plan 完成时校验 execute 契约
-8. **Brainstorm→Plan contract v1** — design.md 输入校验
-
-### 新增契约链
-
-```
-brainstorm → design.md → [Design Contract 校验] → plan → plan.md → [Plan Contract 校验] → execute
-```
-
-- **brainstorm → plan**: `validateDesignForPlan` — 3 error + 3 warning
-- **plan → execute**: `validatePlanForExecute` — 5 error + 1 warning
-- 双重校验：plan 完成时 + execute 启动时
-
-### 新增 Stale Cascade 链
-
-```
-scan → brainstorm → plan → execute → verify → archive
-```
-
-- `checkConsistency` 基于 STAGE_ORDER 遍历上游，自动发现下游假完成
-- `repair` cascade：execute stale → verify/archive stale → verify stale → archive stale
-
-## 测试执行
-
-### 命令
-```bash
-cd ~/Desktop/sillyspec && npm test
-```
-
-### 测试套件 (15 个，274 断言)
-
-| 测试套件 | 断言数 | 状态 |
-|---------|-------|------|
-| brainstorm-plan-contract.test.mjs | 11 | ✅ |
-| plan-execute-contract.test.mjs | 12 | ✅ |
-| platform-artifacts.test.mjs | 31 | ✅ |
-| platform-failure-samples.test.mjs | 20 | ✅ |
-| platform-recovery-chain.test.mjs | 15 | ✅ |
-| platform-recovery.test.mjs | 19 | ✅ |
-| platform-scan-p0.test.mjs | 19 | ✅ |
-| revision-v1.test.mjs | 12 | ✅ |
-| scan-paths.test.mjs | 38 | ✅ |
-| scan-postcheck.test.mjs | 38 | ✅ |
-| spec-dir.test.mjs | 15 | ✅ |
-| stage-contract.test.mjs | 19 | ✅ |
-| stage-definitions.test.mjs | 29 | ✅ |
-| wait-gates.test.mjs | 15 | ✅ |
-| worktree-guard.test.mjs | (included) | ✅ |
-
-**总计：15 套件，274 断言，0 失败。**
-
-## 主链路验收
-
-### 1. 完整主链路 (scan → brainstorm → plan → execute → verify)
-- ✅ stage-contract.test.mjs 覆盖了各阶段的校验与转换
-- ✅ stage-definitions.test.mjs 覆盖了所有阶段定义的步骤初始化
-- ✅ 无 contract 误伤
-
-### 2. Plan 级别验收 (none/light/full)
-- ✅ plan-execute-contract.test.mjs 覆盖 none/light/full
-- ✅ plan postcheck 在 plan completion path 执行
-- ✅ execute startup 二次校验保留
-
-### 3. Revision 链路
-- ✅ revision-v1.test.mjs 覆盖 reopen/repair/checkConsistency
-- ✅ verify/archive --reopen 清除旧 completed steps
-- ✅ execute --reopen 重新解析最新 plan.md
-- ✅ repair cascade execute → verify → archive
-
-### 4. Progress check/repair
-- ✅ 正常状态无误报
-- ✅ 异常状态报告清晰（checkConsistency 输出 upstream/downstream 关系）
-- ✅ repair 只修 progress 元数据，不改产物文件
-
-## 发现
-
-**0 bug。** 274 个断言全部通过，无回归。
-
-### 设计确认
-- checkConsistency 和 repair 基于 STAGE_ORDER 通用遍历，不针对特定 stage
-- verify/archive 用静态 steps，不需要从文件重解析
-- contract validator 只在阶段边界执行，不影响阶段内步骤流转
-- repair cascade 是自然结果，不需要硬编码 stage 间关系
-
-## 文件变更统计
-
-16 commits, 28 files changed, +3675/-689 lines。

package/docs/worktree-isolation.md

@@ -1,252 +0,0 @@
-# Worktree 隔离
-
-SillySpec 在 `execute` 和 `quick` 阶段使用 **git worktree** 隔离 AI 子代理的代码修改，确保主工作区始终干净。
-
-## 概述
-
-AI 子代理在执行任务时会在 worktree 中修改源码，而非直接在主工作区操作。任务完成后通过 `worktree apply` 将变更合入主工作区。这带来几个好处：
-
-- **安全性** — 主工作区不受意外修改影响
-- **可审计** — 变更集中在一个 diff 中，便于 review
-- **可回退** — 不满意直接 cleanup，主工作区零影响
-- **多 Agent 并行** — 多个子代理可以同时工作在不同的 worktree 中
-
-### 架构示意
-
-```
-主工作区                              worktree 隔离区
-┌──────────────────────┐           ┌──────────────────────────┐
-│ src/                 │           │ .sillyspec/.runtime/      │
-│   (hook 禁止写入)     │           │   worktrees/              │
-│ .sillyspec/          │           │     <change-name>/        │
-│   changes/           │           │       src/ (完整副本)      │
-│     <change-name>/    │           │       node_modules/       │
-│       design.md       │           │       ...                 │
-│       tasks.md        │           │                           │
-│ .sillyspec/.runtime/  │           │  分支: sillyspec/<name>   │
-│   gate-status.json    │           └──────────────────────────┘
-│   worktrees/          │                    │
-│     <change-name>/    │                    │ sillyspec worktree apply
-│       meta.json       │────────────────────┘
-└──────────────────────┘
-```
-
-## 命令参考
-
-### `sillyspec worktree create <change-name> [--base <branch>]`
-
-创建一个隔离的 worktree。
-
-- 基于 `--base` 分支（默认当前 HEAD）创建新分支 `sillyspec/<change-name>`
-- worktree 目录位于 `.sillyspec/.runtime/worktrees/<change-name>/`
-- 在目录内生成 `meta.json` 记录元数据（分支名、base hash、创建时间等）
-- 如果 worktree 已存在则报错，提示先执行 cleanup
-
-### `sillyspec worktree apply <change-name> [--check-only]`
-
-将 worktree 中的变更合入主工作区。
-
-- 读取 `meta.json` 中的 base hash，与主工作区比对
-- 从 `design.md` 解析文件变更清单，校验变更范围
-- `--check-only` 只输出检查结果，不实际 apply
-- 校验通过后生成 patch 并 3-way apply 到主工作区
-- apply 成功后自动清理 worktree
-
-**文件变更清单解析：** 从 `.sillyspec/changes/<change-name>/design.md` 中的 `## 文件变更清单` 表格提取。
-
-### `sillyspec worktree list`
-
-列出所有活跃的 worktree。
-
-输出表格包含变更名、分支名和创建时间。
-
-### `sillyspec worktree cleanup <change-name>`
-
-清理指定的 worktree。
-
-- 强制移除 worktree 目录
-- 删除 `sillyspec/<change-name>` 分支
-- 删除 `meta.json`
-
-> ⚠️ cleanup 会丢弃所有未 apply 的变更，请确认后再执行。
-
-## Hook 拦截机制
-
-SillySpec 通过 hook 在 AI 工具调用（Write/Edit/MultiEdit/Bash）前拦截非法写入。判断逻辑采用 **三重门禁**：
-
-```
-allowWrite = stageGate && locationGate && fileGate
-```
-
-### 阶段门禁（stageGate）
-
-- 读取 `.sillyspec/.runtime/gate-status.json`（由 CLI 维护）
-- 只有 `execute` 和 `quick` 阶段允许源码写入
-- 其他阶段（brainstorm/plan/verify/archive/explore）→ 禁止
-- 无 `gate-status.json` → 禁止（默认安全）
-
-### 位置门禁（locationGate）
-
-- 目标路径必须在 `.sillyspec/.runtime/worktrees/` 下才允许源码写入
-- 主工作区的源码目录一律禁止
-
-### 文件门禁（fileGate）
-
-文档类、配置类文件在所有阶段放行，不受阶段和位置限制：
-
-- `.sillyspec/` 开头的路径
-- `.md` 文件
-- `package.json`、`tsconfig.json`、`local.yaml` 等配置文件
-- `.git/` 下的文件
-
-### Bash 命令拦截
-
-| 类型 | 示例 |
-|------|------|
-| **只读放行** | `grep`、`cat`、`git diff`、`git status`、`ls`、`find`、`sillyspec worktree apply/create/list/cleanup` |
-| **禁止** | `git add`、`git commit`、`git push`、`git checkout`、`rm -rf`、`sudo` 等 |
-| **不确定** | 启发式判断，放行但警告 |
-
-> 在 worktree 目录下执行 Bash 命令时全部放行，不做拦截。
-
-## 降级方案和逃生开关
-
-| 场景 | 处理方式 |
-|------|---------|
-| **git < 2.15** | 不支持 worktree，报错停止 |
-| **`--no-worktree` 标志** | 跳过隔离创建，但 hook 仍然拦截源码写入 |
-| **`SILLYSPEC_DISABLE_HOOKS=1`** | 紧急禁用所有 hook，全部放行 |
-| **无 gate-status.json** | stageGate=false，默认禁止源码写入 |
-| **worktree 创建失败** | 自动降级为 in-place + baseline protection（mode: in-place-fallback） |
-| **已在 linked worktree** | 复用当前目录（mode: native-worktree） |
-| **worktree 目录未 ignore** | 阻断创建，提示修复 |
-
-> ⚠️ in-place 降级模式仍会记录 baseline（baselineFiles + baselineHash + baselineCommit），hook 拦截继续生效，不会无保护地直接写源码。
-
-## 多 Agent 并行使用
-
-不同的 AI 子代理可以同时创建各自的 worktree：
-
-```bash
-# Agent A 处理 task-01
-sillyspec worktree create feature-auth
-# worktree: .sillyspec/.runtime/worktrees/feature-auth/
-
-# Agent B 处理 task-02
-sillyspec worktree create feature-ui
-# worktree: .sillyspec/.runtime/worktrees/feature-ui/
-```
-
-两个 Agent 在各自的 worktree 中独立工作，互不干扰。各自完成后分别 apply 合入主工作区。
-
-> 💡 如果两个 Agent 修改了相同的文件，后 apply 的一方可能遇到冲突。建议在 `plan` 阶段通过 Wave 分组避免同一文件被多个 Agent 修改。
-
-## 环境变量
-
-| 变量 | 说明 |
-|------|------|
-| `SILLYSPEC_DISABLE_HOOKS` | 设为 `1` 时禁用所有 hook（紧急逃生） |
-| `SILLYSPEC_WORKTREE_DIR` | 自定义 worktree 存储目录（默认 `.sillyspec/.runtime/worktrees/`） |
-
-## 环境隔离检测
-
-SillySpec 在创建 worktree 前会自动检测当前环境的隔离状态：
-
-### submodule 防护
-
-使用 `git rev-parse --git-dir` 和 `--git-common-dir` 判断是否在 linked worktree 中。
-同时用 `--show-superproject-working-tree` 排除 git submodule 的误判：
-
-```
-if GIT_DIR != GIT_COMMON && 无 superproject:
-  → 已在 linked worktree，复用当前隔离环境
-if 无 superproject 为空:
-  → 在 git submodule 内，阻断创建并提示
-else:
-  → 在主仓库中，正常创建 worktree
-```
-
-### .gitignore 强制校验
-
-worktree 存储目录 `.sillyspec/.runtime/worktrees/` 必须被 `.gitignore` 忽略：
-
-- **init / doctor 阶段：** 预检查并提示修复
-- **execute 阶段：** 未 ignore 则直接阻断 worktree 创建，抛出明确错误
-- **不会自动修改 .gitignore：** 避免污染 baseline
-
-修复方式：在项目 `.gitignore` 中添加：
-```
-.sillyspec/.runtime/worktrees/
-```
-
-### isolation 状态
-
-worktree create 后，isolation 状态写入 `sillyspec.db` 的 `changes` 表（权威状态源）：
-
-| 字段 | 说明 |
-|------|------|
-| `isolation_status` | pending / verified / degraded / blocked |
-| `isolation_mode` | worktree / native-worktree / in-place-fallback / null |
-| `isolation_reason` | blocked 或 degraded 时的原因说明 |
-
-状态映射：
-
-| status | mode | 触发条件 |
-|--------|------|----------|
-| verified | worktree | `git worktree add` 成功 |
-| verified | native-worktree | 已在 linked worktree，复用 |
-| degraded | in-place-fallback | `git worktree add` 失败，降级 in-place |
-| blocked | null | submodule 内 / gitignore 未配置 |
-| null | null | 尚未执行隔离检查 |
-
-> ⚠️ isolation 的权威来源是 sillyspec.db。meta.json 中的 mode 仅作为 worktree 目录的运行时元信息。gate-status.json 不存储 isolation。
-
-## 常见问题和故障排除
-
-### worktree 残留无法清理
-
-```bash
-# 查看所有活跃 worktree
-sillyspec worktree list
-
-# 强制清理指定 worktree
-sillyspec worktree cleanup <change-name>
-
-# 如果 worktree 目录被手动删除但分支残留
-git worktree prune
-git branch -D sillyspec/<change-name>
-```
-
-### apply 失败：base hash 不一致
-
-说明主工作区在 worktree 创建后又被修改过。处理方式：
-
-1. 检查主工作区的变更：`git diff`
-2. 如果主工作区变更不重要 → `git stash` 后重试 apply
-3. 如果重要 → 手动解决冲突
-
-### apply 失败：文件清单校验不通过
-
-说明 worktree 中修改了 `design.md` 清单之外的文件。处理方式：
-
-1. 查看清单外文件：apply 的输出会列出
-2. 确认是否是合理的新增（如测试文件）
-3. 更新 `design.md` 中的文件变更清单后重试
-4. 或用 `--check-only` 排查后再 apply
-
-### Hook 误拦截了合法操作
-
-- 临时方案：设置 `SILLYSPEC_DISABLE_HOOKS=1` 环境变量
-- 检查目标文件是否应加入文件白名单（fileGate）
-- 检查当前阶段是否正确（gate-status.json）
-
-### worktree 内 node_modules 问题
-
-worktree 创建后需要安装依赖：
-
-```bash
-cd .sillyspec/.runtime/worktrees/<change-name>/
-npm install
-```
-
-如果项目使用 pnpm 且有 monorepo，可能需要额外配置。