sillyspec 3.18.3 → 3.18.5

package/src/endpoint-extractor.js

@@ -0,0 +1,315 @@
+/**
+ * endpoint-extractor.js — 从代码中提取 HTTP 端点定义和调用
+ *
+ * provider 端：扫描 router 文件，提取注册的 API 路径
+ * consumer 端：扫描前端文件，提取 apiFetch/request 调用路径
+ *
+ * 契约对账时：provider 产出 ≠ consumer 消费 → gap
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join, extname, basename, dirname, resolve } from 'path'
+import { execSync } from 'child_process'
+
+// ─── Provider: 扫描后端 router 注册的端点 ───────────────────────────────
+
+/**
+ * 从单个文件提取 FastAPI router 端点
+ * 支持 APIRouter(prefix=...) 和 @router.get/post/put/delete/patch("/path")
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function extractFastApiEndpoints(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const endpoints = []
+
+  // 1. 提取 router prefix
+  let routerPrefix = ''
+  for (const line of lines) {
+    const prefixMatch = line.match(/(?:APIRouter|router)\s*\(\s*(?:prefix\s*=\s*)?["'`]([^"'`]+)["'`]/)
+      || line.match(/\.include_router\s*\([^)]*prefix\s*=\s*["'`]([^"'`]+)["'`]/)
+    if (prefixMatch) {
+      routerPrefix = prefixMatch[1]
+    }
+  }
+
+  // 2. 提取 @router.method("/path") 或分散式定义
+  //    FastAPI 支持两种写法：
+  //    a) @router.get("/path", ...) 下一行 def func():
+  //    b) @router.get 下一行 ("/path", ...)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const decoratorMatch = line.match(
+      /@(?:router|api_router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/
+    )
+    if (decoratorMatch) {
+      const method = decoratorMatch[1].toUpperCase()
+      const rawPath = decoratorMatch[2]
+      endpoints.push({
+        method,
+        path: routerPrefix + rawPath,
+        source: filePath,
+        line: i + 1,
+      })
+      continue
+    }
+    // 分散式: @router.get\n    ("/path",
+    const splitMatch = line.match(/@(?:router|api_router)\.(get|post|put|delete|patch)\s*$/)
+    if (splitMatch && i + 1 < lines.length) {
+      const nextLine = lines[i + 1]
+      const pathMatch = nextLine.match(/\(\s*["'`]([^"'`]+)["'`]/)
+      if (pathMatch) {
+        endpoints.push({
+          method: splitMatch[1].toUpperCase(),
+          path: routerPrefix + pathMatch[1],
+          source: filePath,
+          line: i + 1,
+        })
+      }
+    }
+  }
+
+  return endpoints
+}
+
+/**
+ * 从目录递归扫描所有 Python router 文件的端点
+ * @param {string} dir
+ * @param {{ filePattern?: RegExp, excludePatterns?: RegExp[] }} opts
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function scanBackendEndpoints(dir, opts = {}) {
+  const filePattern = opts.filePattern || /(?:router|routes|api|endpoint|controller)\.py$/i
+  const excludePatterns = opts.excludePatterns || [/__pycache__/, /node_modules/, /\.venv/, /test/i]
+
+  const results = []
+  if (!existsSync(dir)) return results
+
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (excludePatterns.some(p => p.test(entry.name))) continue
+        walk(full)
+      } else if (entry.isFile() && filePattern.test(entry.name)) {
+        try {
+          results.push(...extractFastApiEndpoints(full))
+        } catch {}
+      }
+    }
+  }
+  walk(dir)
+  return results
+}
+
+// ─── Consumer: 扫描前端 API 调用路径 ─────────────────────────────────────
+
+/**
+ * 从前端文件提取 API 调用路径
+ * 支持：
+ *   apiFetch("/api/xxx")
+ *   request("/api/xxx")
+ *   axios.get("/api/xxx")
+ *   axios.post("/api/xxx")
+ *   fetch("/api/xxx")
+ *
+ * @param {string} filePath
+ * @returns {Array<{ method: string, path: string, source: string, line: number, raw: string }>}
+ */
+export function extractFrontendApiCalls(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const results = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    // Pattern 1: apiFetch<T>("/path", { method: "POST" }) — default GET
+    const apiFetchMatch = line.match(/apiFetch\s*(?:<[^>]*>)?\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (apiFetchMatch) {
+      // 检查是否有 method 字段（在后续行或同一行）
+      let method = 'GET'
+      const snippet = lines.slice(i, Math.min(i + 3, lines.length)).join(' ')
+      const methodMatch = snippet.match(/method\s*:\s*["'`](GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)["'`]/i)
+      if (methodMatch) method = methodMatch[1].toUpperCase()
+
+      results.push({
+        method,
+        path: normalizePath(apiFetchMatch[1]),
+        source: filePath,
+        line: i + 1,
+        raw: apiFetchMatch[1],
+      })
+      continue
+    }
+
+    // Pattern 2: axios.get/post/put/delete("/path")
+    const axiosMatch = line.match(/axios\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/i)
+    if (axiosMatch) {
+      results.push({
+        method: axiosMatch[1].toUpperCase(),
+        path: normalizePath(axiosMatch[2]),
+        source: filePath,
+        line: i + 1,
+        raw: axiosMatch[2],
+      })
+      continue
+    }
+
+    // Pattern 3: fetch("/api/xxx", { method: "POST" })
+    const fetchMatch = line.match(/(?:api_?)?fetch\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (fetchMatch && !apiFetchMatch) {
+      let method = 'GET'
+      const snippet = lines.slice(i, Math.min(i + 3, lines.length)).join(' ')
+      const methodMatch = snippet.match(/method\s*:\s*["'`](GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)["'`]/i)
+      if (methodMatch) method = methodMatch[1].toUpperCase()
+
+      results.push({
+        method,
+        path: normalizePath(fetchMatch[1]),
+        source: filePath,
+        line: i + 1,
+        raw: fetchMatch[1],
+      })
+      continue
+    }
+  }
+
+  return results
+}
+
+/**
+ * 递归扫描前端目录的 API 调用
+ * @param {string} dir
+ * @param {{ filePattern?: RegExp, excludePatterns?: RegExp[] }} opts
+ * @returns {Array<{ method: string, path: string, source: string, line: number, raw: string }>}
+ */
+export function scanFrontendApiCalls(dir, opts = {}) {
+  const filePattern = opts.filePattern || /\.(ts|tsx|js|jsx)$/
+  const excludePatterns = opts.excludePatterns || [/node_modules/, /\.next/, /dist/, /__tests__/, /\.d\.ts$/]
+
+  const results = []
+  if (!existsSync(dir)) return results
+
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (excludePatterns.some(p => p.test(entry.name))) continue
+        walk(full)
+      } else if (entry.isFile() && filePattern.test(entry.name)) {
+        try {
+          results.push(...extractFrontendApiCalls(full))
+        } catch {}
+      }
+    }
+  }
+  walk(dir)
+  return results
+}
+
+// ─── 路径归一化 ─────────────────────────────────────────────────────────
+
+/**
+ * 将动态路径归一化为参数占位符
+ * /api/ppm/project-plan/${id}/plan-nodes → /api/ppm/project-plan/{param}/plan-nodes
+ * /api/ppm/project-plan/:planId/plan-nodes → /api/ppm/project-plan/{param}/plan-nodes
+ * @param {string} rawPath
+ * @returns {string}
+ */
+export function normalizePath(rawPath) {
+  return rawPath
+    .replace(/\$\{[^}]+\}/g, '{param}')
+    .replace(/:\w+/g, '{param}')
+    .replace(/\$\w+/g, '{param}')
+}
+
+// ─── 对账 ───────────────────────────────────────────────────────────────
+
+/**
+ * 比较前端调用的路径和后端注册的端点，返回差异
+ *
+ * @param {Array<{ path: string, method: string, source: string }>} frontendCalls
+ * @param {Array<{ path: string, method: string, source: string }>} backendEndpoints
+ * @returns {{
+ *   missingBackend: Array<{ path: string, method: string, consumerFile: string, consumerLine: number }>,
+ *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>
+ * }}
+ */
+export function diffApiParity(frontendCalls, backendEndpoints) {
+  // 构建 backend 注册表：归一化 path + method → endpoint
+  const backendMap = new Map()
+  for (const ep of backendEndpoints) {
+    const key = `${ep.method}:${normalizePath(ep.path)}`
+    if (!backendMap.has(key)) backendMap.set(key, ep)
+  }
+
+  const missingBackend = []
+  for (const call of frontendCalls) {
+    const key = `${call.method}:${normalizePath(call.path)}`
+    if (!backendMap.has(key)) {
+      missingBackend.push({
+        path: normalizePath(call.path),
+        method: call.method,
+        consumerFile: call.source,
+        consumerLine: call.line,
+      })
+    }
+  }
+
+  // 构建 frontend 调用表
+  const frontendSet = new Set(
+    frontendCalls.map(c => `${c.method}:${normalizePath(c.path)}`)
+  )
+
+  const unusedBackend = []
+  for (const ep of backendEndpoints) {
+    const key = `${ep.method}:${normalizePath(ep.path)}`
+    if (!frontendSet.has(key)) {
+      unusedBackend.push({
+        path: normalizePath(ep.path),
+        method: ep.method,
+        providerFile: ep.source,
+      })
+    }
+  }
+
+  return { missingBackend, unusedBackend, ok: missingBackend.length === 0 }
+}
+
+// ─── CLI 入口 ────────────────────────────────────────────────────────────
+
+/**
+ * CLI 子命令入口：sillyspec contract scan [--backend dir] [--frontend dir]
+ * 输出 JSON 格式的端点清单和对账结果
+ */
+export async function contractScan(args, cwd) {
+  const backendIdx = args.indexOf('--backend')
+  const frontendIdx = args.indexOf('--frontend')
+  const backendDir = backendIdx !== -1 && args[backendIdx + 1]
+    ? resolve(cwd, args[backendIdx + 1])
+    : resolve(cwd, 'backend')
+  const frontendDir = frontendIdx !== -1 && args[frontendIdx + 1]
+    ? resolve(cwd, args[frontendIdx + 1])
+    : resolve(cwd, 'frontend')
+
+  const backendEndpoints = scanBackendEndpoints(backendDir)
+  const frontendCalls = scanFrontendApiCalls(frontendDir)
+  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, backendEndpoints)
+
+  return {
+    backend: backendEndpoints.map(e => ({ method: e.method, path: normalizePath(e.path), file: e.source })),
+    frontend: frontendCalls.map(c => ({ method: c.method, path: normalizePath(c.path), file: c.source })),
+    missingBackend,
+    unusedBackend,
+    summary: {
+      backendEndpointCount: backendEndpoints.length,
+      frontendCallCount: frontendCalls.length,
+      missingBackendCount: missingBackend.length,
+      unusedBackendCount: unusedBackend.length,
+      ok: missingBackend.length === 0,
+    },
+  }
+}

package/src/index.js

@@ -145,6 +145,21 @@ async function main() {
     targetDir = resolve(filteredArgs[1]);
     filteredArgs.splice(1, 1);
   }
+  // ── 自动纠正 cwd ──
+  // 当 agent 在 worktree 内跑 pnpm 等工具后 shell cwd 可能被改变，
+  // 导致 sillyspec 命令找不到 .sillyspec。此函数尝试从 git root 解析。
+  function resolveEffectiveDir(baseDir) {
+    if (existsSync(join(baseDir, '.sillyspec'))) return baseDir
+    try {
+      const { execSync } = require('child_process')
+      const gitRoot = execSync('git rev-parse --show-toplevel', {
+        cwd: baseDir, encoding: 'utf8', timeout: 5000
+      }).trim()
+      if (gitRoot && existsSync(join(gitRoot, '.sillyspec'))) return gitRoot
+    } catch {}
+    return baseDir
+  }
+
   const dir = targetDir;
 
   if (command === 'init' && !existsSync(dir)) {
@@ -167,6 +182,7 @@ async function main() {
       break;
     case 'progress': {
       const pm = new ProgressManager();
+      const progDir = resolveEffectiveDir(dir);
       const subCommand = filteredArgs[1];
       const stageIdx = filteredArgs.indexOf('--stage');
       const stage = stageIdx >= 0 && filteredArgs[stageIdx + 1] ? filteredArgs[stageIdx + 1] : null;
@@ -176,18 +192,18 @@ async function main() {
 
       switch (subCommand) {
         case 'init':
-          pm.init(dir);
+          pm.init(progDir);
           break;
         case 'status':
         case 'show':
-          pm.show(dir, progChangeName);
+          pm.show(progDir, progChangeName);
           break;
         case 'check':
-          await pm.checkConsistency(dir, progChangeName);
+          await pm.checkConsistency(progDir, progChangeName);
           break;
         case 'repair': {
           const repairApply = filteredArgs.includes('--apply');
-          await pm.repairConsistency(dir, { apply: repairApply, changeName: progChangeName });
+          await pm.repairConsistency(progDir, { apply: repairApply, changeName: progChangeName });
           break;
         }
         case 'validate':
@@ -270,7 +286,7 @@ async function main() {
     }
     case 'run': {
       const { runCommand } = await import('./run.js')
-      await runCommand(filteredArgs.slice(1), dir, specDir)
+      await runCommand(filteredArgs.slice(1), resolveEffectiveDir(dir), specDir)
       break
     }
     case 'dashboard': {
@@ -329,7 +345,8 @@ SillySpec worktree — git worktree 隔离管理
   sillyspec worktree create <change-name> [--base <branch>]   创建隔离 worktree
   sillyspec worktree apply <change-name> [--check-only]        校验并应用变更到主工作区
   sillyspec worktree list                                      列出所有活跃 worktree
-  sillyspec worktree cleanup <change-name>                      强制清理 worktree
+  sillyspec worktree cleanup <change-name> [--force]           强制清理 worktree
+  sillyspec worktree doctor [--fix] [--stale-hours N]          健康检查 + 修复
 
 选项:
   --base <branch>       create: 指定基础分支（默认当前 HEAD）
@@ -429,11 +446,13 @@ SillySpec worktree — git worktree 隔离管理
           const forceFlag = args.includes('--force');
           try {
             const result = wm.cleanup(wtName, { force: forceFlag });
-            if (result.result === 'cleaned') {
+            if (result.result === 'cleaned' || result.result === 'force-cleaned') {
               console.log(`✅ worktree 已清理: ${wtName} (mode: ${result.mode})`);
-            } else if (result.result === 'force-cleaned') {
-              console.log(`⚠️  worktree 已强制清理: ${wtName} (mode: ${result.mode})`);
-              console.log(`   原因: git worktree remove 失败，通过直接删除目录完成`);
+              if (result.details?.length > 0) {
+                for (const d of result.details) {
+                  if (d.startsWith('⚠️')) console.log(`   ${d}`);
+                }
+              }
             } else if (result.result === 'skipped') {
               console.log(`⏭️  worktree 跳过清理: ${wtName} (mode: ${result.mode})`);
               console.log(`   原因: in-place 模式没有隔离目录需要清理`);
@@ -446,6 +465,34 @@ SillySpec worktree — git worktree 隔离管理
           }
           break;
         }
+        case 'doctor': {
+          const fixFlag = args.includes('--fix');
+          const staleIdx = args.indexOf('--stale-hours');
+          const staleHours = staleIdx !== -1 && args[staleIdx + 1] ? parseInt(args[staleIdx + 1], 10) : 24;
+          const diag = wm.doctor({ fix: fixFlag, staleHours });
+          if (diag.issues.length === 0) {
+            console.log('✅ worktree 健康检查通过，无异常');
+          } else {
+            console.log(`🔍 发现 ${diag.issues.length} 个问题：\n`);
+            for (const issue of diag.issues) {
+              const icon = issue.fixable ? '⚠️' : '❌';
+              console.log(`  ${icon} [${issue.type}] ${issue.name}: ${issue.detail}`);
+            }
+            if (fixFlag) {
+              console.log(`\n🔧 修复完成：`);
+              for (const f of diag.fixed) console.log(`  ✅ ${f}`);
+              if (diag.unfixable.length > 0) {
+                for (const u of diag.unfixable) console.log(`  ❌ ${u}`);
+              }
+              if (diag.fixed.length === 0 && diag.unfixable.length === 0) {
+                console.log('  无需修复');
+              }
+            } else {
+              console.log(`\n💡 运行 sillyspec worktree doctor --fix 自动修复`);
+            }
+          }
+          break;
+        }
         default:
           console.error(`❌ 未知子命令: worktree ${wtSubCmd}`);
           console.log('   运行 sillyspec worktree --help 查看帮助');

package/src/init.js

@@ -108,12 +108,39 @@ async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
   // projectDir: 源码项目根目录（用于工具检测、指令注入、.gitignore）
   const spec = specDir || join(projectDir, '.sillyspec');
 
-  // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）
+  // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
+  // ⚠️ 必须保护真实资产：若本地 .sillyspec 含 changes/（非空）、projects/（非空）
+  // 或 sillyspec.db（进度库），说明该项目本身就用 SillySpec 管理，整体删除会丢资产。
+  // 此时只清运行时残留，拒绝整删；确无资产时才视为旧残留清理。
   const legacyDir = join(projectDir, '.sillyspec');
   if (specDir && existsSync(legacyDir)) {
-    try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
-    if (!existsSync(legacyDir)) console.log('🧹 已清理旧版本残留的源码 .sillyspec/ 目录');
-    else console.error('⚠️ 清理残留 .sillyspec/ 失败');
+    let hasChanges = false;
+    try {
+      const changesDir = join(legacyDir, 'changes');
+      if (existsSync(changesDir)) hasChanges = readdirSync(changesDir).length > 0;
+    } catch {}
+    let hasProjects = false;
+    try {
+      const projectsDir = join(legacyDir, 'projects');
+      if (existsSync(projectsDir)) hasProjects = readdirSync(projectsDir).length > 0;
+    } catch {}
+    const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
+
+    if (hasChanges || hasProjects || hasDb) {
+      // 真实资产存在：拒绝整体删除，仅清理运行时残留
+      console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产（changes/、projects/ 或 sillyspec.db）。');
+      console.error('   该项目似乎本身就用 SillySpec 管理。如需改用外部 spec 目录，请先手动迁移/备份。');
+      console.error('   本次仅清理运行时残留（.runtime/、local.yaml、codebase/）。');
+      for (const residue of ['.runtime', 'local.yaml', 'codebase']) {
+        const p = join(legacyDir, residue);
+        if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
+      }
+    } else {
+      // 无真实资产：确属旧版本残留，安全删除
+      try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+      if (!existsSync(legacyDir)) console.log('🧹 已清理旧版本残留的源码 .sillyspec/ 目录');
+      else console.error('⚠️ 清理残留 .sillyspec/ 失败');
+    }
   }
 
   // 创建基础目录

package/src/run.js

@@ -1148,11 +1148,32 @@ export async function runCommand(args, cwd, specDir = null) {
   // runCommand 后续所有 .sillyspec/ 操作必须用 specBase
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
 
-  // 平台模式：清理旧版本残留的 cwd/.sillyspec/（防止源码污染）
+  // 平台模式：清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
+  // ⚠️ 同 init.js：必须保护真实资产（changes/、projects/、sillyspec.db）。
   if (platformOpts.specRoot) {
     const legacyDir = join(cwd, '.sillyspec')
     if (existsSync(legacyDir)) {
-      try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+      let hasChanges = false;
+      try {
+        const cd = join(legacyDir, 'changes');
+        if (existsSync(cd)) hasChanges = readdirSync(cd).length > 0;
+      } catch {}
+      let hasProjects = false;
+      try {
+        const pd = join(legacyDir, 'projects');
+        if (existsSync(pd)) hasProjects = readdirSync(pd).length > 0;
+      } catch {}
+      const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
+
+      if (hasChanges || hasProjects || hasDb) {
+        console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产。仅清理运行时残留。');
+        for (const residue of ['.runtime', 'local.yaml', 'codebase']) {
+          const p = join(legacyDir, residue);
+          if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
+        }
+      } else {
+        try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+      }
     }
   }
 
@@ -1943,12 +1964,38 @@ async function continueStep(pm, progress, stageName, cwd, answer, options = {})
     stageData.completedAt = now
     await pm._write(cwd, progress, changeName)
     console.log(`\n✅ ${stageName} 阶段已完成（${stageData.steps.length}/${stageData.steps.length} 步）`)
+    // ── execute 阶段完成时条件性清理 worktree ──
+    if (stageName === 'execute' && changeName) {
+      try {
+        const { WorktreeManager } = await import('./worktree.js');
+        const wm = new WorktreeManager({ cwd });
+        const meta = wm.getMeta(changeName);
+        if (!meta) {
+          console.log('🔗 Worktree: n/a (no meta)');
+        } else if (meta.mode === 'native-worktree') {
+          console.log('🔗 Worktree: kept (外部隔离环境)');
+        } else if (meta.mode === 'in-place-fallback') {
+          console.log('🔗 Worktree: n/a (in-place 模式)');
+        } else {
+          const check = wm.hasUnappliedChanges(changeName);
+          if (check.hasChanges) {
+            console.log(`🔗 Worktree: pending apply (${check.changedFiles.length} 个未应用变更)`);
+            console.log(`   下一步: sillyspec worktree apply ${changeName}`);
+          } else {
+            const cleanResult = wm.cleanup(changeName);
+            console.log(`🔗 Worktree: ${cleanResult.result}`);
+          }
+        }
+      } catch (e) {
+        console.warn(`🔗 Worktree: check failed — ${e.message}`);
+      }
+    }
     return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 
   // 输出下一步
-  if (nextPendingIdx !== -1 && defSteps) {
-    console.log('')
+    if (nextPendingIdx !== -1 && defSteps) {
+      console.log('')
     await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, answer)
   } else if (nextWaitingIdx !== -1 && defSteps) {
     // 下一个步骤也在等待状态
@@ -2517,6 +2564,42 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       console.log(`\n⚠️ 阶段校验跳过：${actualTotal} 步中仅 ${actualCompleted} 步标记为已完成，可能存在状态不同步。如确认阶段已完成，请运行 --status 确认。`)
     }
 
+    // ── execute 阶段完成时条件性清理 worktree（不依赖 AI agent 的完成确认步骤）──
+    if (stageName === 'execute' && changeName) {
+      try {
+        const { WorktreeManager } = await import('./worktree.js');
+        const wm = new WorktreeManager({ cwd });
+        const meta = wm.getMeta(changeName);
+        if (!meta) {
+          console.log('🔗 Worktree: n/a (no meta)');
+        } else if (meta.mode === 'native-worktree') {
+          console.log('🔗 Worktree: kept (外部隔离环境)');
+        } else if (meta.mode === 'in-place-fallback') {
+          console.log('🔗 Worktree: n/a (in-place 模式)');
+        } else {
+          const check = wm.hasUnappliedChanges(changeName);
+          if (check.hasChanges) {
+            console.log(`🔗 Worktree: pending apply (${check.changedFiles.length} 个未应用变更)`);
+            console.log(`   下一步: sillyspec worktree apply ${changeName}`);
+          } else {
+            const cleanResult = wm.cleanup(changeName);
+            if (cleanResult.result === 'skipped' || cleanResult.result === 'kept') {
+              console.log(`🔗 Worktree: ${cleanResult.result}`);
+            } else {
+              console.log(`🔗 Worktree: ${cleanResult.result}`);
+              if (cleanResult.details?.length > 0) {
+                for (const d of cleanResult.details) {
+                  if (d.startsWith('⚠️')) console.log(`   ${d}`);
+                }
+              }
+            }
+          }
+        }
+      } catch (e) {
+        console.warn(`🔗 Worktree: check failed — ${e.message}`);
+      }
+    }
+
     return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 

package/src/stages/execute.js

@@ -165,6 +165,7 @@ const fixedPrefix = [
 - **worktree 已由 CLI 在 execute 阶段启动时自动创建，不要自行创建或跳过**
 - **后续所有子代理的 cwd 必须设为该 worktree 路径**
 - 如果 meta.json 不存在（说明创建失败），停止并报错
+- **不要自行检查 git dirty/uncommitted 状态来判断是否可以进入 worktree，CLI 已自动处理**
 
 ### 输出
 worktree 路径 + 分支名 + 模式
@@ -406,6 +407,48 @@ function parseWavesFromPlan(planContent) {
  * 为 Wave 生成 prompt（强制子代理执行）
  */
 function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
+  // ── Contract Matrix：检查是否有 provider/consumer 契约需要注入 ──
+  let contractInjection = ''
+  if (changeDir) {
+    try {
+      const { buildContractMatrix, buildConsumerInjection } = require('../contract-matrix.js')
+      const planFile = path.join(changeDir, 'plan.md')
+      if (existsSync(planFile)) {
+        const planContent = readFileSync(planFile, 'utf8')
+        const contracts = buildContractMatrix(planContent, changeDir)
+        if (contracts.length > 0) {
+          // 收集本 wave 所有 task 的注入内容
+          const waveTasks = wave.tasks.map((t, ti) => {
+            const num = String(t.index || (ti + 1)).padStart(2, '0')
+            return `task-${num}`
+          })
+          const relevantContracts = contracts.filter(c => waveTasks.includes(c.consumer))
+          if (relevantContracts.length > 0) {
+            contractInjection = `
+### API Contract Matrix
+本 Wave 存在前端/后端跨 task 契约：
+${relevantContracts.map(c => `- **${c.consumer}** 消费 **${c.provider}** 产出的 API`).join('\n')}
+`
+            // 为每个 consumer task 生成详细注入
+            for (const taskName of waveTasks) {
+              const injection = buildConsumerInjection(changeDir, join(changeDir, '..', '..'), taskName, contracts)
+              if (injection) {
+                contractInjection += `
+### 子代理 ${taskName} 的契约注入
+为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
+
+<contract-injection>
+${injection}
+</contract-injection>
+`
+              }
+            }
+          }
+        }
+      }
+    } catch {}
+  }
+
   // 构建任务摘要（不再内联完整蓝图，减少上下文污染）
   const taskSummary = wave.tasks.map((t, ti) => {
     const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
@@ -476,7 +519,7 @@ ${taskSummary}
    - 🔥 热上下文：design.md 编码铁律 + 当前 Wave 任务（必须加载）
    - 🌡️ 温上下文：CONVENTIONS.md + ARCHITECTURE.md（需要时加载）
    - ❄️ 冷上下文：其他变更的 design.md、历史 plan.md（不要主动加载，除非明确需要）
-
+${contractInjection}
 ### 本 Wave 任务
 ${taskList}
 
@@ -493,7 +536,11 @@ ${taskList}
 5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
 
 ### 完成后
-运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
+1. 为每个后端 router task，扫描变更文件提取 API 端点 artifact：
+   - 在变更文件中搜索所有 router 注册路径（@router.get/post/put/delete）
+   - 将端点清单写入 .sillyspec/.runtime/contract-artifacts/<task-name>/endpoints.json
+   - 格式: { "task": "task-XX", "type": "backend_endpoints", "endpoints": [{ "method": "GET", "path": "/api/ppm/xxx" }] }
+2. 运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
 }