sillyspec 3.28.0 → 3.28.2

package/src/quicklog.js

@@ -713,6 +713,57 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
   })
 }
 
+/**
+ * 以**给定 ql-ID** 追加一条「进行中」骨架条目（不分配新 ID）。
+ *
+ * 坑 platform-takeover-phantom-progress-db 同日变体：quick --done 兜底复用启动分配的
+ * ql-ID（进度库 changes.quicklog_id 可查）时，该 ID 的条目可能不在当前 specBase 的
+ * QUICKLOG 文件里（启动与 --done 落到不同库/文件的分裂形态）——用原 ID 补建骨架再走
+ * 完成翻态，保证「同一次会话只有一个 ql-ID」。条目已存在则幂等跳过（不重复追加）。
+ * 与 allocateQuicklogEntry 同锁同格式同平台推送，仅跳过 ID 分配段。
+ */
+export async function appendQuicklogEntryWithId(specBase, gitUser, qlId, { description = '(guard 缺失补建)', linkedChanges = [], allowedFiles = [] } = {}) {
+  if (!qlId || typeof qlId !== 'string') throw new Error('appendQuicklogEntryWithId: qlId 必填')
+  if (findQuicklogEntry(specBase, gitUser, qlId)) return { qlId, existed: true }
+  const quicklogDir = join(specBase, 'quicklog')
+  mkdirSync(quicklogDir, { recursive: true })
+  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
+  const userFile = join(quicklogDir, `QUICKLOG-${user}.md`)
+  const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
+  const desc = sanitizeDesc(description)
+  const linked = Array.isArray(linkedChanges) ? linkedChanges : []
+  const files = Array.isArray(allowedFiles) ? allowedFiles : []
+
+  return await withFileLock(lockPath, async () => {
+    // 双检（锁内）：并发兜底同 ID 只落一条
+    if (findQuicklogEntry(specBase, gitUser, qlId)) return { qlId, existed: true }
+    await rotateIfNeeded(userFile, user)
+    const entry = [
+      '',
+      `## ${qlId} | ${nowDatetime()} | ${desc}`,
+      '状态：进行中',
+      `关联变更：${linked.length > 0 ? linked.join(', ') : '（无）'}`,
+      `文件：${files.length > 0 ? files.join(', ') : '（见实际改动）'}`,
+      '',
+    ].join('\n')
+    appendFileSync(userFile, entry)
+    for (const c of linked) await appendTaskCheckbox(specBase, c, qlId, desc)
+    await pushQuicklogEntryToPlatform(specBase, {
+      ql_id: qlId,
+      timestamp: nowDatetime(),
+      title: desc,
+      status: 'in_progress',
+      status_note: null,
+      author_raw: user,
+      linked_changes: linked.filter(c => /^\d{4}-\d{2}-\d{2}-/.test(c)),
+      files: files.map(f => ({ path: f, note: null })),
+      body_sections: {},
+      raw_block: entry,
+    }).catch(() => {})
+    return { qlId, existed: false }
+  })
+}
+
 /**
  * 翻某 qlId 条目为「已完成」+ 追加结果 + 勾选关联 tasks.md。持锁。
  */

package/src/run/command.js

@@ -23,7 +23,7 @@ import { basename, join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, ancestorSpecDirs, resolveAncestorCeiling, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, ancestorSpecDirs, resolveAncestorCeiling, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, resolveQuickSessionsDir, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -107,6 +107,38 @@ function warnMsysMangledFlag(flag, value) {
   console.error('   非本意 → 去掉前导 / 或改写表述后重发本命令；确需原样 → 命令前加 MSYS_NO_PATHCONV=1。')
 }
 
+/**
+ * done-like 步骤动作（--done/--skip/--wait/--continue/--reset/--reopen）的目标 change 在当前
+ * 库是否已「物化」（坑 done-phantom-change-silent-create，2026-09-04 事故元凶①）。
+ *
+ * 背景：接管指针切换/重建进度库后，--change 常指向旧库的变更名；新库里既无 DB 行也无
+ * changes/<name>/ 目录，runCommand 的 !progress 分支却无条件 initChange 静默新建——幻影
+ * 变更零进度起步，--done 被记到幻影上，原变更进度停滞（本次事故直接元凶）。
+ *
+ * 物化口径（progress 已知为 null，只查磁盘标记）：
+ *   - 普通变更：changes/<name>/ 存在（archive 已归档目录也算——归档后 DB 行仍可读，
+ *     但行被清理的恢复场景认 archive 目录物化，走 initChange 自愈是合法路径）；
+ *   - quick-<8hex> 会话：无 changes/ 目录，物化标记 = 会话 guard（per-session 目录或
+ *     legacy 单文件——legacy 无法归属会话，保守认物化，宁可漏拦不误杀真会话）。
+ *
+ * 纯函数：只读磁盘，供 command.js 守卫 + 单测复用。
+ * @param {object} opts
+ * @param {string|null} opts.target - 目标 change 名（--change 值或 changes/ 目录唯一推导）
+ * @param {string} opts.specBase - 当前进度库根（平台 specRoot 或 cwd/.sillyspec）
+ * @param {string|null} [opts.quickSessionsDir] - quick 会话 guard 目录（缺省按 specBase/.runtime 推导）
+ * @returns {boolean} true = 目标已物化（可走既有 initChange 自愈），false = 幻影（应拒绝新建）
+ */
+export function doneLikeTargetMaterialized({ target, specBase, quickSessionsDir = null }) {
+  if (!target || !specBase) return false
+  if (/^quick-[0-9a-f]{8}$/.test(target)) {
+    const rt = quickSessionsDir || join(specBase, '.runtime', 'quick-sessions')
+    return existsSync(join(rt, target, 'guard.json'))
+      || existsSync(join(specBase, '.runtime', 'quick-guard.json'))
+  }
+  return existsSync(join(specBase, 'changes', target))
+    || existsSync(join(specBase, 'changes', 'archive', target))
+}
+
 /**
  * 从 progress 或变更目录推导变更名
  */
@@ -951,6 +983,43 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   }
 
   if (!progress) {
+    // ── done-like 存在性守卫（坑 done-phantom-change-silent-create，2026-09-04 事故元凶①）──
+    // --done/--skip/--wait/--continue/--reset/--reopen 都预设「目标 change 已存在于当前进度库」。
+    // 此前 !progress 时无条件 initChange 静默新建——接管指针切库/换库后 --change 指向旧库的
+    // 变更名，新库里凭空建幻影变更再把动作记上去。目标已物化（changes/ 目录或 quick 会话
+    // guard 存在）仍放行走下方 initChange 自愈（DB 重建/迁移后从目录物化是合法恢复路径）。
+    if (isDone || isSkip || isWait || isContinue || isReset || isReopen) {
+      const actionFlag = isDone ? '--done' : isSkip ? '--skip' : isWait ? '--wait'
+        : isContinue ? '--continue' : isReset ? '--reset' : '--reopen'
+      const guardTarget = changeName || resolveChangeNameAuto(cwd, specRoot)
+      if (!doneLikeTargetMaterialized({
+        target: guardTarget,
+        specBase,
+        quickSessionsDir: resolveQuickSessionsDir(platformOpts, specBase),
+      })) {
+        const pointerPath = join(cwd, '.sillyspec-platform.json')
+        const pointerMode = existsSync(pointerPath)
+        let activeList = []
+        try { activeList = pm.listChanges(cwd) } catch { /* 列举失败不掩盖主报错 */ }
+        console.error(`❌ ${actionFlag} 找不到目标变更的进度，拒绝静默新建（防幻影变更）。`)
+        console.error(`   目标变更: ${guardTarget || '(未指定 --change，且当前库无唯一活跃变更)'}`)
+        console.error(`   当前进度库: ${specBase}${pointerMode ? `（平台接管指针 ${pointerPath} 指向此库）` : '（本地模式）'}`)
+        console.error(`   本库活跃变更: ${activeList.length > 0 ? activeList.join('、') : '(无)'}`)
+        console.error('   排查：')
+        console.error(`   ① 变更名是否打错——从上面活跃列表选，或 sillyspec progress show 查看各变更进度`)
+        if (pointerMode) {
+          console.error(`   ② 最近是否切换/重建过平台接管指针（重跑平台 scan 会换库）——原变更可能留在旧库：检查 ${pointerPath} 的 specRoot，或用 --spec-dir 显式指回旧库`)
+        } else {
+          console.error(`   ② cwd 是否漂移/切库——用 --spec-dir <路径>/.sillyspec 显式指定正确的进度库`)
+        }
+        if (stageName === 'quick' || /^quick-[0-9a-f]{8}$/.test(guardTarget || '')) {
+          console.error(`   ③ quick 会话跨进程恢复须带 --change <quick-session-id>；本库无该会话 guard——会话可能属于旧库`)
+        } else {
+          console.error(`   ③ 确要新建变更：先 sillyspec run brainstorm --change <名>（不带 ${actionFlag}）`)
+        }
+        process.exit(2) // 用法/环境错（目标变更不在当前库）→ exit 2
+      }
+    }
     // 如果指定了变更名或有变更目录，自动初始化变更的 progress
     const autoChange = changeName || resolveChangeNameAuto(cwd, specRoot)
     if (autoChange) {

package/src/run/complete-handlers.js

@@ -31,7 +31,7 @@ import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnch
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
 import { printQuickAuditReview, runQuickTestLintGate, printQuickTestLintGate } from './quick-audit.js'
-import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
+import { validateQuickResult, allocateQuicklogEntry, appendQuicklogEntryWithId, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
 
@@ -432,6 +432,31 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
     console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
     return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
   }
+  // ── 归档前 delta.md 自动生成（P3d task-02，fail-soft 零阻断）──
+  // 目录移走前在 changes/<name>/ 落一份 Before/Delta/After 三段式快照（四源采集容缺，
+  // buildDeltaReport 见 ../archive-delta.js），随归档包留存。失败只 console.error 留痕、
+  // 提示 sillyspec delta --change 手动补，绝不抛出——归档主流程既有失败面（rename/git/清理）
+  // 一个不叠加。specRoot 同 complete.js :87 口径（specBase 已含 platform specRoot）；
+  // runtimeRoot 同本文件 archiveWorktreeCleanup 既有用法 resolveRuntimeRoot(platformOpts, specBase)。
+  const deltaChangeName = progress.currentChange || changeName
+  if (deltaChangeName) {
+    try {
+      const { buildDeltaReport } = await import('../archive-delta.js')
+      const deltaChangeDir = join(specBase, 'changes', deltaChangeName)
+      const deltaMd = buildDeltaReport({
+        changeDir: deltaChangeDir,
+        specRoot: specBase,
+        // project 缺参可 null（loadModuleMap null 降级路径已支持，报告内逐段降级注记）
+        project: progress?.project || null,
+        runtimeRoot: resolveRuntimeRoot(platformOpts, specBase),
+      })
+      writeFileSync(join(deltaChangeDir, 'delta.md'), deltaMd)
+      console.log(`📊 归档前已生成 delta.md: ${join(deltaChangeDir, 'delta.md')}`)
+    } catch (e) {
+      console.error(`⚠️  归档前 delta.md 自动生成失败（不阻断归档）: ${e.message}`)
+      console.error(`   可手动补: sillyspec delta --change ${deltaChangeName} --spec-dir ${specBase}`)
+    }
+  }
   // 主仓互斥锁（坑 main-repo-no-mutex 二批）：archiveChangeDirectory 改主仓共享状态（目录
   // rename + 共享 index 的 git add + marker 删除 + worktree 清理），与并行会话的 apply/cleanup
   // 互踩。exit 钩子兜底：其内部 guard 失败 exit(1) 时锁也会被清（见 withMainRepoLock）。
@@ -988,7 +1013,27 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
     }
 
     if (!qlId) {
-      // 无 ql-ID（guard 缺失或 brownfield 无 quicklogId）：补分配后立即完成，不阻断。
+      // 坑 platform-takeover-phantom-progress-db 同日变体：guard 缺失时兜底**优先复用启动
+      // 分配的 ql-ID**（进度库 changes.quicklog_id，quick 启动时 stage.js 回填）——落码
+      // 注释/模块文档的 ql-ID 是启动时就给出的，补分配新号必然制造引用劈叉（同一次会话
+      // 两个 ID、两份 QUICKLOG 各半）。ID 的条目不在当前 specBase（启动/完成分裂库形态）
+      // → 用原 ID 补建骨架，完成态落在同一 ID 上。库中也无（真 brownfield/极老会话）才
+      // 补分配。
+      try {
+        const dbQlId = pm.getQuicklogId(cwd, changeName)
+        if (dbQlId) {
+          const re = await appendQuicklogEntryWithId(specBase, gitUser, dbQlId, {
+            description: guard?.taskDescription || '(guard 缺失补建)',
+            linkedChanges,
+            allowedFiles: Array.isArray(guard?.allowedFiles) ? guard.allowedFiles : [],
+          })
+          qlId = dbQlId
+          console.log(`📝 QUICKLOG 兜底补写复用启动 ql-ID: ${qlId}（guard 缺失，ID 取自进度库 quicklog_id${re.existed ? '' : '，条目已补建'}）`)
+        }
+      } catch { /* 读取/补建失败退回补分配，不阻断 */ }
+    }
+    if (!qlId) {
+      // 无 ql-ID（库中也未回填，真 brownfield）：补分配后立即完成，不阻断。
       try {
         const alloc = await allocateQuicklogEntry(specBase, gitUser, {
           description: guard?.taskDescription || '(补分配)',
@@ -1530,7 +1575,9 @@ export async function handleScanStageCompleted({ stageName, currentIdx, cwd, pro
       try { unlinkSync(platformOptsFile) } catch {}
 
       // CLI 层 post-check（替代旧的简单检查）
-      const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('../scan-postcheck.js')
+      const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult, stampScanDocHeaders } = await import('../scan-postcheck.js')
+      // ② frontmatter CLI 盖章（2026-09-05，幂等兜底——正常已在 scanFinalize / quick postcheck 盖过）
+      stampScanDocHeaders({ cwd, specDir: platformOpts.specRoot, mode: stageData.scanProfile?.mode })
       const postResult = runScanPostCheck({
         cwd,
         specDir: platformOpts.specRoot,
@@ -1613,7 +1660,9 @@ export async function handleScanStageCompleted({ stageName, currentIdx, cwd, pro
 
   // 非 platform 模式 scan 也做轻量 post-check + 结构化输出
   if (stageName === 'scan' && !platformOpts.specRoot && !platformOpts.runtimeRoot) {
-    const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('../scan-postcheck.js')
+    const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult, stampScanDocHeaders } = await import('../scan-postcheck.js')
+    // ② frontmatter CLI 盖章（2026-09-05，幂等兜底）
+    stampScanDocHeaders({ cwd, specDir: null, mode: stageData.scanProfile?.mode })
     const postResult = runScanPostCheck({ cwd, specDir: null, outputText, scanProfile: stageData.scanProfile || null })
     printScanPostCheckResult(postResult)
     // 结构化结果写入 .sillyspec/.runtime/

package/src/run/complete.js

@@ -21,12 +21,13 @@ import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } fr
 import { writeAtomicSync } from '../fs-atomic.js'
 import { withFileLock } from '../quicklog.js'
 import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir } from './shared.js'
-import { executeScanPreflight, executeScanPostcheck, computeScanProfile } from './scan-profile.js'
+import { executeScanPreflight, executeScanPostcheck, computeScanProfile, executeScanDetectProjects, executeScanResumeCheck, executeScanFinalize } from './scan-profile.js'
 import { executePlanPostcheck as runPlanPostcheckLib } from '../stages/plan-postcheck.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { enforceDepsGate, enforceReviewJsonGate, enforceSymbolImpactGate, warnMissingUiPrototype, completeStageGates, readDesignScale } from './gates.js'
 import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact } from './complete-handlers.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
+import { validateDecisionModuleRefs } from '../design-facts.js'
 import { isEndToEndTaskText } from '../change-risk-profile.js'
 import { deriveTitleFromLinkedChange } from '../quicklog.js'
 import { gitQuiet } from '../git-helper.js'
@@ -279,6 +280,37 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   await enforceSymbolImpactGate(stageName, changeName, steps[currentIdx]?.name, specBase)
   // UI 原型软提醒（非阻断）：brainstorm 收尾步 design.md 命中前端文件但无 prototype → 提示用户可否决
   warnMissingUiPrototype(stageName, changeName, steps[currentIdx]?.name, specBase)
+  // 决策模块域核验硬门（task-02 接线 design-facts，FR-02/D-002）：brainstorm「生成规范文件」步
+  // --done 时核验 decisions.md 模块域引用。ERROR（decision_module_ref_invalid，消息已内嵌前缀）
+  // = 模块幻觉/书写错误 → fail-closed exit 1（进度不推进，步骤保持 pending）；WARNING
+  // （decision_module_domain_gap 声明×实改差异）→ warn 放行留人工裁量；skipped（无决策文件/
+  // 无 _module-map.yaml 索引）→ 单行 info 放行（无索引不误拦）。fail-soft：核验自身异常 →
+  // fail-open（warn 留痕后放行——门禁代码缺陷不应误拦真实完成，与「无索引跳过」同向）。
+  // project 解析与 handleWorkflowPostCheck 同链：progress.project（平台模式真实项目名）>
+  // steps[idx].project > null（brainstorm 非 perProject 展开，后两位常规为空）。
+  if (stageName === 'brainstorm' && steps[currentIdx]?.name?.includes('生成规范文件') && changeName) {
+    try {
+      const _dmProject = progress?.project || steps[currentIdx]?.project || null
+      const _dmResult = validateDecisionModuleRefs({
+        changeDir: join(specBase, 'changes', changeName),
+        specRoot: specBase,
+        project: _dmProject,
+      })
+      if ((_dmResult.errors || []).length > 0) {
+        console.error(`❌ ── 决策模块域核验阻断（本次 --done 未完成，进度未推进）──`)
+        for (const _dmErr of _dmResult.errors) console.error(`   • ${_dmErr}`)
+        console.error(`   修复：更正 decisions.md 对应条目的「模块域」字段（模块 ID 取自 docs/${_dmProject || '<项目>'}/modules/_module-map.yaml），或以 NEW:<名> 前缀声明新模块后重跑：`)
+        console.error(`   sillyspec run brainstorm --done${changeName ? ` --change ${changeName}` : ''} --output "修复说明"`)
+        process.exit(1)
+      }
+      for (const _dmWarn of (_dmResult.warnings || [])) console.warn(`   ⚠️ ${_dmWarn}`)
+      if (_dmResult.skipped) {
+        console.log(`ℹ️  [decision_module_check_skipped] ${_dmResult.skipped}`)
+      }
+    } catch (_dmEx) {
+      console.warn(`   ⚠️ 决策模块域核验自身异常，fail-open 放行（不误拦本次完成）：${_dmEx && _dmEx.message ? _dmEx.message : _dmEx}`)
+    }
+  }
 
   // ── noAI 步骤硬门（坑 noai-done-bypass）：noAI 步骤的确定性校验不可被 --done 绕过 ──
   // 正常路径 agent 跑 `run <stage>` 推进到 noAI step 时，runStage 自动执行 _cliAction
@@ -296,6 +328,12 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       await executeScanPreflight(cwd, platformOpts, stageData.scanProfile || computeScanProfile(cwd, platformOpts))
     } else if (_cliAction === 'scanPostcheck') {
       await executeScanPostcheck(cwd, platformOpts, stageData.scanProfile || computeScanProfile(cwd, platformOpts))
+    } else if (_cliAction === 'scanDetectProjects') {
+      await executeScanDetectProjects(cwd, platformOpts)
+    } else if (_cliAction === 'scanResumeCheck') {
+      await executeScanResumeCheck(cwd, platformOpts)
+    } else if (_cliAction === 'scanFinalize') {
+      await executeScanFinalize(cwd, platformOpts)
     } else if (_cliAction === 'planPostcheck') {
       await runPlanPostcheckLib({ cwd, specRoot: platformOpts?.specRoot, resolveChangeDir, progress })
     } else {
@@ -507,6 +545,13 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
         console.log(`\n👉 下一步：sillyspec run verify${changeName ? ` --change ${changeName}` : ''}（验证通过后才能归档）`)
       }
     } else if (stageName === 'archive') {
+      // 机械暂存 CLI 化（2026-09-05 全流程审计）：原步骤 6 的 3 条固定路径 git add agent 指令
+      // 改为完成时 CLI 直做（未变更路径 git add 是无害 no-op）。平台模式跳过（specRoot 在源码仓外）。
+      if (!platformOpts?.specRoot && !platformOpts?.runtimeRoot) {
+        const { stageArchiveArtifacts } = await import('../git-helper.js')
+        const r = stageArchiveArtifacts(cwd)
+        if (r.staged.length > 0) console.log(`  📦 已暂存归档产物（${r.staged.length} 个路径，未提交，由统一提交工具处理）`)
+      }
       console.log('\n👉 归档完成！现在可以提交了：git commit -m "..."')
     } else if (stageName === 'verify') {
       // verify 的"验证通过"提示延后到下方 validator 通过后才打印，