sillyspec 3.14.0 → 3.15.0

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 21:35:00
+updated_at: 2026-06-03 16:00:00
 ---
 
 # SillySpec 文件生命周期描述
@@ -20,9 +20,11 @@ updated_at: 2026-05-31 21:35:00
 │   ├── history/                 ← 已完成阶段的历史快照
 │   ├── logs/                    ← 日志
 │   ├── templates/               ← 模板
+│   ├── workflow-runs/           ← workflow check 结果归档（JSON）
+│   │   └── <timestamp>-<workflow>-<project>-<status>.json
 │   └── worktrees/              ← git worktree 隔离环境
 │       └── <change-name>/
-│           └── meta.json        ← worktree 元数据
+│           └── meta.json        ← worktree 元数据（含 baselineCommit/baselineHash）
 ├── changes/                     ← 变更工作区（git tracked）
 │   ├── <change-name>/          ← 活跃变更目录
 │   │   ├── proposal.md         ← 动机与变更范围
@@ -59,6 +61,9 @@ updated_at: 2026-05-31 21:35:00
 ├── knowledge/                   ← 跨项目共享知识库
 │   ├── INDEX.md               ← 知识索引（关键词匹配）
 │   └── uncategorized.md       ← 待分类知识
+├── workflows/                   ← workflow 定义（init 自动生成，可自定义）
+│   ├── scan-docs.yaml          ← scan 阶段产物检查 workflow
+│   └── archive-impact.yaml     ← archive 阶段影响分析 workflow
 ├── shared/                     ← 共享目录
 ├── workspace/                  ← 工作区
 ├── ROADMAP.md                  ← 路线图（可选）
@@ -529,6 +534,8 @@ PASS / PASS WITH NOTES / FAIL
 
 **断点续扫：** "检查已有扫描文档和子项目列表"步骤检查已有文档，**必须停下来问用户**选择「全部重新扫描」或「只补缺失文档」，不能自行决定跳过。
 
+**Workflow 检查（post_check）：** scan 阶段完成后（verify 步骤），`run.js` 自动加载 `workflows/scan-docs.yaml`，对每个项目的 7 份文档执行结构化产物校验。检查结果为结构化 JSON 对象，包含 `roles[].outputs[].checks[]` 和 `failures[]`。校验规则定义在 `scan-docs.yaml` 的各 role output checks 中（file_exists / min_lines / contains_sections / no_placeholder 等）。检查失败时自动生成 `retry_prompts`，精确到角色级别。
+
 **生命周期：** scan 阶段生成 → 被后续所有阶段（brainstorm/propose/plan/execute/verify）作为上下文读取
 
 ---
@@ -755,6 +762,51 @@ test_strategy: module
 
 ---
 
+### `workflow-runs/` — Workflow Check 结果归档
+
+**创建时机：**
+- `run.js` 在 scan/verify 步骤和 archive extract-module-impact 步骤执行 `runPostCheck()` 后自动归档
+- CLI `sillyspec workflow check ... --save` 手动触发
+
+**存储位置：** `.sillyspec/.runtime/workflow-runs/`
+
+**命名格式：** `<YYYYMMDDHHmmss>-<workflow>-<project>-<status>.json`
+
+**示例：** `20260603035731-scan-docs-dashboard-pass.json`
+
+**内容结构（结构化结果对象）：**
+```json
+{
+  "run_id": "20260603035731-scan-docs-dashboard",
+  "created_at": "2026-06-03T03:57:31.000Z",
+  "source": "run.js",
+  "stage": "verify",
+  "workflow": "scan-docs",
+  "project": "dashboard",
+  "status": "pass",
+  "spec_version": 1,
+  "roles": [
+    { "id": "arch", "name": "技术架构", "status": "pass", "outputs": [...] }
+  ],
+  "workflow_checks": [...],
+  "failures": [],
+  "retry_prompts": []
+}
+```
+
+**写入方：**
+- `run.js` — scan/verify 和 archive post_check 后自动调用 `saveWorkflowRun()`
+- `index.js` — CLI `--save` 时调用 `saveWorkflowRun()`
+
+**读取方：** 人工查阅 / 后续查询命令（待实现）
+
+**注意：**
+- 保存失败只输出 warning，不影响 workflow check 的 exit code
+- CLI `--json --save` 时 stdout 仍为纯净 JSON，保存提示不混入
+- 文件路径在 `.gitignore` 中（`.sillyspec/.runtime/`）
+
+---
+
 ## 8. 文件销毁与归档
 
 ### 变更归档流程
@@ -978,17 +1030,19 @@ graph LR
 
 **大体结构：**
 ```markdown
-## 2026-05-28 14:30:00 — 修复用户登录超时问题
+## ql-20260603-001-a3f2 | 2026-06-03 14:30:00 — 修复用户登录超时问题
 状态：进行中
 文件：src/auth/login.js, src/config/timeout.yaml
 
-## 2026-05-28 15:00:00 — 修复用户登录超时问题
+## ql-20260603-002-7b1c | 2026-06-03 15:00:00 — 修复用户登录超时问题
 状态：已完成
 文件：src/auth/login.js
 结果：调整超时配置为 30s，新增重试逻辑
 ```
 
-**生命周期：** quick 步骤 1 创建（"进行中"）→ 步骤 5 更新为"已完成"并补充实际改动。超过 500 行轮转重命名为 `QUICKLOG-<USER>-YYYY-MM-DD.md`。
+**ID 规则：** 每条记录以 `ql-YYYYMMDD-NNN-XXXX` 开头作为唯一 ID。`XXXX` 为 4 位随机十六进制，防止多文件或并发冲突。追加前扫描文件中已有 `ql-<当天日期>-` 前缀的最大序号 +1，每天从 001 重新开始。此 ID 可被 design.md / plan.md / archive / 模块变更索引引用。
+
+**生命周期：** quick 步骤 1 创建（"进行中"）→ 步骤 5 按 ql-ID 找到条目更新为"已完成"并补充实际改动。超过 500 行轮转重命名为 `QUICKLOG-<USER>-YYYY-MM-DD.md`（日期取最后一条记录），新文件需扫描同目录所有 QUICKLOG 文件中当天最大序号 +1 以继承 ql-ID。
 
 ---
 
@@ -1039,6 +1093,7 @@ graph LR
 | `modules/_module-map.yaml` | scan 可选步骤 | scan | archive/plan/execute |
 | `modules/<module>.md` | scan 可选步骤（全量生成）+ archive sync-module-docs | scan/archive | propose/plan/execute/verify/quick |
 | `verify-result.md` | verify 阶段输出 | verify | 验证报告存档 |
+| `workflows/*.yaml` | init 自动生成（scan-docs.yaml, archive-impact.yaml） | init | run.js post_check + CLI workflow check |
 
 
 ```
@@ -1048,6 +1103,7 @@ sillyspec init
     ├─→ .sillyspec/.runtime/user-inputs.md
     ├─→ .sillyspec/projects/<name>.yaml
     ├─→ .sillyspec/docs/<name>/scan/  (骨架)
+    ├─→ .sillyspec/workflows/  (scan-docs.yaml, archive-impact.yaml 模板)
     ├─→ .sillyspec/knowledge/
     └─→ .gitignore (追加 .sillyspec/.runtime/)
 
@@ -1064,6 +1120,9 @@ scan 阶段（12 步，完成后重置）
     ├─→ docs/<name>/modules/<module>.md (可选，需用户确认)
     └─→ .sillyspec/local.yaml
 
+    [scan 完成后 run.js 自动执行 workflow check]
+    └─→ .sillyspec/.runtime/workflow-runs/<ts>-scan-docs-<project>-<status>.json
+
 brainstorm 阶段
     │
     ├─→ sillyspec.db: changes/stages 记录自动创建
@@ -1112,4 +1171,7 @@ archive 阶段
     ├─→ changes/<name>/module-impact.md
     ├─→ docs/<name>/modules/<module>.md (通过 module-impact.md 同步)
     └─→ changes/<name>/ → changes/archive/YYYY-MM-DD-<name>/
+
+    [archive extract-module-impact 后 run.js 自动执行 workflow check]
+    └─→ .sillyspec/.runtime/workflow-runs/<ts>-archive-impact-<project>-<status>.json
 ```

package/package.json

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

package/src/init.js

@@ -125,6 +125,22 @@ async function doInstall(projectDir, tools, subprojects = []) {
   const gitkeepPath = join(scanDir, '.gitkeep');
   if (!existsSync(gitkeepPath)) writeFileSync(gitkeepPath, '');
 
+  // 复制 workflow 模板到 .sillyspec/workflows/
+  const workflowsDir = join(projectDir, '.sillyspec', 'workflows');
+  const templatesDir = join(__dirname, '..', 'templates', 'workflows');
+  if (existsSync(templatesDir)) {
+    mkdirSync(workflowsDir, { recursive: true });
+    for (const file of readdirSync(templatesDir)) {
+      if (file.endsWith('.yaml')) {
+        const srcPath = join(templatesDir, file);
+        const dstPath = join(workflowsDir, file);
+        if (!existsSync(dstPath)) {
+          writeFileSync(dstPath, readFileSync(srcPath));
+        }
+      }
+    }
+  }
+
   // 创建 shared/workspace 目录
   mkdirSync(join(projectDir, '.sillyspec', 'shared'), { recursive: true });
   mkdirSync(join(projectDir, '.sillyspec', 'workspace'), { recursive: true });

package/src/stages/execute.js

@@ -300,6 +300,9 @@ function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
 \`${worktreePath}\`
 
 不要在主工作区修改源码文件。所有代码变更只在 worktree 中进行。
+
+### 注意
+蓝图文件（tasks.md / design.md / proposal.md / requirements.md）在主工作区 .sillyspec/changes/<change>/ 下，它们可能不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree 路径下。
 子代理的 cwd 参数设为 \`${worktreePath}\`。
 `
     : ''

package/src/stages/quick.js

@@ -27,10 +27,15 @@ export const definition = {
 1. 使用预注入的 git 用户名：\`<git-user>\`
 2. 无 \`--change\`：创建 .sillyspec/quicklog/QUICKLOG-\`<git-user>\`.md\`（已存在则追加），写入：
    \`\`\`
-   ## <now-datetime> — <一句话任务描述>
+   ## ql-<YYYYMMDD>-<NNN>-<short4> | <now-datetime> | <一句话任务描述>
    状态：进行中
    文件：<预估要改的文件>
    \`\`\`
+   - ID 格式：\`ql-YYYYMMDD-NNN-XXXX\`（如 ql-20260603-001-a3f2）
+   - \`XXXX\` 是 4 位随机十六进制（防多文件/并发冲突）
+   - 追加前扫描文件中已有的 \`ql-<当天日期>-\` 前缀的最大序号，+1 作为新序号
+   - 每天从 001 开始，跨日重新计数
+   - 此 ID 可被 design.md / plan.md / archive / module 变更索引引用
 3. 有 \`--change\`：在 \`.sillyspec/changes/<change-name>/tasks.md\` 追加未勾选的 task
 
 这样 Gate 检测到 .sillyspec/\` 下有变更，就不会拦截后续的代码修改。
@@ -67,9 +72,9 @@ export const definition = {
 ### 操作
 1. \`git add -A\` — 暂存改动文件（不要 commit，由用户通过统一提交工具处理）
 2. 更新 Step 1 创建的记录：
-   - 无 \`--change\`：更新 QUICKLOG 条目，将「状态：进行中」改为「状态：已完成」，补充实际改动文件和结果摘要
+   - 无 \`--change\`：找到对应 ql-ID 的条目，将「状态：进行中」改为「状态：已完成」，补充实际改动文件和结果摘要
    - 有 \`--change\`：勾选 tasks.md 中对应的 task checkbox
-3. QUICKLOG 轮转：超过 500 行则重命名为 \`QUICKLOG-<USER>-YYYY-MM-DD.md\`
+3. QUICKLOG 轮转：超过 500 行则重命名为 \`QUICKLOG-<USER>-YYYY-MM-DD.md\`（日期取最后一条记录的日期）。新文件从空开始，ql-ID 需扫描同目录所有 QUICKLOG 文件中当天最大序号 +1
 4. 如果发现项目特有的坑，追加到 \`.sillyspec/knowledge/uncategorized.md\`
 5. 任务比预期复杂 → 建议用完整流程
 
@@ -78,7 +83,8 @@ export const definition = {
 7. 对比本次修改的文件（\`git diff --name-only\`）与模块映射
 8. 如果命中模块 → 直接同步模块文档：
    - 读取对应的 \`.sillyspec/docs/<project>/modules/<module>.md\`（如不存在则新建）
-   - 根据本次改动内容更新模块文档（正文描述当前状态，底部追加变更索引）
+   - 根据本次改动内容更新模块文档（正文描述当前状态，底部变更索引追加本次 ql-ID）
+   - 变更索引格式：\`- ql-YYYYMMDD-NNN-XXXX | <一句话描述>\`
    - 写入模块文档
    - 将更新的模块文件加入 \`git add\`
 9. 未命中任何模块 → 跳过，不做额外操作

package/src/worktree-apply.js

@@ -16,6 +16,7 @@ import { execSync } from 'child_process';
 import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
 import { join, resolve } from 'path';
 import { tmpdir } from 'os';
+import { createHash } from 'crypto';
 import { WorktreeManager } from './worktree.js';
 import { parseFileChangeList } from './change-list.js';
 
@@ -77,7 +78,9 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
     return result;
   }
 
-  const { worktreePath, baseHash } = meta;
+  const { worktreePath, baseHash, baselineCommit } = meta;
+  // diff 起始点：有 baseline checkpoint 用它（只合子代理改动），否则 fallback 到 baseHash
+  const diffBase = baselineCommit || baseHash;
 
   if (!existsSync(worktreePath)) {
     result.errors.push(`worktree 目录不存在: ${worktreePath}`);
@@ -90,10 +93,10 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
   let changedFiles;
   try {
     // tracked 文件的变更（modified/deleted）
-    const trackedRaw = git(worktreePath, `diff --name-only ${baseHash}`);
+    const trackedRaw = git(worktreePath, `diff --name-only ${diffBase}`);
     const trackedFiles = trackedRaw ? trackedRaw.split('\n').filter(Boolean) : [];
 
-    // untracked 新文件（baseHash 中不存在的文件）
+    // untracked 新文件（diffBase 中不存在的文件）
     const untrackedRaw = gitQuiet(worktreePath, `ls-files --others --exclude-standard`);
     const untrackedFiles = untrackedRaw
       ? untrackedRaw.split('\n').filter(Boolean).filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json')
@@ -136,6 +139,24 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
     }
   }
 
+  // --- 4.5 校验：主工作区 baseline 是否变化（防 execute 期间主工作区被修改）---
+  if (meta.baselineHash) {
+    const staged = gitQuiet(projectRoot, 'diff --cached') || '';
+    const unstaged = gitQuiet(projectRoot, 'diff') || '';
+    const untracked = gitQuiet(projectRoot, 'ls-files --others --exclude-standard') || '';
+    const raw = `staged:${staged}\nunstaged:${unstaged}\nuntracked:${untracked}`;
+    const currentHash = createHash('sha256').update(raw).digest('hex').slice(0, 16);
+    if (currentHash !== meta.baselineHash) {
+      result.errors.push(
+        `主工作区 baseline 已变化（execute 前后不一致），不能直接 apply task.patch。\n` +
+        `建议：重新创建 worktree 或手动检查冲突。\n` +
+        `execute 前 baseline: ${meta.baselineHash}\n` +
+        `当前 baseline: ${currentHash}`
+      );
+      return result;
+    }
+  }
+
   // --- 5. 校验：主工作区文件 base hash 一致 ---
   // 5a. 检查主工作区是否有未 commit 的脏文件（会影响 apply）
   const mainDirtyRaw = gitQuiet(projectRoot, 'diff --name-only HEAD');
@@ -196,7 +217,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
     // 分 tracked 变更和 untracked 新文件生成 patch
     const trackedFiles = patchFiles.filter(f => {
       // untracked 文件在 baseHash 的 tree 中不存在
-      return gitQuiet(worktreePath, `cat-file -e ${baseHash}:${f}`) !== null;
+      return gitQuiet(worktreePath, `cat-file -e ${diffBase}:${f}`) !== null;
     });
     const untrackedPatchFiles = patchFiles.filter(f => !trackedFiles.includes(f));
 
@@ -204,7 +225,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
     if (trackedFiles.length > 0) {
       const trackedArgs = trackedFiles.map(f => `-- ${f}`).join(' ');
       patchContent += execSync(
-        `git diff --binary ${baseHash} ${trackedArgs}`,
+        `git diff --binary ${diffBase} ${trackedArgs}`,
         { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
       );
     }

package/src/worktree.js

@@ -10,7 +10,8 @@
 
 import { execSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync } from 'fs';
-import { join, resolve } from 'path';
+import { join, resolve, dirname } from 'path';
+import { createHash } from 'crypto';
 
 const WORKTREES_REL = '.sillyspec/.runtime/worktrees';
 const BRANCH_PREFIX = 'sillyspec/';
@@ -32,6 +33,16 @@ function parseJSON(raw) {
   try { return JSON.parse(raw); } catch { return null; }
 }
 
+function computeBaselineHash(cwd) {
+  const staged = gitQuiet(cwd, 'diff --cached') || '';
+  const unstaged = gitQuiet(cwd, 'diff') || '';
+  const untracked = gitQuiet(cwd, 'ls-files --others --exclude-standard') || '';
+  const raw = `staged:${staged}
+unstaged:${unstaged}
+untracked:${untracked}`;
+  return createHash('sha256').update(raw).digest('hex').slice(0, 16);
+}
+
 function validateChangeName(changeName) {
   if (!changeName || typeof changeName !== 'string' || changeName.trim() === '') {
     throw new Error('changeName 不能为空');
@@ -175,16 +186,29 @@ export class WorktreeManager {
  // fetch/merge 失败不影响 worktree 创建，只记录警告
     }
 
+    // 5.6 Dirty baseline overlay：将主工作区未提交变更同步到 worktree
+    const baselineResult = this._overlayBaseline(this.cwd, worktreePath);
+    const baselineFiles = baselineResult.files;
+    const baselineHash = baselineResult.baselineHash;
+
+    // 5.7 创建 baseline checkpoint（有 dirty baseline 时才创建）
+    let baselineCommit = null;
+    if (baselineFiles.length > 0) {
+      baselineCommit = this._createBaselineCheckpoint(worktreePath, name);
+    }
+
     // 6. 写入 meta.json
     const meta = {
       changeName: name,
       branch,
       baseBranch,
       baseHash,
-      // actualBaseHash 记录 fetch+merge 后的实际 HEAD（可能与 baseHash 不同）
       actualBaseHash: gitQuiet(worktreePath, 'rev-parse HEAD') || baseHash,
       createdAt: new Date().toISOString(),
       worktreePath,
+      baselineFiles,
+      baselineCommit,
+      baselineHash,  // 有 dirty baseline 时指向 checkpoint commit
     };
 
     const metaPath = join(worktreePath, META_FILE);
@@ -260,4 +284,118 @@ export class WorktreeManager {
       rmSync(worktreePath, { recursive: true, force: true });
     }
   }
+
+  /**
+   * 将主工作区未提交变更同步到 worktree（dirty baseline overlay）
+   * 覆盖 staged + unstaged 的文件变更，以及 untracked 文件。
+   * 使用 git diff + git apply 确保正确处理删除/rename/binary。
+   * @param {string} mainCwd - 主工作区路径
+   * @param {string} worktreePath - worktree 路径
+   * @returns {Array<string>} overlay 的文件列表
+   */
+  _overlayBaseline(mainCwd, worktreePath) {
+    const files = [];
+    const errors = [];
+
+    try {
+      // staged 变更
+      const staged = gitQuiet(mainCwd, 'diff --cached --name-only') || '';
+      if (staged) {
+        try {
+          const patchContent = execSync(`git diff --cached --binary`, { cwd: mainCwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] });
+          if (patchContent) {
+            const patchFile = join(worktreePath, '.sillyspec-baseline-staged.patch');
+            writeFileSync(patchFile, patchContent);
+            git(worktreePath, `apply --binary ${patchFile}`);
+            rmSync(patchFile, { force: true });
+          }
+        } catch (e) {
+          errors.push(`staged: ${e.message}`);
+        }
+        files.push(...staged.split('\n').filter(Boolean));
+      }
+
+      // unstaged 变更
+      const unstaged = gitQuiet(mainCwd, 'diff --name-only') || '';
+      if (unstaged) {
+        try {
+          const patchContent = execSync(`git diff --binary`, { cwd: mainCwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] });
+          if (patchContent) {
+            const patchFile = join(worktreePath, '.sillyspec-baseline-unstaged.patch');
+            writeFileSync(patchFile, patchContent);
+            git(worktreePath, `apply --binary ${patchFile}`);
+            rmSync(patchFile, { force: true });
+          }
+        } catch (e) {
+          errors.push(`unstaged: ${e.message}`);
+        }
+        files.push(...unstaged.split('\n').filter(Boolean));
+      }
+
+      // untracked 文件（排除 .sillyspec/.runtime 等）
+      const untracked = gitQuiet(mainCwd, 'ls-files --others --exclude-standard') || '';
+      if (untracked) {
+        for (const f of untracked.split('\n').filter(Boolean)) {
+          const src = join(mainCwd, f);
+          const dst = join(worktreePath, f);
+          if (existsSync(src)) {
+            mkdirSync(dirname(dst), { recursive: true });
+            try { writeFileSync(dst, readFileSync(src)); files.push(f); } catch {}
+          }
+        }
+      }
+
+      if (files.length > 0) {
+        console.log(`📁 baseline overlay: ${files.length} 个未提交文件已同步到 worktree`);
+      }
+    } catch (e) {
+      errors.push(`unexpected: ${e.message}`);
+    }
+
+    // 有 pending 文件但 overlay 部分失败 → fail-fast
+    if (errors.length > 0) {
+      throw new Error(`baseline overlay 失败 (${errors.length} 个错误): ${errors.join('; ')}`);
+    }
+
+    const uniqueFiles = [...new Set(files)];
+
+    // 计算 baseline hash（用于 merge 前校验主工作区是否变化）
+    const baselineHash = uniqueFiles.length > 0 ? computeBaselineHash(mainCwd) : null;
+
+    return { files: uniqueFiles, baselineHash };
+  }
+
+  /**
+   * 在 worktree 内创建 baseline checkpoint commit
+   * 用于区分 "前置 dirty baseline" 和 "子代理新增改动"
+   * @param {string} worktreePath
+   * @param {string} changeName
+   * @returns {string} commit hash
+   */
+  _createBaselineCheckpoint(worktreePath, changeName) {
+    // 使用临时 git identity，避免用户未配置 user.name/user.email 导致失败
+    const env = {
+      GIT_AUTHOR_NAME: 'sillyspec',
+      GIT_AUTHOR_EMAIL: 'sillyspec@baseline',
+      GIT_COMMITTER_NAME: 'sillyspec',
+      GIT_COMMITTER_EMAIL: 'sillyspec@baseline',
+    };
+    try {
+      execSync('git add -A', { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe','pipe','pipe'], env });
+      // 检查是否有实际变更（可能 overlay 后和 HEAD 完全一致）
+      const status = gitQuiet(worktreePath, 'status --porcelain');
+      if (!status) {
+        return gitQuiet(worktreePath, 'rev-parse HEAD');
+      }
+      execSync(
+        `git commit -m "sillyspec: baseline checkpoint for ${changeName}"`,
+        { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe','pipe','pipe'], env }
+      );
+      const hash = git(worktreePath, 'rev-parse HEAD');
+      console.log(`📌 baseline checkpoint: ${hash}`);
+      return hash;
+    } catch (e) {
+      throw new Error(`baseline checkpoint 创建失败: ${e.message}`);
+    }
+  }
 }

package/templates/workflows/archive-impact.yaml

@@ -0,0 +1,79 @@
+name: archive-impact
+description: 分析变更影响的模块并同步模块文档
+spec_version: 1
+
+roles:
+  - id: impact-analyzer
+    name: "影响分析"
+    task: "分析 git diff，提取变更影响模块"
+    inputs:
+      paths: [".sillyspec/changes/", ".sillyspec/docs/*/modules/"]
+      hints:
+        grep_patterns: ["_module-map", "module-impact", "git diff"]
+    outputs:
+      - path: ".sillyspec/changes/<change-name>/module-impact.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 20
+          - type: contains_sections
+            sections: ["模块影响矩阵", "未匹配文件"]
+    constraints:
+      - "以 git diff 为准（真实 > 声明）"
+      - "影响类型：逻辑变更/数据结构变更/接口变更/调用关系变更/配置变更/新增"
+      - "需要 review 标记不确定的影响"
+
+  - id: doc-syncer
+    name: "文档同步"
+    task: "根据 module-impact.md 同步更新模块索引和卡片"
+    depends_on:
+      - impact-analyzer
+    inputs:
+      from_role: impact-analyzer
+      output: module-impact
+      output_description: "变更影响分析结果，包含模块影响矩阵"
+      paths: [".sillyspec/docs/*/modules/"]
+      hints:
+        grep_patterns: ["_module-map", "module-impact"]
+    outputs:
+      - path: ".sillyspec/docs/sillyspec/modules/_module-map.yaml"
+        required: false
+        checks:
+          - type: file_exists
+      - path: ".sillyspec/docs/sillyspec/modules/<module-id>.md"
+        required: false
+        # checks 跳过：路径含动态 <module-id> 占位符，不适合静态检查
+    constraints:
+      - "结构化事实改 _module-map.yaml，语义解释改模块卡片"
+      - "人工备注区域永远保护，不覆盖"
+      - "更新前展示 diff 摘要，请用户确认"
+
+orchestration:
+  mode: sequential
+  timeout_per_role: 180
+
+checks:
+  role_level:
+    - type: file_exists
+    - type: min_lines
+      min: 10
+  workflow_level:
+    - type: file_exists
+      path: ".sillyspec/changes/<change-name>/module-impact.md"
+
+retry:
+  max_attempts: 1
+  include_failure_context: true
+  retry_scope: failed_role_only
+
+on_check_failure: prompt_retry
+
+permissions:
+  write_mode: patch_only
+  write_scope:
+    - ".sillyspec/docs/"
+    - ".sillyspec/changes/<change-name>/"
+  allow_shell: true
+  allow_network: false
+  allow_git: true

package/templates/workflows/scan-docs.yaml

@@ -0,0 +1,132 @@
+name: scan-docs
+description: 并行生成项目的扫描文档（7份）
+spec_version: 1
+
+roles:
+  - id: arch
+    name: "技术架构"
+    task: "生成 ARCHITECTURE.md"
+    inputs:
+      paths:
+        - "src/*.js"
+        - "package.json"
+      hints:
+        grep_patterns: ["class ", "export ", "import ", "schema", "CREATE TABLE"]
+    outputs:
+      - path: ".sillyspec/docs/<project>/scan/ARCHITECTURE.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 20
+          - type: contains_sections
+            sections: ["技术栈", "架构概览"]
+    constraints:
+      - "禁止读源码全文，只用 grep/rg 搜索"
+      - "Schema 只记表名+说明+字段数"
+
+  - id: conventions
+    name: "代码约定"
+    task: "生成 CONVENTIONS.md"
+    inputs:
+      paths: ["src/"]
+      hints:
+        grep_patterns: ["function ", "const ", "async ", "try ", "catch "]
+    outputs:
+      - path: ".sillyspec/docs/<project>/scan/CONVENTIONS.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+          - type: contains_sections
+            sections: ["框架隐形规则", "代码风格"]
+    constraints:
+      - "禁止读源码全文"
+      - "提取 3-5 个典型模式"
+
+  - id: structure
+    name: "目录结构+外部集成"
+    task: "生成 STRUCTURE.md 和 INTEGRATIONS.md"
+    inputs:
+      paths: ["./"]
+      hints:
+        grep_patterns: ["fetch", "http", "WebSocket", "ws", "chokidar"]
+    outputs:
+      - path: ".sillyspec/docs/<project>/scan/STRUCTURE.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+      - path: ".sillyspec/docs/<project>/scan/INTEGRATIONS.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+    constraints:
+      - "STRUCTURE: 目录树+模块说明"
+      - "INTEGRATIONS: 按类型分组外部依赖"
+
+  - id: quality
+    name: "测试+债务+概览"
+    task: "生成 TESTING.md、CONCERNS.md、PROJECT.md"
+    inputs:
+      paths: ["src/", "packages/"]
+      hints:
+        grep_patterns: ["TODO", "FIXME", "deprecated", "test", "describe"]
+    outputs:
+      - path: ".sillyspec/docs/<project>/scan/TESTING.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 10
+          - type: no_placeholder
+      - path: ".sillyspec/docs/<project>/scan/CONCERNS.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 10
+          - type: contains_sections
+            sections: ["代码质量", "依赖风险"]
+      - path: ".sillyspec/docs/<project>/scan/PROJECT.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+          - type: contains_sections
+            sections: ["项目简介", "技术栈"]
+    constraints:
+      - "CONCERNS 按严重程度分组（🔴/🟡/🟢）"
+      - "不编造不存在的测试"
+
+orchestration:
+  mode: parallel
+  max_concurrent: 4
+  timeout_per_role: 120
+
+checks:
+  workflow_level:
+    - type: file_count
+      path: "scan/"
+      min: 7
+    - type: no_empty_files
+
+retry:
+  max_attempts: 1
+  include_failure_context: true
+  retry_scope: failed_role_only
+
+on_check_failure: prompt_retry
+
+permissions:
+  write_mode: direct
+  write_scope:
+    - ".sillyspec/docs/<project>/scan/"
+  allow_shell: true
+  allow_network: false
+  allow_git: false