sillyspec 3.25.1 → 3.25.3

package/src/run/quick-audit.js

@@ -1,102 +1,107 @@
-/**
- * run/quick-audit.js（W6 Step2 从 run.js 抽出）。
- *
- * quick 审计结论打印 + quick 多变更关联选择（自洽，不依赖 run.js 闭包）。
- * 安全锚：run.js 始终 barrel，本模块函数 run.js import 回来；无 test 直接 import，无需 re-export。
- *
- * 路径修正（相对 src/run/）：
- *   - resolveQuickLinkedChanges 的 quick-recommend.js 动态 import './quick-recommend.js' → '../quick-recommend.js'
- *   - 原动态 import('child_process') 删除，改顶部静态 execSync
- *   - parsePorcelainPath 从 ./shared.js 重 import；checkbox 顶部 import
- */
-import { execSync } from 'node:child_process'
-import { checkbox } from '@inquirer/prompts'
-import { parsePorcelainPath } from './shared.js'
-
-/**
- * 打印 quick 完成审计结论（按 review.status 输出 SAFE/WARNING/BLOCKED）。
- */
-export function printQuickAuditReview(review) {
-  if (review.status === 'blocked') {
-    console.error(`\n🚫 quick 变更边界审计 — BLOCKED：`)
-    for (const r of review.reasons) {
-      console.error(`   - ${r}`)
-    }
-    console.error(`\n   quick 已停止：请恢复/拆分这些变更，或重新运行 quick 并显式声明范围。`)
-  } else if (review.status === 'warning') {
-    console.warn(`\n⚠️ quick 变更边界审计 — WARNING：`)
-    for (const r of review.reasons) {
-      console.warn(`   - ${r}`)
-    }
-  } else {
-    console.log(`\n✅ quick 变更边界审计 — SAFE (变更 ${review.changedFiles.length} 个文件)`)
-  }
-}
-
-/**
- * quick 阶段多变更交互式选择关联变更。
- * - 0 活跃变更 → []（仅记 QUICKLOG，不关联）
- * - 1 活跃变更 → 默认关联它（保持现状友好，不弹交互）
- * - ≥2 活跃变更 + 交互 → checkbox 多选（推荐项默认勾，空选 = 不关联）
- * - ≥2 活跃变更 + 非交互 → []（不关联）+ 提示用 --change a,b
- */
-export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDescription, nonInteractive }) {
-  let activeChanges = []
-  try {
-    activeChanges = await pm.listChanges(cwd)
-  } catch {
-    activeChanges = []
-  }
-  if (activeChanges.length === 0) return []
-  if (activeChanges.length === 1) return [activeChanges[0]]
-
-  if (nonInteractive || !process.stdin.isTTY) {
-    console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
-    return []
-  }
-
-  // 脏文件（推荐信号之一）
-  let baselineFiles = []
-  try {
-    const gs = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
-    baselineFiles = gs.split('\n').filter(Boolean)
-      .map(l => parsePorcelainPath(l))
-      .filter(Boolean)
-      .filter(f => !f.startsWith('.sillyspec/'))
-  } catch {}
-
-  // 推荐打分（脏文件 + 任务描述双信号）
-  let recommendations = []
-  try {
-    // quick-recommend.js 在 src/，本模块在 src/run/ → 退一层（真环依赖，保留动态 import）
-    const { recommendChanges } = await import('../quick-recommend.js')
-    recommendations = recommendChanges({ activeChanges, specDir, baselineFiles, quickFiles, taskDescription })
-  } catch {
-    recommendations = activeChanges.map(name => ({ name, score: 0, reasons: [] }))
-  }
-  const scoreMap = new Map(recommendations.map(r => [r.name, r.score]))
-  const reasonMap = new Map(recommendations.map(r => [r.name, r.reasons]))
-  const recommendedSet = new Set(recommendations.filter(r => r.score > 0).map(r => r.name))
-
-  // 按推荐分降序展示
-  const ordered = [...activeChanges].sort((a, b) =>
-    (scoreMap.get(b) || 0) - (scoreMap.get(a) || 0) || a.localeCompare(b))
-
-  const choices = ordered.map(name => {
-    const reasons = reasonMap.get(name) || []
-    const isRec = recommendedSet.has(name)
-    return {
-      name: `${isRec ? '⭐ ' : '   '}${name}`,
-      value: name,
-      description: reasons.length > 0 ? reasons.join('；') : '无推荐信号',
-      checked: isRec,
-    }
-  })
-
-  console.log('🔗 检测到多个活跃变更，选择本次 quick 关联哪些（可多选；不勾选任何项 = 仅记 QUICKLOG，不关联变更）')
-  if (recommendedSet.size > 0) {
-    console.log('   ⭐ = 基于脏文件/任务描述推荐，已默认勾选')
-  }
-  const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
-  return selected
-}
+/**
+ * run/quick-audit.js（W6 Step2 从 run.js 抽出）。
+ *
+ * quick 审计结论打印 + quick 多变更关联选择（自洽，不依赖 run.js 闭包）。
+ * 安全锚：run.js 始终 barrel，本模块函数 run.js import 回来；无 test 直接 import，无需 re-export。
+ *
+ * 路径修正（相对 src/run/）：
+ *   - resolveQuickLinkedChanges 的 quick-recommend.js 动态 import './quick-recommend.js' → '../quick-recommend.js'
+ *   - 原动态 import('child_process') 删除，改顶部静态 execSync
+ *   - parsePorcelainPath 从 ./shared.js 重 import；checkbox 顶部 import
+ */
+import { execSync } from 'node:child_process'
+import { checkbox } from '@inquirer/prompts'
+import { parsePorcelainPath } from './shared.js'
+
+/**
+ * 打印 quick 完成审计结论（按 review.status 输出 SAFE/WARNING/BLOCKED）。
+ */
+export function printQuickAuditReview(review) {
+  if (review.status === 'blocked') {
+    console.error(`\n🚫 quick 变更边界审计 — BLOCKED：`)
+    for (const r of review.reasons) {
+      console.error(`   - ${r}`)
+    }
+    console.error(`\n   quick 已停止：请恢复/拆分这些变更，或重新运行 quick 并显式声明范围。`)
+    // 解锁咒语须在 BLOCKED 分支也给出 —— 原只在 confirm/review 分支打印，
+    // 普通 --done 走这里只看到「恢复/拆分」反方向指引，正确解法（带 flag 重跑）根本不出现。
+    console.error(`   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
+    console.error(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
+    console.error(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件）`)
+  } else if (review.status === 'warning') {
+    console.warn(`\n⚠️ quick 变更边界审计 — WARNING：`)
+    for (const r of review.reasons) {
+      console.warn(`   - ${r}`)
+    }
+  } else {
+    console.log(`\n✅ quick 变更边界审计 — SAFE (变更 ${review.changedFiles.length} 个文件)`)
+  }
+}
+
+/**
+ * quick 阶段多变更交互式选择关联变更。
+ * - 0 活跃变更 → []（仅记 QUICKLOG，不关联）
+ * - 1 活跃变更 → 默认关联它（保持现状友好，不弹交互）
+ * - ≥2 活跃变更 + 交互 → checkbox 多选（推荐项默认勾，空选 = 不关联）
+ * - ≥2 活跃变更 + 非交互 → []（不关联）+ 提示用 --change a,b
+ */
+export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDescription, nonInteractive }) {
+  let activeChanges = []
+  try {
+    activeChanges = await pm.listChanges(cwd)
+  } catch {
+    activeChanges = []
+  }
+  if (activeChanges.length === 0) return []
+  if (activeChanges.length === 1) return [activeChanges[0]]
+
+  if (nonInteractive || !process.stdin.isTTY) {
+    console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
+    return []
+  }
+
+  // 脏文件（推荐信号之一）
+  let baselineFiles = []
+  try {
+    const gs = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
+    baselineFiles = gs.split('\n').filter(Boolean)
+      .map(l => parsePorcelainPath(l))
+      .filter(Boolean)
+      .filter(f => !f.startsWith('.sillyspec/'))
+  } catch {}
+
+  // 推荐打分（脏文件 + 任务描述双信号）
+  let recommendations = []
+  try {
+    // quick-recommend.js 在 src/，本模块在 src/run/ → 退一层（真环依赖，保留动态 import）
+    const { recommendChanges } = await import('../quick-recommend.js')
+    recommendations = recommendChanges({ activeChanges, specDir, baselineFiles, quickFiles, taskDescription })
+  } catch {
+    recommendations = activeChanges.map(name => ({ name, score: 0, reasons: [] }))
+  }
+  const scoreMap = new Map(recommendations.map(r => [r.name, r.score]))
+  const reasonMap = new Map(recommendations.map(r => [r.name, r.reasons]))
+  const recommendedSet = new Set(recommendations.filter(r => r.score > 0).map(r => r.name))
+
+  // 按推荐分降序展示
+  const ordered = [...activeChanges].sort((a, b) =>
+    (scoreMap.get(b) || 0) - (scoreMap.get(a) || 0) || a.localeCompare(b))
+
+  const choices = ordered.map(name => {
+    const reasons = reasonMap.get(name) || []
+    const isRec = recommendedSet.has(name)
+    return {
+      name: `${isRec ? '⭐ ' : '   '}${name}`,
+      value: name,
+      description: reasons.length > 0 ? reasons.join('；') : '无推荐信号',
+      checked: isRec,
+    }
+  })
+
+  console.log('🔗 检测到多个活跃变更，选择本次 quick 关联哪些（可多选；不勾选任何项 = 仅记 QUICKLOG，不关联变更）')
+  if (recommendedSet.size > 0) {
+    console.log('   ⭐ = 基于脏文件/任务描述推荐，已默认勾选')
+  }
+  const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
+  return selected
+}

package/src/run/shared.js

@@ -19,6 +19,49 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 // ── Wait State Constants ──（W6 Step3 从 run.js 搬入：prompt.js outputStep 与 run.js wait-detection 共用）
 // 正则匹配：只识别独立一行的标记，避免误伤文档正文引用
 export const WAIT_MARKER_RE = /^\s*\[(WAIT_FOR_USER|NEEDS_CONFIRM|NEEDS_DECISION)\]\s*$/m
+
+// ── did-you-mean（命令级 + flag 级 typo 建议，零依赖）──
+// 历史：agent 打错命令名/flag 名只报「未知」+整屏列表，要自己捞正确拼写。
+export function levenshtein(a, b) {
+  const m = String(a).length, n = String(b).length
+  if (!m) return n; if (!n) return m
+  let prev = Array.from({ length: n + 1 }, (_, i) => i)
+  for (let i = 1; i <= m; i++) {
+    const cur = [i]
+    for (let j = 1; j <= n; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    prev = cur
+  }
+  return prev[n]
+}
+export function didYouMean(input, candidates) {
+  if (!input) return null
+  let best = null, bestD = Infinity
+  for (const c of candidates) {
+    const d = levenshtein(String(input).toLowerCase(), String(c).toLowerCase())
+    if (d < bestD) { bestD = d; best = c }
+  }
+  return (best !== null && bestD <= Math.max(1, Math.floor(String(input).length / 2))) ? best : null
+}
+
+// ── 变更名路径穿越消毒（F6）──
+// change 名会被 join 进 .sillyspec/changes/<name>/ 当目录用。若含 ../ 或路径分隔符，
+// 会逃出 changes/ 写到任意位置（如 --change ../../etc/x 把 proposal.md 写到 changes 同级之外）。
+// 在 --change 解析边界统一消毒，比在每个 join 点守卫更集中。合法名：字母/数字/._-，禁分隔符与 ..
+export function assertSafeChangeName(name, label = '变更名') {
+  if (name == null) return
+  const s = String(name)
+  if (s === '') throw new Error(`${label}不能为空`)
+  // 含路径分隔符 或 父目录穿越段 → 拒绝（Windows 下 \\ 也算）
+  if (/[\\/]/.test(s) || /(^|[/\\])\.\.(?=$|[/\\])/.test(s) || s === '..' || s.includes('..')) {
+    throw new Error(`${label}「${s}」含路径分隔符或 ..，禁止路径穿越（变更名只能是 .sillyspec/changes/ 下的一个目录名，不能逃出）`)
+  }
+  if (!/^[\w.\-]+$/.test(s)) {
+    throw new Error(`${label}「${s}」含非法字符（仅允许字母、数字、._-）`)
+  }
+}
+
 import { buildExecuteSteps } from '../stages/execute.js'
 import { buildPlanSteps } from '../stages/plan.js'
 import { stageRegistry } from '../stages/index.js'
@@ -145,6 +188,38 @@ export function parsePorcelainPath(line) {
   return path.replace(/\\/g, '/')
 }
 
+/**
+ * quick 自身写入的 .sillyspec/ 元数据判定（auditQuickCompletion 审计 与 QUICKLOG「文件：」行回填
+ * 单源）。回填文件行时复用：review.changedFiles 含这些元数据时过滤掉，只留真实业务文件。
+ *
+ * 归类口径：
+ * - quicklog/.runtime/modules/_module-map/knowledge-uncategorized 等 quick 自身产物 → 元数据
+ * - .sillyspec/changes/：quick 自己没有该目录，其下文件要么是关联变更（reverse-sync），
+ *   要么是并发他者会话的工作。非关联变更目录整体视为元数据放行；关联变更文件不算（属本 quick 真实改动）
+ *
+ * 「并发工作 vs 偷建变更」的意图软判定留给 sillyhub，确定性校验只做路径归类。
+ *
+ * @param {string} p 文件路径（容错 \\ / 混用）
+ * @param {string[]} [linkedChanges] 关联变更名列表（影响 changes/ 归类）
+ * @returns {boolean} true=quick 元数据，应从业务文件列表过滤掉
+ */
+export function isQuickMetadata(p, linkedChanges = []) {
+  const normalizeGitPath = (x) => String(x).replace(/\\/g, '/')
+  const file = normalizeGitPath(p)
+  if (file.startsWith('.sillyspec/quicklog/')
+    || file.startsWith('.sillyspec/.runtime/')
+    || file === '.sillyspec/knowledge/uncategorized.md'
+    || (/^\.sillyspec\/docs\/[^/]+\/modules\/[^/]+\.md$/.test(file))
+    || (/^\.sillyspec\/docs\/[^/]+\/modules\/_module-map\.yaml$/.test(file))) return true
+  if (file.startsWith('.sillyspec/changes/')) {
+    const linkedChangeNames = new Set((Array.isArray(linkedChanges) ? linkedChanges : []).map(c => normalizeGitPath(c)))
+    const m = file.match(/^\.sillyspec\/changes\/([^/]+)(\/|$)/)
+    // bare 折叠 token（git 把全新未跟踪 changes/ 折叠成 `changes/`）或具体但非关联的变更 → 放行
+    if (!m || !linkedChangeNames.has(m[1])) return true
+  }
+  return false
+}
+
 /**
  * quick 完成审计：对比 baseline 与实际变更。
  * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[] }}
@@ -172,26 +247,6 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       const f = normalizeGitPath(p)
       return baselineExact.has(f) || baselineDirs.some(d => f.startsWith(d))
     }
-    // quick 自己没有 .sillyspec/changes/ 目录——该路径下任何文件要么是关联变更（reverse-sync），
-    // 要么是并发其他会话的变更工作。多会话并行时别人的 changes/ 不应被本 quick 审计拦截
-    // （确定性校验无法区分「并发工作」与「本 quick 偷建变更」，后者这类意图软判定留给 sillyhub）。
-    // 故：非关联变更目录整体放行；关联变更的文件仍走正常审计（reverse-sync 可见，需 --force-baseline）。
-    const linkedChangeNames = new Set((Array.isArray(guard.linkedChanges) ? guard.linkedChanges : []).map(c => normalizeGitPath(c)))
-    const isQuickMetadata = (p) => {
-      const file = normalizeGitPath(p)
-      if (file.startsWith('.sillyspec/quicklog/')
-        || file.startsWith('.sillyspec/.runtime/')
-        || file === '.sillyspec/knowledge/uncategorized.md'
-        || (/^\.sillyspec\/docs\/[^/]+\/modules\/[^/]+\.md$/.test(file))
-        || (/^\.sillyspec\/docs\/[^/]+\/modules\/_module-map\.yaml$/.test(file))) return true
-      // .sillyspec/changes/ 下：bare 折叠 token（git 把全新未跟踪 changes/ 折叠成 `changes/`）
-      // 或具体但【非关联】的变更 → 都属并发其他会话工作，放行；关联变更文件仍走审计。
-      if (file.startsWith('.sillyspec/changes/')) {
-        const m = file.match(/^\.sillyspec\/changes\/([^/]+)(\/|$)/)
-        if (!m || !linkedChangeNames.has(m[1])) return true
-      }
-      return false
-    }
     const DANGEROUS_PATTERNS = [
       'package.json',
       'package-lock.json',
@@ -226,7 +281,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       }
 
       // 检查危险文件（除非 force-baseline）
-      if (file.startsWith('.sillyspec/') && !isQuickMetadata(file) && !forceBaseline) {
+      if (file.startsWith('.sillyspec/') && !isQuickMetadata(file, guard.linkedChanges) && !forceBaseline) {
         result.reasons.push(`危险文件变更: ${file}`)
       }
 
@@ -250,7 +305,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     // 检查 new files（除非 allow-new）
     if (!allowNew) {
       for (const f of result.newFiles) {
-        if (!isQuickMetadata(f)) {
+        if (!isQuickMetadata(f, guard.linkedChanges)) {
           result.reasons.push(`新增文件（需 --allow-new）: ${f}`)
         }
       }
@@ -259,7 +314,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     // 检查 allowedFiles 范围
     if (allowedFiles.length > 0) {
       for (const f of result.changedFiles) {
-        if (!allowedFiles.includes(f) && !isQuickMetadata(f)) {
+        if (!allowedFiles.includes(f) && !isQuickMetadata(f, guard.linkedChanges)) {
           result.reasons.push(`超出 allowedFiles: ${f}`)
         }
       }

package/src/run.js

@@ -12,8 +12,8 @@
  */
 // W6 Step8c: 主命令分发（runCommand）+ auto 模式 + ensureStageSteps 搬至 ./run/command.js
 export { runCommand, ensureStageSteps } from './run/command.js'
-// barrel re-export: parsePorcelainPath + auditQuickCompletion 被 test 直接 import（契约保留）
-export { parsePorcelainPath, auditQuickCompletion } from './run/shared.js'
+// barrel re-export: parsePorcelainPath + auditQuickCompletion + isQuickMetadata 被 test 直接 import（契约保留）
+export { parsePorcelainPath, auditQuickCompletion, isQuickMetadata } from './run/shared.js'
 // barrel re-export: applyRootPlaceholders 被 test/prompt-placeholders.test.mjs 直接 import（契约保留）
 export { applyRootPlaceholders } from './run/prompt.js'
 // barrel re-export: sanitizeProjectName + validateParsedProjects 被 test 直接 import（随 handleScan 搬走，契约保留）

package/src/stage-contract-engine.js

@@ -0,0 +1,150 @@
+/**
+ * stage-contract-engine.js — 产物字面校验通用引擎
+ *
+ * 消费 stage-contract-spec.js 的 manifest 规则,按 kind dispatch 判定,产出 {errors, warnings}。
+ * 哲学对齐 workflow.js 的 checkOutput(声明式 check + type 分发),但独立:支持 severity(error/warning)、
+ * 更丰富的纯 kind、custom kind(引擎 skip,留 validator 保留算法)。
+ *
+ * 设计原则:
+ *   - 引擎不直接碰 fs:readFile/readDir 由调用方注入(默认原生)。CRLF 归一化在调用方收敛
+ *     (plan-postcheck 注入 LF-normalizing reader),引擎拿到什么判什么,不在引擎层二次引入差异。
+ *   - regex 每次 new RegExp:manifest 存 {pattern, flags} 字符串,规避 lastIndex 状态坑
+ *     (旧代码多处 /g 正则跨调用复用需手写 lastIndex=0,是潜在 bug)。
+ *   - 内容规则(literal-any、literal-all、regex、contains-section、field-present、header-field、list-non-empty、
+ *     min-lines/no-placeholder-line)在 target 文件不存在时自动 skip(不报错)——存在性由独立的
+ *     file-exists 规则保证,避免"文件缺失"被内容规则重复报。
+ *   - custom kind 引擎 skip(不计 errors/warnings),由调用方 validator 保留判定算法,
+ *     但 import manifest 的 data + failMessage(同源)。
+ */
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { getRulesFor, isCustomKind } from './stage-contract-spec.js'
+import { hasAllSections, hasNoPlaceholderLine, meetsMinLines } from './check-primitives.js'
+
+// ============ IO 注入(默认原生 fs,调用方可替换为 normalized reader)============
+
+function defaultReadFile(absPath) {
+  if (!existsSync(absPath)) return { exists: false, content: '' }
+  return { exists: true, content: readFileSync(absPath, 'utf8') }
+}
+
+function defaultReadDir(absPath) {
+  if (!existsSync(absPath)) return { exists: false, files: [] }
+  try {
+    return { exists: true, files: readdirSync(absPath) }
+  } catch {
+    return { exists: false, files: [] }
+  }
+}
+
+const DEFAULT_IO = { readFile: defaultReadFile, readDir: defaultReadDir }
+
+// ============ target 解析 + scope 截取 ============
+
+function resolveTargetPath(target, ctx) {
+  if (!target || !target.path) return null
+  switch (target.root) {
+    case 'change': return ctx.changeDir ? join(ctx.changeDir, target.path) : null
+    case 'docs': return ctx.docsRoot ? join(ctx.docsRoot, target.path) : null
+    case 'archive': return ctx.archiveDir ? join(ctx.archiveDir, target.path) : null
+    case 'specBase': return ctx.specBase ? join(ctx.specBase, target.path) : null
+    default: return null
+  }
+}
+
+/** 按 scope 截取文本:full=全文 / head=前 512 字节(对齐 scan-postcheck header 切片)/ fm=frontmatter 块内容 */
+function sliceScope(content, scope) {
+  if (!scope || scope === 'full') return content
+  if (scope === 'head') return content.slice(0, 512)
+  if (scope === 'fm') {
+    const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+    return m ? m[1] : ''
+  }
+  return content
+}
+
+// ============ 纯 kind dispatch ============
+
+function dispatchPure(rule, entry) {
+  const { exists, content } = entry
+  // 存在性 kind:不存在即 fail
+  if (rule.kind === 'file-exists' || rule.kind === 'dir-exists') return exists
+  // 其余为内容规则:文件不存在 → skip(通过,存在性由 file-exists 规则保证)
+  if (!exists) return true
+  const scoped = sliceScope(content, rule.target && rule.target.scope)
+  switch (rule.kind) {
+    case 'literal-any': return (rule.data.literals || []).some(s => scoped.includes(s))
+    case 'literal-all': return (rule.data.literals || []).every(s => scoped.includes(s))
+    case 'regex': return new RegExp(rule.data.pattern, rule.data.flags || '').test(scoped)
+    case 'contains-section': return hasAllSections(scoped, rule.data.sections || [])
+    case 'no-placeholder-line': return hasNoPlaceholderLine(scoped, rule.data.patterns)
+    case 'field-present':
+      // frontmatter 字段:行首 `<field>:`(与 plan-postcheck /^goal:/m 一致,字段名为固定标识符无正则元字符)
+      return (rule.data.fields || []).every(f => new RegExp(`^${f}:`, 'm').test(scoped))
+    case 'header-field':
+      // 头部 N 字节内含 `<field>:`(对齐 scan-postcheck/complete.js author:/created_at: 检查)
+      return (rule.data.fields || []).every(f => scoped.includes(`${f}:`))
+    case 'list-non-empty':
+      // 至少一行 trim 后以 - / * / 数字. 开头(逐字对齐 validateBrainstormOutputs tasks.md 检查)
+      return scoped.split(/\r?\n/).some(l => {
+        const t = l.trim()
+        return t.startsWith('-') || t.startsWith('*') || /^\d+\./.test(t)
+      })
+    case 'min-lines': return meetsMinLines(scoped, rule.data.min || 1)
+    default: return true  // 未知纯 kind,放过(不阻断),避免新 kind 上线时误杀
+  }
+}
+
+function checkDirNonEmpty(rule, absPath, readDir) {
+  const { exists, files } = readDir(absPath)
+  if (!exists) return false
+  const glob = rule.data.glob || '.md'
+  const min = rule.data.min || 1
+  return files.filter(f => f.endsWith(glob)).length >= min
+}
+
+// ============ 报错文案格式化 ============
+
+/** failMessage 里的 ${path} 占位 → 替换为解析后的绝对路径(与旧 validator join(changeDir, file) 文案一致)。 */
+function formatFail(failMessage, absPath) {
+  return failMessage && failMessage.includes('${path}')
+    ? failMessage.replace('${path}', absPath)
+    : failMessage
+}
+
+// ============ 主入口 ============
+
+/**
+ * 对某 stage 的全部纯 kind 规则跑判定。custom kind / target 基缺失 / enabled=false 的规则计入 skipped。
+ *
+ * @param {string} stage
+ * @param {{ changeDir?: string, docsRoot?: string, archiveDir?: string, specBase?: string }} ctx
+ * @param {{ readFile?: Function, readDir?: Function }} [io]  默认原生 fs;plan-postcheck 可注入 CRLF-normalizing reader
+ * @returns {{ ok: boolean, errors: string[], warnings: string[], applied: string[], skipped: string[] }}
+ */
+export function evaluateRules(stage, ctx, io, opts = {}) {
+  const readFile = (io || DEFAULT_IO).readFile || defaultReadFile
+  const readDir = (io || DEFAULT_IO).readDir || defaultReadDir
+  const errors = []
+  const warnings = []
+  const applied = []
+  const skipped = []
+
+  for (const rule of getRulesFor(stage, { source: opts.source })) {
+    if (rule.enabled === false) { skipped.push(rule.id); continue }
+    if (isCustomKind(rule.kind)) { skipped.push(rule.id); continue }
+    const absPath = resolveTargetPath(rule.target, ctx)
+    if (absPath == null) { skipped.push(rule.id); continue }
+
+    const ok = rule.kind === 'dir-non-empty'
+      ? checkDirNonEmpty(rule, absPath, readDir)
+      : dispatchPure(rule, readFile(absPath))
+
+    applied.push(rule.id)
+    if (!ok) {
+      (rule.severity === 'error' ? errors : warnings).push(formatFail(rule.failMessage, absPath))
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings, applied, skipped }
+}