sillyspec 3.26.7 → 3.26.8

package/src/scan-staleness.js

@@ -0,0 +1,90 @@
+/**
+ * scan-staleness — scan 文档漂移检测（债单 D-7 方案 A，change: 2026-08-15 ql-20260815-013）
+ *
+ * 原则（doc-consistency-debt 第六节用户裁决）：CLI 算事实注入——git 算出 scan 文档落后程度，
+ * 注入给 agent 的是一行结论不是一段劝说指令。brainstorm「加载项目上下文」读 scan 文档前
+ * 就知道"我读的架构描述可能过期"，不再盲信。
+ *
+ * 判定口径：scan 文档 frontmatter 的 source_commit（modules.js 写入、worktree-guard 覆盖
+ * 保护同源字段）vs 当前 HEAD——`git rev-list --count <source_commit>..HEAD` + 提交时间差。
+ * 纯读操作（git 只读 + frontmatter 解析），任何失败降级 null（advisory 信号不阻断流程）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { safeGit } from './git-helper.js'
+
+/** 漂移阈值（commit 数 / 天数，超过任一即 stale；advisory 性质允许保守默认） */
+export const STALENESS_THRESHOLDS = { commits: 50, days: 14 }
+
+/**
+ * 纯函数：从 scan 文档内容解析 frontmatter 的 source_commit。
+ * @param {string} content 文档全文
+ * @returns {string|null} commit hex（短/长均可）；无字段/无 frontmatter → null
+ */
+export function parseSourceCommit(content) {
+  if (!content || typeof content !== 'string') return null
+  // \r? 容错 CRLF（$ 前的 \r 会致 LF 正则失配）
+  const m = content.match(/^---\r?\n[\s\S]*?^source_commit:\s*([0-9a-f]{7,40})\s*\r?$/m)
+  return m ? m[1] : null
+}
+
+/**
+ * 计算单个 project 的 scan 文档漂移事实。
+ * @param {{ projectRoot: string, specBase: string, projectName: string, thresholds?: { commits: number, days: number } }} opts
+ * @returns {{ status: 'fresh'|'stale'|'unknown', behindCommits: number|null, daysSinceScan: number|null, sourceCommit: string|null, message: string }|null}
+ *   null = 无 scan 文档目录（绿地项目等），调用方直接跳过；unknown = 有文档但算不出（无
+ *   source_commit 字段 / git 失败），message 说明降级原因。
+ */
+export function computeScanStaleness(opts) {
+  const { projectRoot, specBase, projectName, thresholds = STALENESS_THRESHOLDS } = opts || {}
+  if (!projectRoot || !specBase || !projectName) return null
+  const scanDir = join(specBase, 'docs', projectName, 'scan')
+  if (!existsSync(scanDir)) return null
+
+  // 任一 scan 文档带 source_commit 即可代表整批（modules.js 同批写入同值）
+  let sourceCommit = null
+  let checked = 0
+  for (const f of readdirSync(scanDir)) {
+    if (!f.endsWith('.md')) continue
+    checked++
+    const c = parseSourceCommit(readFileSync(join(scanDir, f), 'utf8'))
+    if (c) { sourceCommit = c; break }
+  }
+  if (checked === 0) return null
+  if (!sourceCommit) {
+    return { status: 'unknown', behindCommits: null, daysSinceScan: null, sourceCommit: null,
+      message: 'scan 文档无 source_commit 字段（旧版生成），无法判漂移——如架构已大改建议重跑 sillyspec run scan --standard' }
+  }
+
+  const head = safeGit(projectRoot, ['rev-parse', 'HEAD'])
+  if (head.error || !head.value) {
+    return { status: 'unknown', behindCommits: null, daysSinceScan: null, sourceCommit,
+      message: `git 读取失败（${head.error || '无 HEAD'}），跳过漂移判定` }
+  }
+  const isAncestor = safeGit(projectRoot, ['merge-base', '--is-ancestor', sourceCommit, head.value.trim()])
+  if (isAncestor.error) {
+    return { status: 'unknown', behindCommits: null, daysSinceScan: null, sourceCommit,
+      message: `source_commit ${sourceCommit.slice(0, 7)} 不在当前分支历史（分支切换/rebase），跳过漂移判定` }
+  }
+  const countRes = safeGit(projectRoot, ['rev-list', '--count', `${sourceCommit}..HEAD`])
+  const behindCommits = countRes.error ? null : parseInt(countRes.value, 10)
+  if (behindCommits === null || Number.isNaN(behindCommits)) {
+    return { status: 'unknown', behindCommits: null, daysSinceScan: null, sourceCommit,
+      message: 'rev-list 计数失败，跳过漂移判定' }
+  }
+  const dateRes = safeGit(projectRoot, ['log', '-1', '--format=%cI', sourceCommit])
+  const daysSinceScan = dateRes.error ? null
+    : Math.floor((Date.now() - new Date(dateRes.value.trim()).getTime()) / 86400000)
+
+  const stale = behindCommits >= thresholds.commits || (daysSinceScan !== null && daysSinceScan >= thresholds.days)
+  if (!stale) {
+    return { status: 'fresh', behindCommits, daysSinceScan, sourceCommit,
+      message: `scan 文档新鲜（落后 ${behindCommits} commit / ${daysSinceScan ?? '?'} 天）` }
+  }
+  return {
+    status: 'stale', behindCommits, daysSinceScan, sourceCommit,
+    message: `⚠️ scan 文档过期：停在 ${sourceCommit.slice(0, 7)}（${daysSinceScan ?? '?'} 天前），期间源码已推进 ${behindCommits} commit。` +
+      `本次加载的架构/结构描述可能失真——涉及结构变更的 design 不要盲信 scan 文档，以实读代码为准；` +
+      `如需刷新基线跑 sillyspec run scan --standard --force-rescan`,
+  }
+}

package/src/stage-contract-spec.js

@@ -47,6 +47,7 @@ export const CUSTOM_KINDS = new Set([
   'cross-task-contract',     // task 卡片 provides/expects_from 对账(plan-postcheck)
   'design-file-coverage',    // design.md 文件清单 vs allowed_paths 覆盖(plan-postcheck)
   'task-id-continuity',      // task-NN id 连续性
+  'task-plan-reconciliation', // plan.md 声明任务 ↔ tasks/ 卡片双向对账(plan-postcheck)
   'design-readiness',        // design.md 进入 plan 前的章节就绪检查(validateDesignForPlan)
   'task-card-fields',        // task-NN.md 卡片字段存在性(validateBlueprintConsistency + validatePlanFeasibility)
   'verify-conclusion-gate',  // verify-result.md 结论 PASS/FAIL 门控
@@ -321,6 +322,20 @@ const PLAN_RULES = [
     spec: 'design.md「文件变更清单」中的每个源码文件,必须被至少一个 task 的 allowed_paths 覆盖(前缀/glob 容差匹配),否则 execute 子代理无权改它→必然漏改。有 task 卡片但 design 缺「文件变更清单」章节也阻断(清单是覆盖对账的基准)。',
     failMessage: 'design.md 文件变更清单中 ${count} 个文件未被任何 task 的 allowed_paths 覆盖：\n${files}\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，或在 design.md「不修改文件」章节说明不改原因。',
   },
+  // task-plan-reconciliation(custom):plan.md 声明任务 ↔ tasks/ 卡片双向对账（债单 D-2b）。
+  // 修复场景：plan 列 17 个任务只生成 12 张卡（尾部文档同步类任务漏卡），execute 审计只看
+  // 卡片 → 漏卡任务零失败信号（sillyhub conversation-driven T-13~T-17 实证）。
+  // ${declared}/${cards} replaceAll。
+  {
+    id: 'plan.task-plan-reconciliation', stage: 'plan', source: 'validateBlueprintConsistency', severity: 'error', kind: 'task-plan-reconciliation',
+    target: { root: 'change', path: 'tasks' },
+    data: {
+      messageMissingCards: 'plan.md 声明了 ${declared} 个任务，但 tasks/ 只有部分卡片。缺卡: ${missing}\n   无卡片的任务不进 Wave、不受 execute 审计（allowed_paths/review.json 都不覆盖）→ 必然漏做（典型：尾部文档同步类任务）。\n   修复：为每个缺卡任务补 task-NN.md（含 allowed_paths/验收标准），或从 plan.md 删除该任务。',
+      messageOrphanCards: 'tasks/ 存在 plan.md 未声明的卡片: ${orphans}\n   这些任务不进任何 Wave，execute 不会执行。修复：在 plan.md 补声明，或删除孤儿卡片。',
+    },
+    spec: 'plan.md 中声明的每个 task-NN 必须有对应 tasks/task-NN.md 卡片（反向亦然），否则阻断——无卡片任务不受 execute 审计，必然漏做。',
+    failMessage: 'plan.md 任务与 tasks/ 卡片不对账',
+  },
   // task-id-continuity(custom):task-NN id 从 task-01 起连续。算法留 validatePlanFeasibility。
   // ${expected}/${actual} replaceAll(零填充 2 位)。
   {

package/src/stage-contract.js

@@ -12,6 +12,7 @@ import { detectChangeRisk, checkIntegrationEvidence, VERIFICATION_NEEDS, RISK_LE
 import { SCAN_REQUIRED_DOCS, AUXILIARY_STAGES } from './constants.js'
 import { evaluateRules } from './stage-contract-engine.js'
 import { getRule } from './stage-contract-spec.js'
+import { parseAllowedPaths } from './stages/plan-postcheck.js'
 
 /**
  * 校验结果
@@ -381,11 +382,13 @@ function validatePlanOutputs(cwd, changeName, context = {}) {
         const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/i.test(f))
         for (const taskFile of taskFiles) {
           const taskContent = readFileSync(join(tasksDir, taskFile), 'utf8')
-          const allowedSection = taskContent.match(/allowed_paths:\s*\n((?:\s+-\s+.+\n?)+)/)
-          if (allowedSection) {
-            const paths = allowedSection[1].match(/-\s+(.+)/g) || []
-            for (const p of paths) allAllowedPaths.add(p.replace(/^-\s+/, '').trim().toLowerCase())
-          }
+          // 复用 parseAllowedPaths（坑6①：认 inline 数组/缩进块/顶格块 + 剥反引号 + CRLF 归一，
+          // 消除此处内联正则与 plan-postcheck 的解析漂移）。卡片无 frontmatter 时退全文扫描
+          // （包裹伪 frontmatter 复用同一解析器）——原内联正则是全文匹配语义，entry-point-wiring
+          // 只关心路径覆盖，卡片格式合法性归 plan-postcheck 把关，此处不收紧。
+          const paths = parseAllowedPaths(taskContent)
+          const effective = paths.length > 0 ? paths : parseAllowedPaths(`---\n${taskContent}\n---`)
+          for (const p of effective) allAllowedPaths.add(p.toLowerCase())
         }
       }
       // 也从 plan.md 文件变更清单中收集

package/src/stages/brainstorm-auto.js

@@ -66,7 +66,6 @@ export const definition = {
       maxWaitRounds: 5,
       waitReason: '等待用户回答需求问题',
       waitOptions: ['回答见--answer', '信息够了，进入设计'],
-      waitFreeAnswer: true, // 开放回答型：--answer 内容为自由文本（需求澄清回答），非封闭单选，豁免 enforceWaitChoice
       prompt: `分析需求，必要时追问，然后设计方案。
 
 ### 操作

package/src/stages/brainstorm.js

@@ -32,6 +32,7 @@ export const definition = {
 
 ### 操作
 1. 读取项目总览 \`{SPEC_ROOT}/docs/<project>/scan/PROJECT.md\` + 共享规范 + 子项目上下文
+   - 漂移事实（CLI 算）：{SCAN_STALENESS}
 2. 加载项目信息：\`cat {SPEC_ROOT}/projects/*.yaml 2>/dev/null\`
 3. 加载本地配置：\`cat {SPEC_ROOT}/local.yaml 2>/dev/null\`
 4. 棕地项目：读取 {SPEC_ROOT}/docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
@@ -79,7 +80,6 @@ export const definition = {
       maxWaitRounds: 8,
       waitReason: '等待用户回答需求问题或澄清',
       waitOptions: ['回答见--answer', '信息够了，进入方案讨论'],
-      waitFreeAnswer: true, // 开放回答型：--answer 内容为自由文本（需求澄清回答），非封闭单选，豁免 enforceWaitChoice
       prompt: `通过对话探索需求细节、分析原型（如有）、判断拆分/批量、并对歧义点做需求澄清 Grill。本步骤合并了原有的对话探索、原型分析、需求范围评估、需求澄清 Grill 四个环节——按下方 A→D 顺序按需执行。提问遵守「一次只问一个」（见 D 节追问策略）：必须问的问题逐个问，能查代码/文档解决的不问；不要把多个歧义打包成一屏清单一次抛给用户（用户记不住、答不全，反而漏掉关键约束）；也不要为凑数把单个问题拖成多轮。
 
 ### A. 原型/设计图分析（如用户提供）