sillyspec 3.12.0 → 3.12.2

package/CLAUDE.md

@@ -0,0 +1,18 @@
+# Claude Code 指引
+
+## 文件生命周期文档同步
+每次修改 `src/stages/` 下的阶段定义（prompt、步骤、输出文件名等）或 `src/run.js`、`src/progress.js` 等影响文件生命周期的代码后，**必须同步更新** `docs/sillyspec/file-lifecycle.md`，确保文档与代码一致。
+
+### 触发更新的典型改动
+- 新增/删除/重命名阶段步骤
+- 修改步骤 prompt 中的输出文件名（如 verify-result.md）
+- 修改阶段间的流转逻辑（如 archive 归档方式）
+- 新增/删除运行时文件类型（如 gate-status.json）
+- 修改 ProgressManager 的数据存储方式（如 SQLite 表结构变更）
+
+### 更新检查清单
+- [ ] 文件名引用一致（prompt 输出的文件名 == validateFileLocations 期望的文件名）
+- [ ] 阶段步骤描述与 `src/stages/*.js` 一致
+- [ ] 归档/清理流程描述与实际代码逻辑一致
+- [ ] 数据库 Schema 描述与 `src/db.js` 一致
+- [ ] 更新文档头部 `updated_at` 时间戳

package/docs/sillyspec/file-lifecycle.md

@@ -1,7 +1,7 @@
 ---
 author: qinyi
 created_at: 2026-05-31 11:00:00
-updated_at: 2026-05-31 11:00:00
+updated_at: 2026-05-31 21:35:00
 ---
 
 # SillySpec 文件生命周期描述
@@ -33,7 +33,7 @@ updated_at: 2026-05-31 11:00:00
 │   │   ├── tasks/              ← 单任务实现文档目录（plan 阶段创建）
 │   │   │   └── task-NN.md
 │   │   ├── module-impact.md    ← 模块影响分析矩阵
-│   │   ├── verification.md     ← 验证报告（⚠️ prompt 写 verification.md，validateFileLocations 期望 verify-result.md）
+│   │   ├── verify-result.md    ← 验证报告（归档产物）
 │   │   ├── prototype-*.html   ← HTML 原型（可选，brainstorm 判断）
 │   │   └── MASTER.md           ← 大需求拆分主控（可选，brainstorm 判断拆分时）
 │   └── archive/               ← 已归档变更
@@ -472,9 +472,7 @@ created_at: <YYYY-MM-DD HH:mm:ss>
 
 ---
 
-### `verify-result.md` / `verification.md` — 验证报告
-
-> ⚠️ **代码存在命名不一致**：verify 阶段 prompt 中输出文件名为 `verification.md`，但 `validateFileLocations()` 期望的文件名是 `verify-result.md`。实际运行时 AI 按照 prompt 写入 `verification.md`，但位置校验会报 `verify-result.md` 缺失。这是已知的不一致。
+### `verify-result.md` — 验证报告
 
 **创建时机：** verify 阶段"输出验证报告"步骤
 
@@ -529,7 +527,7 @@ PASS / PASS WITH NOTES / FAIL
 
 **临时文件：** `_env-detect.md`（环境探测中间产物，扫描完成后删除）
 
-**断点续扫：** "断点续扫检测"步骤检查已有文档，只生成缺失的
+**断点续扫：** "检查已有扫描文档和子项目列表"步骤检查已有文档，**必须停下来问用户**选择「全部重新扫描」或「只补缺失文档」，不能自行决定跳过。
 
 **生命周期：** scan 阶段生成 → 被后续所有阶段（brainstorm/propose/plan/execute/verify）作为上下文读取
 
@@ -580,7 +578,9 @@ modules:
 
 ### `<module>.md` — 模块当前状态描述
 
-**创建时机：** archive 阶段 `sync-module-docs` 步骤（首次受影响时创建，后续更新）
+**创建时机：**
+- scan 阶段"生成模块核心文档"步骤（可选，首次全量生成，需用户确认）
+- archive 阶段 `sync-module-docs` 步骤（首次受影响时创建，后续更新）
 
 **大体结构：**
 ```markdown
@@ -629,7 +629,8 @@ modules:
 - 更新头部元数据：`> 最后更新：YYYY-MM-DD` 和 `> 最近变更：<change-name>`
 
 **更新时机：**
-- archive 阶段 `sync-module-docs` 步骤（通过 module-impact.md 驱动）
+- scan 阶段"生成模块核心文档"步骤（首次全量生成，需用户确认）
+- archive 阶段 `sync-module-docs` 步骤（通过 module-impact.md 驱动增量更新）
 - quick 阶段"暂存和更新记录"步骤（直接匹配 git diff 文件到模块，同步更新）
 
 **消费方：** brainstorm/propose/plan/execute 阶段"加载上下文"时读取，作为开发参考
@@ -758,12 +759,12 @@ test_strategy: module
 
 ### 变更归档流程
 
-**触发：** archive 阶段"确认归档"步骤 + `--confirm` 标志
+**触发：** archive 阶段"确认归档"步骤（AI 直接执行 mkdir + mv 移动变更目录）
 
 **操作：**
-1. `mkdirSync` 创建 `archive/` 目录
-2. `renameSync` 将 `changes/<name>/` 移动到 `changes/archive/YYYY-MM-DD-<name>/`
-3. 校验：源目录不存在 + 目标目录存在
+1. AI 创建 `archive/` 目录：`mkdir -p .sillyspec/changes/archive`
+2. AI 移动变更目录：`mv .sillyspec/changes/<name> .sillyspec/changes/archive/<name>`
+3. AI 确认移动成功：`ls .sillyspec/changes/archive/<name>/`
 4. `unregisterChange()` 将 `changes.status` 更新为 `archived`（SQL UPDATE）
 
 ### Worktree 清理流程
@@ -1036,7 +1037,8 @@ graph LR
 | `AGENTS.md` 等 | 选了 codex/gemini/opencode 工具 | init | AI 工具读取 |
 | `projects/*.yaml` | init 自动创建 | init | 子项目上下文加载 |
 | `modules/_module-map.yaml` | scan 可选步骤 | scan | archive/plan/execute |
-| `verification.md` | verify 阶段输出 | verify | 验证报告存档 |
+| `modules/<module>.md` | scan 可选步骤（全量生成）+ archive sync-module-docs | scan/archive | propose/plan/execute/verify/quick |
+| `verify-result.md` | verify 阶段输出 | verify | 验证报告存档 |
 
 
 ```
@@ -1049,7 +1051,7 @@ sillyspec init
     ├─→ .sillyspec/knowledge/
     └─→ .gitignore (追加 .sillyspec/.runtime/)
 
-scan 阶段
+scan 阶段（12 步，完成后重置）
     │
     ├─→ docs/<name>/scan/ARCHITECTURE.md
     ├─→ docs/<name>/scan/CONVENTIONS.md
@@ -1059,6 +1061,7 @@ scan 阶段
     ├─→ docs/<name>/scan/CONCERNS.md
     ├─→ docs/<name>/scan/PROJECT.md
     ├─→ docs/<name>/modules/_module-map.yaml (可选)
+    ├─→ docs/<name>/modules/<module>.md (可选，需用户确认)
     └─→ .sillyspec/local.yaml
 
 brainstorm 阶段
@@ -1093,15 +1096,17 @@ execute 阶段
 
 verify 阶段
     │
-    └─→ changes/<name>/verification.md （⚠️ prompt 输出 verification.md，validateFileLocations 期望 verify-result.md）
+    └─→ changes/<name>/verify-result.md
 
-quick 阶段（辅助阶段，不走完整流程）
+quick 阶段（辅助阶段，不走完整流程，完成后重置）
     │
     ├─→ .sillyspec/quicklog/QUICKLOG-<user>.md (无 --change 时)
     ├─→ .sillyspec/.runtime/worktrees/<name>/meta.json
     ├─→ .sillyspec/.runtime/gate-status.json
     └─→ docs/<name>/modules/<module>.md (直接同步，不经过 module-impact.md)
 
+> quick 阶段"理解任务"步骤会加载模块文档作为上下文参考。
+
 archive 阶段
     │
     ├─→ changes/<name>/module-impact.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.12.0",
+  "version": "3.12.2",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/hooks/worktree-guard.js

@@ -5,7 +5,7 @@
  * 纯判断模块，不做实际的 hook 注入。
  *
  * P0 优化：
- * - 阶段检测 fallback：gate-status.json → progress.json currentStage
+ * - 阶段检测 fallback：gate-status.json → sillyspec.db currentStage
  * - 拦截提示针对每个阶段给出具体修复建议
  */
 
@@ -100,41 +100,27 @@ function readGateStatus(cwd) {
 }
 
 /**
- * 从 progress.json fallback 读取 currentStage
- * 优先级：gate-status.json > 全局 progress.json > 变更级 progress.json
+ * 从 sillyspec.db 读取 currentStage
+ * 优先级：gate-status.json > sillyspec.db
  * @param {string} cwd
  * @returns {string|null} 阶段名，null 表示无法确定
  */
 function readCurrentStage(cwd) {
-  // 1. gate-status.json（权威来源）
+  // 1. gate-status.json（高速缓存，权威来源）
   const gateStatus = readGateStatus(cwd)
   if (gateStatus && gateStatus.stage) return gateStatus.stage
 
-  // 2. 全局 progress.json
-  const globalProgress = path.join(cwd, '.sillyspec', '.runtime', 'progress.json')
-  if (existsSync(globalProgress)) {
-    try {
-      const data = JSON.parse(readFileSync(globalProgress, 'utf8'))
-      if (data.currentStage) return data.currentStage
-    } catch { /* skip */ }
-  }
-
-  // 3. 变更级 progress.json（从 global.json 找到活跃变更）
-  const globalFile = path.join(cwd, '.sillyspec', '.runtime', 'global.json')
-  if (existsSync(globalFile)) {
-    try {
-      const global = JSON.parse(readFileSync(globalFile, 'utf8'))
-      const changesDir = path.join(cwd, '.sillyspec', 'changes')
-      for (const cn of (global.activeChanges || [])) {
-        const pp = path.join(changesDir, cn, 'progress.json')
-        if (!existsSync(pp)) continue
-        try {
-          const data = JSON.parse(readFileSync(pp, 'utf8'))
-          if (data.currentStage) return data.currentStage
-        } catch { /* skip */ }
-      }
-    } catch { /* skip */ }
-  }
+  // 2. 从 sillyspec.db 读取（通过 sqlite3 CLI 同步调用）
+  const dbPath = path.join(cwd, '.sillyspec', '.runtime', 'sillyspec.db')
+  if (!existsSync(dbPath)) return null
+  try {
+    const { execSync } = require('child_process')
+    const result = execSync(
+      `sqlite3 "${dbPath}" "SELECT current_stage FROM changes WHERE status='active' AND current_stage IN ('execute','quick') ORDER BY last_active DESC LIMIT 1"`,
+      { encoding: 'utf8', timeout: 2000 }
+    ).trim()
+    return result || null
+  } catch { /* sqlite3 CLI 不可用或查询失败 */ }
 
   return null
 }
@@ -149,35 +135,17 @@ function isNoWorktreeMode(cwd) {
   const gateStatus = readGateStatus(cwd)
   if (gateStatus && gateStatus.noWorktree) return true
 
-  // 2. 检查 progress.json
-  const progressFiles = [
-    path.join(cwd, '.sillyspec', '.runtime', 'progress.json'),
-  ]
-  for (const p of progressFiles) {
-    if (!existsSync(p)) continue
-    try {
-      const data = JSON.parse(readFileSync(p, 'utf8'))
-      if (data.noWorktree) return true
-    } catch { /* skip */ }
-  }
-
-  // 3. 检查变更级 progress.json
-  const runtimeDir = path.join(cwd, '.sillyspec', '.runtime')
-  const globalFile = path.join(runtimeDir, 'global.json')
-  if (existsSync(globalFile)) {
-    try {
-      const global = JSON.parse(readFileSync(globalFile, 'utf8'))
-      const changesDir = path.join(cwd, '.sillyspec', 'changes')
-      for (const cn of (global.activeChanges || [])) {
-        const pp = path.join(changesDir, cn, 'progress.json')
-        if (!existsSync(pp)) continue
-        try {
-          const data = JSON.parse(readFileSync(pp, 'utf8'))
-          if (data.noWorktree) return true
-        } catch { /* skip */ }
-      }
-    } catch { /* skip */ }
-  }
+  // 2. 从 sillyspec.db 读取
+  const dbPath = path.join(cwd, '.sillyspec', '.runtime', 'sillyspec.db')
+  if (!existsSync(dbPath)) return false
+  try {
+    const { execSync } = require('child_process')
+    const result = execSync(
+      `sqlite3 "${dbPath}" "SELECT no_worktree FROM changes WHERE status='active' AND current_stage IN ('execute','quick') LIMIT 1"`,
+      { encoding: 'utf8', timeout: 2000 }
+    ).trim()
+    return result === '1'
+  } catch { /* sqlite3 CLI 不可用或查询失败 */ }
 
   return false
 }

package/src/index.js

@@ -4,7 +4,7 @@
  * SillySpec CLI — 安装工具
  *
  * 只负责两件事：init（安装命令模板）和 setup（安装 MCP 工具）。
- * 状态管理通过 progress.json 完成，使用 `sillyspec progress` 命令。
+ * 状态管理通过 sillyspec.db（SQLite）完成，使用 `sillyspec progress` 命令。
  */
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join, resolve } from 'path';
@@ -39,7 +39,7 @@ SillySpec CLI — 规范驱动开发工具包
     quick, explore, status, doctor
 
   sillyspec progress <cmd>     进度记录（轻量，不强制顺序）
-    init                       初始化 progress.json
+    init                       初始化项目数据库
     show                       查看当前进度
     set-stage <stage>          设置当前阶段
     add-step <stage> <name>    添加步骤

package/src/init.js

@@ -56,7 +56,7 @@ const INJECTION_CONTENT = `## SillySpec — 规范驱动开发
 - 遵循 \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\` 中的代码风格
 
 ### 工作流程
-- 读取当前变更的 progress.json 确认当前阶段（使用 \`sillyspec progress show\`）
+- 读取 sillyspec.db 确认当前阶段（使用 \`sillyspec progress show\`）
 - 各阶段产出文件位于 \`.sillyspec/changes/<变更名>/\` 下
 `;
 

package/src/progress.js

@@ -3,11 +3,12 @@
  *
  * 纯 Node.js，无外部依赖。支持多变更并行。
  *
- * 存储结构（v3）：
- *   .sillyspec/.runtime/global.json          — 全局状态（项目名、活跃变更列表）
- *   .sillyspec/changes/<name>/progress.json  — 每个变更独立的阶段/步骤状态
+ * 存储结构：
+ *   .sillyspec/.runtime/sillyspec.db          — SQLite 数据库（权威状态源）
+ *   .sillyspec/.runtime/global.json           — 全局状态缓存（项目名、活跃变更列表）
+ *   .sillyspec/.runtime/gate-status.json      — worktree-guard 门禁状态缓存
  *
- * 向后兼容：如果存在旧的 .sillyspec/.runtime/progress.json，自动迁移。
+ * 历史迁移：v1/v2 使用 progress.json 文件，v3 已全部迁移至 SQLite。
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'fs';
@@ -17,7 +18,6 @@ import { DB } from './db.js';
 const RUNTIME_DIR = '.sillyspec/.runtime';
 const CHANGES_DIR = '.sillyspec/changes';
 const GLOBAL_FILE = 'global.json';
-const PROGRESS_FILE = 'progress.json';
 const CURRENT_VERSION = 3;
 const VALID_STAGES = ['scan', 'brainstorm', 'propose', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
 const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked'];
@@ -154,7 +154,7 @@ export class ProgressManager {
    * 读取指定变更的 progress（SQL 版）
    * @param {string} cwd
    * @param {string|null} changeName - 变更名，null 时尝试自动检测
-   * @returns {Promise<object|null>} 与旧版 progress.json 结构完全一致的 JS 对象
+   * @returns {Promise<object|null>} 与 SQLite 查询结果一致的 JS 对象
    */
   async read(cwd, changeName = null) {
     // 自动检测变更名
@@ -759,7 +759,7 @@ export class ProgressManager {
   async _showChange(cwd, changeName) {
     const data = await this.read(cwd, changeName);
     if (!data) {
-      console.log(`❌ 未找到变更 ${changeName} 的 progress.json`);
+      console.log(`❌ 未找到变更 ${changeName}`);
       return;
     }
 
@@ -816,7 +816,7 @@ export class ProgressManager {
 
   async validate(cwd, changeName = null) {
     const data = await this.read(cwd, changeName);
-    if (!data) { console.log('❌ 无法读取 progress.json'); return false; }
+    if (!data) { console.log('❌ 无法读取进度数据'); return false; }
 
     const errors = [];
     if (!data._version || !Number.isInteger(data._version) || data._version < 1) {
@@ -825,7 +825,7 @@ export class ProgressManager {
     if (!data.stages || typeof data.stages !== 'object') errors.push('缺少 stages');
     if (!VALID_STAGES.every(s => data.stages[s])) errors.push('缺少阶段定义');
 
-    if (errors.length === 0) { console.log('✅ progress.json 格式正确'); return true; }
+    if (errors.length === 0) { console.log('✅ 进度数据格式正确'); return true; }
 
     console.log(`⚠️  发现问题，尝试修复...`);
     let fixed = { ...data, stages: { ...data.stages } };
@@ -852,7 +852,7 @@ export class ProgressManager {
   async reset(cwd, stage, changeName = null) {
     if (stage) {
       const data = await this.read(cwd, changeName);
-      if (!data) { console.log('❌ 无法读取 progress.json'); return; }
+      if (!data) { console.log('❌ 无法读取进度数据'); return; }
       if (!data.stages[stage]) { console.log(`❌ 未知阶段: ${stage}`); return; }
       data.stages[stage] = emptyStage();
       data.lastActive = new Date().toLocaleString('zh-CN',{hour12:false});

package/src/run.js

@@ -2,7 +2,7 @@
  * sillyspec run 命令实现
  *
  * CLI 成为流程引擎，AI 变成步骤执行器。
- * 支持多变更并行：每个变更独立 progress.json。
+ * 支持多变更并行：每个变更状态存储在 sillyspec.db 中。
  */
 import { basename, join } from 'path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, statSync } from 'fs'
@@ -267,7 +267,11 @@ export async function runCommand(args, cwd) {
     const autoChange = changeName || resolveChangeNameAuto(cwd)
     if (autoChange) {
       progress = await pm.initChange(cwd, autoChange)
-    } else if (!isAuxiliary) {
+    } else if (isAuxiliary) {
+      // 辅助阶段（scan/explore/quick/doctor/status）不需要 currentChange
+      // 但仍然需要初始化一个空的 progress 对象以避免后续引用报错
+      progress = { currentStage: stageName, stages: {}, lastActive: new Date().toLocaleString('zh-CN', { hour12: false }) }
+    } else {
       // brainstorm / propose 作为流程入口，自动生成变更名并初始化
       if (stageName === 'brainstorm' || stageName === 'propose') {
         const date = new Date().toISOString().slice(0, 10)
@@ -277,7 +281,7 @@ export async function runCommand(args, cwd) {
         progress = await pm.initChange(cwd, autoName)
         changeName = autoName
       } else {
-        console.error('❌ 未找到 progress.json，请先运行 sillyspec init 或指定 --change <变更名>')
+        console.error('❌ 未找到进度数据，请先运行 sillyspec init 或指定 --change <变更名>')
         process.exit(1)
       }
     }
@@ -304,10 +308,10 @@ export async function runCommand(args, cwd) {
 
   // 确保步骤已初始化
   const changed = await ensureStageSteps(progress, stageName, cwd)
-  if (changed) {
+  if (changed && effectiveChange) {
     await pm._write(cwd, progress, effectiveChange)
     triggerSync(cwd, effectiveChange)
-    progress = await pm.read(cwd, effectiveChange)
+    progress = await pm.read(cwd, effectiveChange) || progress
   }
 
   // --status

package/src/stages/archive.js

@@ -165,7 +165,7 @@ module-impact.md 路径 + 影响模块数量 + 未匹配文件数量`,
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
 2. \`git add .sillyspec/changes/\` — 暂存归档结果（不要 commit，由用户通过统一提交工具处理）
 3. \`git add .sillyspec/docs/\` — 暂存模块文档更新（如有）
-4. 更新 progress.json：
+4. 更新 sillyspec.db 中的阶段状态：
    - 清除当前变更信息（归档后不再活跃）
    - 如果是主变更（有 MASTER.md），标记所有阶段为 ✅，然后清除
    - 历史记录追加时间 + 归档完成

package/src/stages/brainstorm.js

@@ -5,7 +5,7 @@ export const definition = {
   steps: [
     {
       name: '状态检查',
-      prompt: `检查当前变更的 progress.json 确认当前状态。
+      prompt: `检查当前变更的进度状态（sillyspec.db）。
 
 ### 操作
 1. 运行 \`sillyspec progress show\`

package/src/stages/doctor.js

@@ -18,15 +18,10 @@ export const definition = {
 for d in .sillyspec .sillyspec/projects .sillyspec/docs .sillyspec/changes .sillyspec/.runtime; do
   [ -d "$d" ] && echo "✅ $d" || echo "❌ $d"
 done
-# 检查 progress.json（支持新版按变更隔离和旧版全局）
-if [ -d .sillyspec/changes ]; then
-  PROGRESS_FILE=$(find .sillyspec/changes -maxdepth 2 -name progress.json | head -1)
-fi
-if [ -z "$PROGRESS_FILE" ]; then
-  PROGRESS_FILE='.sillyspec/.runtime/progress.json'
-fi
-[ -f "$PROGRESS_FILE" ] && echo "✅ progress.json 存在 ($PROGRESS_FILE)" || echo "❌ progress.json 不存在"
-node -e "JSON.parse(require('fs').readFileSync('$PROGRESS_FILE','utf8')); console.log('✅ progress.json 可解析')" 2>/dev/null || echo "⚠️ progress.json 不可解析"
+# 检查 sillyspec.db（SQLite 权威状态源）
+DB_FILE='.sillyspec/.runtime/sillyspec.db'
+[ -f "$DB_FILE" ] && echo "✅ sillyspec.db 存在" || echo "❌ sillyspec.db 不存在"
+sqlite3 "$DB_FILE" "SELECT count(*) FROM project" 2>/dev/null && echo "✅ sillyspec.db 可查询" || echo "⚠️ sillyspec.db 不可查询"
 \`\`\`
 
 ### 2. 项目配置检查
@@ -46,40 +41,31 @@ done
 
 ### 3. 进度数据一致性
 \`\`\`bash
-# 读取 currentChange 并检查目录存在性
-node -e "
-const p = JSON.parse(require('fs').readFileSync(process.env.PROGRESS_FILE || '.sillyspec/.runtime/progress.json','utf8'));
-const cc = p.currentChange;
-if (!cc) { console.log('ℹ️ 无当前变更'); process.exit(0); }
-const dir = '.sillyspec/changes/' + cc;
-const exists = require('fs').existsSync(dir);
-console.log(exists ? '✅ currentChange 目录存在: ' + cc : '❌ currentChange 目录不存在: ' + cc);
-// 检查各阶段产出
-const stages = p.stages || {};
-for (const [name, sd] of Object.entries(stages)) {
-  if (sd.status === 'completed' && sd.steps.length > 0) {
-    const hasOutput = sd.steps.some(s => s.output && s.output.trim());
-    console.log('  ' + name + ': ' + (hasOutput ? '✅ 有产出' : '⚠️ 已完成但无产出记录'));
-  }
-}
-" 2>/dev/null || echo "⚠️ 无法读取 progress.json"
+# 从 sillyspec.db 读取活跃变更并检查目录存在性
+DB_FILE='.sillyspec/.runtime/sillyspec.db'
+if [ ! -f "$DB_FILE" ]; then echo "⚠️ sillyspec.db 不存在"; exit 0; fi
+ACTIVE_CHANGE=$(sqlite3 "$DB_FILE" "SELECT name FROM changes WHERE status='active' ORDER BY last_active DESC LIMIT 1" 2>/dev/null)
+if [ -z "$ACTIVE_CHANGE" ]; then echo "ℹ️ 无当前变更"; exit 0; fi
+echo "当前变更: $ACTIVE_CHANGE"
+DIR=".sillyspec/changes/$ACTIVE_CHANGE"
+[ -d "$DIR" ] && echo "✅ 变更目录存在: $ACTIVE_CHANGE" || echo "❌ 变更目录不存在: $ACTIVE_CHANGE"
+# 检查各阶段状态
+sqlite3 -header -column "$DB_FILE" "SELECT stage, status FROM stages s JOIN changes c ON s.change_id=c.id WHERE c.name='$ACTIVE_CHANGE' ORDER BY s.stage" 2>/dev/null || echo "⚠️ 无法查询阶段数据"
 \`\`\`
 
 ### 4. 孤儿文件检查
 \`\`\`bash
+DB_FILE='.sillyspec/.runtime/sillyspec.db'
+if [ ! -f "$DB_FILE" ]; then echo "⚠️ sillyspec.db 不存在"; exit 0; fi
 node -e "
 const fs = require('fs');
 const dir = '.sillyspec/changes';
 if (!fs.existsSync(dir)) { console.log('ℹ️ changes/ 目录不存在'); process.exit(0); }
 const subs = fs.readdirSync(dir).filter(f => fs.statSync(dir+'/'+f).isDirectory());
 if (subs.length === 0) { console.log('ℹ️ 无变更目录'); process.exit(0); }
-let progress;
-try { progress = JSON.parse(fs.readFileSync(process.env.PROGRESS_FILE || '.sillyspec/.runtime/progress.json','utf8')); } catch { console.log('⚠️ 无法读取 progress.json'); subs.forEach(s => console.log('❓ ' + s)); process.exit(0); }
-const known = new Set();
-if (progress.currentChange) known.add(progress.currentChange);
-for (const sd of Object.values(progress.stages || {})) {
-  (sd.steps || []).forEach(s => { if (s.output) known.add(s.output); });
-}
+const { execSync } = require('child_process');
+let known;
+try { const rows = execSync('sqlite3 -json \".sillyspec/.runtime/sillyspec.db\" \"SELECT name FROM changes WHERE status=\\\"active\\\"\"', {encoding:'utf8'}).trim(); known = new Set(JSON.parse(rows).map(r => r.name)); } catch { known = new Set(); }
 subs.forEach(s => {
   console.log(known.has(s) ? '✅ ' + s + ' — 已关联' : '⚠️ ' + s + ' — 孤儿目录（可清理）');
 });
@@ -124,12 +110,12 @@ done
 
 ### 1. 探测构建工具
 \`\`\`bash
-# 确定项目路径（使用 progress.json 中的项目或当前目录）
-PROJECT_DIR=$(node -e "
+# 确定项目路径（使用 sillyspec.db 中的项目路径或当前目录）
+PROJECT_DIR=$(sqlite3 -json '.sillyspec/.runtime/sillyspec.db' "SELECT name FROM project WHERE id=1" 2>/dev/null | node -e "const r=JSON.parse(require('fs').readFileSync(0,'utf8'));console.log(r.length>0&&r[0].name?r[0].name:'.')" 2>/dev/null || node -e "
 const fs=require('fs');
-try{const fs=require('fs'),path=require('path');const changesDir='.sillyspec/changes';let pp=null;if(fs.existsSync(changesDir)){const entries=fs.readdirSync(changesDir,{withFileTypes:true}).filter(e=>e.isDirectory()&&e.name!=='archive');if(entries.length===1)pp=path.join(changesDir,entries[0].name,'progress.json');}if(!pp)pp='.sillyspec/.runtime/progress.json';const p=JSON.parse(fs.readFileSync(pp,'utf8'));if(p.project){console.log(p.project);process.exit(0)}}catch{}
-const files=fs.readdirSync('.sillyspec/projects').filter(f=>f.endsWith('.yaml'));
+try{const files=fs.readdirSync('.sillyspec/projects').filter(f=>f.endsWith('.yaml'));
 if(files.length>0){const c=fs.readFileSync('.sillyspec/projects/'+files[0],'utf8');const m=c.match(/^path:\\s*(.+)/m);console.log(m?m[1].trim():'.')}else console.log('.')
+}catch{console.log('.')}
 " 2>/dev/null)
 echo "项目目录: $PROJECT_DIR"
 
@@ -264,7 +250,7 @@ timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ D
 ✅ .sillyspec/ 目录结构 — 正常
 ✅ projects/*.yaml — N 个项目已注册
 ⚠️  local.yaml (xxx) — 缺少 test 命令
-❌ progress.json — brainstorm 标记完成但 design.md 不存在
+❌ sillyspec.db 阶段状态 — brainstorm 标记完成但 design.md 不存在
 
 ## 构建环境
 ✅ Node.js v23.4.0 — 可用
@@ -291,7 +277,7 @@ timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ D
 - 缺少 local.yaml → \`sillyspec init\` 重新生成，或手动创建
 - local.yaml 缺少 build/test → 补充对应命令
 - 缺少 STACK.md → \`sillyspec run scan\` 重新扫描
-- progress.json 不一致 → \`sillyspec run <阶段> --reset\` 重置对应阶段
+- sillyspec.db 状态不一致 → \`sillyspec run <阶段> --reset\` 重置对应阶段
 - 孤儿目录 → 确认后 \`rm -rf .sillyspec/changes/<目录名>\`
 - Maven 私服不可达 → 检查 VPN、settings.xml 配置、私服状态
 - Git remote 不可达 → 检查网络、SSH key 或凭证

package/src/stages/execute.js

@@ -322,6 +322,7 @@ ${taskSummary}
 1. 任务目标（简短描述）
 2. 蓝图文件路径（让子代理自行读取详情）
 3. 编码铁律：先读后写、TDD、不编造方法、只做蓝图里写的事、遵守边界处理规则、不超出 allowed_paths
+4. 如存在模块文档（.sillyspec/docs/*/modules/），按需读取涉及模块的 <module>.md 参考接口约定和数据流
 
 ### Wave 开始前
 1. 读取 design.md 的「编码铁律」章节（如果存在），严格遵守

package/src/stages/index.js

@@ -27,5 +27,5 @@ export const stageRegistry = {
   doctor: { ...doctor, ...auxiliaryFlag }
 }
 
-// 辅助命令（在没有 progress.json 时也可执行）
+// 辅助命令（在无活跃变更时也可执行）
 export const auxiliaryStages = ['scan', 'quick', 'explore', 'archive', 'status', 'doctor']

package/src/stages/plan.js

@@ -316,8 +316,13 @@ export function buildCoordinatorStep(changeDir, taskNames) {
 
 操作：
 1. 读取 ${changeDir}/design.md 和 ${changeDir}/plan.md 了解上下文
-2. 读取相关源文件了解现有代码
-3. 按以下格式编写任务蓝图并保存到 ${changeDir}/tasks/task-${num}.md：
+2. 读取相关模块文档（如存在）：
+   - \
+ls .sillyspec/docs/*/modules/_module-map.yaml 2>/dev/null\
+   确认模块划分，读取涉及模块的 \
+ls .sillyspec/docs/*/modules/*.md 2>/dev/null\
+3. 读取相关源文件了解现有代码
+4. 按以下格式编写任务蓝图并保存到 ${changeDir}/tasks/task-${num}.md：
 
 ---
 id: task-${num}

package/src/stages/quick.js

@@ -17,6 +17,11 @@ export const definition = {
 6. 如有 \`--change\`，加载设计文档：\`cat .sillyspec/changes/<change-name>/design.md 2>/dev/null\`（理解设计意图）
 7. 如有需要，查询知识库：\`cat .sillyspec/knowledge/INDEX.md 2>/dev/null\`
 
+### 模块文档加载
+8. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+9. 根据任务描述初步判断可能涉及的模块
+10. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
+
 ### 创建任务记录（必须执行）
 理解完任务后，立即创建记录文件：
 1. \`git config user.name\` 获取用户名
@@ -57,7 +62,7 @@ worktree 路径 + 变更名 + 分支名`,
       prompt: `实现任务。
 
 ### 工作目录
-你必须在 worktree 中工作（将子代理的 cwd 设为上一步记录的 worktree 路径）。
+你必须在上一步记录的 worktree 路径中工作。
 不要在主工作区修改源码文件。所有代码变更只在 worktree 中进行。
 
 ### 操作

package/src/stages/scan.js

@@ -44,11 +44,16 @@ export const definition = {
 1. \`ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .\` — 检查已有文档
 1. \`ls .sillyspec/docs/*/scan/ 2>/dev/null\` — 检查已有文档
 2. \`wc -l .sillyspec/docs/*/scan/*.md 2>/dev/null\` — 文档行数
-3. 已有 3 份 → 建议升级深度扫描；已有 7 份 → 建议刷新或跳过
-5. 显示子项目列表供选择扫描范围
+3. 显示子项目列表供选择扫描范围
+
+### ⛔ 重要：已有文档时的处理
+如果发现已有 scan 文档（如 7 份齐全），**必须停下来问用户**：
+- 列出已有文档状态（哪些存在、哪些缺失）
+- 明确提供两个选项：**重新扫描（全部覆盖）** 或 **只补扫描缺失的文档**
+- **不要自行决定跳过**，等用户选择后再继续
 
 ### 输出
-已有文档状态 + 扫描建议`,
+已有文档状态 + 等待用户选择`,
       outputHint: '工作区和文档状态',
       optional: false
     },
@@ -71,7 +76,7 @@ export const definition = {
       prompt: `检测已有扫描文档，只生成缺失的。
 
 ### 操作
-1. \`PROJECT=$(python3 -c "import sys,json,glob; files=glob.glob('.sillyspec/changes/*/progress.json'); print(json.load(open(files[0])).get('project','')) if files else print('')" 2>/dev/null || basename "$(pwd)")\`
+1. \`PROJECT=$(sqlite3 -json '.sillyspec/.runtime/sillyspec.db' "SELECT name FROM project WHERE id=1" 2>/dev/null | node -e "const r=JSON.parse(require('fs').readFileSync(0,'utf8'));console.log(r.length>0?r[0].name:'')" 2>/dev/null || basename "$(pwd)")\`
 2. 检查 7 份文档是否存在：ARCHITECTURE、STRUCTURE、CONVENTIONS、INTEGRATIONS、TESTING、CONCERNS、PROJECT
 3. 列出已有 ✅ 和缺失 ⬜
 4. 只生成缺失的文档
@@ -82,73 +87,67 @@ export const definition = {
       optional: false
     },
     {
-      name: '深度扫描 — 技术架构',
-      prompt: `扫描技术栈 + 数据库 Schema + 架构模式。参考 _env-detect.md。
-
-### 操作
-1. 用 grep/rg 搜索（\`@Entity\`、\`schema.prisma\`、\`models.py\` 等），**禁止读源码全文**
-2. Schema 只记表名+说明+字段数
-3. 写入 \`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`
-4. 包含 \`## 技术栈\` \`## 架构概览\` \`## 数据模型（摘要）\`
-
-### 输出
-ARCHITECTURE.md 路径
-
-### 注意
-- 路径用反引号，不编造`,
-      outputHint: 'ARCHITECTURE.md 路径',
-      optional: false
-    },
-    {
-      name: '深度扫描 — 代码约定',
-      prompt: `扫描框架隐形规则 + 实体继承 + 代码风格。参考 _env-detect.md。
-
-### 操作
-1. 用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**
-2. 根据检测到的语言/框架自行决定搜索什么模式
-3. 提取 3-5 个典型示例
-4. 写入 \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`
-5. 包含 \`## 框架隐形规则\` \`## 实体继承规范\` \`## 代码风格\`
-
-### 输出
-CONVENTIONS.md 路径
-
-### 注意
-- 路径用反引号，不编造`,
-      outputHint: 'CONVENTIONS.md 路径',
-      optional: false
-    },
-    {
-      name: '深度扫描 — 目录结构和集成',
-      prompt: `扫描目录结构 + 外部集成。参考 _env-detect.md。
-
-### 操作
-1. 用 find/ls/tree 和 grep，**禁止读源码全文**
-2. 搜索 API 调用、MQ 配置、缓存、第三方 SDK
-3. 写入 \`.sillyspec/docs/<project>/scan/STRUCTURE.md\`（目录树+模块说明）
-4. 写入 \`.sillyspec/docs/<project>/scan/INTEGRATIONS.md\`（按类型分组）
-
-### 输出
-STRUCTURE.md 和 INTEGRATIONS.md 路径
-
-### 注意
-- 路径用反引号，不编造`,
-      outputHint: 'STRUCTURE.md + INTEGRATIONS.md 路径',
-      optional: false
-    },
-    {
-      name: '深度扫描 — 测试和债务',
-      prompt: `扫描测试现状 + 技术债务 + 项目概览。参考 _env-detect.md。
-
-### 操作
-1. 用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**
-2. 写入 \`.sillyspec/docs/<project>/scan/TESTING.md\`（测试结构）
-3. 写入 \`.sillyspec/docs/<project>/scan/CONCERNS.md\`（按严重程度分组）
-4. 写入 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（项目信息）
-
-### 输出
-TESTING.md、CONCERNS.md、PROJECT.md 路径`,
-      outputHint: '三份文档路径',
+      name: '深度扫描 — 7 份文档（子代理并行）',
+      prompt: `使用子代理并行生成 7 份扫描文档。**你必须使用子代理执行，不要自己写文档。**
+
+### 执行方式
+1. 为每个扫描任务启动独立子代理（可并行），每个子代理负责 1-2 份文档
+2. 子代理直接用 grep/rg 搜索源码并写入文件，结果不回传到你的上下文
+3. 等待所有子代理完成后，验证文件是否生成且非空
+
+### 子代理任务分配
+
+**子代理 A — 技术架构**
+目标文件：\`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`
+搜索范围：技术栈 + 数据库 Schema + 架构模式
+- 用 grep/rg 搜索（\`@Entity\`、\`schema.prisma\`、\`models.py\` 等），**禁止读源码全文**
+- Schema 只记表名+说明+字段数
+- 包含 \`## 技术栈\` \`## 架构概览\` \`## 数据模型（摘要）\`
+- 参考 _env-detect.md（如存在）
+
+**子代理 B — 代码约定**
+目标文件：\`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`
+搜索范围：框架隐形规则 + 实体继承 + 代码风格
+- 用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**
+- 根据检测到的语言/框架自行决定搜索什么模式
+- 提取 3-5 个典型示例
+- 包含 \`## 框架隐形规则\` \`## 实体继承规范\` \`## 代码风格\`
+- 参考 _env-detect.md（如存在）
+
+**子代理 C — 目录结构 + 外部集成**
+目标文件：\`.sillyspec/docs/<project>/scan/STRUCTURE.md\` + \`.sillyspec/docs/<project>/scan/INTEGRATIONS.md\`
+搜索范围：目录树 + 模块说明 + 外部集成
+- 用 find/ls/tree 和 grep，**禁止读源码全文**
+- 搜索 API 调用、MQ 配置、缓存、第三方 SDK
+- STRUCTURE.md：目录树+模块说明
+- INTEGRATIONS.md：外部集成（按类型分组）
+- 参考 _env-detect.md（如存在）
+
+**子代理 D — 测试 + 债务 + 项目概览**
+目标文件：\`.sillyspec/docs/<project>/scan/TESTING.md\` + \`.sillyspec/docs/<project>/scan/CONCERNS.md\` + \`.sillyspec/docs/<project>/scan/PROJECT.md\`
+搜索范围：测试文件 + TODO/FIXME + 过时依赖 + 项目信息
+- 用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**
+- TESTING.md：测试结构
+- CONCERNS.md：技术债务（按严重程度分组）
+- PROJECT.md：项目概览
+- 参考 _env-detect.md（如存在）
+
+### 每个子代理的共同要求
+- **上下文注入**：主 agent 在启动子代理前，必须将以下信息拼入子代理 prompt：
+  - 项目名（<project>）
+  - 断点续扫步骤列出的缺失文档列表（哪些要生成、哪些跳过）
+  - 环境探测结果摘要（构建工具、语言框架、关键依赖）
+  - _env-detect.md 内容（如存在，直接贴入）
+- 路径用反引号，不编造
+- 目标文件不存在则创建，已存在则覆盖
+- 只生成缺失文档（根据断点续扫结果）
+
+### 完成后
+验证 7 份文档全部生成且非空，列出结果：
+- ✅ ARCHITECTURE.md / ❌ 缺失
+- ✅ CONVENTIONS.md / ❌ 缺失
+- ...`,
+      outputHint: '7 份文档生成状态',
       optional: false
     },
     {
@@ -235,15 +234,72 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
       outputHint: '_module-map.yaml 生成状态',
       optional: true
     },
+    {
+      name: '生成模块核心文档',
+      prompt: `根据 _module-map.yaml 中的模块划分，为每个模块生成核心文档（用于后续归档和开发上下文）。
+
+### 操作
+1. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`，获取模块列表和路径
+2. 检查 \`.sillyspec/docs/<project>/modules/\` 下已有的模块文档（<module>.md）
+3. 列出每个模块的状态：已有文档 / 缺失
+4. **必须停下来问用户**：
+   - 展示模块列表及现有文档状态
+   - 明确提供选项：**为缺失模块生成初始文档** / **全部重新生成（覆盖已有）** / **跳过**
+5. 用户选择后执行
+
+### 生成方法（子代理并行，只针对用户选中的模块）
+**你必须为每个模块启动独立子代理执行，不要自己写文档。**
+
+每个子代理的 prompt（**主 agent 启动前必须拼入**：
+- 模块名和路径（从 _module-map.yaml 读取）
+- 环境探测结果摘要（构建工具、语言框架）
+- scan 文档关键信息摘要（ARCHITECTURE.md 的技术栈、CONVENTIONS.md 的代码风格要点，如已生成）
+\`\`\`
+模块名：<module-name>
+模块路径：<glob patterns>
+目标文件：.sillyspec/docs/<project>/modules/<module>.md
+
+操作：
+1. 用 grep/rg 搜索模块路径范围内的源码（禁止读源码全文）
+2. 提取：模块职责、对外接口（导出函数/API）、关键依赖、设计要点
+3. 按以下模板写入目标文件：
+
+# <module-name>
+> 最后更新：YYYY-MM-DD
+> 最近变更：scan（初始生成）
+> 模块路径：<glob patterns>
+
+## 职责
+## 当前设计
+## 对外接口（表格）
+## 关键数据流
+## 设计决策（表格）
+## 依赖关系
+## 注意事项
+## 变更索引（表格，初始为空）
+
+规则：
+- 不要编造接口或依赖，只写 grep/rg 能搜到的
+- 模板与 archive 阶段格式一致
+\`\`\`
+
+等待所有子代理完成，验证文件是否生成且非空。
+
+### 输出
+已生成的模块文档路径列表`,
+      outputHint: '模块文档生成状态',
+      optional: true
+    },
     {
       name: '自检和提交',
       prompt: `验证扫描完整性，清理并提交。
 
 ### 操作
-1. 检查 7 份文档是否全部生成
-2. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
-3. 清理：\`rm -f .sillyspec/docs/<project>/scan/_env-detect.md\`
-4. \`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）
+1. 检查 7 份 scan 文档是否全部生成
+2. 检查模块文档状态（如有）
+3. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
+4. 清理：\`rm -f .sillyspec/docs/<project>/scan/_env-detect.md\`
+5. \`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）
 
 ### 输出
 扫描完整性报告