sillyspec 3.15.2 → 3.16.0

package/.husky/pre-push

@@ -0,0 +1,13 @@
+#!/bin/sh
+echo "🔧 pre-push: running lint + test..."
+npm run lint --silent 2>&1
+if [ $? -ne 0 ]; then
+  echo "❌ pre-push: lint failed, aborting push"
+  exit 1
+fi
+npm test --silent 2>&1
+if [ $? -ne 0 ]; then
+  echo "❌ pre-push: test failed, aborting push"
+  exit 1
+fi
+echo "✅ pre-push: lint + test passed"

package/docs/sillyspec/file-lifecycle.md

@@ -1,7 +1,7 @@
 ---
 author: qinyi
 created_at: 2026-05-31 11:00:00
-updated_at: 2026-06-03 16:00:00
+updated_at: 2026-06-04 13:20:00
 ---
 
 # SillySpec 文件生命周期描述
@@ -75,6 +75,63 @@ updated_at: 2026-06-03 16:00:00
 └── codebase/SCAN-RAW.md        ← 原始扫描数据（gitignore）
 ```
 
+## 1.1 平台模式目录结构（SillyHub 等）
+
+> 当通过 `--spec-root` 和 `--runtime-root` 参数调用时，SillySpec 进入平台模式。
+> `--spec-root` 的语义是 **SillySpec Storage Root**（替代 `.sillyspec/` 的位置），不是 scan docs root。
+
+**调用方式：**
+```shell
+sillyspec run scan   --spec-root <storage-root>   --runtime-root <runtime-root>   --workspace-id <id>   --scan-run-id <id>
+```
+
+**平台模式输出结构：**
+```
+<spec-root>/
+└── .sillyspec/                    ← SillySpec storage root（由 --spec-root 指定）
+    ├── docs/                      ← 扫描文档（scan/modules/flows/glossary）
+    │   └── <project>/
+    │       ├── scan/
+    │       ├── modules/
+    │       ├── flows/
+    │       └── glossary.md
+    ├── projects/                  ← 项目注册表
+    ├── workflows/                 ← workflow 定义
+    ├── knowledge/                 ← 知识库
+    ├── local.yaml                 ← 本地配置
+    └── manifest.json              ← 平台模式元数据
+
+<runtime-root>/
+└── scan-runs/
+    └── <scan-run-id>/            ← 单次 scan 的运行时产物
+```
+
+**路径映射：**
+| 本地模式路径 | 平台模式路径 |
+|-------------|-------------|
+| `.sillyspec/docs/` | `<spec-root>/.sillyspec/docs/` |
+| `.sillyspec/projects/` | `<spec-root>/.sillyspec/projects/` |
+| `.sillyspec/workflows/` | `<spec-root>/.sillyspec/workflows/` |
+| `.sillyspec/knowledge/` | `<spec-root>/.sillyspec/knowledge/` |
+| `.sillyspec/.runtime/` | `<runtime-root>/` |
+| `.sillyspec/.runtime/artifacts/` | `<runtime-root>/scan-runs/<scan-run-id>/` |
+| `.sillyspec/.runtime/workflow-runs/` | `<runtime-root>/scan-runs/<scan-run-id>/workflow-runs/` |
+
+**不传参数时，行为与本地模式完全一致。**
+
+**路径占位符机制：**
+scan.js 模板中使用 `{DOCS_ROOT}` 和 `{PROJECTS_ROOT}` 占位符，由 `run.js` 的 `outputStep` 在输出 prompt 前替换：
+
+| 占位符 | 本地模式 | 平台模式 |
+|--------|---------|---------|
+| `{DOCS_ROOT}` | `cwd/.sillyspec/docs/<project>` | `<spec-root>/.sillyspec/docs/<project>` |
+| `{PROJECTS_ROOT}` | `cwd/.sillyspec/projects` | `<spec-root>/.sillyspec/projects` |
+
+> 这确保 agent 看到的 prompt 中路径已替换为真实路径，不会因为模板硬编码而写错位置。
+
+---
+
+
 ## 2. 全局状态文件
 
 ### `sillyspec.db` — SQLite 数据库（全局状态与变更进度）
@@ -96,7 +153,7 @@ updated_at: 2026-06-03 16:00:00
 | 表 | 用途 | 对应旧版 |
 |------|------|------|
 | `project` | 项目名、schema 版本 | `global.json` 的 `_version` + `project` |
-| `changes` | 变更注册表（名称、当前阶段、状态） | `global.json` 的 `activeChanges` + `progress.json` 的顶层字段 |
+| `changes` | 变更注册表（名称、当前阶段、状态、isolation） | `global.json` 的 `activeChanges` + `progress.json` 的顶层字段 |
 | `stages` | 阶段状态（status / startedAt / completedAt） | `progress.json` 的 `stages.*` |
 | `steps` | 步骤状态（name / status / output） | `progress.json` 的 `stages.*.steps[]` |
 | `batch_progress` | 批量进度统计 | `progress.json` 的 `batchProgress` |
@@ -165,6 +222,9 @@ updated_at: 2026-06-03 16:00:00
 | `currentChange` | `changes.name` | 当前变更名 |
 | `lastActive` | `changes.last_active` | 最后活跃时间 |
 | `noWorktree` | `changes.no_worktree` | 跳过 worktree 标记 |
+| `isolation_status` | `changes.isolation_status` | 隔离状态：pending/verified/degraded/blocked |
+| `isolation_mode` | `changes.isolation_mode` | 隔离模式：worktree/native-worktree/in-place-fallback |
+| `isolation_reason` | `changes.isolation_reason` | blocked/degraded 时的原因说明 |
 | `stages.<name>.status` | `stages.status` | 阶段状态 |
 | `stages.<name>.startedAt` | `stages.started_at` | 阶段开始时间 |
 | `stages.<name>.completedAt` | `stages.completed_at` | 阶段完成时间 |
@@ -517,7 +577,11 @@ PASS / PASS WITH NOTES / FAIL
 
 **创建时机：** scan 阶段的深度扫描步骤
 
-**存储位置：** `.sillyspec/docs/<project>/scan/`
+**存储位置：**
+- 本地模式：`.sillyspec/docs/<project>/scan/`
+- 平台模式：`<spec-root>/.sillyspec/docs/<project>/scan/`
+
+> scan.js 模板中使用 `{DOCS_ROOT}` 占位符，由 `outputStep` 在运行时替换为实际路径。平台模式通过 `--spec-root` 参数指定 storage root。
 
 **七份文档：**
 | 文件 | 生成步骤 | 内容 |
@@ -661,7 +725,11 @@ modules:
   "baseHash": "abc123...",
   "actualBaseHash": "def456...",
   "createdAt": "2026-05-28T14:00:00.000Z",
-  "worktreePath": "/path/to/.sillyspec/.runtime/worktrees/..."
+  "worktreePath": "/path/to/.sillyspec/.runtime/worktrees/...",
+  "mode": "worktree",
+  "baselineFiles": [],
+  "baselineCommit": null,
+  "baselineHash": null
 }
 ```
 
@@ -675,6 +743,10 @@ modules:
 | `actualBaseHash` | string | fetch+merge 后的实际 HEAD（可能与 baseHash 不同） |
 | `createdAt` | string | ISO 时间戳 |
 | `worktreePath` | string | worktree 目录绝对路径 |
+| `mode` | string | 隔离模式：`worktree` / `native-worktree` / `in-place-fallback` |
+| `baselineFiles` | string[] | dirty baseline overlay 的文件列表 |
+| `baselineCommit` | string? | baseline checkpoint commit hash |
+| `baselineHash` | string? | baseline snapshot hash |
 
 **特殊行为：** 创建后自动 `fetch origin` + `merge origin/main --ff-only` 同步远程最新代码，`actualBaseHash` 记录 merge 后的实际 HEAD。如果本地和远程没有共同祖先则跳过 merge。
 
@@ -807,7 +879,45 @@ test_strategy: module
 
 ---
 
-## 8. 文件销毁与归档
+## 8. manifest.json — 平台模式元数据
+
+**创建时机：** 平台模式 scan 阶段全部步骤完成后，由 `runStage()` 自动生成
+
+**存储位置：** `<spec-root>/.sillyspec/manifest.json`
+
+**触发条件：** `sillyspec run scan --spec-root <path>` 传入时
+
+**数据结构：**
+```json
+{
+  "workspace_id": "ws-001",
+  "scan_run_id": "scan-20260604-103000",
+  "source_commit": "abc123def456...",
+  "generated_at": "2026-06-04T10:30:00.000+08:00",
+  "schema_version": 1
+}
+```
+
+**字段说明：**
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `workspace_id` | string? | SillyHub workspace ID（来自 `--workspace-id`） |
+| `scan_run_id` | string? | 本次 scan run ID（来自 `--scan-run-id`） |
+| `source_commit` | string? | 被扫描源码的 git HEAD（非 git 目录时为 null，summary 会提示） |
+| `generated_at` | string | ISO 时间戳 |
+| `schema_version` | integer | manifest 格式版本，当前为 1 |
+
+**写入方：** `runStage()` 中 scan 阶段完成回调（使用 `platformOpts.specRoot` 解析路径）
+
+**后置校验：** scan 完成后检查 source_root（cwd）的 `.sillyspec/docs/` 是否被意外污染，发现时输出 warning。
+
+**读取方：** SillyHub 后端读取 workspace spec 信息
+
+**生命周期：** 每次 scan run 完成时覆盖写入（同 workspace 下只保留最新一次）
+
+---
+
+## 9. 文件销毁与归档
 
 ### 变更归档流程
 
@@ -821,12 +931,32 @@ test_strategy: module
 
 ### Worktree 清理流程
 
-**触发：** `WorktreeManager.cleanup()`
+**触发：** `WorktreeManager.cleanup(changeName)`
 
-**操作：**
+**安全检查（mode-based）：**
+
+| mode | 行为 | 结果 |
+|------|------|------|
+| `worktree`（SillySpec 创建） | 执行删除 | `cleaned` |
+| `native-worktree`（外部隔离） | **拒绝删除**（除非 `--force`） | 抛错 / `kept` |
+| `in-place-fallback`（降级） | 跳过，无目录可删 | `skipped` / `none` |
+| unknown / missing | 不删除 | `kept` |
+
+**操作（mode=worktree 时）：**
 1. `git worktree remove <path> --force`
-2. `git branch -D <branch>`（忽略分支不存在错误）
-3. 确保目录已删除
+2. 确保目录已删除（fallback rmSync）
+3. `git branch -D <branch>`（忽略分支不存在错误）
+4. 清除 meta 目录
+5. 返回 `{ result: 'cleaned', mode }`
+
+**执行摘要 Worktree 状态：**
+
+| 场景 | 摘要显示 |
+|------|----------|
+| worktree 目录已被删除 | `Worktree: cleaned` |
+| native-worktree 保留 | `Worktree: kept (external worktree)` |
+| in-place-fallback | `Worktree: none (in-place)` |
+| worktree 仍存在 | `Worktree: exists` |
 
 ### 数据存储迁移
 
@@ -859,7 +989,7 @@ test_strategy: module
 
 ---
 
-## 9. 可选 / 条件生成文件
+## 10. 可选 / 条件生成文件
 
 以下文件不一定存在，在特定条件下才会生成。
 

package/docs/worktree-isolation.md

@@ -117,9 +117,11 @@ allowWrite = stageGate && locationGate && fileGate
 | **`--no-worktree` 标志** | 跳过隔离创建，但 hook 仍然拦截源码写入 |
 | **`SILLYSPEC_DISABLE_HOOKS=1`** | 紧急禁用所有 hook，全部放行 |
 | **无 gate-status.json** | stageGate=false，默认禁止源码写入 |
-| **worktree 创建失败** | 报错停止，不进入无隔离状态 |
+| **worktree 创建失败** | 自动降级为 in-place + baseline protection（mode: in-place-fallback） |
+| **已在 linked worktree** | 复用当前目录（mode: native-worktree） |
+| **worktree 目录未 ignore** | 阻断创建，提示修复 |
 
-> ⚠️ 不存在"降级到放行"的路径。只有"降级到更严格"或"紧急逃生开关"。设计原则是默认安全。
+> ⚠️ in-place 降级模式仍会记录 baseline（baselineFiles + baselineHash + baselineCommit），hook 拦截继续生效，不会无保护地直接写源码。
 
 ## 多 Agent 并行使用
 
@@ -146,6 +148,59 @@ sillyspec worktree create feature-ui
 | `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 残留无法清理

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.15.2",
+  "version": "3.16.0",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",
@@ -23,6 +23,10 @@
     "spec-driven"
   ],
   "license": "MIT",
+  "scripts": {
+    "test": "node test/*.test.mjs",
+    "lint": "node --check src/index.js && node --check src/run.js && node --check src/progress.js && node --check src/db.js && node --check src/worktree.js && node --check src/workflow.js && node --check src/worktree-apply.js"
+  },
   "dependencies": {
     "@inquirer/prompts": "^7.10.1",
     "chalk": "^5.6.2",

package/src/db.js

@@ -164,5 +164,22 @@ export class DB {
     this.db.run('CREATE INDEX IF NOT EXISTS idx_changes_status ON changes(status)');
     this.db.run('CREATE INDEX IF NOT EXISTS idx_stages_change ON stages(change_id)');
     this.db.run('CREATE INDEX IF NOT EXISTS idx_steps_stage ON steps(stage_id)');
+
+    // Migration: add isolation columns to changes table (idempotent)
+    this._migrateAddColumn('changes', 'isolation_status', 'TEXT');
+    this._migrateAddColumn('changes', 'isolation_mode', 'TEXT');
+    this._migrateAddColumn('changes', 'isolation_reason', 'TEXT');
+  }
+
+  /**
+   * 幂等地给表添加列（列已存在则跳过）
+   * @private
+   */
+  _migrateAddColumn(table, column, type) {
+    try {
+      this.db.run(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+    } catch {
+      // 列已存在，静默跳过
+    }
   }
 }

package/src/index.js

@@ -32,6 +32,10 @@ SillySpec CLI — 规范驱动开发工具包
     --status                   查看阶段进度
     --reset                    重置阶段
     --change <name>            设置当前变更名
+    --spec-root <path>         平台模式：SillySpec storage root 路径
+    --runtime-root <path>       平台模式：运行时产物根路径
+    --workspace-id <id>         平台模式：workspace ID
+    --scan-run-id <id>          平台模式：scan run ID
     auto                       连续推进 brainstorm→plan→execute→verify
 
   可选阶段:
@@ -270,10 +274,29 @@ async function main() {
     }
     case 'worktree': {
       const { WorktreeManager } = await import('./worktree.js');
+      const { ProgressManager } = await import('./progress.js');
       const wtSubCmd = filteredArgs[1];
-      // 提取第一个非 -- 开头的位置参数作为 wtName
       const wtName = filteredArgs.slice(2).find(a => !a.startsWith('-'));
       const wm = new WorktreeManager({ cwd: dir });
+      const pm = new ProgressManager();
+
+      // isolation 写入 DB 的辅助函数
+      async function _writeIsolationToDB(cwd, changeName, info) {
+        if (info.blocked) {
+          await pm.updateChangeIsolation(cwd, changeName, {
+            status: 'blocked',
+            mode: null,
+            reason: info.reason,
+          });
+        } else {
+          const mode = info.mode || 'worktree';
+          const statusMap = { 'worktree': 'verified', 'native-worktree': 'verified', 'in-place-fallback': 'degraded' };
+          await pm.updateChangeIsolation(cwd, changeName, {
+            status: statusMap[mode] || 'verified',
+            mode,
+          });
+        }
+      }
 
       if (!wtSubCmd || wtSubCmd === 'help' || wtSubCmd === '--help' || wtSubCmd === '-h') {
         console.log(`
@@ -306,8 +329,15 @@ SillySpec worktree — git worktree 隔离管理
             console.log(`   分支: ${info.branch}`);
             console.log(`   路径: ${info.worktreePath}`);
             console.log(`   基准: ${info.baseHash.slice(0, 8)}`);
+            if (info.mode) {
+              console.log(`   模式: ${info.mode}`);
+            }
+            // 写入 isolation 信息到 gate-status.json
+            await _writeIsolationToDB(dir, wtName, info);
           } catch (e) {
             console.error(`❌ ${e.message}`);
+            // 写入 blocked 状态到 gate-status.json
+            await _writeIsolationToDB(dir, wtName, { blocked: true, reason: e.message });
             process.exit(1);
           }
           break;
@@ -373,9 +403,20 @@ SillySpec worktree — git worktree 隔离管理
             console.error('❌ 用法: sillyspec worktree cleanup <change-name>');
             process.exit(1);
           }
+          const forceFlag = args.includes('--force');
           try {
-            wm.cleanup(wtName);
-            console.log(`✅ worktree 已清理: ${wtName}`);
+            const result = wm.cleanup(wtName, { force: forceFlag });
+            if (result.result === 'cleaned') {
+              console.log(`✅ worktree 已清理: ${wtName} (mode: ${result.mode})`);
+            } else if (result.result === 'force-cleaned') {
+              console.log(`⚠️  worktree 已强制清理: ${wtName} (mode: ${result.mode})`);
+              console.log(`   原因: git worktree remove 失败，通过直接删除目录完成`);
+            } else if (result.result === 'skipped') {
+              console.log(`⏭️  worktree 跳过清理: ${wtName} (mode: ${result.mode})`);
+              console.log(`   原因: in-place 模式没有隔离目录需要清理`);
+            } else {
+              console.log(`ℹ️  worktree 未找到: ${wtName}`);
+            }
           } catch (e) {
             console.error(`❌ ${e.message}`);
             process.exit(1);

package/src/progress.js

@@ -393,6 +393,48 @@ export class ProgressManager {
     });
   }
 
+  /**
+   * 更新变更的隔离状态
+   * @param {string} cwd - 项目根目录
+   * @param {string} changeName - 变更名
+   * @param {{ status: string, mode?: string, reason?: string }} isolation
+   */
+  async updateChangeIsolation(cwd, changeName, isolation) {
+    const db = await this._ensureDB(cwd);
+    const sqlDb = db.getDb();
+    try {
+      sqlDb.run(
+        `UPDATE changes SET isolation_status = ?, isolation_mode = ?, isolation_reason = ?, last_active = ? WHERE name = ?`,
+        [isolation.status, isolation.mode || null, isolation.reason || null, new Date().toISOString(), changeName]
+      );
+      db._save();
+    } catch (err) {
+      console.warn('⚠️  更新 isolation 状态失败:', err.message);
+    }
+  }
+
+  /**
+   * 读取变更的隔离状态
+   * @param {string} cwd - 项目根目录
+   * @param {string} changeName - 变更名
+   * @returns {{ status: string|null, mode: string|null, reason: string|null }|null}
+   */
+  async readChangeIsolation(cwd, changeName) {
+    const db = await this._ensureDB(cwd);
+    const sqlDb = db.getDb();
+    try {
+      const rows = sqlDb.exec(
+        `SELECT isolation_status, isolation_mode, isolation_reason FROM changes WHERE name = ?`,
+        [changeName]
+      );
+      if (!rows || rows.length === 0 || rows[0].values.length === 0) return null;
+      const [status, mode, reason] = rows[0].values[0];
+      return { status: status || null, mode: mode || null, reason: reason || null };
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * 重命名变更：同步更新 DB + 目录
    * @param {string} cwd - 项目根目录