sillyspec 3.14.1 → 3.15.2

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.1",
+  "version": "3.15.2",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/run.js

@@ -10,6 +10,7 @@ import { ProgressManager } from './progress.js'
 import { stageRegistry, auxiliaryStages } from './stages/index.js'
 import { buildExecuteSteps } from './stages/execute.js'
 import { buildPlanSteps } from './stages/plan.js'
+import { formatExecuteSummary } from './worktree-apply.js'
 
 /**
  * 同步触发辅助函数：_write 后 best-effort 同步到平台
@@ -745,7 +746,21 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
 
     if (stageName === 'execute') {
-      console.log('\n👉 下一步：sillyspec run verify（验证通过后才能归档）')
+      // execute run summary：展示真实可得的结构化信息
+      try {
+        const lastOutput = steps[steps.length - 1]?.output || ''
+        const summary = formatExecuteSummary({
+          changeName,
+          stepsCompleted: total,
+          stepsTotal: total,
+          agentSummary: lastOutput,
+          cwd,
+        })
+        console.log(`\n${summary}`)
+      } catch (e) {
+        // summary 失败不影响主流程
+        console.log('\n👉 下一步：sillyspec run verify（验证通过后才能归档）')
+      }
     } else if (stageName === 'verify') {
       console.log('\n👉 下一步：sillyspec run archive（验证通过，可以归档了）')
     } else if (stageName === 'archive') {

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}`);
@@ -89,17 +92,25 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
   // 同时检测 untracked 新文件（git diff 不包含 untracked）
   let changedFiles;
   try {
-    // tracked 文件的变更（modified/deleted）
-    const trackedRaw = git(worktreePath, `diff --name-only ${baseHash}`);
-    const trackedFiles = trackedRaw ? trackedRaw.split('\n').filter(Boolean) : [];
+    // 用 --name-status 捕获 rename/delete（--name-only 会丢失 rename 源文件）
+    const statusRaw = git(worktreePath, `diff --name-status ${diffBase}`);
+    const statusFiles = new Set();
+    if (statusRaw) {
+      for (const line of statusRaw.split('\n').filter(Boolean)) {
+        const parts = line.split('\t');
+        // R100 old.txt new.txt → 提取两个文件
+        if (parts.length >= 2) statusFiles.add(parts[parts.length - 1]);
+        if (parts.length >= 3) statusFiles.add(parts[parts.length - 2]);
+      }
+    }
 
-    // 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')
       : [];
 
-    changedFiles = [...new Set([...trackedFiles, ...untrackedFiles])];
+    changedFiles = [...new Set([...statusFiles, ...untrackedFiles])];
   } catch (e) {
     result.errors.push(`获取变更文件列表失败: ${e.message}`);
     return result;
@@ -136,6 +147,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');
@@ -195,8 +224,11 @@ 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;
+      // 文件在 diffBase 的 tree 中存在 → tracked（包括 rename 目标可能的情况）
+      if (gitQuiet(worktreePath, `cat-file -e ${diffBase}:${f}`) !== null) return true;
+      // 文件在工作区 index 中已存在（比如被 git mv 处理过）→ 也视为 tracked
+      if (gitQuiet(worktreePath, `ls-files --error-unmatch ${f}`) !== null) return true;
+      return false;
     });
     const untrackedPatchFiles = patchFiles.filter(f => !trackedFiles.includes(f));
 
@@ -204,7 +236,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'] }
       );
     }
@@ -269,3 +301,91 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
 
   return result;
 }
+
+/**
+ * 格式化 execute run summary（人类可读）
+ *
+ * 只展示 CLI 真实掌握的信息，不声称知道 per-task 状态。
+ * @param {object} opts
+ * @param {string} opts.changeName - 变更名
+ * @param {number} opts.stepsCompleted - 已完成步骤数
+ * @param {number} opts.stepsTotal - 总步骤数
+ * @param {string} opts.agentSummary - Agent 最终输出摘要
+ * @param {string} [opts.cwd] - 项目根目录（默认 process.cwd()）
+ * @returns {string} 格式化的 summary 文本
+ */
+export function formatExecuteSummary({ changeName, stepsCompleted, stepsTotal, agentSummary, cwd }) {
+  const wm = new WorktreeManager({ cwd });
+  const meta = wm.getMeta(changeName);
+  const lines = [];
+
+  const SEPARATOR = '─'.repeat(32);
+
+  // --- Header ---
+  lines.push(`Execute Summary`);
+  lines.push(SEPARATOR);
+
+  // --- Status ---
+  if (!meta) {
+    // worktree 不存在（可能已 cleanup 或没有用过 worktree）
+    lines.push(`Status:     COMPLETED`);
+    lines.push(`Steps:      ${stepsCompleted} / ${stepsTotal}`);
+    lines.push(`Apply:      N/A`);
+  } else {
+    const hasBaseline = meta.baselineCommit != null;
+    const wtExists = existsSync(meta.worktreePath);
+
+    const applyStatus = wtExists ? 'pending' : 'applied';
+    const baselineCount = meta.baselineFiles?.length || 0;
+    const baselineStatus = hasBaseline
+      ? `dirty (${baselineCount} baseline file${baselineCount === 1 ? '' : 's'} protected)`
+      : 'clean';
+
+    lines.push(`Status:     COMPLETED`);
+    lines.push(`Steps:      ${stepsCompleted} / ${stepsTotal}`);
+    lines.push(`Baseline:   ${baselineStatus}`);
+    lines.push(`Apply:      ${applyStatus}`);
+  }
+
+  // --- Changed files ---
+  // 从主工作区 diff 获取（worktree 已 apply）或从 worktree diff 获取
+  if (meta && existsSync(meta.worktreePath)) {
+    // worktree 还在，用 baselineCommit 或 baseHash 做 diff
+    try {
+      const diffBase = meta.baselineCommit || meta.baseHash;
+      const { execSync: es } = require('child_process');
+      const filesRaw = es(`git -C ${meta.worktreePath} diff --name-only ${diffBase} 2>/dev/null`, { encoding: 'utf8' });
+      const files = filesRaw ? filesRaw.trim().split('\n').filter(Boolean) : [];
+      if (files.length > 0) {
+        lines.push(``);
+        const maxShow = 10;
+        const showFiles = files.slice(0, maxShow);
+        const remain = files.length - maxShow;
+        lines.push(`Changed Files (${files.length})`);
+        showFiles.forEach(f => lines.push(`  ${f}`));
+        if (remain > 0) {
+          lines.push(`  ... ${remain} more`);
+        }
+      }
+    } catch {}
+  }
+
+  // --- Agent Summary ---
+  if (agentSummary) {
+    lines.push(``);
+    lines.push(`Agent Summary`);
+    // 缩进每行，截断过长内容
+    const maxLen = 200;
+    const summary = agentSummary.length > maxLen
+      ? agentSummary.slice(0, maxLen) + '...'
+      : agentSummary;
+    summary.split('\n').forEach(l => lines.push(`  ${l}`));
+  }
+
+  // --- Next ---
+  lines.push(``);
+  lines.push(`Next`);
+  lines.push(`  → sillyspec run verify`);
+
+  return lines.join('\n');
+}

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,120 @@ 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 {
+          // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
+          const patchBuf = execSync(`git diff --cached --binary`, { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
+          if (patchBuf && patchBuf.length > 0) {
+            const patchFile = join(worktreePath, '.sillyspec-baseline-staged.patch');
+            writeFileSync(patchFile, patchBuf);
+            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 {
+          // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
+          const patchBuf = execSync(`git diff --binary`, { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
+          if (patchBuf && patchBuf.length > 0) {
+            const patchFile = join(worktreePath, '.sillyspec-baseline-unstaged.patch');
+            writeFileSync(patchFile, patchBuf);
+            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}`);
+    }
+  }
 }