sillyspec 3.27.2 → 3.27.6

package/src/endpoint-extractor.js

@@ -13,6 +13,17 @@ import { execSync } from 'child_process'
 
 // ─── Provider: 扫描后端 router 注册的端点 ───────────────────────────────
 
+/**
+ * matchIndex → 装饰器/路由起始行号（全文匹配配套；1-based）。
+ * 坑 endpoint-multiline-decorator-miss（2026-08-24 用户实证）：三框架提取器原为逐行匹配，
+ * 多行装饰器（`@router.get(\n  "/path",\n  response_model=…)` 等）路径不在装饰器行 → 端点
+ * 静默漏 → endpoints.json artifact 与 live 扫描双失真 → probe5 missingBackend 误报（11 个
+ * 存量端点）。装饰器匹配改为全文正则（`\s*` 天然跨换行），行号取起始行。
+ */
+function lineOfIndex(content, index) {
+  return content.slice(0, index).split('\n').length
+}
+
 /**
  * 从单个文件提取 FastAPI router 端点
  * 支持 APIRouter(prefix=...) 和 @router.get/post/put/delete/patch("/path")
@@ -25,7 +36,7 @@ export function extractFastApiEndpoints(filePath) {
   const lines = content.split('\n')
   const endpoints = []
 
-  // 1. 提取 router prefix
+  // 1. 提取 router prefix（逐行，同文件近似——维持原行为）
   let routerPrefix = ''
   for (const line of lines) {
     const prefixMatch = line.match(/(?:APIRouter|router)\s*\(\s*(?:prefix\s*=\s*)?["'`]([^"'`]+)["'`]/)
@@ -35,40 +46,17 @@ export function extractFastApiEndpoints(filePath) {
     }
   }
 
-  // 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,
-        })
-      }
-    }
+  // 2. 装饰器全文匹配：单行 `@router.get("/path")`、分散式 `@router.get\n("/path")`、
+  //    多行参数 `@router.get(\n  "/path",\n  response_model=…)` 三态合一（\s* 跨换行）
+  const decoratorRe = /@(?:router|api_router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/g
+  let m
+  while ((m = decoratorRe.exec(content)) !== null) {
+    endpoints.push({
+      method: m[1].toUpperCase(),
+      path: routerPrefix + m[2],
+      source: filePath,
+      line: lineOfIndex(content, m.index),
+    })
   }
 
   return endpoints
@@ -94,16 +82,18 @@ export function extractExpressEndpoints(filePath) {
     if (useMatch) routerPrefix = useMatch[1]
   }
 
+  // 路由全文匹配（坑 endpoint-multiline-decorator-miss：`router.get(\n  "/path",\n  handler)` 同病）
+  const routeRe = /\b(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/gi
+  let m
+  while ((m = routeRe.exec(content)) !== null) {
+    endpoints.push({ method: m[1].toUpperCase(), path: routerPrefix + m[2], source: filePath, line: lineOfIndex(content, m.index) })
+  }
+
+  // 链式 .route(path).get(h).put(h) —— 同行所有 method 配上 path（跨行链式不扩面，维持逐行）
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]
-    const m = line.match(/\b(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/i)
-    if (m) {
-      endpoints.push({ method: m[1].toUpperCase(), path: routerPrefix + m[2], source: filePath, line: i + 1 })
-      continue
-    }
     const routeChain = line.match(/\.route\s*\(\s*["'`]([^"'`]+)["'`]/)
     if (routeChain) {
-      // 链式 .route(path).get(h).put(h) —— 同行所有 method 配上 path
       const chainPath = routerPrefix + routeChain[1]
       for (const mm of line.matchAll(/\.(get|post|put|delete|patch)\s*\(/gi)) {
         endpoints.push({ method: mm[1].toUpperCase(), path: chainPath, source: filePath, line: i + 1 })
@@ -135,17 +125,16 @@ export function extractSpringEndpoints(filePath) {
 
   const methodMap = { get: 'GET', post: 'POST', put: 'PUT', delete: 'DELETE', patch: 'PATCH' }
 
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    const shortMatch = line.match(/@(Get|Post|Put|Delete|Patch)Mapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`]/i)
-    if (shortMatch) {
-      endpoints.push({ method: methodMap[shortMatch[1].toLowerCase()], path: classPrefix + shortMatch[2], source: filePath, line: i + 1 })
-      continue
-    }
-    const oldMatch = line.match(/@RequestMapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`][^)]*?method\s*=\s*RequestMethod\.(\w+)/i)
-    if (oldMatch) {
-      endpoints.push({ method: oldMatch[2].toUpperCase(), path: classPrefix + oldMatch[1], source: filePath, line: i + 1 })
-    }
+  // 短形式全文匹配（坑 endpoint-multiline-decorator-miss：`@GetMapping(\n  "/path"\n)` 同病）
+  const shortRe = /@(Get|Post|Put|Delete|Patch)Mapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`]/gi
+  let m
+  while ((m = shortRe.exec(content)) !== null) {
+    endpoints.push({ method: methodMap[m[1].toLowerCase()], path: classPrefix + m[2], source: filePath, line: lineOfIndex(content, m.index) })
+  }
+  // 旧形式全文匹配（[^)]*? 字符类可跨行，`@RequestMapping(\n value="/p",\n method=…)` 随全文化一并覆盖）
+  const oldRe = /@RequestMapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`][^)]*?method\s*=\s*RequestMethod\.(\w+)/gi
+  while ((m = oldRe.exec(content)) !== null) {
+    endpoints.push({ method: m[2].toUpperCase(), path: classPrefix + m[1], source: filePath, line: lineOfIndex(content, m.index) })
   }
 
   return endpoints

package/src/foreign-declared.js

@@ -0,0 +1,155 @@
+/**
+ * 他者会话显式声明文件集（坑 verify-reconcile-foreign-wip，2026-08-23 实证：verify 实测
+ * 对账在主仓共享工作区取 git diff，无 meta 回退时把并行会话在途 WIP 全量算进本变更——误
+ * 命中他者模块跑他者测试 / 他者删除进本变更删除对账误报）。
+ *
+ * 归属口径与坑 35（quick 审计豁免，run/shared 的 collectOtherQuickSessionDeclarations）
+ * 同款：只认**显式声明**——其他 quick 会话 guard.allowedFiles + 其他变更 design §6 清单；
+ * 无主文件保留参与判定（fail-closed，不放松「未声明删除/越界」的抓取底线）。
+ *
+ * 独立零环模块：被 verify-postcheck / verify-probes / contract-matrix 共用（verify-
+ * postcheck import contract-matrix，parity 侧不能反向 import verify-postcheck）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { parseFileChangeListDetailed } from './change-list.js'
+import { safeGit, unquoteGitPath } from './git-helper.js'
+
+/**
+ * 主仓未提交文件集（staged + unstaged + untracked，rename 取新路径）。
+ * 活性判定的事实源：他者声明的文件若已不在未提交集，说明其工作已 apply+commit（或从未发生），
+ * 声明随之失效（坑 foreign-declared-stale-noise，2026-08-25 实证：并行会话 pathspec 重叠期
+ * execute/verify 每轮重复刷「已排除 N 个并行会话声明的文件」，其中大量是对方早已 apply+commit
+ * 的存量声明——design §6 清单与残留 quick guard 不随 commit 自动失效，纯噪音）。
+ * @param {string} cwd 项目根
+ * @returns {Set<string>|null} null = git 调用失败（调用方 fail-closed 不过滤）
+ */
+function getMainDirtySet(cwd) {
+  const r = safeGit(cwd, ['status', '--porcelain', '--untracked-files=all'], { trim: false })
+  if (r.value === null) return null
+  const set = new Set()
+  for (const line of r.value.split('\n')) {
+    if (!line.trim()) continue
+    let p = line.slice(3).trim()
+    const arrow = p.lastIndexOf(' -> ')
+    if (arrow !== -1) p = p.slice(arrow + 4)
+    if (p.startsWith('"') && p.endsWith('"')) p = unquoteGitPath(p.slice(1, -1))
+    p = p.replace(/\\/g, '/')
+    if (p) set.add(p)
+  }
+  return set
+}
+
+/**
+ * 变更 worktree 活性速查（.runtime/worktrees/<change>/meta.json）。
+ * isolated=true：有存活隔离 worktree（meta 在、非 in-place、worktreePath 目录在）——
+ * 其 WIP 在 worktree 内主仓 porcelain 不可见，整份 design 声明按在途处理。
+ * @returns {Map<string, { isolated: boolean }>|null} null = 读取失败（fail-closed）
+ */
+function loadWorktreeLiveness(specBase) {
+  const map = new Map()
+  try {
+    const dir = join(specBase, '.runtime', 'worktrees')
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue
+      try {
+        const meta = JSON.parse(readFileSync(join(dir, e.name, 'meta.json'), 'utf8'))
+        const isolated = Boolean(meta && meta.mode !== 'in-place-fallback'
+          && meta.worktreePath && existsSync(meta.worktreePath))
+        map.set(meta.changeName || e.name, { isolated })
+      } catch { /* 单条损坏跳过（该变更走主仓 dirty 判定） */ }
+    }
+  } catch { return null }
+  return map
+}
+
+/**
+ * 他者声明活性收敛：声明只在「工作仍在途」时有效，已 apply+commit 的存量声明自动失效。
+ *   - quick 会话（主仓直接改）：文件仍在主仓未提交集才算在途
+ *   - 变更：有存活隔离 worktree → 整份声明在途；否则与 quick 同口径看主仓未提交集
+ * 判定所需事实读不出来（git/meta 失败）→ 一律保留（fail-closed，不放大放行面）。
+ * @param {Map<string, string[]>} foreign collectForeignDeclaredFiles 的原始结果（原地收敛）
+ */
+function filterStaleForeignDeclarations(foreign, cwd, specBase) {
+  if (foreign.size === 0) return
+  const dirty = getMainDirtySet(cwd)
+  const worktrees = loadWorktreeLiveness(specBase)
+  if (dirty === null && worktrees === null) return // 两个事实源全失败 → 原样保留
+  for (const [file, owners] of [...foreign.entries()]) {
+    const live = owners.filter(owner => {
+      if (!owner.startsWith('quick-')) {
+        const wt = worktrees ? worktrees.get(owner) : undefined
+        if (wt && wt.isolated) return true // 隔离 worktree 在途，声明整份有效
+      }
+      // quick 会话 / 无存活 worktree 的变更：看主仓未提交集；dirty 集不可用则保守保留
+      return dirty === null ? true : dirty.has(file)
+    })
+    if (live.length === 0) foreign.delete(file)
+    else if (live.length < owners.length) foreign.set(file, live)
+  }
+}
+
+/**
+ * @param {string} cwd 项目根
+ * @param {string|null} currentChangeName 本变更名（quick 会话名或 change 名，排除自身）
+ * @returns {Map<string, string[]>} file → 声明者列表（quick-<hex> 或变更名）
+ */
+export function collectForeignDeclaredFiles(cwd, currentChangeName) {
+  const foreign = new Map()
+  const add = (file, owner) => {
+    const f = String(file || '').replace(/\\/g, '/')
+    if (!f) return
+    if (!foreign.has(f)) foreign.set(f, [])
+    if (!foreign.get(f).includes(owner)) foreign.get(f).push(owner)
+  }
+  const specBase = join(cwd, '.sillyspec')
+  try {
+    // ① 其他 quick 会话的 --files 显式声明（guard.json）
+    const sessionsDir = join(specBase, '.runtime', 'quick-sessions')
+    let sessionDirs = []
+    try { sessionDirs = readdirSync(sessionsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) } catch {}
+    for (const sid of sessionDirs) {
+      if (sid === currentChangeName) continue
+      try {
+        const guard = JSON.parse(readFileSync(join(sessionsDir, sid, 'guard.json'), 'utf8'))
+        for (const f of Array.isArray(guard.allowedFiles) ? guard.allowedFiles : []) add(f, sid)
+      } catch { /* 损坏/缺失跳过 */ }
+    }
+    // ② 其他变更的 design §6 清单（目录在即视为在途变更；archive/ 下不算）
+    const changesDir = join(specBase, 'changes')
+    let changeDirs = []
+    try { changeDirs = readdirSync(changesDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) } catch {}
+    for (const cn of changeDirs) {
+      if (cn === currentChangeName || cn === 'archive') continue
+      const designPath = join(changesDir, cn, 'design.md')
+      if (!existsSync(designPath)) continue
+      try {
+        for (const e of parseFileChangeListDetailed(designPath)) add(e.path, cn)
+      } catch { /* 清单解析失败跳过该变更 */ }
+    }
+  } catch { /* 整体异常 → 空集（等价不过滤，回到原行为） */ }
+  // 活性收敛（坑 foreign-declared-stale-noise）：已 apply+commit 的他者声明不再产生排除噪音
+  try { filterStaleForeignDeclarations(foreign, cwd, specBase) } catch { /* 收敛失败 → 原样保留（fail-closed） */ }
+  return foreign
+}
+
+/**
+ * 按他者声明集切分 diff 文件（collectForeignDeclaredFiles 的消费端快捷封装）。
+ * @param {string} cwd 项目根
+ * @param {string|null} currentChangeName 本变更名
+ * @param {string[]|null} diffFiles 待切分文件列表（null 透传，保持调用方 null 语义）
+ * @returns {{ own: string[]|null, foreign: Array<{file: string, owners: string[]}> }}
+ */
+export function splitOwnVsForeignDiffFiles(cwd, currentChangeName, diffFiles) {
+  if (!Array.isArray(diffFiles)) return { own: diffFiles, foreign: [] }
+  const foreignMap = collectForeignDeclaredFiles(cwd, currentChangeName)
+  if (foreignMap.size === 0) return { own: diffFiles, foreign: [] }
+  const own = []
+  const foreign = []
+  for (const f of diffFiles) {
+    const owners = foreignMap.get(String(f).replace(/\\/g, '/'))
+    if (owners) foreign.push({ file: f, owners })
+    else own.push(f)
+  }
+  return { own, foreign }
+}

package/src/index.js

@@ -100,6 +100,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec module-impact --change <name>       生成 module-impact.md 骨架（文件×模块归属按 module-map 预填 + 未匹配清单）
   sillyspec endpoints extract --change <name> [--task task-NN] [--dir <dir>|--files <a.py,b.js>]  静态扫描路由装饰器生成 endpoints.json
   sillyspec scan-fix-headers [--project <名>]   scan 文档补 author/created_at header（幂等）
+  sillyspec plan-adopt-waves --change <名> [--dry-run]   plan.md Wave 段一键重排为 depends_on 拓扑分组（同步任务总表 W 列，幂等）
   sillyspec workspace add <名> <路径> [--role] [--repo] | remove <名> | status   多项目工作区登记与状态探测
   sillyspec scan-fix-leak --spec-dir <specRoot>  source_root 误写产物搬到平台 specRoot（污染一键修复）
   sillyspec run quick --cancel --change <会话ID> [--ql <ql-id>]  取消误启动的 quick 会话（QUICKLOG 翻已取消 + 挂载行移除）
@@ -778,15 +779,22 @@ async function main() {
         process.exit(2);
       }
       assertSafeChangeName(vpChange, '--change 变更名');
-      const { runVerifyProbes, renderVerifyProbesReport, generateVerifyResultSkeleton } = await import('./verify-probes.js');
-      const vpResult = runVerifyProbes({ cwd: dir, changeName: vpChange, specDir });
+      const { runVerifyProbes, renderVerifyProbesReport, generateVerifyResultSkeleton, resolveVerifyProbesSpecBase } = await import('./verify-probes.js');
+      // spec 根统一走漂移锚定（坑 worktree-spec-artifact-misplace）：在 worktree 内跑时锚回主仓，
+      // 探针读取与 --init 骨架都落主仓——与 plan/execute/verify/archive 的 command.js 守卫同口径。
+      // resolvePlatformSpecDir 仍先调（保留平台接管 fail-closed 检查副作用），但仅 pointer 存在时
+      // 才把它的返回值当平台根——无 pointer 时它回退 resolveSpecDir(cwd)，会返回 worktree 副本
+      // 根，当作 platformBase 传入会让锚定被跳过（骨架落回副本）。
+      const vpResolved = resolvePlatformSpecDir(dir, specDir);
+      const vpPlatformBase = existsSync(join(dir, '.sillyspec-platform.json')) ? vpResolved : null;
+      const vpSpecBase = resolveVerifyProbesSpecBase(dir, specDir, vpPlatformBase);
+      const vpResult = runVerifyProbes({ cwd: dir, changeName: vpChange, specDir: vpSpecBase });
       if (json) {
         console.log(JSON.stringify({ command: 'verify-probes', change: vpChange, ...vpResult }, null, 2));
         break;
       }
       console.log(renderVerifyProbesReport(vpResult));
       if (vpInit) {
-        const vpSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
         const vpReportPath = join(vpSpecBase, 'changes', vpChange, 'verify-result.md');
         if (existsSync(vpReportPath)) {
           console.log(`\nℹ️  verify-result.md 已存在，不覆盖: ${vpReportPath}`);
@@ -797,6 +805,52 @@ async function main() {
       }
       break;
     }
+    case 'plan-adopt-waves': {
+      // plan.md Wave 段一键重排（坑 wave-manual-mismatch-noise，2026-08-24 用户反馈二期）：
+      // 手排 Wave 与拓扑比对不一致需手改；依赖方向硬拦（plan-postcheck）落地后给一条零手写出路。
+      // depMap 与 postcheck 同源（collectTaskDepMap）→ topoSortWaves → 重写 Wave 段 + 同步任务总表 W 列。
+      const pawChangeIdx = args.indexOf('--change');
+      const pawChange = pawChangeIdx >= 0 && args[pawChangeIdx + 1] ? args[pawChangeIdx + 1] : null;
+      const pawDryRun = args.includes('--dry-run');
+      if (!pawChange) {
+        console.error('用法: sillyspec plan-adopt-waves --change <name> [--dry-run] [--json] [--spec-dir <path>]\n  把 plan.md 的 Wave 段一键重排为 depends_on 拓扑分组（同步任务总表 W 列；--dry-run 只看不写）');
+        process.exit(2);
+      }
+      assertSafeChangeName(pawChange, '--change 变更名');
+      const { adoptPlanWaves } = await import('./plan-adopt-waves.js');
+      const pawSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const pawResult = adoptPlanWaves({ changeDir: join(pawSpecBase, 'changes', pawChange), dryRun: pawDryRun });
+      if (json) {
+        console.log(JSON.stringify({ command: 'plan-adopt-waves', change: pawChange, ...pawResult }, null, 2));
+        break;
+      }
+      if (!pawResult.ok) {
+        console.error(`❌ ${pawResult.error}`);
+        process.exit(1);
+      }
+      console.log('📊 拓扑分组（depends_on）：');
+      pawResult.waves.forEach((wave, i) => {
+        console.log(`   Wave ${i + 1}: ${wave.join(', ')}`);
+      });
+      if (pawDryRun) {
+        console.log(`\n👁️ dry-run——将写入 ${pawResult.planPath} 的 Wave 段预览：`);
+        for (const l of pawResult.waveBlock) console.log(`   ${l}`);
+      } else {
+        console.log(`\n✅ plan.md Wave 段已重排: ${pawResult.planPath}（任务总表 W 列更新 ${pawResult.tableRowsUpdated} 行${pawResult.tableRowsSkipped > 0 ? `，${pawResult.tableRowsSkipped} 行非模板格式未改` : ''}；行尾统一 LF）`);
+      }
+      if (pawResult.postcheck) {
+        const pc = pawResult.postcheck;
+        if ((pc.errors || []).length > 0) {
+          console.warn(`⚠️ 重排后 blueprint 一致性问题（topo 只看依赖不看文件重叠——同 Wave 共享路径需手动拆分或补 depends_on）：`);
+          for (const e of pc.errors.slice(0, 10)) console.warn(`   ${e}`);
+          if (pc.errors.length > 10) console.warn(`   …等共 ${pc.errors.length} 条`);
+        } else {
+          console.log('✅ 重排后 blueprint 一致性校验通过（无同 Wave 共享路径冲突）');
+        }
+        for (const w of (pc.warnings || []).slice(0, 5)) console.warn(`⚠️ ${w}`);
+      }
+      break;
+    }
     case 'module-impact': {
       // archive 模块影响矩阵骨架（2026-08-21 审计第三批 D3）：文件×模块归属按 _module-map.yaml
       // paths 前缀匹配预填（机械），影响类型/review 标记留 <!--TODO-->（语义）。已存在不覆盖。
@@ -1499,8 +1553,8 @@ async function main() {
 SillySpec worktree — git worktree 隔离管理
 
 用法:
-  sillyspec worktree create <change-name> [--base <branch>]   创建隔离 worktree
-  sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge]   校验并应用变更到主工作区
+  sillyspec worktree create <change-name> [--base <branch>] [--adopt-branch]   创建隔离 worktree（--adopt-branch：收编既有同名分支为工作分支，分支现状作 baseline）
+  sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge] [--skip-overlap] [--stash-dirty]   校验并应用变更到主工作区（--stash-dirty：主仓在途改动自动 stash→apply→恢复，SHA 兜底可审计）
   sillyspec worktree assess <change-name>                     风险审计 + 自动 apply
   sillyspec worktree diff <change-name> [--base <commit>]      查看 worktree 相对 base 的变更
   sillyspec worktree list                                      列出所有活跃 worktree
@@ -1518,7 +1572,7 @@ SillySpec worktree — git worktree 隔离管理
       switch (wtSubCmd) {
         case 'create': {
           if (!wtName) {
-            console.error('❌ 用法: sillyspec worktree create <change-name> [--base <branch>]');
+            console.error('❌ 用法: sillyspec worktree create <change-name> [--base <branch>] [--adopt-branch]');
             process.exit(1);
           }
           // F6 路径穿越消毒：worktree 名用于分支名 + worktree 目录，含 ../ 会逃出 .sillyspec/worktrees/。
@@ -1526,8 +1580,9 @@ SillySpec worktree — git worktree 隔离管理
           catch (e) { console.error(`❌ ${e.message}`); process.exit(2); }
           const baseIdx = args.indexOf('--base');
           const base = baseIdx >= 0 && args[baseIdx + 1] ? args[baseIdx + 1] : undefined;
+          const adoptBranch = args.includes('--adopt-branch'); // 收编既有同名分支为工作分支（坑 worktree-user-branch-conflict）
           try {
-            const info = wm.create(wtName, { base });
+            const info = wm.create(wtName, { base, adoptBranch });
             console.log(`✅ worktree 已创建`);
             console.log(`   分支: ${info.branch}`);
             console.log(`   路径: ${info.worktreePath}`);
@@ -1547,11 +1602,13 @@ SillySpec worktree — git worktree 隔离管理
         }
         case 'apply': {
           if (!wtName) {
-            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge]');
+            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge] [--skip-overlap] [--stash-dirty]');
             process.exit(1);
           }
           const checkOnly = args.includes('--check-only');
           const merge = args.includes('--merge');
+          const skipOverlap = args.includes('--skip-overlap');
+          const stashDirty = args.includes('--stash-dirty');
 
           // 解析 --base 参数（默认 merge-base）
           let base = 'merge-base';
@@ -1565,7 +1622,7 @@ SillySpec worktree — git worktree 隔离管理
             base = baseVal;
           }
 
-          const { applyWorktree } = await import('./worktree-apply.js');
+          const { applyWorktree, withMainRepoLock } = await import('./worktree-apply.js');
           // W3 task-09：apply 链路构造 ctx（D-013），让 task-05 applyWorktree 按 ctx 区分主仓 A5 / 跨仓 no-op。
           // 跨仓 apply=no-op（G1 D-009）：校验 review.head 是跨仓真实 commit + 跳过 wm.cleanup。
           // ctx 构造 fail-closed（约束②）——跨仓配置错时 apply 必须阻断（走错仓=数据所有权事故），不降级。
@@ -1577,7 +1634,17 @@ SillySpec worktree — git worktree 隔离管理
             console.error(`❌ apply 失败：跨仓 MultiRepoContext 构造失败（${e.message}）`);
             process.exit(1);
           }
-          const result = applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx });
+          // 主仓 apply 互斥锁（坑 main-apply-no-mutex）：真 apply（非 checkOnly）在锁内跑——
+          // apply 链（rollback/merge/cleanup）直接改主仓工作区，两会话并发互踩会互相清文件。
+          let result;
+          try {
+            result = checkOnly
+              ? applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap, stashDirty })
+              : await withMainRepoLock(dir, wtName, 'apply', () => applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap, stashDirty }));
+          } catch (lockErr) {
+            console.error(`❌ ${lockErr.message}`);
+            process.exit(1);
+          }
 
           if (result.errors.length > 0) {
             console.error(`❌ 校验失败:`);
@@ -1685,8 +1752,15 @@ SillySpec worktree — git worktree 隔离管理
           console.log('');
           if (assessment.decision === 'SAFE' || assessment.decision === 'WARNING') {
             console.log('Action: auto-applying...');
-            const { applyWorktree } = await import('./worktree-apply.js');
-            const applyResult = applyWorktree(wtName, { cwd: dir, ctx: _assessCtx });
+            const { applyWorktree, withMainRepoLock } = await import('./worktree-apply.js');
+            // 主仓互斥锁（与手动 apply 同款）：自动 apply 同样改主仓工作区，必须互斥
+            let applyResult;
+            try {
+              applyResult = await withMainRepoLock(dir, wtName, 'assess-auto-apply', () => applyWorktree(wtName, { cwd: dir, ctx: _assessCtx }));
+            } catch (lockErr) {
+              console.error(`❌ 自动 apply 未执行：${lockErr.message}`);
+              break;
+            }
             if (applyResult.errors.length > 0) {
               console.error('❌ apply 失败:', applyResult.errors.join('; '));
             } else {
@@ -1785,7 +1859,10 @@ SillySpec worktree — git worktree 隔离管理
           }
           const forceFlag = args.includes('--force');
           try {
-            const result = wm.cleanup(wtName, { force: forceFlag });
+            // 主仓互斥锁（坑 main-repo-no-mutex 二批）：cleanup 删 worktree 注册表/分支/目录，
+            // 与并行会话的 apply/cleanup 互踩会互相清——与其他写主仓操作共用一把 main-repo.lock
+            const { withMainRepoLock } = await import('./worktree-apply.js');
+            const result = await withMainRepoLock(dir, wtName, 'worktree-cleanup', () => wm.cleanup(wtName, { force: forceFlag }));
             if (result.result === 'cleaned' || result.result === 'force-cleaned') {
               console.log(`✅ worktree 已清理: ${wtName} (mode: ${result.mode})`);
               if (result.details?.length > 0) {
@@ -1798,6 +1875,11 @@ SillySpec worktree — git worktree 隔离管理
               console.log(`   原因: in-place 模式没有隔离目录需要清理`);
             } else if (result.result === 'blocked') {
               console.error(`🚫 拒绝清理：有未落主仓交付变更，请先 sillyspec worktree apply ${wtName} 或 --force`);
+            } else if (result.result === 'partial') {
+              // 坑 ghost-dir-junction-pierce：partial 残留此前落进 else 打成「未找到」，用户误以为
+              // 干净、人工 rm -rf 穿透 junction——必须明示残留 + 安全清理指引
+              console.warn(`⚠️ 部分清理（残留：${(result.residual || []).join('; ') || 'worktree 目录'}）`);
+              console.warn(`   Windows 手动清理勿 rm -rf（穿透 node_modules junction 删主仓依赖）：先 cmd /c rmdir "<worktree>\\node_modules" 解链再删，或 sillyspec worktree doctor --fix`);
             } else {
               console.log(`ℹ️  worktree 未找到: ${wtName}`);
             }

package/src/init.js

@@ -23,6 +23,9 @@ const __dirname = dirname(__filename);
 // 详见 docs/sillyspec/runtime-cleanup-destroys-worktree-meta.md
 //
 // 策略：白名单保留权威状态，逐项删除可重建的缓存子项；未知子项默认保留（安全侧倾斜）。
+// local.yaml 同样保留：gitignored 凭据文件（平台 init lease 第 5 步下发 / local detect /
+// platform connect 写入，含用户手调 mcp 段），删除即永久丢失无法从 git 找回。本函数曾把它
+// 当非权威残留整删，与 platformMode 跳过清理的保护语义自相矛盾，2026-08-23 起不再删。
 const RUNTIME_KEEP = new Set([
   'worktrees',          // worktree 目录 + meta.json（worktree.js:17）
   'sillyspec.db',       // SQLite 进度库（权威状态源，progress.js:7）
@@ -33,15 +36,14 @@ const RUNTIME_KEEP = new Set([
 
 /**
  * 清理 .sillyspec/ 下的运行时残留，保留权威状态。
- * 同时清理 local.yaml、codebase/（这些非权威，整删安全）。
+ * 同时清理 codebase/（非权威，整删安全）。local.yaml 受保护不删——
+ * 平台 init 下发的凭据配置，见上方策略注释。
  * @param {string} legacyDir - 源码目录的 .sillyspec/ 路径
  */
 export function cleanupRuntimeResidue(legacyDir) {
-  // local.yaml、codebase/ 非权威，整删
-  for (const residue of ['local.yaml', 'codebase']) {
-    const p = join(legacyDir, residue);
-    if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
-  }
+  // codebase/ 非权威，整删；local.yaml 是凭据配置，保留
+  const codebasePath = join(legacyDir, 'codebase');
+  if (existsSync(codebasePath)) { try { rmSync(codebasePath, { recursive: true, force: true }) } catch {} }
   // .runtime/ 逐项清理，白名单保留
   const runtimeDir = join(legacyDir, '.runtime');
   if (existsSync(runtimeDir)) {
@@ -251,7 +253,7 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null, options
       // 真实资产存在：拒绝整体删除，仅清理运行时残留
       console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产（changes/、projects/ 或 sillyspec.db）。');
       console.error('   该项目似乎本身就用 SillySpec 管理。如需改用外部 spec 目录，请先手动迁移/备份。');
-      console.error('   本次仅清理运行时残留（.runtime/ 缓存、local.yaml、codebase/），保留 worktrees 与进度状态。');
+      console.error('   本次仅清理运行时残留（.runtime/ 缓存、codebase/），保留 local.yaml、worktrees 与进度状态。');
       cleanupRuntimeResidue(legacyDir);
     } else {
       // 无真实资产：确属旧版本残留，安全删除