sillyspec 3.23.8 → 3.24.0

package/src/run.js

@@ -9,8 +9,28 @@ import { existsSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, read
 import { randomBytes, randomUUID } from 'crypto'
 import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
+import { fileURLToPath } from 'url'
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * 解析 prompt 中的 {{include: <name>}} 占位符：读包内 templates/prompts/<name>.md 注入。
+ * 把 stage step prompt 里 self-contained 的大块（如 verify 探针）抽到外部模板，
+ * CLI 端组装时注入——agent 收到的仍是自包含 prompt 字符串，无需自己 Read。
+ * 单次替换（不递归）；模板缺失则保留占位符并 warn，便于发现配置错误。
+ */
+function resolvePromptIncludes(text) {
+  return text.replace(/\{\{include:\s*([\w.-]+)\s*\}\}/g, (match, name) => {
+    const tplPath = join(__dirname, '..', 'templates', 'prompts', `${name}.md`)
+    if (!existsSync(tplPath)) {
+      console.warn(`⚠️ prompt include 模板缺失: ${name} (期望: ${tplPath})`)
+      return match
+    }
+    return readFileSync(tplPath, 'utf8')
+  })
+}
 import { ProgressManager } from './progress.js'
 import { SCAN_STATUS, POINTER_STATUS, isPointerCorrupted } from './constants.js'
+import { allocateQuicklogEntry, completeQuicklogEntry, findQuicklogEntry, validateQuickResult } from './quicklog.js'
 import { checkbox } from '@inquirer/prompts'
 
 /**
@@ -158,7 +178,7 @@ function resolveSpecDir(cwd, opts = {}) {
   return join(resolve(cwd), '.sillyspec')
 }
 import { stageRegistry, auxiliaryStages } from './stages/index.js'
-import { checkTransition, runValidators } from './stage-contract.js'
+import { checkTransition, runValidators, validateChangeExists } from './stage-contract.js'
 import { buildExecuteSteps } from './stages/execute.js'
 import { buildPlanSteps } from './stages/plan.js'
 import { formatExecuteSummary } from './worktree-apply.js'
@@ -676,7 +696,8 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     console.log(`changeDir: ${changeDir}`)
   }
   console.log(`---\n`)
-  if (personas[stageName]) {
+  // persona 只在 stage 首步注入（step0）——角色设定一次即可，后续 step 重复注入纯属 token 浪费
+  if (personas[stageName] && stepIndex === 0) {
     console.log(personas[stageName])
     console.log('')
   }
@@ -689,7 +710,9 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     console.log(guardrails.trim())
     console.log('')
   }
-  let promptText = step.prompt
+  // 先解析 {{include: name}}（把外部模板片段拉进 prompt），再做下方占位符替换，
+  // 保证模板内容里的 {SPEC_ROOT}/<change-name> 等也能被替换
+  let promptText = resolvePromptIncludes(step.prompt)
   // 替换 prompt 中的占位符
   if (projectName && promptText.includes('<project>')) {
     promptText = promptText.replace(/<project>/g, projectName)
@@ -721,6 +744,19 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   if (changeName && promptText.includes('<quick-session-id>')) {
     promptText = promptText.replace(/<quick-session-id>/g, changeName)
   }
+  // 替换 <quicklog-id> 占位符（quick 阶段：从 session guard.json 读 CLI 分配的 ql-ID，
+  // 供 agent 在模块文档变更索引等处引用）
+  if (promptText.includes('<quicklog-id>')) {
+    const specBaseQl = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    let qlIdVal = ''
+    try {
+      const sessionGuardFile = join(specBaseQl, '.runtime', 'quick-sessions', changeName, 'guard.json')
+      if (existsSync(sessionGuardFile)) {
+        qlIdVal = JSON.parse(readFileSync(sessionGuardFile, 'utf8')).quicklogId || ''
+      }
+    } catch {}
+    promptText = promptText.replace(/<quicklog-id>/g, qlIdVal || '(未分配)')
+  }
   // 替换 <linked-changes> 占位符（quick 阶段：从 .runtime/quick-sessions/<sessionId>/guard.json 读关联变更）
   if (promptText.includes('<linked-changes>')) {
     const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
@@ -1553,6 +1589,18 @@ export async function runCommand(args, cwd, specDir = null) {
     process.exit(1)
   }
 
+  // --change 变更名存在性校验（治 cwd 漂移误匹配，缺陷 execute-in-place-windows-pitfalls 坑5）：
+  // 必须在 pm.read/initChange 之前——initChange 会为 --change 指定的新名字创建 changes/ 目录，
+  // 校验若在其后则目录已存在、永远通过。用原始 changeName（--change 参数），覆盖 plan/execute/
+  // verify/archive；quick-<8hex> sessionId 与 brainstorm 新建豁免（见 validateChangeExists）。
+  const changeMissing = validateChangeExists(specBase, stageName, changeName)
+  if (changeMissing) {
+    console.error(`❌ ${changeMissing.message}`)
+    console.error(`   可能 cwd 漂移——当前 cwd=${cwd}，命中的 spec=${specBase}。`)
+    console.error(`   若意图操作别的项目，请 cd 到对应项目根，或用 --spec-dir 指定正确的 spec 目录。`)
+    process.exit(1)
+  }
+
   let progress = await pm.read(cwd, changeName)
 
   if (!progress) {
@@ -1740,7 +1788,7 @@ export async function runCommand(args, cwd, specDir = null) {
   }
 
   // 默认：输出当前步骤
-  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline, isForceRescan, linkedChanges })
+  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline, isForceRescan, linkedChanges, taskDescription: inputText })
 }
 
 /**
@@ -2000,45 +2048,67 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
     console.log(`🔄 ${stageName} 阶段已自动重置，重新开始。\n`)
   }
 
-  // quick 阶段：记录 baselineFiles
-  if (stageName === 'quick' && !progress.quickGuard) {
+  // quick 阶段：记录 baselineFiles + 分配 ql-ID（CLI 接管 QUICKLOG 写入）
+  // 幂等判据是 session guard.json 文件（跨进程可靠），不是 progress.quickGuard
+  // （D-003@v1：顶层 quickGuard 不跨进程持久化；agent 在 step 间用 `run quick` 取下一步
+  // prompt 时每个新进程都进此块，按文件判幂等才不会重复分配 ql-ID / 重复写条目）。
+  if (stageName === 'quick') {
+    const sessionGuardDir = join(specBase, '.runtime', 'quick-sessions', changeName)
+    const guardFile = join(sessionGuardDir, 'guard.json')
+    let existingGuard = null
     try {
-      const { execSync } = await import('child_process')
-      const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
-      // 记录全部预存脏文件（含 untracked + .sillyspec/ 路径）。quick 会话期间自身写入的元数据
-      // （quicklog/.runtime/modules/_module-map 等）由 auditQuickCompletion 的 isQuickMetadata 精确豁免，
-      // 不需要这里粗放过滤 .sillyspec/——旧过滤致预存 untracked .sillyspec/changes/ 不进 baseline，
-      // 却在 audit 被当「危险(.sillyspec/)+新增」误判永久 blocked（ql-20260713-002-7628 修复）。
-      const baselineFiles = gitStatus
-        .trim().split('\n').filter(Boolean)
-        .map(line => line.slice(3).trim())
-      const allowedFiles = quickOpts?.quickFiles || []
-      const allowNew = quickOpts?.isAllowNew || false
-      const forceBaseline = quickOpts?.isForceBaseline || false
-      progress.quickGuard = {
-        sessionId: changeName,
-        name_zh: '快速任务守卫',
-        baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
-        baselineFiles,
-        allowedFiles,
-        allowNew,
-        forceBaseline,
-        linkedChanges: Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : [],
-        startedAt: new Date().toISOString(),
+      if (existsSync(guardFile)) existingGuard = JSON.parse(readFileSync(guardFile, 'utf8'))
+    } catch {}
+    if (existingGuard) {
+      // 跨进程重入：复用已分配的 ql-ID，跳过 baseline 重捕与分配（幂等）
+      progress.quickGuard = existingGuard
+    } else {
+      try {
+        const { execSync } = await import('child_process')
+        const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
+        // 记录全部预存脏文件（含 untracked + .sillyspec/ 路径）。quick 会话期间自身写入的元数据
+        // （quicklog/.runtime/modules/_module-map 等）由 auditQuickCompletion 的 isQuickMetadata 精确豁免，
+        // 不需要这里粗放过滤 .sillyspec/——旧过滤致预存 untracked .sillyspec/changes/ 不进 baseline，
+        // 却在 audit 被当「危险(.sillyspec/)+新增」误判永久 blocked（ql-20260713-002-7628 修复）。
+        const baselineFiles = gitStatus
+          .trim().split('\n').filter(Boolean)
+          .map(line => line.slice(3).trim())
+        const allowedFiles = quickOpts?.quickFiles || []
+        const allowNew = quickOpts?.isAllowNew || false
+        const forceBaseline = quickOpts?.isForceBaseline || false
+        const linkedChanges = Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : []
+        // CLI 接管：分配 ql-ID + 写 QUICKLOG「进行中」条目 + 关联 tasks.md（持锁、当天唯一）
+        const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
+        const { qlId } = await allocateQuicklogEntry(specBase, gitUser, {
+          description: quickOpts?.taskDescription || '',
+          linkedChanges,
+          allowedFiles,
+        })
+        progress.quickGuard = {
+          sessionId: changeName,
+          name_zh: '快速任务守卫',
+          baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
+          baselineFiles,
+          allowedFiles,
+          allowNew,
+          forceBaseline,
+          linkedChanges,
+          quicklogId: qlId,
+          startedAt: new Date().toISOString(),
+        }
+        // 写入 .runtime/quick-sessions/<sessionId>/guard.json 供 worktree-guard hook 读取
+        // （D-002：按 session 存，多会话各自 guard 不互覆盖。runStage 作用域内 sessionId == changeName == quick-<uuid8>，见 §4.4/4.5）
+        mkdirSync(sessionGuardDir, { recursive: true })
+        writeFileSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
+        const parts = [`${baselineFiles.length} 个已有脏文件`]
+        if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
+        if (allowNew) parts.push('允许新增文件')
+        console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
+        console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
+        await pm._write(cwd, progress, changeName)
+      } catch (e) {
+        console.warn(`⚠️ baseline 记录失败: ${e.message}`)
       }
-      // 写入 .runtime/quick-sessions/<sessionId>/guard.json 供 worktree-guard hook 读取
-      // （D-002：按 session 存，多会话各自 guard 不互覆盖。runStage 作用域内 sessionId == changeName == quick-<uuid8>，见 §4.4/4.5）
-      const sessionGuardDir = join(specBase, '.runtime', 'quick-sessions', changeName)
-      mkdirSync(sessionGuardDir, { recursive: true })
-      const guardFile = join(sessionGuardDir, 'guard.json')
-      writeFileSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
-      const parts = [`${baselineFiles.length} 个已有脏文件`]
-      if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
-      if (allowNew) parts.push('允许新增文件')
-      console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
-      await pm._write(cwd, progress, changeName)
-    } catch (e) {
-      console.warn(`⚠️ baseline 记录失败: ${e.message}`)
     }
   }
 
@@ -3011,61 +3081,118 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       if (steps[wsIdx].waitReason) console.log(`   原因：${steps[wsIdx].waitReason}`)
       return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
     }
-    // quick 阶段完成前强制检查 quicklog 是否创建
+    // quick 收尾：强校验 QUICKLOG 条目 + 翻状态 + 勾 tasks.md（CLI 接管）
     if (stageName === 'quick') {
-      const quicklogDir = join(specBase, 'quicklog')
-      const hasQuicklog = existsSync(quicklogDir) && readdirSync(quicklogDir).some(f => f.endsWith('.md') && f.startsWith('QUICKLOG'))
-      if (!hasQuicklog) {
-        console.error(`\n❌ quick 阶段完成校验失败：未检测到 QUICKLOG 记录文件。`)
-        console.error(`   step 2 要求创建 quicklog 记录，但文件不存在。`) 
-        console.error(`   请先创建 quicklog 记录再 --done。`)
-        return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
-      }
-      // §4.6 quick 收尾：从 session guard.json 读 guard（不依赖 progress.quickGuard）。
+      // §4.6 从 session guard.json 读 guard（不依赖 progress.quickGuard）。
       // D-003@v1：progress._write 不持久化顶层 quickGuard，跨进程 --done 时读出的 progress 无 quickGuard，
       // 若仍用 if (progress.quickGuard) 驱动收尾会整体跳过，导致 .runtime/quick-sessions/<sessionId>/ 残留僵尸。
       // 改为从文件读 guard：优先 session 目录 guard.json，回退旧单文件 quick-guard.json（task-03 前兼容）。
       // sessionId == changeName == quick-<uuid8>（completeStep 作用域内 changeName 已解构自 options）。
-      {
-        const runtimeBase = platformOpts.runtimeRoot || join(specBase, '.runtime')
-        const sessionGuardFile = join(runtimeBase, 'quick-sessions', changeName, 'guard.json')
-        const legacyGuardFile = join(specBase, '.runtime', 'quick-guard.json')
-        let guard = null
-        try {
-          guard = existsSync(sessionGuardFile)
-            ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
-            : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
-        } catch {}
-        if (guard) {
-          // --done 的 --force-baseline/--allow-new 并入 guard（与 step1 持久化值取或）。
-          // 修复 ql-20260713-002-7628：旧代码解析了这两个 flag 但只传 {isConfirm} 给审计，
-          // 致 --done --force-baseline 静默无效、用户被误导「重跑 --confirm」也无法解锁。
-          const mergedGuard = {
-            ...guard,
-            forceBaseline: guard.forceBaseline || isForceBaseline,
-            allowNew: guard.allowNew || isAllowNew,
-          }
-          const review = await auditQuickCompletion(cwd, mergedGuard, { isConfirm: confirm })
-          printQuickAuditReview(review)
-          if (review.status === 'blocked') {
-            steps[currentIdx].status = 'pending'
-            steps[currentIdx].completedAt = null
-            if (outputText) steps[currentIdx].output = null
-            process.exit(1)
-          }
-          progress.lastQuickReview = review
+      const runtimeBase = platformOpts.runtimeRoot || join(specBase, '.runtime')
+      const sessionGuardFile = join(runtimeBase, 'quick-sessions', changeName, 'guard.json')
+      const legacyGuardFile = join(specBase, '.runtime', 'quick-guard.json')
+      let guard = null
+      try {
+        guard = existsSync(sessionGuardFile)
+          ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
+          : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
+      } catch {}
+
+      // 强校验 / 收尾：本会话必须有一条真实 QUICKLOG 条目（治「报 SAFE 但漏写」bug）。
+      // guard 缺失（brownfield：新代码前启动的会话）不阻断——兜底补写一条记录，保住「完成必有记录」不变量。
+      const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
+      let qlId = guard?.quicklogId || null
+      const linkedChanges = Array.isArray(guard?.linkedChanges) ? guard.linkedChanges : []
+
+      // 审计：仅在有 guard 时跑（brownfield 无 guard 跳过，兼容 D-003 brownfield 行为）。
+      if (guard) {
+        // --done 的 --force-baseline/--allow-new 并入 guard（与 step1 持久化值取或）。
+        // 修复 ql-20260713-002-7628：旧代码解析了这两个 flag 但只传 {isConfirm} 给审计，
+        // 致 --done --force-baseline 静默无效、用户被误导「重跑 --confirm」也无法解锁。
+        const mergedGuard = {
+          ...guard,
+          forceBaseline: guard.forceBaseline || isForceBaseline,
+          allowNew: guard.allowNew || isAllowNew,
+        }
+        const review = await auditQuickCompletion(cwd, mergedGuard, { isConfirm: confirm })
+        printQuickAuditReview(review)
+        if (review.status === 'blocked') {
+          steps[currentIdx].status = 'pending'
+          steps[currentIdx].completedAt = null
+          if (outputText) steps[currentIdx].output = null
+          process.exit(1)
         }
-        // 清理：guard 命中与缺失两种情况都执行（guard 缺失 → 跳过审计，仅清理不抛错）。
-        // rmSync {recursive,force} / unlinkSync 都容忍文件不存在（brownfield）。
+        progress.lastQuickReview = review
+      }
+
+      // 结果摘要结构校验（最后一步、isDone 且带了 --output 时）：--output 是 QUICKLOG「结果：」
+      // 归档的唯一来源，要求按 需求/根因/方案/结果 模板给全（见 stages/quick.js step3 prompt）。
+      // 确定性校验：只查必填字段是否齐全，不判内容质量。缺字段 → 本次不完成（回滚 step 状态 +
+      // exit 1），保留「进行中」条目，agent 补全 --output 后重跑 --done 即可，不丢进度。
+      // 仅 completeQuicklogEntry 会实际持久化时才校验；前两个 step 的 --done output 不入 QUICKLOG，不校验。
+      if (outputText) {
+        const resultCheck = validateQuickResult(outputText)
+        if (!resultCheck.ok) {
+          console.error(`\n❌ quick 结果摘要结构不完整：缺少字段 ${resultCheck.missing.join('、')}`)
+          console.error(`   --output 会写入 QUICKLOG「结果：」，请按模板补全再重跑 --done：`)
+          console.error(`     需求：用户/任务要什么`)
+          console.error(`     根因：为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）`)
+          console.error(`     方案：怎么改的`)
+          console.error(`     结果：验证情况（测试数 / lint / typecheck / 部署状态）`)
+          steps[currentIdx].status = 'pending'
+          steps[currentIdx].completedAt = null
+          if (outputText) steps[currentIdx].output = null
+          process.exit(1)
+        }
+      }
+
+      if (!qlId) {
+        // 无 ql-ID（guard 缺失或 brownfield 无 quicklogId）：补分配后立即完成，不阻断。
         try {
-          const { unlinkSync } = await import('fs')
-          if (changeName) {
-            const sessionDir = join(runtimeBase, 'quick-sessions', changeName)
-            rmSync(sessionDir, { recursive: true, force: true })
-          }
-          if (existsSync(legacyGuardFile)) unlinkSync(legacyGuardFile)
-        } catch {}
+          const alloc = await allocateQuicklogEntry(specBase, gitUser, {
+            description: guard?.taskDescription || '(补分配)',
+            linkedChanges,
+            allowedFiles: Array.isArray(guard?.allowedFiles) ? guard.allowedFiles : [],
+          })
+          qlId = alloc.qlId
+          console.log(`📝 QUICKLOG 兜底补写: ${qlId}（guard 缺失/brownfield 会话）`)
+        } catch (e) {
+          console.error(`\n❌ QUICKLOG 补分配失败: ${e.message}`)
+          steps[currentIdx].status = 'pending'
+          steps[currentIdx].completedAt = null
+          if (outputText) steps[currentIdx].output = null
+          process.exit(1)
+        }
+      }
+      if (!findQuicklogEntry(specBase, gitUser, qlId)) {
+        console.error(`\n❌ quick 阶段完成校验失败：QUICKLOG 条目 ${qlId} 不存在。`)
+        console.error(`   会话期间记录被删除或从未写入。请检查 .sillyspec/quicklog/ 后重跑 --done。`)
+        steps[currentIdx].status = 'pending'
+        steps[currentIdx].completedAt = null
+        if (outputText) steps[currentIdx].output = null
+        process.exit(1)
+      }
+      // 翻状态进行中→已完成 + 追加结果 + 勾选关联 tasks.md
+      // resultText 不再截断：结构化结果块（需求/根因/方案/结果）完整落盘，多行写成字段化块。
+      try {
+        await completeQuicklogEntry(specBase, gitUser, qlId, {
+          resultText: outputText || '',
+          linkedChanges,
+        })
+        console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)
+      } catch (e) {
+        console.warn(`⚠️ QUICKLOG 完成态写入失败: ${e.message}`)
       }
+
+      // 清理 session 目录（rmSync/unlinkSync 容忍不存在）。
+      try {
+        const { unlinkSync } = await import('fs')
+        if (changeName) {
+          const sessionDir = join(runtimeBase, 'quick-sessions', changeName)
+          rmSync(sessionDir, { recursive: true, force: true })
+        }
+        if (existsSync(legacyGuardFile)) unlinkSync(legacyGuardFile)
+      } catch {}
     }
 
     stageData.status = 'completed'

package/src/stage-contract.js

@@ -33,6 +33,36 @@ function resolveChangeDir(cwd, changeName, specRoot = null) {
   return join(changesRoot, changeName)
 }
 
+/**
+ * --change 变更名存在性校验（治 cwd 漂移误匹配，缺陷 execute-in-place-windows-pitfalls 坑5）。
+ *
+ * 多项目 monorepo 下，cwd 在子项目目录会让 resolveSpecDir 命中子项目 spec，
+ * 此时 --change 传根项目变更名，旧逻辑（resolveChangeDir 纯拼路径）不报错而静默
+ * fallback 误启动子项目流程。本校验对「操作已有变更」的阶段强制 changes/<changeName>
+ * 存在，不存在则 fail-fast，把 cwd 漂移暴露给用户。
+ *
+ * 豁免：
+ *   - 非 plan/execute/verify/archive 阶段（scan/brainstorm/quick/explore 不校验：
+ *     brainstorm 可新建变更、quick 用 sessionId、scan/explore 无 change 语义）
+ *   - quick-<8hex> sessionId（quick 会话 changeName 是 sessionId，不在 changes/）
+ *
+ * @param {string} specBase - 规范根目录（.sillyspec 或平台 specRoot）
+ * @param {string} stageName - 阶段名
+ * @param {string} changeName - 变更名（--change 或 auto）
+ * @returns {{ changeName: string, specBase: string, message: string } | null} null=通过，对象=失败
+ */
+export function validateChangeExists(specBase, stageName, changeName) {
+  const STAGES_REQUIRE_EXISTING_CHANGE = new Set(['plan', 'execute', 'verify', 'archive'])
+  if (!changeName || !STAGES_REQUIRE_EXISTING_CHANGE.has(stageName)) return null
+  if (/^quick-[0-9a-f]{8}$/.test(changeName)) return null
+  if (existsSync(join(specBase, 'changes', changeName))) return null
+  return {
+    changeName,
+    specBase,
+    message: `变更 "${changeName}" 在当前 spec 下不存在：${join(specBase, 'changes', changeName)}`,
+  }
+}
+
 function collectIdsFromLine(line, re, ids) {
   for (const match of line.matchAll(re)) {
     ids.add(match[0].toUpperCase())