sillyspec 3.26.11 → 3.26.13

package/src/run/gates.js

@@ -26,15 +26,16 @@ import { runValidators } from '../stage-contract.js'
 import { handleScanStageCompleted, handleExecuteWorktreeCleanup } from './complete-handlers.js'
 import { detectConcurrentChanges, formatConcurrentWarning } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
+import { normalizeTaskId } from '../taskcard.js'
 
 /**
- * 从 plan.md 提取全部 task id（task-XX）——符号影响面覆盖度校验用。
- * 只认 checkbox 行 `- [ ] task-XX:` / `- [x] task-XX:`（与 execute.js parseWavesFromPlan 的
- * 收容口径一致：### 标题式 task / 非 task 区 checkbox 不算），light plan 的 `## Tasks` 段同样收。
+ * 从任务注册表（tasks.md）提取全部 task id（task-XX）——符号影响面覆盖度校验用。
+ * 只认 checkbox 行 `- [ ] task-XX:` / `- [x] task-XX:`（与 execute.js parseTaskRegistry 同口径）。
+ * 2026-08-20-task-truth-unify：源从 plan.md 迁 tasks.md（任务唯一真相）；ql-xxx 行不收。
  */
-function extractTaskIdsFromPlan(planContent) {
-  if (!planContent) return []
-  return [...String(planContent).matchAll(/^[-*]\s*\[[ x]\]\s*(?:.*\b)?task-(\d+)\b/gim)]
+function extractTaskIdsFromRegistry(tasksContent) {
+  if (!tasksContent) return []
+  return [...String(tasksContent).matchAll(/^[-*]\s*\[[ xX]\]\s*task-(\d+)\b/gim)]
     .map(m => `task-${m[1].padStart(2, '0')}`)
 }
 
@@ -56,8 +57,10 @@ export function validateSymbolImpactReport({ reportContent, planContent }) {
   if (!reportContent || !String(reportContent).trim()) {
     return { ok: false, errors: ['symbol-impact.md 不存在或内容为空——「加载上下文」步的符号影响面报告必须落盘（逐 task 一行结论，「无签名级变更」也要显式写）'] }
   }
-  const taskIds = extractTaskIdsFromPlan(planContent)
-  if (taskIds.length === 0) return { ok: true, errors } // plan 无 task 可列（默认兜底形态）→ 无可校验对象
+  // 2026-08-20-task-truth-unify：task 清单源迁 tasks.md（参数名 planContent 保持兼容既有调用，
+  // 语义=任务注册表内容；调用方 enforceSymbolImpactGate 已改读 tasks.md）
+  const taskIds = extractTaskIdsFromRegistry(planContent)
+  if (taskIds.length === 0) return { ok: true, errors } // 注册表无 task 可列（默认兜底形态）→ 无可校验对象
   const missing = taskIds.filter(id => !String(reportContent).includes(id))
   for (const id of missing) {
     errors.push(`${id} 未在 symbol-impact.md 中出现——每个 task 都要有一行结论（含「无签名级变更」的显式声明）`)
@@ -72,14 +75,14 @@ export function validateSymbolImpactReport({ reportContent, planContent }) {
 export async function enforceSymbolImpactGate(stageName, changeName, currentStepName, specBase) {
   if (stageName !== 'execute') return
   if (!currentStepName || !currentStepName.includes('加载上下文')) return
-  const planPath = join(specBase, 'changes', changeName || '', 'plan.md')
+  const tasksPath = join(specBase, 'changes', changeName || '', 'tasks.md')
   const reportPath = join(specBase, 'changes', changeName || '', 'symbol-impact.md')
-  if (!existsSync(planPath)) return // plan.md 缺失场景已有 plan 阶段 gate 把关，此处不重复拦
-  let planContent = ''
-  try { planContent = readFileSync(planPath, 'utf8') } catch { return }
+  if (!existsSync(tasksPath)) return // 注册表缺失场景已有 plan 阶段 gate 把关，此处不重复拦
+  let tasksContent = ''
+  try { tasksContent = readFileSync(tasksPath, 'utf8') } catch { return }
   let reportContent = null
   try { reportContent = readFileSync(reportPath, 'utf8') } catch { /* 缺失由 validate 报 */ }
-  const result = validateSymbolImpactReport({ reportContent, planContent })
+  const result = validateSymbolImpactReport({ reportContent, planContent: tasksContent })
   if (result.ok) return
   console.error('❌ ── 符号影响面报告校验阻断（本次 --done 未完成，进度未推进）──')
   console.error(`   「加载上下文」步的符号影响面检查报告未落盘或不完整：`)
@@ -105,10 +108,13 @@ function isCurrentWaveAllNoDepsVerify(stepName, changeDir) {
   const waveRe = new RegExp(`^##\\s*Wave\\s+${waveN}\\b[^\\n]*\\n([\\s\\S]*?)(?=\\n##\\s|\\n#\\s|$)`, 'm')
   const waveMatch = plan.match(waveRe)
   if (!waveMatch) return false
-  const taskIds = [...waveMatch[1].matchAll(/^[-*]\s*\[[ x]\]\s*(task-\d+)/gim)].map(x => x[1])
+  // 2026-08-20-task-truth-unify：Wave 段任务为纯 ID 引用行（"- task-XX"），不再有 checkbox
+  const taskIds = [...waveMatch[1].matchAll(/^[-*]\s+(task-\d+)\s*$/gim)].map(x => x[1])
   if (taskIds.length === 0) return false
   for (const id of taskIds) {
-    const cardPath = join(changeDir, 'tasks', `${id}.md`)
+    // 体检 BUG-19：plan 常态写补零 task-01，但 AI 写出 task-3 时卡片实际是 task-03.md——
+    // 未归一则 existsSync 恒 false，wave 级 no_deps_verify 豁免静默失效（保守方向）
+    const cardPath = join(changeDir, 'tasks', `${normalizeTaskId(id)}.md`)
     if (!existsSync(cardPath)) return false // 卡片缺失 → 保守不跳
     const card = readFileSync(cardPath, 'utf8')
     const fm = card.match(/^---\n([\s\S]*?)\n---/)
@@ -118,6 +124,99 @@ function isCurrentWaveAllNoDepsVerify(stepName, changeDir) {
   return true
 }
 
+/**
+ * doctor --align-execute-progress --confirm 的前置 review 门（坑 doctor-align-bypass-review-gate，
+ * 2026-08-20 实证）：alignExecuteToPlan 直写 completed「绕过 completeStep 推导」，此前 execute 的
+ * Stage Review Gate 与 Task Review Gate 被整体跳过——而 worktree 清理后的恢复场景恰是最需要
+ * review 审计的时刻（实证靠 15 份 task review + verify 全程补足覆盖才没出事）。
+ *
+ * 本函数供 CLI 层（index.js doctor align 分支）在 confirm 落盘前调用，跑与正常完成路径同源的
+ * 只读校验（不自动生成 marker/runId——恢复读场景缺失就是缺失，如实报告）：
+ *   1. Stage Review：tier=independent 时须存在有效 execute stage review.json（verdict 非 fail）；
+ *      tier=self 放行（与正常 gate 分级一致）。
+ *   2. Task Review：所有 task 的 review.json 齐备且 verdict 非 fail（runId 解析同 Task Review Gate：
+ *      marker → 含 tasks/ 目录扫描；不 generate）。
+ *
+ * @param {{ cwd: string, changeName: string, specBase: string, platformOpts?: object }} opts
+ * @returns {Promise<boolean>} true=被门阻断（CLI 应放弃 align 并 exit 1）；false=校验通过可继续
+ */
+export async function enforceAlignExecuteReviewGate({ cwd, changeName, specBase, platformOpts = {} }) {
+  const effectiveSpecBase = platformOpts?.specRoot || specBase
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, effectiveSpecBase)
+  const reviewChangeDir = resolveChangeDir(cwd, { currentChange: changeName }, platformOpts?.specRoot || null)
+  const blocked = (msgs) => {
+    console.error('\n❌ doctor --align-execute-progress 前置 review 校验未过——execute 完成审计不能绕过：')
+    for (const m of msgs) console.error('   - ' + m)
+    console.error('   解法：补齐上述 review 后重跑 align（stage review：sillyspec register-stage-review --change ' + changeName + ' --stage execute；task review：按报错路径补 review.json）')
+    return true
+  }
+
+  // 1. Stage Review（tier 分级同正常 gate）
+  try {
+    const { classifyReviewTier } = await import('../review-tier.js')
+    const { validateStageReview, getLatestStageReviewRunId, printStageReviewResult } = await import('../stage-review.js')
+    const designPath = reviewChangeDir ? join(reviewChangeDir, 'design.md') : null
+    let planLevel = null
+    if (reviewChangeDir) {
+      const planPath = join(reviewChangeDir, 'plan.md')
+      if (existsSync(planPath)) {
+        const fmLine = readFileSync(planPath, 'utf8').split('\n').find(l => l.trim().startsWith('plan_level:'))
+        if (fmLine) planLevel = fmLine.split(':')[1].trim()
+      }
+    }
+    const tier = classifyReviewTier({ planLevel, designPath })
+    if (tier.tier === 'self') {
+      console.log('ℹ️  Stage Review: execute tier=self（' + tier.reason + '），align 前置门放行（不强制独立审查）')
+    } else {
+      // 只读解析（不 generate/写 marker）：恢复场景下缺失即缺失
+      const reviewRunId = getLatestStageReviewRunId(runtimeRoot, 'execute', changeName)
+      if (!reviewRunId) {
+        return blocked(['execute stage review runId 无法定位（marker 缺失且 stage-reviews/ 无含 review 的 run 目录）'])
+      }
+      const searchDirs = [effectiveSpecBase, reviewChangeDir, cwd].filter(Boolean)
+      const reviewResult = validateStageReview({ stage: 'execute', reviewType: 'acceptance', runtimeRoot, reviewRunId, searchDirs })
+      printStageReviewResult(reviewResult, { stage: 'execute', reviewRunId, runtimeRoot })
+      if (!reviewResult.ok) return true // printStageReviewResult 已给明细，不再重复列
+    }
+  } catch (e) {
+    // fail-closed：门自身异常阻断 align（与正常 gate 一致），不静默放行
+    console.error('❌ align 前置 Stage Review 校验异常，阻断对齐: ' + e.message)
+    return true
+  }
+
+  // 2. Task Review（runId 只读解析：marker → 含 tasks/ 扫描；不 generate）
+  try {
+    const { validateTaskReviews, printReviewResult, resolveLatestExecuteRunIdWithTasks, isValidExecuteRunId } = await import('../task-review.js')
+    const planPath = reviewChangeDir ? join(reviewChangeDir, 'plan.md') : null
+    if (!planPath || !existsSync(planPath)) {
+      return blocked(['plan.md 不存在，Task Review 无从校验（align 的 checkbox 判定依赖同目录，疑似路径解析异常）'])
+    }
+    const planContent = readFileSync(planPath, 'utf8')
+    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    let executeRunId = ''
+    try {
+      if (existsSync(runIdFile)) {
+        const c = readFileSync(runIdFile, 'utf8').trim()
+        if (c && isValidExecuteRunId(c)) executeRunId = c
+      }
+    } catch {}
+    if (!executeRunId) {
+      executeRunId = resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName }) || ''
+    }
+    if (!executeRunId) {
+      return blocked(['execute runId 无法定位（marker 缺失且 execute-runs/ 无含 review 的 run 目录）——15/N 份 task review 所在 run 不可寻，无法对账'])
+    }
+    const reviewResult = validateTaskReviews({ planContent, runtimeRoot, executeRunId, changeDir: reviewChangeDir, gitDir: cwd })
+    printReviewResult(reviewResult, { runtimeRoot, executeRunId })
+    if (!reviewResult.ok) return true // 报错明细已在 printReviewResult 输出
+    console.log('✅ align 前置 review 校验通过（stage review + task review 均齐备），继续对齐')
+  } catch (e) {
+    console.error('❌ align 前置 Task Review 校验异常，阻断对齐: ' + e.message)
+    return true
+  }
+  return false
+}
+
 /**
  * execute deps 验证硬门（change 2026-06-28-worktree-deps-provision / D-001@v1, D-003@v1, D-006@v2）。
  * depsStatus 不达标且非 wave 级 opt-out 时阻断 --done：置 step=blocked + exit(1)，与 requiresWait 同范式。
@@ -178,19 +277,34 @@ export async function enforceReviewJsonGate(stageName, cwd, changeName, step, st
   const planPath = join(specBase, 'changes', changeName, 'plan.md')
   if (!existsSync(runIdFile) || !existsSync(planPath)) return true
   const { validateCheckedTaskReviews, resolveLatestExecuteRunIdWithTasks, isValidExecuteRunId } = await import('../task-review.js')
-  let executeRunId = readFileSync(runIdFile, 'utf8').trim()
+  // existsSync 与 read 之间 marker 可能被并发 cleanup/归档删除（多 agent 场景）：读失败按
+  //「marker 缺失」处理，走漂移兜底重定位，不让 ENOENT 冒成顶层 stack（与 :426-435 口径对齐）
+  let executeRunId = ''
+  try {
+    executeRunId = readFileSync(runIdFile, 'utf8').trim()
+  } catch {
+    console.warn('⚠️ execute run marker 读取失败（可能被并发清理），改扫真实 run 目录')
+    executeRunId = resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName }) || ''
+  }
   // marker 是 agent 可写内容：格式校验防注入/穿越，非法视为缺失走漂移兜底重定位
   if (executeRunId && !isValidExecuteRunId(executeRunId)) {
     console.warn(`⚠️ execute run marker 内容非法（期望 exec-YYYY-MM-DD-HHMMSS，实得 ${JSON.stringify(executeRunId.slice(0, 60))}），改扫真实 run 目录`)
     executeRunId = ''
   }
-  const planContent = readFileSync(planPath, 'utf8')
+  // 2026-08-20-task-truth-unify：已勾 task 清单源迁 tasks.md（勾选唯一落点）；tasks.md 缺失
+  // 回退 planPath 内容（旧变更兼容读侧）。planPath 存在性已在上方把关。
+  const tasksRegistryPath = join(specBase, 'changes', changeName, 'tasks.md')
+  const planContent = existsSync(tasksRegistryPath)
+    ? readFileSync(tasksRegistryPath, 'utf8')
+    : readFileSync(planPath, 'utf8')
+  // marker 读失败且重定位无果（无任何含 tasks/ 的 run）：无 run 可校验，放行（下游 Task Review Gate 兜底）
+  if (!executeRunId) return true
   // marker 漂移兜底（gate-atom-a 正确修法）：marker 指向的 run 缺 tasks/（generateExecuteRunId 只写
   // marker 不建目录，漂移后新 run 不继承旧 review）时，无视 marker 改扫 execute-runs/ 取 mtime 最新
   // 且真正含 tasks/ 的 run，用其齐备的 review.json 校验，避免误报「review.json 不存在」。注意不能用
   // resolveLatestExecuteRunId——它见 marker 非空即原样返回（不校验目录），恰是本场景要绕开的值。
   if (executeRunId && !existsSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'))) {
-    const relocated = resolveLatestExecuteRunIdWithTasks({ runtimeRoot })
+    const relocated = resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName })
     if (relocated && relocated !== executeRunId) {
       console.warn(`⚠️ execute run marker 漂移：${executeRunId} 无 tasks/，改用真实含 review 的 run ${relocated}`)
       executeRunId = relocated
@@ -331,18 +445,21 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     console.log('\n✅ 验证通过，下一步：sillyspec run archive')
   }
 
-  // ── Plan postcheck contract：plan.md 必须满足 execute 契约 ──
+  // ── Plan postcheck contract：tasks.md（注册表）× plan.md（Wave 引用）须满足 execute 契约 ──
   if (stageName === 'plan') {
     const planFile = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
     const planPath = planFile ? join(planFile, 'plan.md') : null
     if (planPath && existsSync(planPath)) {
       const { validatePlanForExecute } = await import('../stages/execute.js')
-      const planContent = readFileSync(planPath, 'utf8')
-      const planValidation = validatePlanForExecute(planContent)
+      // CRLF 归一：Windows 编辑器/python 写文件可产生 CRLF，归一后交校验（与 plan-postcheck.js 同口径）
+      const planContent = readFileSync(planPath, 'utf8').replace(/\r\n/g, '\n')
+      const tasksPath = join(planFile, 'tasks.md')
+      const tasksContent = existsSync(tasksPath) ? readFileSync(tasksPath, 'utf8').replace(/\r\n/g, '\n') : ''
+      const planValidation = validatePlanForExecute(tasksContent, planContent)
       if (!planValidation.ok) {
         console.error(`\n❌ Plan → Execute Contract 校验失败：`)
         for (const err of planValidation.errors) console.error(`   - ${err}`)
-        console.error(`\n   plan.md 不满足 execute 契约，请修复后重新完成此步骤。`)
+        console.error(`\n   tasks.md/plan.md 不满足 execute 契约，请修复后重新完成此步骤。`)
         // 阻断 completed
         return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
       }
@@ -415,7 +532,12 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       const planPath = planFile ? join(planFile, 'plan.md') : null
 
       if (planPath && existsSync(planPath)) {
-        const planContent = readFileSync(planPath, 'utf8')
+        // 2026-08-20-task-truth-unify：任务清单源迁 tasks.md（validateTaskReviews 内按
+        // checkbox 行解析，tasks.md 行格式兼容原正则）；缺失回退 plan.md（旧变更兼容读侧）
+        const tasksRegistryPath = join(planFile, 'tasks.md')
+        const planContent = existsSync(tasksRegistryPath)
+          ? readFileSync(tasksRegistryPath, 'utf8')
+          : readFileSync(planPath, 'utf8')
         const runtimeRoot = resolveRuntimeRoot(platformOpts, effectiveSpecBase)
 
         // execute run id：从变更专属标记文件读取（agent 可写内容，格式校验防注入/穿越）
@@ -436,7 +558,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           // marker 缺失：先扫描 execute-runs/ 既有目录找回真实 runId（与 getLatestStageReviewRunId
           // 目录扫描兜底同语义），避免 marker 丢失而 agent 已用旧 runId 落盘时，直接 generate 新 ID
           // 找不到旧 review、误判缺 review.json。仅当确实无既有 run 才 generate 新 ID 并落盘。
-          const { generateExecuteRunId, resolveLatestExecuteRunId } = await import('../task-review.js')
+          const { generateExecuteRunId, resolveLatestExecuteRunId, stampExecuteRunChange } = await import('../task-review.js')
           executeRunId = resolveLatestExecuteRunId({ runtimeRoot, changeName }) || ''
           if (!executeRunId) {
             executeRunId = generateExecuteRunId()
@@ -446,6 +568,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
             //（gate 自身写 run 目录失败不能静默放行完成）。
             mkdirSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'), { recursive: true })
             writeFileSync(runIdFile, executeRunId + '\n')
+            stampExecuteRunChange(runtimeRoot, executeRunId, changeName)
           }
         }
 
@@ -480,7 +603,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           // 检查是否存在 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('\n⚠️  部分任务已在 tasks.md 中勾选，但 review.json 不存在。')
             console.error(`   请取消勾选这些任务的 checkbox，或补充对应的 review.json（execute run ID: ${executeRunId}）。`)
           }
           return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)

package/src/run/prompt.js

@@ -257,7 +257,9 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       if (existsSync(sessionGuardFile)) {
         qlIdVal = JSON.parse(readFileSync(sessionGuardFile, 'utf8')).quicklogId || ''
       }
-    } catch {}
+    } catch (err) {
+      console.warn(`⚠️ quicklog-id 占位符读取 guard.json 失败: ${err && err.message ? err.message : err}`);
+    }
     promptText = promptText.replace(/<quicklog-id>/g, qlIdVal || '(未分配)')
   }
   // 替换 <linked-changes> 占位符（quick 阶段：从 .runtime/quick-sessions/<sessionId>/guard.json 读关联变更）
@@ -414,14 +416,16 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       const { matchKnowledge } = await import('../knowledge-match.js')
       const effectiveSpecBase = resolvePromptSpecBase(platformOpts, cwd)
       const knowledgeDir = join(effectiveSpecBase, 'knowledge')
-      // taskContext: changeName + plan.md task names for better matching
+      // taskContext: changeName + tasks.md 任务名（注册表唯一真相，2026-08-20-task-truth-unify）
       let taskContext = changeName || ''
       if (changeName) {
+        const tasksMdPath = join(effectiveSpecBase, 'changes', changeName, 'tasks.md')
         const planPath = join(effectiveSpecBase, 'changes', changeName, 'plan.md')
+        const srcPath = existsSync(tasksMdPath) ? tasksMdPath : planPath
         try {
-          const planContent = readFileSync(planPath, 'utf8')
-          // match both "- [ ] task-01: title" and "## task-01: title" formats
-          const taskLines = [...planContent.matchAll(/(?:^\- \[[ x]\] |^## )task-\d+[^:]*:?\s*(.+)/gm)]
+          const registryContent = readFileSync(srcPath, 'utf8')
+          // match "- [ ] task-01: title" / "## task-01: title"（兼容旧 plan.md 内联两种形态）
+          const taskLines = [...registryContent.matchAll(/(?:^\- \[[ x]\] |^## )task-\d+[^:]*:?\s*(.+)/gm)]
           if (taskLines.length > 0) {
             taskContext += ' ' + taskLines.map(t => t[1]).join(' ')
           }

package/src/run/shared.js

@@ -11,7 +11,7 @@
  *     本模块仅 re-export，run/ 层现有调用方路径与行为不变。
  */
 import { basename, join, resolve, dirname, sep } from 'node:path'
-import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import os from 'node:os'
 
@@ -336,12 +336,26 @@ export const PLATFORM_MANAGED_FILENAME = '.sillyspec-platform-managed'
 
 export function writePlatformPointer(cwd, platformOpts, extra = {}) {
   if (!platformOpts || (!platformOpts.specRoot && !platformOpts.runtimeRoot)) return false
+  // HUB-05：合并保留既有生命周期字段。scan 完成时指针被写入 status/completedAt/scanStatus
+  //（complete-handlers），但下一次任何平台模式 run（含只读 --status）都会重写指针——
+  // 恢复链只回填 specRoot 等四字段，不保留 status → 指针永远回 active、isPointerStale
+  // 恒 false、`platform pointer --cleanup` 的 STALE 分支不可达。extra 显式传值仍可覆盖。
+  let preserved = {}
+  try {
+    const existing = JSON.parse(readFileSync(join(cwd, '.sillyspec-platform.json'), 'utf8'))
+    if (existing && typeof existing === 'object') {
+      for (const k of ['status', 'completedAt', 'scanStatus']) {
+        if (existing[k] !== undefined && extra[k] === undefined) preserved[k] = existing[k]
+      }
+    }
+  } catch { /* 无既有指针/损坏 → 全新写入 */ }
   const payload = {
     specRoot: platformOpts.specRoot || null,
     runtimeRoot: platformOpts.runtimeRoot || null,
     workspaceId: platformOpts.workspaceId || null,
     scanRunId: platformOpts.scanRunId || null,
     savedAt: new Date().toISOString(),
+    ...preserved,
     ...extra,
   }
   // 声明文件字段集独立于指针 payload（D-E@v2 四字段：无 status/savedAt/scanRunId——
@@ -415,54 +429,90 @@ export function resolveChangeDir(cwd, progress, specDir = null) {
 // sync 总超时熔断：sync.js 是 best-effort 后台回传（每请求已有 10s 超时），但 sync() 可能串行多次
 // fetchJson 累积等待、阻塞 --done。给 8s 总超时，超时放弃（best-effort，失败不影响正确性，下次 --done 重试）。
 // 历史痛点：--done 在 sync 慢时体感 hang，用户被迫用外部 timeout 兜底。
+// HUB-09：熔断超时时必须 abort 底层在飞请求（opts.signal 一路传到 fetch）——否则熔断后请求
+// 仍在跑，平台可能已接受推送而客户端当作超时放弃（spec 树推送无 base_ts 自愈兜底）。
 const SYNC_TOTAL_TIMEOUT_MS = 8_000
 
+/**
+ * 熔断 race + 确定性取消：超时触发 controller.abort() 并 resolve，在飞 fetch 收到
+ * AbortError 后自然失败（各调用方 catch 返回降级值，进程不挂起）。
+ * @param {() => Promise} op 接收 { signal } 的异步操作
+ * @param {number} timeoutMs 熔断时长（测试可缩短）
+ */
+async function raceWithAbort(op, timeoutMs = SYNC_TOTAL_TIMEOUT_MS) {
+  const controller = new AbortController()
+  let timer
+  try {
+    await Promise.race([
+      op({ signal: controller.signal }),
+      new Promise((resolve) => { timer = setTimeout(() => { controller.abort(); resolve(null) }, timeoutMs) }),
+    ])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 // quick 会话 ID 形态（quick-<hex8>）。与 run/command.js QUICK_SID_RE、progress.js
 // initChange 的跳过实体目录判断同源；shared.js 不反向 import command.js（重模块），
 // 局部复制正则保持轻载——改形态时三处同改。
 const QUICK_SID_RE = /^quick-[0-9a-f]{8}$/
 
-export async function triggerSync(cwd, changeName, platformOpts = {}) {
+export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {}) {
   // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
   try {
-    if (changeName && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) {
-      // ql-20260818-011：quick 会话按设计无实体变更目录（progress.js initChange 同款
-      // 跳过建目录），progress/四件套上行对它是孤儿数据；但 spec 树增量（QUICKLOG/
-      // 模块文档的上行通道）以服务器清单为锚，与变更目录无关——降级只推 spec 树。
-      // 其余形态（真实变更名拼错）维持静默 return，防噪音混入 spec 树通道。
-      if (QUICK_SID_RE.test(changeName)) {
-        // shared.js 在 src/run/，sync.js 在 src/ → 退一层
-        const syncMod = await import('../sync.js')
-        let timer
-        try {
-          await Promise.race([
-            syncMod.syncSpecTreeOnly(changeName, cwd),
-            new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
-          ])
-        } finally {
-          clearTimeout(timer)
-        }
-      }
+    // ql-20260818-011：quick 会话按设计无实体变更目录（progress.js initChange 同款
+    // 跳过建目录），progress/四件套上行对它是孤儿数据；但 spec 树增量（QUICKLOG/
+    // 模块文档的上行通道）以服务器清单为锚，与变更目录无关——降级只推 spec 树。
+    if (changeName && QUICK_SID_RE.test(changeName) && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) {
+      // shared.js 在 src/run/，sync.js 在 src/ → 退一层
+      const syncMod = await import('../sync.js')
+      await raceWithAbort((sig) => syncMod.syncSpecTreeOnly(changeName, cwd, sig), opts.timeoutMs)
       return
     }
+    // 目录缺失的非 quick 变更不再静默 return（archive-final-state-sync）：归档把
+    // changes/<name>/ 移到 changes/archive/<name>/ 并注销 DB 行后，第 4/5 步收尾的
+    // triggerSync 仍会触发——DB 里的终态（steps 完成态 + status='archived'）与文件树
+    // 移动必须推平台，否则平台进度永远停在移动前的最后一步。sync() 内部对目录缺失
+    // 本就是 warn-and-continue（serializeForSync 从 DB 读不依赖目录）；真实拼错名时
+    // 无 DB 行，sync() 在发出任何 HTTP 前即 return，仅多一行 warn（未连接平台则完全静默）。
     // shared.js 在 src/run/，sync.js 在 src/ → 退一层
     const syncMod = await import('../sync.js')
-    let timer
-    try {
-      await Promise.race([
-        syncMod.sync(changeName, cwd),
-        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
-      ])
-    } finally {
-      clearTimeout(timer) // sync 先完成则清掉未触发的 timer，避免泄漏
-    }
+    await raceWithAbort((sig) => syncMod.sync(changeName, cwd, sig), opts.timeoutMs)
   } catch (e) {
     // sync.js 不存在或同步失败，静默跳过
     console.warn('⚠️ 同步失败:', e.message)
   }
 }
 
+/**
+ * 自动 pull 节流（体检 PERF-02）：triggerPull/triggerPullActiveChange 在每条 stage 命令
+ * 启动时注入，agent 命令往往是秒级连发——每次都发 HTTP GET（daemon 挂/慢时单命令最多
+ * 阻塞 8s）。跨进程 marker 节流：10s 内已有自动 pull 则跳过（手动 `platform pull` 不走
+ * 此门，语义不变）。错过窗口的平台更新由下一条 >10s 的命令或 push 409 自愈兜底。
+ */
+const AUTO_PULL_THROTTLE_MS = 10_000
+
+function _autoPullThrottlePath(cwd) {
+  return join(cwd, '.sillyspec', '.runtime', 'auto-pull-throttle.json')
+}
+
+function _autoPullRecently(cwd) {
+  try {
+    const t = JSON.parse(readFileSync(_autoPullThrottlePath(cwd), 'utf8'))
+    return typeof t.at === 'number' && Date.now() - t.at < AUTO_PULL_THROTTLE_MS
+  } catch {
+    return false
+  }
+}
+
+function _stampAutoPull(cwd) {
+  try {
+    mkdirSync(dirname(_autoPullThrottlePath(cwd)), { recursive: true })
+    writeFileSync(_autoPullThrottlePath(cwd), JSON.stringify({ at: Date.now() }) + '\n', 'utf8')
+  } catch { /* best-effort：节流失效仅退化为逐次 pull */ }
+}
+
 /**
  * 触发 pull（下行同步，task-10 / D-009 / FR-04 / FR-06）。
  * 复用 triggerSync 的 8s 熔断与 Best Effort 语义；未连接平台静默跳过（与现状一致）。
@@ -474,23 +524,18 @@ export async function triggerSync(cwd, changeName, platformOpts = {}) {
  * @param {string} changeName - 当前活跃变更（多变更时传 null 跳过，避免误拉）
  * @param {object} [platformOpts] - 平台模式 opts（specRoot/runtimeRoot 存在则跳过，走平台自有链路）
  */
-export async function triggerPull(cwd, changeName, platformOpts = {}) {
+export async function triggerPull(cwd, changeName, platformOpts = {}, opts = {}) {
   // 平台模式（SillyHub）走自己的链路，跳过
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
   try {
     const syncMod = await import('../sync.js')
     const sm = new syncMod.SyncManager(cwd)
-    // 未连接平台静默跳过（本地独立用户合法状态，不噪音）
+    // 未连接平台静默跳过（本地独立用户合法状态，不噪音）——节流 stamp 必须在此之后：
+    // 否则未连接的项目每次 run 都写 .sillyspec/.runtime/ 标记（凭空造目录）
     if (!sm._getPlatform()) return
-    let timer
-    try {
-      await Promise.race([
-        sm.pull(changeName, { skipIfLocalDirty: true }),
-        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
-      ])
-    } finally {
-      clearTimeout(timer)
-    }
+    if (_autoPullRecently(cwd)) return
+    _stampAutoPull(cwd)
+    await raceWithAbort((sig) => sm.pull(changeName, { skipIfLocalDirty: true, signal: sig.signal }), opts.timeoutMs)
   } catch (e) {
     // pull 失败静默跳过（Best Effort，失败不影响正确性）
     console.warn('⚠️ 拉取失败:', e.message)
@@ -513,6 +558,10 @@ export async function triggerPullActiveChange(cwd, platformOpts = {}) {
   } catch {
     return
   }
+  // PERF-02 节流（连接确认后才 stamp——未连接项目不得凭空写 .sillyspec/.runtime/）：
+  // 与 triggerPull 共用同一 marker（本函数与它在同一命令启动链上互斥出现）
+  if (_autoPullRecently(cwd)) return
+  _stampAutoPull(cwd)
   let cn = null
   try {
     const { ProgressManager } = await import('../progress.js')
@@ -523,29 +572,48 @@ export async function triggerPullActiveChange(cwd, platformOpts = {}) {
     // progress 不可达则跳过（Best Effort）
   }
   if (!cn) return
-  // 已确认连接 + 单活跃变更，调 pull（复用 triggerPull 的 8s 熔断；skipIfLocalDirty 保守守卫
+  // 已确认连接 + 单活跃变更，调 pull（复用 8s 熔断 + abort（HUB-09）；skipIfLocalDirty 保守守卫
   // 同 triggerPull——本地脏时跳过 import，防平台旧快照覆盖本地领先进度，ql-20260818-008）
   try {
-    let timer
-    try {
-      await Promise.race([
-        sm.pull(cn, { skipIfLocalDirty: true }),
-        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
-      ])
-    } finally {
-      clearTimeout(timer)
-    }
+    await raceWithAbort((sig) => sm.pull(cn, { skipIfLocalDirty: true, signal: sig.signal }))
   } catch (e) {
     console.warn('⚠️ 拉取失败:', e.message)
   }
 }
 
+/**
+ * 审批状态 unknown（体检 HUB-07）的统一处置：醒目多行警告 + 落 .runtime/approval-unknown.log 留痕。
+ *
+ * 语义边界：unknown = 已连接平台但 404/断网/超时/非 JSON——**不是审批通过**。放行是
+ * fail-open 的既定取舍（网络故障不应硬阻断每一条 execute），但静默放行会让团队审批
+ * 形同虚设且无迹可查；至少要（a）让操作者当场看见（b）留下可审计记录。
+ * 留痕选 .runtime 日志而非 QUICKLOG：QUICKLOG 是 quick 会话的任务记录，run 流程的
+ * 审批事件写进去会污染 quick 语义与边界审计。
+ * @param {string} cwd
+ * @param {string} changeName
+ * @param {string} reason checkApproval 返回的 reason
+ */
+export function warnApprovalUnknown(cwd, changeName, reason) {
+  console.warn('')
+  console.warn('⚠️⚠️⚠️══════════════════════════════════════════════')
+  console.warn(`⚠️ 审批状态未知：变更「${changeName}」无法核实审批（${reason || '请求失败'}）`)
+  console.warn('⚠️ 本次 execute 按 fail-open 放行——这不是审批通过；平台恢复后请到平台复核审批记录')
+  console.warn('⚠️ 排查：平台服务是否可达（sillyspec platform status）/ 网络代理；确认无需审批可 --skip-approval 显式跳过')
+  console.warn('⚠️ 本次放行已记录：.sillyspec/.runtime/approval-unknown.log')
+  console.warn('⚠️⚠️══════════════════════════════════════════════')
+  try {
+    const logDir = join(cwd, '.sillyspec', '.runtime')
+    mkdirSync(logDir, { recursive: true })
+    appendFileSync(join(logDir, 'approval-unknown.log'),
+      `${new Date().toISOString()} | change=${changeName} | reason=${reason || 'unknown'}\n`, 'utf8')
+  } catch { /* 留痕失败不阻断流程（警告横幅已输出） */ }
+}
+
 /**
  * 审批检查：execute 阶段启动前检查（W6 Step8a 从 run.js 搬入，runStage + runAutoMode 共用）。
  * 平台模式走自己的链路，跳过；否则 await import sync.js。
  * @returns {{ status: string, reason?: string } | null}
- */
-export async function checkApproval(cwd, changeName, platformOpts = {}) {
+ */export async function checkApproval(cwd, changeName, platformOpts = {}) {
   // 平台模式不需要 CLI 内置审批检查
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return null
   try {
@@ -774,7 +842,11 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     ]
 
     for (const entry of currentEntries) {
-      const status = entry.slice(0, 2).trim()
+      // porcelain 两字符状态码（X=暂存区 Y=工作区）不能先 trim：' D'.trim()==='D' 使第二分支恒假、
+      // 'DD'/'AD' 等 trim 后不等于 'D' 而漏检——--allow-delete 门对此类删除静默放行（体检 BUG-04）。
+      // 用原始两字符判定任一侧为 D 即删除。
+      const rawStatus = entry.slice(0, 2)
+      const status = rawStatus.trim()
       const file = parsePorcelainPath(entry)   // 已去引号/处理 rename/归一化，修正首行丢首字符
       if (!file) continue
 
@@ -786,7 +858,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       if (isBaselineFile(file)) continue
 
       result.changedFiles.push(file)
-      if (status === 'D' || status === ' D') result.deletedFiles.push(file)
+      if (rawStatus[0] === 'D' || rawStatus[1] === 'D') result.deletedFiles.push(file)
       if (status === '??') result.newFiles.push(file)
 
       // 检查是否命中 baseline protected files
@@ -885,8 +957,12 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     const mdChanged = result.changedFiles.filter((f) => f.endsWith('.md') && !deletedSet.has(f) && !isQuickMetadata(f, guard.linkedChanges))
     if (mdChanged.length > 0) {
       try {
-        const { runDocsCheck } = await import('../docs-check.js')
-        const dc = runDocsCheck({ projectRoot: cwd, docs: mdChanged })
+        const { runDocsCheck, readDocsCheckConfig } = await import('../docs-check.js')
+        // HUB-06：补传 crossRepoRoots（与 docs gate / index.js docs check 同口径）——
+        // 否则 repo:// 跨仓引用在这条链路恒跳过；无 local.yaml 配置时 undefined = 不启用
+        let quickCfg = {}
+        try { quickCfg = readDocsCheckConfig(cwd) || {} } catch { quickCfg = {} }
+        const dc = runDocsCheck({ projectRoot: cwd, docs: mdChanged, crossRepoRoots: quickCfg.crossRepoRoots })
         if (!dc.ok) {
           result.reasons.push(`本次改动文档含 ${dc.invalid.length} 处失效 file:line 引用（sillyspec docs check 可复现）`)
           result.docsCheckHint = { invalid: dc.invalid.length, total: dc.total }
@@ -906,7 +982,11 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     const srcChangedFiles = result.changedFiles.filter((f) => f.startsWith('src/') && !deletedSet.has(f))
     if (srcChangedFiles.length > 0) {
       try {
-        const { collectDocRefs, runDocsCheck } = await import('../docs-check.js')
+        const { collectDocRefs, runDocsCheck, readDocsCheckConfig } = await import('../docs-check.js')
+        // HUB-06：活文档（platform-interface-map.md 等最可能写 repo:// 引用的文档）同样补传
+        // crossRepoRoots；配置读一次提到循环外（per-cwd 恒同）
+        let livingCfg = {}
+        try { livingCfg = readDocsCheckConfig(cwd) || {} } catch { livingCfg = {} }
         const livingDocs = await resolveLivingDocs(cwd)
         const files = []
         const docs = []
@@ -918,7 +998,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
           if (hit.length === 0) continue
           files.push(...hit)
           docs.push(docRel)
-          const r = runDocsCheck({ projectRoot: cwd, docs: [docRel], keywordAssert: true })
+          const r = runDocsCheck({ projectRoot: cwd, docs: [docRel], keywordAssert: true, crossRepoRoots: livingCfg.crossRepoRoots })
           for (const x of r.invalid) invalidAll.push({ ...x, doc: docRel })
         }
         const invalid = matchInvalidRefsToChanged(invalidAll, srcChangedFiles)