sillyspec 3.18.6 → 3.19.1

package/package.json

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

package/src/run.js

@@ -772,6 +772,23 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     }
   }
 
+  // Execute: 注入 currentExecuteRunId（从 runtime 标记文件读取）
+  if (stageName === 'execute' && promptText.includes('{EXECUTE_RUN_ID}')) {
+    const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const runIdFile = join(execSpecBase, '.runtime', 'current-execute-run-id')
+    let runId = ''
+    try {
+      if (existsSync(runIdFile)) {
+        runId = readFileSync(runIdFile, 'utf8').trim()
+      }
+    } catch {}
+    if (!runId) {
+      const { generateExecuteRunId, getLatestExecuteRunId } = await import('./task-review.js')
+ runId = getLatestExecuteRunId(join(execSpecBase, '.runtime')) || generateExecuteRunId()
+    }
+    promptText = promptText.replace(/\{EXECUTE_RUN_ID\}/g, runId)
+  }
+
   // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
   if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
     const effectiveSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
@@ -1485,6 +1502,18 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
     }
   }
 
+  // ── execute 阶段启动时固定 executeRunId ──
+  let currentExecuteRunId = null
+  if (stageName === 'execute') {
+    const { generateExecuteRunId, getLatestExecuteRunId } = await import('./task-review.js')
+    const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const runtimeRoot = join(execSpecBase, '.runtime')
+    currentExecuteRunId = getLatestExecuteRunId(runtimeRoot) || generateExecuteRunId()
+    // 写入 runtime 标记文件，确保整个 execute 生命周期内 runId 不变
+    mkdirSync(runtimeRoot, { recursive: true })
+    writeFileSync(join(runtimeRoot, 'current-execute-run-id'), currentExecuteRunId + '\n')
+  }
+
   // 自动探测 currentChange
   if (autoDetectChange(progress, cwd)) {
     progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
@@ -2592,6 +2621,56 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           }
         }
       }
+
+      // ── Execute Task Review Gate：所有 task 必须有 review.json 且 verdict 通过 ──
+      if (stageName === 'execute') {
+        try {
+          const { validateTaskReviews, printReviewResult, writeVerifyRequiredEvidence, getLatestExecuteRunId, generateExecuteRunId } = await import('./task-review.js')
+          const effectiveSpecBase = platformOpts?.specRoot || specBase
+          const planFile = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
+          const planPath = planFile ? join(planFile, 'plan.md') : null
+
+          if (planPath && existsSync(planPath)) {
+            const planContent = readFileSync(planPath, 'utf8')
+            const runtimeRoot = join(effectiveSpecBase, '.runtime')
+
+            // 找到 execute run id：优先从 runtime 目录找最新，否则生成新的
+            let executeRunId = getLatestExecuteRunId(runtimeRoot)
+            if (!executeRunId) {
+              executeRunId = generateExecuteRunId()
+            }
+
+            const reviewResult = validateTaskReviews({ planContent, runtimeRoot, executeRunId })
+            printReviewResult(reviewResult)
+
+            if (!reviewResult.ok) {
+              // Task review 校验失败，阻断 execute 完成
+              // 检查是否存在 checkbox 已勾但 review 不通过的情况
+              const uncheckedTasks = reviewResult.errors.filter(e => e.includes('缺少 review.json'))
+              if (uncheckedTasks.length > 0) {
+                console.error('\n⚠️  部分任务已在 plan.md 中勾选，但 review.json 不存在。')
+                console.error('   请取消勾选这些任务的 checkbox，或补充对应的 review.json。')
+              }
+              progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
+              await pm._write(cwd, progress, changeName)
+              triggerSync(cwd, changeName, platformOpts)
+              return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
+            }
+
+            // cannot_verify 的 requiredEvidence 写入 change 目录，供 verify 阶段消费
+            if (reviewResult.requiredEvidence.length > 0) {
+              const evidencePath = writeVerifyRequiredEvidence(join(effectiveSpecBase, 'changes', changeName), reviewResult.requiredEvidence)
+              if (evidencePath) {
+                console.log(`📄 verify-required-evidence.json 已写入: ${evidencePath}`)
+                console.log('   verify 阶段必须满足这些证据要求。')
+              }
+            }
+          }
+        } catch (e) {
+          console.warn(`⚠️ Task Review Gate 异常: ${e.message}`)
+          // 不阻断，但记录异常
+        }
+      }
     } else if (actualCompleted < actualTotal) {
       // 实际步骤未全部完成，跳过 validator（状态可能不同步）
       console.log(`\n⚠️ 阶段校验跳过：${actualTotal} 步中仅 ${actualCompleted} 步标记为已完成，可能存在状态不同步。如确认阶段已完成，请运行 --status 确认。`)

package/src/stages/execute.js

@@ -531,10 +531,40 @@ ${taskList}
    - 最后一个 Wave 完成后做一次全量编译验证
    - 用户明确要求编译时
 4. 每个任务完成后：
-   - 勾选 plan.md / tasks.md 中对应任务的 checkbox
+   - **先写 review.json 再勾选 checkbox**（见下方 Task Review Gate）
    - 记录改动文件和测试结果
 5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
 
+### Task Review Gate（必须执行，不可跳过）
+
+每个子代理完成后、勾选 checkbox **之前**，你必须创建 task review。
+
+**操作步骤：**
+1. 读取当前 task 的 git diff（从 task 开始到完成的变更）
+2. 对照 plan.md 中该 task 的描述和 tasks/task-XX.md（如果存在）检查实现是否符合要求
+3. 写入 review.json 文件
+4. **只有 review.json 写入成功后，才允许勾选 plan.md 中的 checkbox**
+
+**review.json 路径：**
+
+task-XX 对应：.sillyspec/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-XX/review.json
+
+本 execute run 的固定 ID 是：{EXECUTE_RUN_ID}
+**所有 task 的 review.json 必须使用这个 ID，不要自行创建新目录。**
+
+**review.json 必填字段：**
+
+{ "schemaVersion": 1, "task": "task-XX", "base": "<git-base-commit>", "head": "<git-head-commit>",
+ "changedFiles": ["src/foo.js"], "specVerdict": "pass|fail|cannot_verify",
+ "qualityVerdict": "pass|fail|cannot_verify", "reviewerNotes": "评审说明",
+ "requiredEvidence": [] }
+
+**评审铁律：**
+- 不信任 implementer 自报结果，对照 diff 和 task brief 验证
+- 只看当前 task 的 diff，不做全仓库漫游审查
+- \`cannot_verify\` 只在确实无法验证且有待补充证据时使用，且 requiredEvidence 必须非空
+- \`sillyspec run execute --done\` 会校验所有 task 的 review.json，缺失或 fail 会阻断完成
+
 ### 完成后
 1. 为每个后端 router task，扫描变更文件提取 API 端点 artifact：
    - 在变更文件中搜索所有 router 注册路径（@router.get/post/put/delete）
@@ -543,7 +573,6 @@ ${taskList}
 2. 运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
 }
 
-
 /**
  * 动态构建 execute 步骤列表
  * @param {string|null} planFilePath - plan 文件路径，null 则用默认 3 Wave

package/src/stages/verify.js

@@ -62,6 +62,14 @@ export const definition = {
 5. 加载代码规范：\`cat .sillyspec/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
 6. 标注每个文件的存在/不存在状态
 
+### Execute Evidence 传递检查
+7. 检查 verify-required-evidence.json 是否存在（由 execute 阶段 Task Review Gate 写入）
+   - 路径：变更目录下的 verify-required-evidence.json
+   - 如果存在 → 读取其中的 requiredEvidence 列表，逐条验证是否已满足
+   - 每条 evidence 必须在 verify-result.md 中给出明确结论（satisfied / missing / partial）
+   - 如果有任何 evidence 为 missing → verify 结论不能为 PASS
+   - 如果文件不存在 → 表示 execute 阶段无 cannot_verify 任务，正常继续
+
 ### 模块文档加载
 7. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
 8. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块

package/src/task-review.js

@@ -0,0 +1,346 @@
+/**
+ * SillySpec Task Review Gate — execute 阶段任务级评审校验
+ *
+ * execute 阶段每个 task 完成后，controller 必须写入 review.json。
+ * execute --done 时 CLI 硬校验：缺失 review 或 verdict 不通过则阻断。
+ *
+ * 目录结构：
+ *   .sillyspec/.runtime/execute-runs/<runId>/tasks/<taskId>/review.json
+ */
+
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync } from 'fs'
+import { join, resolve } from 'path'
+
+// ── review.json schema version ──
+export const REVIEW_SCHEMA_VERSION = 1
+
+// ── 合法 verdict 枚举 ──
+export const VALID_VERDICTS = ['pass', 'fail', 'cannot_verify']
+
+/**
+ * 解析 plan.md 中的 task 列表
+ * @param {string} planContent - plan.md 文件内容
+ * @returns {string[]} task id 列表，如 ['task-01', 'task-02']
+ */
+export function parseTaskIdsFromPlan(planContent) {
+  if (!planContent) return []
+  const ids = new Set()
+  const re = /^\s*[-*]\s*\[[ x]\]\s*task-(\d+)/gim
+  for (const m of planContent.matchAll(re)) {
+    ids.add(`task-${m[1].padStart(2, '0')}`)
+  }
+  return [...ids].sort()
+}
+
+/**
+ * 校验单个 review.json 文件
+ * @param {object} review - 解析后的 JSON 对象
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateReviewSchema(review) {
+  const errors = []
+  if (!review || typeof review !== 'object') {
+    errors.push('review.json 不是有效 JSON 对象')
+    return { ok: false, errors }
+  }
+
+  if (review.schemaVersion !== REVIEW_SCHEMA_VERSION) {
+    errors.push(`schemaVersion 应为 ${REVIEW_SCHEMA_VERSION}，实际为 ${review.schemaVersion}`)
+  }
+
+  if (!review.task || typeof review.task !== 'string') {
+    errors.push('缺少 task 字段（应为 "task-XX" 格式）')
+  }
+
+  if (!VALID_VERDICTS.includes(review.specVerdict)) {
+    errors.push(`specVerdict 无效：${review.specVerdict}（应为 ${VALID_VERDICTS.join('/')})`)
+  }
+
+  if (!VALID_VERDICTS.includes(review.qualityVerdict)) {
+    errors.push(`qualityVerdict 无效：${review.qualityVerdict}（应为 ${VALID_VERDICTS.join('/')})`)
+  }
+
+  // cannot_verify 必须提供 requiredEvidence
+  if (review.specVerdict === 'cannot_verify' || review.qualityVerdict === 'cannot_verify') {
+    if (!Array.isArray(review.requiredEvidence) || review.requiredEvidence.length === 0) {
+      errors.push('cannot_verify 的 verdict 必须提供非空的 requiredEvidence 数组')
+    }
+  }
+
+  // base/head 非空检查
+  if (!review.base || typeof review.base !== 'string') {
+    errors.push('缺少 base 字段（git commit hash）')
+  }
+  if (!review.head || typeof review.head !== 'string') {
+    errors.push('缺少 head 字段（git commit hash）')
+  }
+
+  return { ok: errors.length === 0, errors }
+}
+
+/**
+ * 读取单个 task 的 review.json
+ * @param {string} reviewPath - review.json 文件路径
+ * @returns {{ ok: boolean, review: object|null, errors: string[] }}
+ */
+export function readReview(reviewPath) {
+  if (!existsSync(reviewPath)) {
+    return { ok: false, review: null, errors: ['review.json 不存在'] }
+  }
+
+  let raw
+  try {
+    raw = readFileSync(reviewPath, 'utf8')
+  } catch (e) {
+    return { ok: false, review: null, parseError: true, errors: [`review.json 读取失败: ${e.message}`] }
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (e) {
+    // 文件存在但 JSON 非法：review 设为 null 但标记 parseError=true
+    return { ok: false, review: null, parseError: true, errors: [`review.json 解析失败: ${e.message}`] }
+  }
+
+  const schemaResult = validateReviewSchema(parsed)
+  if (!schemaResult.ok) {
+    return { ok: false, review: parsed, schemaError: true, errors: schemaResult.errors }
+  }
+
+  return { ok: true, review: parsed, errors: [] }
+}
+
+/**
+ * execute --done 时的 task review 总校验
+ *
+ * 规则：
+ *   - 每个 plan task 必须有 review.json
+ *   - specVerdict 或 qualityVerdict 为 fail → 整体 fail
+ *   - specVerdict 或 qualityVerdict 为 cannot_verify → warning（requiredEvidence 非空）
+ *   - cannot_verify + requiredEvidence 为空 → fail（agent 逃避判断）
+ *   - cannot_verify 的 requiredEvidence 汇总到 requiredEvidence 字段，供 verify 阶段消费
+ *
+ * @param {object} opts
+ * @param {string} opts.planContent - plan.md 内容
+ * @param {string} opts.runtimeRoot - .sillyspec/.runtime 的绝对路径
+ * @param {string} opts.executeRunId - execute run id（如 'exec-2026-06-23-131400'）
+ * @param {boolean} [opts.allowCannotVerify=true] - 是否允许 cannot_verify（默认允许，给 warning）
+ * @returns {{ ok: boolean, errors: string[], warnings: string[], requiredEvidence: Array<{task: string, verdict: string, evidence: string[]}> }}
+ */
+export function validateTaskReviews(opts) {
+  const { planContent, runtimeRoot, executeRunId, allowCannotVerify = true } = opts
+
+  const taskIds = parseTaskIdsFromPlan(planContent)
+
+  // 如果 plan 里没有 task，跳过校验（向后兼容）
+  if (taskIds.length === 0) {
+    return { ok: true, errors: [], warnings: [], requiredEvidence: [] }
+  }
+
+  const errors = []
+  const warnings = []
+  const requiredEvidence = []
+
+  for (const taskId of taskIds) {
+    const reviewDir = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', taskId)
+    const reviewPath = join(reviewDir, 'review.json')
+
+    const result = readReview(reviewPath)
+
+    if (!result.ok) {
+      if (result.parseError) {
+        // review.json 存在但 JSON 非法
+        errors.push(`${taskId}: review.json 解析失败 — ${result.errors.join('; ')}`)
+      } else if (result.schemaError) {
+        // review.json 存在且 JSON 合法，但 schema 校验失败
+        errors.push(`${taskId}: review.json 校验失败 — ${result.errors.join('; ')}`)
+      } else {
+        // review.json 不存在
+        errors.push(`${taskId}: 缺少 review.json — task 未经过评审`)
+      }
+      continue
+    }
+
+    const review = result.review
+
+    // 检查 review.task 是否与 plan 中的 taskId 一致
+    if (review.task && review.task !== taskId) {
+      errors.push(`${taskId}: review.json 中的 task 字段为 "${review.task}"，与 plan 不一致（应为 "${taskId}"）— agent 可能复制模板未修改`)
+      continue
+    }
+
+    // 检查 fail verdict
+    if (review.specVerdict === 'fail' || review.qualityVerdict === 'fail') {
+      errors.push(`${taskId}: review 未通过 — spec: ${review.specVerdict}, quality: ${review.qualityVerdict}`)
+      if (review.reviewerNotes) {
+        errors.push(`${taskId}: ${review.reviewerNotes}`)
+      }
+      continue
+    }
+
+    // 检查 cannot_verify
+    if (review.specVerdict === 'cannot_verify' || review.qualityVerdict === 'cannot_verify') {
+      if (!allowCannotVerify) {
+        errors.push(`${taskId}: cannot_verify 不被允许 — 必须提供评审结果`)
+        continue
+      }
+
+      if (review.requiredEvidence && review.requiredEvidence.length > 0) {
+        const verdicts = []
+        if (review.specVerdict === 'cannot_verify') verdicts.push('spec')
+        if (review.qualityVerdict === 'cannot_verify') verdicts.push('quality')
+        warnings.push(`${taskId}: ${verdicts.join('+')}=cannot_verify，requiredEvidence 必须在 verify 阶段满足`)
+        requiredEvidence.push({
+          task: taskId,
+          verdict: verdicts.join('+'),
+          evidence: review.requiredEvidence,
+        })
+      } else {
+        // cannot_verify + 空 requiredEvidence = agent 逃避判断
+        errors.push(`${taskId}: cannot_verify 但 requiredEvidence 为空 — 这是无效评审`)
+      }
+    }
+  }
+
+  // 额外检查：扫描 execute-runs/<runId>/tasks/ 下是否有 plan 里没有的 task review
+  // （agent 可能写错了 task id）
+  try {
+    const tasksDir = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks')
+    if (existsSync(tasksDir)) {
+      const taskDirs = readdirSync(tasksDir, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+      const taskIdSet = new Set(taskIds)
+      for (const dirName of taskDirs) {
+        if (!taskIdSet.has(dirName) && existsSync(join(tasksDir, dirName, 'review.json'))) {
+          warnings.push(`${dirName}: 存在 review.json 但不在 plan.md 的 task 列表中（可能是多余文件）`)
+        }
+      }
+    }
+  } catch (e) {
+    warnings.push(`task review extra-check 异常: ${e.message}`)
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    requiredEvidence,
+  }
+}
+
+/**
+ * 将 cannot_verify 的 requiredEvidence 写入 change 目录
+ * 供 verify 阶段消费
+ *
+ * @param {string} changeDir - 变更目录（.sillyspec/changes/<name>）
+ * @param {Array<{task: string, verdict: string, evidence: string[]}>} requiredEvidence
+ * @returns {string|null} 写入的文件路径，null 表示无需写入
+ */
+export function writeVerifyRequiredEvidence(changeDir, requiredEvidence) {
+  if (!requiredEvidence || requiredEvidence.length === 0) return null
+
+  const filePath = join(changeDir, 'verify-required-evidence.json')
+  const data = {
+    generatedAt: new Date().toISOString(),
+    schemaVersion: 1,
+    items: requiredEvidence,
+  }
+
+  mkdirSync(changeDir, { recursive: true })
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n')
+
+  return filePath
+}
+
+/**
+ * 生成 execute run id
+ * @returns {string} 如 'exec-2026-06-23-131400'
+ */
+export function generateExecuteRunId() {
+  const now = new Date()
+  const pad = (n) => String(n).padStart(2, '0')
+  return `exec-${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
+}
+
+/**
+ * 获取当前（或最新）execute run id
+ * 从 runtime 目录下查找 execute-runs/ 子目录
+ *
+ * @param {string} runtimeRoot - .sillyspec/.runtime 路径
+ * @returns {string|null} 最新 run id，null 表示无任何 run
+ */
+/**
+ * 获取当前 execute run id
+ * 优先从 current-execute-run-id 标记文件读取（execute 阶段启动时写入），
+ * fallback 到 execute-runs/ 下最新的 exec- 前缀目录。
+ *
+ * @param {string} runtimeRoot - .sillyspec/.runtime 路径
+ * @returns {string|null} 当前 run id，null 表示无任何 run
+ */
+export function getLatestExecuteRunId(runtimeRoot) {
+  // 优先读标记文件（execute 阶段启动时由 run.js 写入，生命周期内不变）
+  const markerPath = join(runtimeRoot, 'current-execute-run-id')
+  try {
+    if (existsSync(markerPath)) {
+      const content = readFileSync(markerPath, 'utf8').trim()
+      if (content) return content
+    }
+  } catch {}
+
+  // fallback：扫描 execute-runs/ 目录
+  const runsDir = join(runtimeRoot, 'execute-runs')
+  if (!existsSync(runsDir)) return null
+
+  try {
+    const entries = readdirSync(runsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name.startsWith('exec-'))
+      .map(e => e.name)
+      .sort()
+      .reverse()
+    return entries[0] || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 确保 task review 目录存在
+ * @param {string} runtimeRoot
+ * @param {string} executeRunId
+ * @param {string} taskId
+ * @returns {string} task review 目录路径
+ */
+export function ensureTaskReviewDir(runtimeRoot, executeRunId, taskId) {
+  const dir = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', taskId)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/**
+ * 打印校验结果
+ * @param {{ ok: boolean, errors: string[], warnings: string[], requiredEvidence: Array }} result
+ */
+export function printReviewResult(result) {
+  if (result.ok && result.warnings.length === 0) {
+    console.log('\n✅ Task Review Gate — 所有任务评审通过')
+    return
+  }
+
+  if (result.errors.length > 0) {
+    console.error('\n🚫 Task Review Gate — FAILED')
+    for (const err of result.errors) {
+      console.error(`   - ${err}`)
+    }
+    console.error('\n   提示：为缺失/失败的任务补充 review.json，然后重新 --done')
+  }
+
+  if (result.warnings.length > 0) {
+    console.warn('\n⚠️ Task Review Gate — WARNING')
+    for (const w of result.warnings) {
+      console.warn(`   - ${w}`)
+    }
+    console.warn('\n   cannot_verify 的 requiredEvidence 将在 verify 阶段校验')
+  }
+}

package/src/worktree.js

@@ -9,7 +9,7 @@
  */
 
 import { execSync } from 'child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync } from 'fs';
 import { join, resolve, dirname } from 'path';
 import { createHash } from 'crypto';
 
@@ -120,7 +120,43 @@ export function isGitWorktreeSupported(cwd = process.cwd()) {
 export class WorktreeManager {
   constructor({ cwd, worktreeDir } = {}) {
     this.cwd = cwd || process.cwd();
-    this.worktreeBase = worktreeDir || resolve(this.cwd, WORKTREES_REL);
+
+    // worktreeBase 必须固定到主仓库路径，不能跟着 cwd 变化。
+    // native-worktree 模式下 cwd 是 worktree 子目录，用 cwd 推导 worktreeBase
+    // 会导致 meta 写入 worktree 内部路径，worktree 内再次执行时找不到。
+    // 解决：用 git rev-parse --git-common-dir 反推主仓库路径。
+    if (worktreeDir) {
+      this.worktreeBase = worktreeDir;
+    } else {
+      this.worktreeBase = resolve(this._resolveMainRepoRoot(), WORKTREES_REL);
+    }
+  }
+
+  /**
+   * 解析当前 git 环境对应的主仓库根目录
+   * 在主仓库内执行：返回 cwd 自身
+   * 在 linked worktree 内执行：返回 git-common-dir 的父目录（即主仓库 .git 所在地）
+   * @private
+   */
+  _resolveMainRepoRoot() {
+    try {
+      // git-common-dir 在主仓库内 = <main>/.git
+      // 在 linked worktree 内 = <main>/.git（git 共享 .git 目录）
+      const commonDir = gitQuiet(this.cwd, 'rev-parse --git-common-dir');
+      if (!commonDir) return this.cwd;
+
+      // commonDir 应该是 <main-repo>/.git
+      // dirname(commonDir) = <main-repo>
+      if (existsSync(commonDir)) {
+        const st = statSync(commonDir);
+        if (st.isDirectory()) {
+          return dirname(commonDir);
+        }
+      }
+    } catch (e) {
+      // 静默 fallback：主仓库内执行或 git 异常
+    }
+    return this.cwd;
   }
 
   /**
@@ -167,11 +203,19 @@ export class WorktreeManager {
     if (isolation.inWorktree) {
       // 已在 linked worktree 中，复用当前目录作为 worktree 路径
       console.log(`ℹ️  已在 linked worktree 中（git-dir: ${isolation.gitDir}），复用当前隔离环境。`);
-      return this._createInPlaceMeta(name, {
+
+      // 幂等守卫：meta 已存在时不重新 overlay baseline
+      const existingMeta = this.getMeta(name)
+      if (existingMeta) {
+        return { branch: existingMeta.branch, worktreePath: existingMeta.worktreePath, baseHash: existingMeta.baseHash, mode: existingMeta.mode }
+      }
+
+      // meta 不存在但已在 worktree 内：可能是 meta 被损坏/误删。
+      // 绝对禁止 overlay baseline（source === target 会冲突），
+      // 只恢复 meta 引用，不触碰文件系统。
+      return this._recoverNativeWorktreeMeta(name, {
         worktreePath: this.cwd,
         branch: gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || 'detached',
-        mode: 'native-worktree',
-        base,
       });
     }
 
@@ -304,12 +348,76 @@ export class WorktreeManager {
     return { branch, worktreePath, baseHash, mode: meta.mode };
   }
 
+  /**
+   * native-worktree 模式下恢复 meta 引用
+   * 当 meta.json 被损坏/误删时，只重建 meta 文件，不触碰文件系统（不 overlay）
+   * @private
+   */
+  _recoverNativeWorktreeMeta(name, { worktreePath, branch }) {
+    const baseHash = gitQuiet(worktreePath, 'rev-parse HEAD') || null
+    const meta = {
+      changeName: name,
+      branch: branch || BRANCH_PREFIX + name,
+      baseBranch: branch,
+      baseHash,
+      actualBaseHash: baseHash,
+      createdAt: new Date().toISOString(),
+      worktreePath,
+      mode: 'native-worktree',
+      baselineFiles: [],
+      baselineCommit: null,
+      baselineHash: null,
+      recoveredAt: new Date().toISOString(),
+      recoveryNote: 'meta was missing in native-worktree; recovered without baseline overlay',
+    }
+    if (!existsSync(this.worktreeBase)) mkdirSync(this.worktreeBase, { recursive: true })
+    const metaDir = join(this.worktreeBase, name)
+    if (!existsSync(metaDir)) mkdirSync(metaDir, { recursive: true })
+    writeFileSync(join(metaDir, META_FILE), JSON.stringify(meta, null, 2) + '\n')
+    console.log(`🔗 native-worktree meta 已恢复: ${metaDir}/meta.json`)
+    return { branch: meta.branch, worktreePath, baseHash, mode: meta.mode }
+  }
+
   /**
    * 创建 in-place 模式的 meta.json（降级路径）
    * 不创建 git worktree，直接在当前目录记录 baseline 并写入 meta
    * @private
    */
   _createInPlaceMeta(name, { worktreePath, branch, baseBranch, baseHash, mode } = {}) {
+    // 幂等守卫：meta 已存在时不重新创建（避免 overlay baseline 和已有改动冲突）
+    const existingMeta = this.getMeta(name)
+    if (existingMeta) {
+      return { branch: existingMeta.branch, worktreePath: existingMeta.worktreePath, baseHash: existingMeta.baseHash, mode: existingMeta.mode }
+    }
+
+    // 硬规则：禁止 self-overlay（source 和 target 相同时 overlay 必然冲突）
+    const resolvedSource = resolve(this.cwd)
+    const resolvedTarget = resolve(worktreePath)
+    if (resolvedSource === resolvedTarget) {
+      console.warn('⚠️  跳过 baseline overlay：当前目录与目标目录相同（native-worktree 或 in-place 模式）')
+      // 写 meta 但不 overlay
+      baseBranch = baseBranch || gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || gitQuiet(this.cwd, 'rev-parse HEAD')
+      baseHash = baseHash || git(this.cwd, 'rev-parse HEAD')
+      const meta = {
+        changeName: name,
+        branch: branch || BRANCH_PREFIX + name,
+        baseBranch,
+        baseHash,
+        actualBaseHash: gitQuiet(worktreePath, 'rev-parse HEAD') || baseHash,
+        createdAt: new Date().toISOString(),
+        worktreePath,
+        mode: mode || 'in-place-fallback',
+        baselineFiles: [],
+        baselineCommit: null,
+        baselineHash: null,
+      }
+      if (!existsSync(this.worktreeBase)) mkdirSync(this.worktreeBase, { recursive: true })
+      const metaDir = join(this.worktreeBase, name)
+      if (!existsSync(metaDir)) mkdirSync(metaDir, { recursive: true })
+      writeFileSync(join(metaDir, META_FILE), JSON.stringify(meta, null, 2) + '\n')
+      return { branch: meta.branch, worktreePath, baseHash, mode: meta.mode }
+    }
+
     // 解析 base
     if (!baseHash) {
       baseBranch = baseBranch || gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || gitQuiet(this.cwd, 'rev-parse HEAD');

package/test/worktree-native-overlay.test.mjs

@@ -0,0 +1,188 @@
+/**
+ * worktree native-worktree overlay regression tests
+ *
+ * 验证 Bug 1 + Bug 2 修复：
+ * 1. worktreeBase 固定到主仓库路径，不跟着 cwd 变化
+ * 2. 禁止 self-overlay（source === target 时）
+ * 3. native-worktree meta 缺失时 recover，不 overlay
+ * 4. meta 已存在时幂等返回，不重建
+ */
+
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { execSync } from 'child_process'
+
+// ── Test 1: _resolveMainRepoRoot 在主仓库内返回 cwd ──
+
+async function test1_mainRepoRoot() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+
+  // Add .gitignore to allow worktreeBase path
+  fs.mkdirSync(path.join(d, '.sillyspec'), { recursive: true })
+  fs.writeFileSync(path.join(d, '.gitignore'), '.sillyspec/\n')
+
+  const { WorktreeManager } = await import('../src/worktree.js')
+  const wm = new WorktreeManager({ cwd: d })
+  const root = wm._resolveMainRepoRoot()
+  console.assert(root === d, `Test 1 FAIL: expected ${d}, got ${root}`)
+  console.log('✅ Test 1: main repo root resolves to cwd')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Test 2: native-worktree 检测 + 幂等守卫 ──
+
+async function test2_nativeWorktreeIdempotent() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+
+  const wtDir = path.join(d, 'wt')
+  execSync(`git worktree add ${wtDir} -b test-branch`, { cwd: d, stdio: 'pipe' })
+
+  // wtDir is a linked worktree
+  const { WorktreeManager } = await import('../src/worktree.js')
+
+  // First: create meta from inside worktree (simulating native-worktree mode)
+  const wm1 = new WorktreeManager({ cwd: wtDir })
+  // This simulates what happens when Claude Code runs in the worktree
+  // and SillySpec calls create() — detectIsolation should return inWorktree=true
+  // and meta should be written to main repo's worktreeBase, not worktree's
+
+  // Verify worktreeBase points to main repo
+  const expectedBase = path.join(d, '.sillyspec', '.runtime', 'worktrees')
+  console.assert(wm1.worktreeBase === expectedBase, `Test 2 FAIL: worktreeBase=${wm1.worktreeBase}, expected=${expectedBase}`)
+  console.log('✅ Test 2: worktreeBase fixed to main repo path')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Test 3: self-overlay 禁止 ──
+
+async function test3_selfOverlayBlocked() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+  fs.mkdirSync(path.join(d, '.sillyspec'), { recursive: true })
+  fs.writeFileSync(path.join(d, '.gitignore'), '.sillyspec/\n')
+
+  const { WorktreeManager } = await import('../src/worktree.js')
+  const wm = new WorktreeManager({ cwd: d })
+
+  // Create with in-place-fallback mode (source === target)
+  const result = wm._createInPlaceMeta('test-change', {
+    worktreePath: d,
+    branch: 'test-branch',
+    mode: 'in-place-fallback',
+  })
+
+  console.assert(result.mode === 'in-place-fallback', `Test 3 FAIL: mode=${result.mode}`)
+  // 返回值不包含 baselineFiles（是简化的返回结构），验证 meta 文件本身
+  const meta3 = wm.getMeta('test-change')
+  console.assert(meta3 && meta3.baselineFiles.length === 0, `Test 3 FAIL: meta baselineFiles should be empty`)
+  console.log('✅ Test 3: self-overlay blocked, baselineFiles empty')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Test 4: meta 幂等，不重复 overlay ──
+
+async function test4_metaIdempotent() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+  fs.mkdirSync(path.join(d, '.sillyspec'), { recursive: true })
+  fs.writeFileSync(path.join(d, '.gitignore'), '.sillyspec/\n')
+
+  const { WorktreeManager } = await import('../src/worktree.js')
+  const wm = new WorktreeManager({ cwd: d })
+
+  // First create
+  const r1 = wm._createInPlaceMeta('test-change', {
+    worktreePath: d,
+    branch: 'test-branch',
+    mode: 'in-place-fallback',
+  })
+
+  // Second create (should return existing, not re-overlay)
+  const r2 = wm._createInPlaceMeta('test-change', {
+    worktreePath: d,
+    branch: 'test-branch',
+    mode: 'in-place-fallback',
+  })
+
+  console.assert(r1.baseHash === r2.baseHash, `Test 4 FAIL: hashes differ`)
+  console.log('✅ Test 4: _createInPlaceMeta idempotent')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Test 5: native-worktree meta 恢复 ──
+
+async function test5_nativeRecovery() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+
+  const wtDir = path.join(d, 'wt')
+  execSync(`git worktree add ${wtDir} -b test-branch`, { cwd: d, stdio: 'pipe' })
+
+  const { WorktreeManager } = await import('../src/worktree.js')
+  const wm = new WorktreeManager({ cwd: wtDir })
+
+  // Simulate meta missing in native-worktree (should recover, not overlay)
+  const result = wm._recoverNativeWorktreeMeta('test-change', {
+    worktreePath: wtDir,
+    branch: 'test-branch',
+  })
+
+  console.assert(result.mode === 'native-worktree', `Test 5 FAIL: mode=${result.mode}`)
+  // 返回值不包含 baselineFiles，验证 meta 文件本身
+  const meta5 = wm.getMeta('test-change')
+  console.assert(meta5 && meta5.baselineFiles.length === 0, `Test 5 FAIL: meta baselineFiles should be empty`)
+
+  // Verify meta is readable now
+  const meta = wm.getMeta('test-change')
+  console.assert(meta !== null, `Test 5 FAIL: meta should exist after recovery`)
+  console.assert(meta.mode === 'native-worktree', `Test 5 FAIL: meta.mode=${meta.mode}`)
+  console.log('✅ Test 5: native-worktree meta recovery without overlay')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Run all ──
+
+const tests = [
+  ['main repo root', test1_mainRepoRoot],
+  ['native worktree worktreeBase', test2_nativeWorktreeIdempotent],
+  ['self-overlay blocked', test3_selfOverlayBlocked],
+  ['meta idempotent', test4_metaIdempotent],
+  ['native recovery', test5_nativeRecovery],
+]
+
+let passed = 0, failed = 0
+for (const [name, fn] of tests) {
+  try {
+    await fn()
+    passed++
+  } catch (e) {
+    console.log(`❌ ${name}: ${e.message}`)
+    failed++
+  }
+}
+
+console.log(`\n${passed}/${tests.length} passed`)
+if (failed) process.exit(1)