sillyspec 3.27.5 → 3.27.6

package/src/foreign-declared.js

@@ -13,6 +13,81 @@
 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 项目根
@@ -27,8 +102,8 @@ export function collectForeignDeclaredFiles(cwd, currentChangeName) {
     if (!foreign.has(f)) foreign.set(f, [])
     if (!foreign.get(f).includes(owner)) foreign.get(f).push(owner)
   }
+  const specBase = join(cwd, '.sillyspec')
   try {
-    const specBase = join(cwd, '.sillyspec')
     // ① 其他 quick 会话的 --files 显式声明（guard.json）
     const sessionsDir = join(specBase, '.runtime', 'quick-sessions')
     let sessionDirs = []
@@ -53,6 +128,8 @@ export function collectForeignDeclaredFiles(cwd, currentChangeName) {
       } catch { /* 清单解析失败跳过该变更 */ }
     }
   } catch { /* 整体异常 → 空集（等价不过滤，回到原行为） */ }
+  // 活性收敛（坑 foreign-declared-stale-noise）：已 apply+commit 的他者声明不再产生排除噪音
+  try { filterStaleForeignDeclarations(foreign, cwd, specBase) } catch { /* 收敛失败 → 原样保留（fail-closed） */ }
   return foreign
 }
 

package/src/index.js

@@ -1553,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
@@ -1572,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/。
@@ -1580,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}`);
@@ -1601,12 +1602,13 @@ SillySpec worktree — git worktree 隔离管理
         }
         case 'apply': {
           if (!wtName) {
-            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge] [--skip-overlap]');
+            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';
@@ -1637,8 +1639,8 @@ SillySpec worktree — git worktree 隔离管理
           let result;
           try {
             result = checkOnly
-              ? applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap })
-              : await withMainRepoLock(dir, wtName, 'apply', () => applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap }));
+              ? 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);

package/src/run/command.js

@@ -723,6 +723,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     '--json', '--dir', '--help',
     '--reopen', '--from-step', '--mode',
     '--deep', '--quick', '--standard', // scan profile 三档显式选择（scan-profile.js 从 argv 读；互斥见下方 PROFILE_FLAGS 检测）
+    '--adopt-branch', // execute 显式收编既有 sillyspec/<change> 分支为 worktree 工作分支（坑 worktree-user-branch-conflict）
     '--diff', '--base', '--full', '--report', // scan diff（D-001：command.js 只补 flag，裸 token 解析归 index.js 子命令拦截）
     '-h',
   ])
@@ -1241,7 +1242,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   }
 
   // 默认：输出当前步骤
-  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isAllowDelete, isForceBaseline, isForceRescan, linkedChanges, taskDescription: inputText })
+  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isAllowDelete, isForceBaseline, isForceRescan, linkedChanges, taskDescription: inputText, adoptBranch: stageName === 'execute' && flags.includes('--adopt-branch') })
 }
 
 /**

package/src/run/gates.js

@@ -473,6 +473,23 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       ensureDecisionDocHeader(resolveChangeDir(cwd, changeName, platformOpts?.specRoot))
     } catch { /* 补齐失败不阻断 gate */ }
   }
+  // TaskCard 骨架幂等预生成（坑 taskcard-parallel-cli-lock，2026-08-25 用户实证：并行 batch
+  // 子代理各自起 sillyspec taskcard CLI 撞进度库 SQLite 锁，改主代理预生成+子代理只 Edit 才稳）。
+  // gate 前主流程单进程补齐缺卡骨架（已存在跳过），与 ensureDecisionDocHeader 同层同范式——
+  // 补的是 CLI 可自证的机械骨架，占位符硬拦（plan-postcheck）仍逼子代理 Edit 填语义。
+  if (stageName === 'plan' && changeName) {
+    try {
+      const { ensureTaskcardSkeletons } = await import('../taskcard.js')
+      const r = ensureTaskcardSkeletons(changeName, { cwd, specDir: platformOpts?.specRoot })
+      if (r.created.length > 0) {
+        console.log(`📌 已预生成 ${r.created.length} 张 TaskCard 骨架（主流程单进程生成，子代理只 Edit 填充，勿并行跑 taskcard CLI）:`)
+        for (const f of r.created.slice(0, 8)) console.log(`   + ${f}`)
+        if (r.created.length > 8) console.log(`   … 共 ${r.created.length} 张`)
+      }
+    } catch (e) {
+      console.warn(`⚠️ TaskCard 骨架预生成失败（不阻断 gate，仍可逐卡手动 sillyspec taskcard 生成）: ${e.message}`)
+    }
+  }
   const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
   if (contractResult.errors.length > 0) {
     console.error(`\n❌ 阶段 ${stageName} 校验失败：`)

package/src/run/stage.js

@@ -74,14 +74,17 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
       console.log(`🔗 worktree 已存在: ${existingMeta.worktreePath} (${existingMeta.mode})`)
     } else {
       try {
-        const result = wm.create(effectiveChange)
-        console.log(`🔗 worktree 已创建: ${result.worktreePath} (分支: ${result.branch}, 模式: ${result.mode})`)
+        const result = wm.create(effectiveChange, { adoptBranch: !!(quickOpts && quickOpts.adoptBranch) })
+        console.log(`🔗 worktree 已创建: ${result.worktreePath} (分支: ${result.branch}, 模式: ${result.mode}${result.adoptedBranch ? ', 收编既有分支' : ''})`)
       } catch (e) {
         console.error(`❌ worktree 创建失败: ${e.message}`)
+        // 修复建议不再无条件推荐 git branch -D（坑 worktree-user-branch-conflict，2026-08-24：
+        // 同名分支可能是用户有意创建的——分支冲突时 create 报错已带三选一决策菜单，删不删
+        // 交由菜单/人工判断；doctor 的分支删除也有 review 锚点 + 无库保守双保护）。
         console.error(`   修复建议：`)
-        console.error(`   1. 运行 sillyspec worktree doctor --fix 检查并修复 worktree 状态`)
-        console.error(`   2. 或手动清理残留：git worktree prune && git branch -D sillyspec/${effectiveChange}`)
-        console.error(`   3. 必要时删除残留目录 .sillyspec/.runtime/worktrees/${effectiveChange}/ 后重试`)
+        console.error(`   1. 同名分支冲突/收编：按上方报错内三选一菜单处置（遗留分支确认作废后才删；用户指定分支用 --adopt-branch 收编）`)
+        console.error(`   2. worktree 状态异常：sillyspec worktree doctor --fix（分支删除有 review 锚点保护，不会误删在用分支）`)
+        console.error(`   3. 目录残留：确认无未提交改动后清理 .sillyspec/.runtime/worktrees/${effectiveChange}/ 再重试`)
         process.exit(1)
       }
     }

package/src/stage-contract-spec.js

@@ -223,7 +223,7 @@ const VERIFY_RULES = [
     target: { root: 'change', path: 'verify-result.md', scope: 'full' },
     data: {},
     spec: 'verify-result.md 结论不得为 FAIL(FAIL 阻断 verify 完成)。结论在含「结论/Conclusion/Result/结果」的二级标题后,值为 PASS / PASS WITH NOTES / FAIL。',
-    failMessage: 'verify-result.md 结论为 FAIL — 验证未通过，不能标记 verify 完成；请修复后重新运行验证',
+    failMessage: 'verify-result.md 结论为 FAIL — 验证未通过，不能标记 verify 完成；请修复后重新运行验证。⚠️ 重验成本预告：修复后 verify --done 时 CLI 会重新执行 local.yaml 的 commands.test 全量对账（同步执行，长套件可达数分钟、中途无输出属正常；可按 local.yaml test_strategy: module + modules 收窄命中模块），请在修复时一并评估测试范围',
     noConclusionWarning: 'verify-result.md 未识别到结论章节（含 结论/Conclusion/Result/结果 的二级标题，后跟 PASS / PASS WITH NOTES / FAIL）',
   },
   // integration-evidence(custom,D10 事前契约):风险门控。判定算法 detectChangeRisk +

package/src/stages/brainstorm-auto.js

@@ -149,7 +149,49 @@ AC-011: 不涉及业务规则/产品范围/默认行为/用户可见行为变更
 ### 产物文件
 
 #### design.md（必填，写入变更根目录 \`design.md\`）
-包含：背景、设计目标、非目标、总体方案、文件变更清单、接口定义、数据模型（如涉及）、兼容策略（brownfield）、风险登记、决策追踪。
+包含：背景、设计目标、非目标、总体方案、文件变更清单、接口定义、数据模型（如涉及）、兼容策略（brownfield）、风险登记、决策追踪、自审。
+**章节骨架必须按下述字面格式写**（校验器按字面短语匹配，措辞偏离会连环卡门——坑 literal-template-trap，2026-08-24 用户反馈五期②）：
+\`\`\`markdown
+# 设计文档（Design）— <变更简述>
+
+## 背景
+<为什么做、解决什么问题>
+
+## 设计目标
+<要达成什么>
+
+## 非目标
+<明确不做的事——标题必须字面含「非目标」（Non-Goals 也认，但大小写须完全一致）>
+
+## 总体方案
+<技术方案>
+
+## 文件变更清单
+| 操作 | 文件路径 | 说明 |
+|---|---|---|
+| 新增 | src/xxx/NewFile.ts | ... |
+| 修改 | src/xxx/ExistingFile.ts | ... |
+
+## 生命周期契约表
+<仅当涉及 session/lease/agent_run/daemon/lifecycle/state_transition/claim/heartbeat 关键词时必填；
+若不涉及，删掉本节或在正文写紧邻豁免短语：「不涉及生命周期契约」或「生命周期契约：无/N/A」
+——「无需 lifecycle 事件」这类宽写法不被识别（否定词必须紧邻「生命周期契约/lifecycle contract」）>
+
+| 事件 | 发起方 | 接收方 | 必需字段 | 状态变化 |
+|---|---|---|---|---|
+| <事件名> | <发起方> | <接收方> | <字段清单> | <初始态 → 终态> |
+
+## 风险登记
+| 编号 | 风险 | 等级 | 应对策略 |
+|---|---|---|---|
+| R-01 | ... | P0/P1/P2 | ... |
+
+## 决策追踪
+<列出 D-xxx@vN 决策 ID 及覆盖关系；无决策可写「无」>
+
+## 自审
+<对自身设计的校验——标题必须字面含「自审」或「Self-Review」（自我审查等宽写法不识别）>
+\`\`\`
 
 #### decisions.md（必填，写入变更根目录 \`decisions.md\`）
 记录所有决策：

package/src/stages/brainstorm.js

@@ -308,6 +308,8 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
 
    判断规则：
    - design.md 或需求中出现上述关键词 → 必须生成此表
+   - 确实不涉及 → 写**紧邻豁免短语**（照抄其一）：「不涉及生命周期契约」「不适用 lifecycle contract」「生命周期契约：无/N/A」
+     ——「本变更无需 lifecycle 事件」「lifecycle 状态无变化」这类宽写法**不被识别**（否定词必须紧邻「生命周期契约/lifecycle contract」）
    - 表中的每个事件 → 必须有对应代码任务、接口任务、测试任务
    - 表中的必需字段 → 必须出现在相关 DTO/interface 定义中
    - 缺少任一事件 → 在 design.md 风险登记中明确记录

package/src/stages/plan.js

@@ -456,7 +456,12 @@ ${taskList}
 
 **你必须使用 Agent tool 启动子代理来写卡片，不要自己写。**
 
-1. 确认 \`${changeDir}/tasks/\` 目录存在（不存在则创建）
+0. **先由你（主 agent）一次性预生成全部骨架**（2026-08-25 实证：并行子代理各自跑 taskcard CLI 撞进度库 SQLite 锁，主代理单进程预生成 + 子代理只 Edit 才稳）：
+   \`\`\`
+   sillyspec taskcard ${changeName} --all
+   \`\`\`
+   幂等，已存在的卡跳过不覆盖；骨架带 LF 行尾 + 闭合 frontmatter + 硬校验 9 字段 + depends_on 反填。**只有主 agent 跑这一次，子代理一律不再运行 taskcard CLI。**
+1. 确认 \`${changeDir}/tasks/\` 目录存在（上一步预生成会自动创建）
 2. **按 batch 分派子代理（减少总子代理数量，而不是一个 task 一个子代理）：**
    - 把任务按「同一 Wave + 同一模块/相近能力 + 无跨 batch 强依赖」原则分组
    - **每个 batch 包含 2~4 个 task**；Wave 内任务数 ≤4 时整个 Wave 可作为一个 batch
@@ -474,7 +479,7 @@ ${taskList}
 你是一个专注的 TaskCard 生成器。你的任务是为指定 batch 生成全部 TaskCard。
 
 ## ⚠️ 格式形态（第一眼必读，坑 taskcard-body-section-rework）
-TaskCard 的契约字段全部在 **frontmatter**（首对 --- 包裹的 YAML 键值对：id/title/title_zh/allowed_paths/goal/...）——**不是 body 章节**（## 标题下的段落）。goal 是 frontmatter 的 \`goal: >\` 多行标量、implementation/acceptance/verify/constraints 是 frontmatter 的列表项；写成 body 章节（\`## goal\` / \`## Goal\` 等）会三组校验全挂返工。先跑骨架命令再 Edit 填充，骨架即正确形态。
+TaskCard 的契约字段全部在 **frontmatter**（首对 --- 包裹的 YAML 键值对：id/title/title_zh/allowed_paths/goal/...）——**不是 body 章节**（## 标题下的段落）。goal 是 frontmatter 的 \`goal: >\` 多行标量、implementation/acceptance/verify/constraints 是 frontmatter 的列表项；写成 body 章节（\`## goal\` / \`## Goal\` 等）会三组校验全挂返工。骨架已由主 agent 预生成（正确形态），直接 Edit 填充即可。
 
 ## 输入
 - 变更目录：${changeDir}
@@ -486,8 +491,7 @@ TaskCard 的契约字段全部在 **frontmatter**（首对 --- 包裹的 YAML
 ## 操作
 1. 读取 ${changeDir}/design.md 和 ${changeDir}/plan.md 了解整体上下文
 2. 读取本 batch 涉及的相关源文件
-3. 为 batch 中的**每一个 task** 先运行 CLI 生成 Windows 安全骨架（在项目根目录执行；编号/标题自动取自 plan.md，author/created_at 自动填写）：
-   sillyspec taskcard ${changeName} --task <本 batch 任务号，逗号分隔，如 task-01,task-02>
+3. **骨架已由主 agent 预生成**（\`${changeDir}/tasks/task-NN.md\` 已存在，LF 行尾 + 闭合 frontmatter + 硬校验 9 字段齐全）。**禁止再运行 \`sillyspec taskcard\` CLI**——并行子代理各起 CLI 进程会撞进度库 SQLite 锁（2026-08-25 实证）；若发现本 batch 某卡骨架缺失，报告主 agent 补跑，不要自己跑
 4. 用 Edit tool 逐卡填充骨架占位符（allowed_paths/goal/implementation/acceptance/verify/constraints 等）。**禁止用 Write 整文件重写**——手写整卡是 CRLF 行尾/漏闭合 --- /漏硬校验字段三类 postcheck 拒绝的根源，骨架 + Edit 从源头消灭
 5. 骨架字段含义与可选字段（provides/expects_from/related_tests，按需插进 frontmatter）参考下述模板：
 

package/src/stages/verify.js

@@ -236,7 +236,7 @@ verify-result.md 路径 + 验证报告摘要 + 下一步命令
 
 ### 注意
 - PASS → 运行 \`sillyspec run archive\` 归档
-- FAIL → 修复后运行 \`sillyspec run verify\` 重新验证
+- FAIL → 修复后运行 \`sillyspec run verify\` 重新验证——注意重验时 CLI 会重新执行 commands.test 全量对账（长套件数分钟、同步无输出属正常；可 local.yaml test_strategy: module 收窄）
 - verify-result.md 是变更包的正式验收记录，归档后保留
 - **CLI 对账机制**：本步骤 --done 时 CLI 会亲自执行 local.yaml 的 commands.test；结论写 PASS 但实测失败 → verify 完成被阻断`,
       outputHint: '验证报告',

package/src/taskcard.js

@@ -126,6 +126,39 @@ constraints:
 `
 }
 
+/**
+ * TaskCard 骨架幂等预生成（坑 taskcard-parallel-cli-lock，2026-08-25 实证：plan 生成
+ * TaskCard 步骤让并行 batch 子代理各自跑 sillyspec taskcard CLI，多进程并发撞进度库
+ * SQLite 锁——用户改为主代理预生成骨架+子代理只 Edit 才稳。本函数把该实践内建：
+ * plan gate 前主流程单进程调用，注册表（tasks.md）里有声明而 tasks/ 缺卡的任务一律
+ * 补骨架，已存在跳过不覆盖；骨架占位符硬拦（plan-postcheck）不变——预生成只消灭
+ * CLI 并发与格式错误，不替子代理产语义内容）。
+ *
+ * @param {string} changeName
+ * @param {{ cwd: string, specDir?: string|null }} opts
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+export function ensureTaskcardSkeletons(changeName, opts = {}) {
+  const { cwd, specDir = null } = opts
+  assertSafeChangeName(changeName, '变更名')
+  const changeDir = join(resolveSpecDir(cwd, { specDir }), 'changes', changeName)
+  if (!existsSync(changeDir)) return { created: [], skipped: [] }
+  // 注册表口径与 cmdTaskcard 同源：tasks.md 优先，回退 plan.md（旧归档变更兼容读侧）
+  const tasksMdPath = join(changeDir, 'tasks.md')
+  const planPath = join(changeDir, 'plan.md')
+  const registryPath = existsSync(tasksMdPath) ? tasksMdPath : (existsSync(planPath) ? planPath : null)
+  if (!registryPath) return { created: [], skipped: [] }
+  const registry = parseTaskRegistry(readFileSync(registryPath, 'utf8').replace(/\r\n/g, '\n'))
+  if (registry.length === 0) return { created: [], skipped: [] }
+  const tasksDir = join(changeDir, 'tasks')
+  const missing = registry.map(t => t.id).filter(id => !existsSync(join(tasksDir, `${id}.md`)))
+  if (missing.length === 0) {
+    return { created: [], skipped: registry.map(t => join(tasksDir, `${t.id}.md`)) }
+  }
+  return cmdTaskcard(changeName, { cwd, specDir, taskIds: missing })
+}
+
+
 /**
  * taskcard 命令主逻辑：定位变更目录 → 解析任务清单（--task 显式列表 / 'all' 从 plan.md 取）→
  * 逐个写骨架。

package/src/verify-probes.js

@@ -19,7 +19,7 @@ import { join, dirname, basename } from 'path'
 import { gitQuiet } from './git-helper.js'
 import { parseFileChangeListDetailed } from './change-list.js'
 import { parseAllowedPaths } from './stages/plan-postcheck.js'
-import { verifyApiParity } from './contract-matrix.js'
+import { verifyApiParity, _readWorktreeMeta } from './contract-matrix.js'
 import { splitOwnVsForeignDiffFiles } from './foreign-declared.js'
 import { resolveSpecDir, resolveRuntimeRoot, detectWorktreeSpecDrift } from './run/shared.js'
 
@@ -101,17 +101,29 @@ export function runVerifyProbes({ cwd, changeName, specDir = null }) {
   const designOps = new Map(detailed.map(e => [e.path, e.operation]))
 
   // ── 探针 1：未实现标记扫描（design 清单具体文件；glob 项列出让 agent 展开）──
-  const probe1 = { matches: [], globEntries: [], skippedFiles: [] }
+  // worktree 路径回退（坑 probe1-worktree-path-blind，2026-08-24 用户实证：verify 从主仓跑、
+  // apply 前 design 清单新文件只在 worktree → 6 个新文件被报「不存在」跳过不扫）。主仓路径
+  // 缺失且存在真实 worktree（gitDir≠cwd，与探针 5 的 _readWorktreeMeta 同源解析）→ 读 worktree
+  // 版本并计数；两处皆缺才进 skippedFiles。in-place meta（gitDir==cwd）零行为变化。
+  const wtInfo = _readWorktreeMeta(specBase, cwd, changeName)
+  const wtRoot = (wtInfo && wtInfo.gitDir && wtInfo.gitDir !== cwd) ? wtInfo.gitDir : null
+  const probe1 = { matches: [], globEntries: [], skippedFiles: [], worktreeHits: 0 }
   for (const e of detailed) {
     if (e.path.startsWith('.sillyspec/')) continue
     if (/[*?[\]]/.test(e.path)) {
       probe1.globEntries.push(e.path)
       continue
     }
-    const abs = join(cwd, e.path)
+    let abs = join(cwd, e.path)
     if (!existsSync(abs)) {
-      probe1.skippedFiles.push(e.path)
-      continue
+      const wtAbs = wtRoot ? join(wtRoot, e.path) : null
+      if (wtAbs && existsSync(wtAbs)) {
+        abs = wtAbs
+        probe1.worktreeHits++
+      } else {
+        probe1.skippedFiles.push(e.path)
+        continue
+      }
     }
     try {
       const lines = readFileSync(abs, 'utf8').split('\n')
@@ -134,7 +146,15 @@ export function runVerifyProbes({ cwd, changeName, specDir = null }) {
     const moduleDirs = [...new Set(allowed.map(p => dirname(p.split('\\').join('/'))).filter(d => d && d !== '.'))]
     const testFiles = []
     for (const d of moduleDirs) {
-      for (const f of findTestFiles(join(cwd, d), cwd)) {
+      // 同探针 1 的 worktree 回退（坑 probe1-worktree-path-blind）：新模块目录 apply 前只在
+      // worktree——主仓目录缺失时到 worktree 找 co-located 测试（路径相对 worktree 根呈现）
+      let searchRoot = join(cwd, d)
+      let relBase = cwd
+      if (!existsSync(searchRoot) && wtRoot && existsSync(join(wtRoot, d))) {
+        searchRoot = join(wtRoot, d)
+        relBase = wtRoot
+      }
+      for (const f of findTestFiles(searchRoot, relBase)) {
         if (!testFiles.includes(f)) testFiles.push(f)
       }
     }
@@ -200,6 +220,7 @@ export function renderVerifyProbesReport(result) {
     for (const m of probe1.matches) L.push(`- ⚠️ \`${m.file}:${m.line}\` ${m.content}`)
   }
   if (probe1.globEntries.length > 0) L.push(`- ℹ️ glob 项未展开（agent 手动展开扫描）：${probe1.globEntries.join('、')}`)
+  if (probe1.worktreeHits > 0) L.push(`- ℹ️ ${probe1.worktreeHits} 个清单文件主仓不存在、已从 worktree 读取（apply 前新文件形态）`)
   if (probe1.skippedFiles.length > 0) L.push(`- ℹ️ 清单文件不存在（跳过）：${probe1.skippedFiles.join('、')}`)
   L.push('')