sillyspec 3.27.6 → 3.27.7

package/.worktrees/2c37b1d7/src/spec-dir-typo.js

@@ -0,0 +1,50 @@
+/**
+ * SillySpec spec 目录拼写变体检测
+ *
+ * review.json missing 时调用：检测 SPEC_ROOT 父目录下是否存在 .sillyspec 的
+ * 近似拼写变体目录（如 .silyspec / .sillyspc），命中则提示「路径疑似拼错」。
+ *
+ * 触发场景：agent/用户手动创建 review.json 时把 .sillyspec 拼错（少 l / 多 k 等），
+ * 文件落到变体目录，CLI 按规范名找不到。给一条模糊匹配提示比静默报 missing 友好。
+ *
+ * 放独立模块（而非 stage-review.js / task-review.js 内联）的原因：两者已存在
+ * stage-review → task-review 的常量依赖，反向 import 会形成循环依赖。
+ */
+
+import { dirname, basename, join } from 'path'
+import { readdirSync } from 'fs'
+// levenshtein 单一实现收敛到 run/shared.js（原本地副本与 shared.js 逐行相同）；
+// shared.js 不静态 import review 族，此处引入不成环
+import { levenshtein } from './run/shared.js'
+
+/**
+ * 检测 spec 目录拼写变体。
+ * @param {string} runtimeRoot — .runtime 目录绝对路径（= <SPEC_ROOT>/.runtime）
+ * @returns {{ typoDir: string, canonical: string } | null} 命中返回变体目录与规范名，否则 null
+ */
+export function detectSpecDirTypo(runtimeRoot) {
+  if (!runtimeRoot) return null
+  // runtimeRoot = <SPEC_ROOT>/.runtime → SPEC_ROOT = dirname(runtimeRoot)
+  const specRoot = dirname(runtimeRoot)
+  const parent = dirname(specRoot)
+  const canonical = basename(specRoot) // 期望 '.sillyspec'
+  if (!canonical.startsWith('.')) return null // 非隐藏目录命名，跳过（避免误报）
+
+  let siblings = []
+  try {
+    siblings = readdirSync(parent, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && d.name.startsWith('.') && !d.name.startsWith('..') && d.name !== canonical)
+      .map((d) => d.name)
+  } catch {
+    return null
+  }
+  if (siblings.length === 0) return null
+
+  // 编辑距离 ≤2 视为拼写变体（覆盖少 l / 多 k / 漏字母等常见笔误）
+  const typo = siblings.find((name) => {
+    const dist = levenshtein(name, canonical)
+    return dist > 0 && dist <= 2
+  })
+  if (!typo) return null
+  return { typoDir: join(parent, typo), canonical }
+}

package/.worktrees/2c37b1d7/src/spec-sync.js

@@ -0,0 +1,358 @@
+/**
+ * CLI 直跑 spec 文件增量同步模块。
+ *
+ * Change 2026-08-17-spec-file-incremental-sync：daemon↔后端已有增量同步协议，但 CLI
+ * 直跑场景（本地 agent 直接跑 sillyspec 无 daemon）只有四件套直推到 documents 列。
+ * 本模块补齐 CLI 直跑的文件树增量同步：以服务器清单为锚，walk/hash/diff 后只推送
+ * 变化文件（add/update/delete/rename），无差异时短路不发请求。
+ *
+ * 复用 daemon 已验证的排除口径（UPLOAD_EXCLUDE_TOP_BASE / UPLOAD_PRUNE_NAMES_BASE），
+ * 与 daemon 共用同一套清单语义（base_version 乐观锁、conflict 提示但不阻塞）。
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'fs';
+import { join, relative, sep } from 'path';
+
+// 与 sillyhub-daemon/src/spec-sync.ts 共用排除口径（task-07 / FR-06 / D-008@v2）：
+// .runtime（有点）/ runtime（无点）/ projects（本地环境文件）在顶层排除；
+// worktrees 在任意深度按 basename 剪枝（可能嵌在 .runtime/worktrees 下）。
+const UPLOAD_EXCLUDE_TOP_BASE = new Set(['.runtime', 'runtime', 'projects']);
+const UPLOAD_PRUNE_NAMES_BASE = new Set(['worktrees']);
+// ql-20260818-002：local.yaml 是本机连接配置（platform/mcp 段含 shpsync_ token），
+// 不上传——与服务器侧过滤（backend spec_workspace SERVER_EXCLUDED_FILENAMES）双侧
+// 对齐。服务器清单残留 local.yaml 行时，本地 walk 不含它 → 生成 delete op，
+// 服务器放行 delete 清存量（token 不落 landing 树、不随 bundle 跨机分发）。
+const UPLOAD_EXCLUDE_FILENAMES = new Set(['local.yaml']);
+
+function isUploadExcludedPath(relPath) {
+  const segs = relPath.split('/');
+  if (UPLOAD_EXCLUDE_TOP_BASE.has(segs[0] ?? '')) return true;
+  if (UPLOAD_EXCLUDE_FILENAMES.has(segs[segs.length - 1] ?? '')) return true;
+  return segs.some((s) => UPLOAD_PRUNE_NAMES_BASE.has(s));
+}
+
+function toPosix(p) {
+  return p.replace(/\\/g, '/');
+}
+
+function debugLog(msg) {
+  if (process.env.SILLYSPEC_DEBUG_SYNC) console.warn(msg);
+}
+
+function _hashBuffer(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * 单遍 walk 本地 .sillyspec 树。
+ *
+ * 返回 { path, absPath, mtimeMs } 列表；path 已统一为 POSIX。
+ * 不收集目录项（只关心文件）；命中排除规则的路径直接跳过不递归。
+ */
+export function walkSpecTree(specRoot) {
+  const out = [];
+  if (!existsSync(specRoot)) return out;
+
+  function recurse(dir) {
+    let names;
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const abs = join(dir, name);
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      const relToRoot = toPosix(relative(specRoot, abs));
+      if (isUploadExcludedPath(relToRoot)) continue;
+      // pruneNames：任意深度按 basename 命中即不收集/不递归
+      if (UPLOAD_PRUNE_NAMES_BASE.has(name)) continue;
+
+      if (st.isDirectory()) {
+        recurse(abs);
+      } else if (st.isFile()) {
+        out.push({ path: relToRoot, absPath: abs, mtimeMs: st.mtimeMs });
+      }
+      // symlink / 其他：跳过
+    }
+  }
+
+  recurse(specRoot);
+  return out;
+}
+
+/**
+ * 计算本地文件哈希。
+ *
+ * 返回 { path, hash, mtime, absPath }（mtime 为 Unix 秒，供 os.utime；absPath
+ * 保留给 computeSpecOps 读 content 用，避免按相对路径回退错位）。
+ */
+export function hashFiles(entries) {
+  return entries.map((e) => {
+    const buf = readFileSync(e.absPath);
+    return {
+      path: e.path,
+      hash: _hashBuffer(buf),
+      mtime: Math.floor(e.mtimeMs / 1000),
+      absPath: e.absPath,
+    };
+  });
+}
+
+/**
+ * 根据服务器清单与本地文件差异生成 FileOp[]。
+ *
+ * 服务器清单格式：{ [path]: { hash, version, exists } }
+ * 本地文件格式：hashFiles 结果 { path, hash, mtime }
+ *
+ * 规则（与 daemon computeIncrementalOps 对齐）：
+ * - 本地有、服务器无 → add（base_version=0）
+ * - 服务器有 exists=true、本地无 → delete（base_version=服务器 version）
+ * - 服务器有 exists=false、本地无 → 不生成 delete（已软删）
+ * - 同路径 hash 不同 → update（base_version=服务器 version）
+ * - 服务器旧路径有、本地新路径有且 hash 相同 → rename（base_version=服务器旧路径 version）
+ */
+export function computeSpecOps(serverManifest, localFiles) {
+  const server = serverManifest || {};
+  const localMap = new Map(localFiles.map((f) => [f.path, f]));
+  const localSet = new Set(localMap.keys());
+
+  // 只拿服务器 exists=true 的行参与 diff；exists=false 视为已删除，不生成 delete
+  const serverPaths = Object.keys(server).filter((p) => server[p]?.exists !== false);
+  const serverSet = new Set(serverPaths);
+
+  // fail-closed 护栏（2026-08-20 全量体检 BUG-01）：本地树为空而服务器非空时，
+  // 全量 delete 几乎必然是「锚错了目录」（如平台模式 cwd/.sillyspec 只剩 local.yaml
+  // 被 walk 排除），而不是用户真的删光了所有文件——一旦发出就是服务器整树清空。
+  // 唯一放行：服务器只剩 local.yaml 存量（顶层单文件），保留「delete 清 token 存量」
+  // 的既定语义（见 UPLOAD_EXCLUDE_FILENAMES 注释）。真实清空需求需本地树非空逐轮收敛。
+  const nonTrivialServer = serverPaths.filter((p) => p !== 'local.yaml');
+  if (localFiles.length === 0 && nonTrivialServer.length > 0) {
+    console.warn(
+      `[spec-sync] 本地 spec 树为空但服务器有 ${serverPaths.length} 个文件，跳过同步（防误清空；请检查 spec 目录锚点）`
+    );
+    return [];
+  }
+
+  // rename 检测：旧路径（服务器有、本地无）↔ 新路径（本地有、服务器无）hash 相同
+  const renames = [];
+  const consumedNew = new Set();
+  for (const oldPath of serverPaths) {
+    if (localSet.has(oldPath)) continue;
+    const cachedEntry = server[oldPath];
+    for (const newPath of localMap.keys()) {
+      if (serverSet.has(newPath)) continue;
+      if (consumedNew.has(newPath)) continue;
+      if (localMap.get(newPath).hash === cachedEntry.hash) {
+        renames.push({ oldPath, newPath });
+        consumedNew.add(newPath);
+        break;
+      }
+    }
+  }
+  const renamedOld = new Set(renames.map((r) => r.oldPath));
+  const renamedNew = new Set(renames.map((r) => r.newPath));
+
+  const ops = [];
+
+  for (const r of renames) {
+    ops.push({
+      op: 'rename',
+      path: r.oldPath,
+      new_path: r.newPath,
+      base_version: server[r.oldPath].version,
+    });
+  }
+
+  for (const p of serverPaths) {
+    if (renamedOld.has(p)) continue;
+    if (localSet.has(p)) {
+      const localEntry = localMap.get(p);
+      if (localEntry.hash !== server[p].hash) {
+        const content = readFileSync(localEntry.absPath ?? join('.', p)).toString('base64');
+        ops.push({
+          op: 'update',
+          path: p,
+          hash: localEntry.hash,
+          content,
+          base_version: server[p].version,
+          mtime: localEntry.mtime,
+        });
+      }
+    } else {
+      ops.push({
+        op: 'delete',
+        path: p,
+        base_version: server[p].version,
+      });
+    }
+  }
+
+  for (const p of localMap.keys()) {
+    if (renamedNew.has(p)) continue;
+    if (!serverSet.has(p)) {
+      const localEntry = localMap.get(p);
+      const content = readFileSync(localEntry.absPath ?? join('.', p)).toString('base64');
+      ops.push({
+        op: 'add',
+        path: p,
+        hash: localEntry.hash,
+        content,
+        base_version: 0,
+        mtime: localEntry.mtime,
+      });
+    }
+  }
+
+  return ops;
+}
+
+/**
+ * 从 ops 提取本次涉及的变更目录名集合（change_dirs 标注，D-005@v1）。
+ *
+ * 对每个 op 的 path（rename 含新旧 path），取 `changes/<name>/` 或
+ * `changes/archive/<name>/` 前缀分组的 key（去掉前缀、取第一段目录名），去重。
+ * 非 changes 前缀路径不进结果。best-effort，失败降级 []。
+ */
+export function extractChangeDirs(ops) {
+  const dirs = new Set();
+  for (const op of ops) {
+    collectChangeDir(dirs, op.path);
+    if (op.new_path) collectChangeDir(dirs, op.new_path);
+  }
+  return [...dirs];
+}
+
+function collectChangeDir(dirs, p) {
+  const norm = p.split(/[\\/]/).join('/');
+  let rest = null;
+  if (norm.startsWith('changes/')) {
+    rest = norm.slice('changes/'.length);
+  } else if (norm.startsWith('changes\\')) {
+    rest = norm.slice('changes\\'.length).replace(/\\/g, '/');
+  }
+  if (!rest) return;
+
+  if (rest.startsWith('archive/')) {
+    rest = rest.slice('archive/'.length);
+  }
+  const first = rest.split('/', 1)[0];
+  if (first && first !== 'archive' && !first.includes('/')) {
+    dirs.add(first);
+  }
+}
+
+/**
+ * 同步本地 .sillyspec 树到平台（CLI 直跑增量同步入口）。
+ *
+ * @param {string} specRoot - 本地 .sillyspec 目录绝对路径
+ * @param {object} platform - { url, token }
+ * @param {string} changeName - 当前变更名
+ * @returns {Promise<{synced: number, conflict?: boolean, serverVersions?: object}>}
+ */
+export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
+  if (!platform || !platform.url || !platform.token) {
+    debugLog('[spec-sync] 未连接平台（本地合法状态）；跳过 spec 树增量同步');
+    return { synced: 0 };
+  }
+  // HUB-09：单请求超时与外部熔断 signal 合并——trigger* 熔断时在飞请求被真实取消
+  const withSignal = (timeoutMs) => (opts.signal ? AbortSignal.any([AbortSignal.timeout(timeoutMs), opts.signal]) : AbortSignal.timeout(timeoutMs));
+
+  const manifestUrl = `${platform.url.replace(/\/$/, '')}/api/changes/-/spec-manifest`;
+  const syncUrl = `${platform.url.replace(/\/$/, '')}/api/changes/-/spec-sync`;
+
+  // 1. GET 服务器清单
+  let serverManifest = {};
+  try {
+    const res = await fetch(manifestUrl, {
+      headers: { Authorization: `Bearer ${platform.token}` },
+      signal: withSignal(10000),
+    });
+    if (!res.ok) {
+      // ql-20260818-008：debugLog → console.warn。树同步失败原本完全静默（要
+      // SILLYSPEC_DEBUG_SYNC=1 才可见），文件迟到平台且无任何线索（multi-agent-platform
+      // 2026-08-18-workspace-file-browser 实证：design/decisions 迟到 27 分钟、plan.md 迟到
+      // 8 分钟才被后续步骤的同步补上）。失败可见、成功不打扰。
+      console.warn(`[spec-sync] 拉取清单失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）: ${changeName}`);
+      return { synced: 0 };
+    }
+    const body = await res.json().catch(() => ({}));
+    serverManifest = body.files || {};
+  } catch (err) {
+    console.warn(`[spec-sync] 拉取清单异常（文件树本次未同步，下次自动重试）: ${changeName}: ${err.message}`);
+    return { synced: 0 };
+  }
+
+  // 2. walk/hash/diff
+  const entries = walkSpecTree(specRoot);
+  const localFiles = hashFiles(entries);
+  const ops = computeSpecOps(serverManifest, localFiles);
+
+  if (ops.length === 0) {
+    debugLog(`[spec-sync] 无差异，跳过同步: ${changeName}`);
+    return { synced: 0 };
+  }
+
+  // 3. POST ops
+  try {
+    const res = await fetch(syncUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${platform.token}`,
+      },
+      body: JSON.stringify({ ops }),
+      signal: withSignal(30000),
+    });
+    if (!res.ok) {
+      console.warn(`[spec-sync] 同步请求失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）: ${changeName}`);
+      return { synced: 0 };
+    }
+    const body = await res.json().catch(() => ({}));
+    if (body.conflict) {
+      // HUB-08 冲突闭环：落 spec-sync-conflict-<change>.json（与进度 sync-conflict-* 同目录），
+      // 供 platform status 列出 + platform resolve 三态处置。此前只 warn 返回，下次 sync 用
+      // 同一 base_version 继续冲突循环，无人工裁决入口。
+      const serverVersions = body.server_versions || {};
+      let conflictPath = null;
+      try {
+        const runtimeDir = join(specRoot, '.runtime');
+        mkdirSync(runtimeDir, { recursive: true });
+        conflictPath = join(runtimeDir, `spec-sync-conflict-${changeName}.json`);
+        writeFileSync(conflictPath, JSON.stringify({
+          change: changeName,
+          kind: 'spec-tree',
+          created_at: new Date().toISOString(),
+          server_versions: serverVersions,
+          conflicting_paths: Object.keys(serverVersions),
+          note: 'spec 树文件冲突（服务器版本领先于本地 diff 基线）。resolve --keep-local 以本地为准重推；--take-platform 暂不支持（平台无文件下载端点）',
+        }, null, 2) + '\n', 'utf8');
+      } catch (e) {
+        console.warn(`[spec-sync] 冲突文件写入失败（冲突信息仅打印）: ${e.message}`);
+      }
+      console.warn('');
+      console.warn(`⚠️ [spec-sync] 检测到 spec 树冲突（${Object.keys(serverVersions).length} 个文件，服务器版本: ${JSON.stringify(serverVersions)}）`);
+      console.warn(`⚠️ 处置：sillyspec platform resolve ${changeName} --keep-local | --abort（冲突详情: ${conflictPath || '(写入失败)'}）`);
+      return { synced: 0, conflict: true, serverVersions, conflictPath };
+    }
+    console.log(`[spec-sync] 已同步 ${ops.length} 个文件变更: ${changeName}`);
+    return { synced: ops.length };
+  } catch (err) {
+    console.warn(`[spec-sync] 同步异常（文件树本次未同步，下次自动重试）: ${changeName}: ${err.message}`);
+    return { synced: 0 };
+  }
+}
+
+export default {
+  walkSpecTree,
+  hashFiles,
+  computeSpecOps,
+  extractChangeDirs,
+  syncSpecTree,
+};

package/.worktrees/2c37b1d7/src/stage-contract-engine.js

@@ -0,0 +1,171 @@
+/**
+ * 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
+}
+
+/**
+ * 规则条件判定：condition 不满足时规则跳过(同 enabled=false)。
+ * 用于「某规则仅在特定上下文生效」——如 brainstorm 的 proposal/requirements/tasks 仅在 scale≠small 时必需
+ * (小变更 scale=small 只产 design.md，见 BRAINSTORM_RULES)。
+ *
+ * condition schema: { ctxField: '<ctx 键名>', ne|eq: <值> }
+ *   - ne: ctx[ctxField] !== ne 时条件成立(规则适用);相等则跳过
+ *   - eq: ctx[ctxField] === eq 时条件成立;否则跳过
+ * fail-safe：ctx 或 ctxField 缺失 → ne 判定为「undefined !== ne 值」成立(eq 不成立)，
+ *   即 scale 读不到时四件套仍全要求(保守默认，走重流程)，不会因 condition 误放开必填项。
+ */
+function conditionHolds(condition, ctx) {
+  if (!condition) return true
+  const actual = ctx ? ctx[condition.ctxField] : undefined
+  if ('ne' in condition) return actual !== condition.ne
+  if ('eq' in condition) return actual === condition.eq
+  return true  // 未知操作符,放过(不阻断),避免新操作符上线时误杀
+}
+
+// ============ 主入口 ============
+
+/**
+ * 对某 stage 的全部纯 kind 规则跑判定。custom kind / target 基缺失 / enabled=false 的规则计入 skipped。
+ *
+ * @param {string} stage
+ * @param {{ changeDir?: string, docsRoot?: string, archiveDir?: string, specBase?: string, scale?: string }} ctx
+ *        规则 target.root 解析基目录;额外字段(如 scale)供 rule.condition 按 ctxField 判定(见 conditionHolds)
+ * @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 (rule.condition && !conditionHolds(rule.condition, ctx)) { 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 }
+}