sillyspec 3.26.14 → 3.27.1

package/src/doctor-diagnostics.js

@@ -582,6 +582,57 @@ function detectExecuteProgressPlanMismatch(authoritySpecRoot, authDb) {
 
 // ── 主入口 ────────────────────────────────────────────────────────────
 
+// ── 文档膨胀检测（token 成本优化 P0b/P2b，2026-08-22-token-cost-optimization）──
+// 模块卡与 knowledge/uncategorized.md 是每个 task 子代理的重复读取税：实测 backend.md
+// 18 天 15KB→55KB（变更索引段每变更追加、单调膨胀）、uncategorized.md 38KB 从未迁出。
+// 只读软检查（WARNING 级，不阻断）：超限给 safe_action 指路，不自动改文件。
+
+/** 模块卡整卡可读软上限（字节），与 module-resolve.js MODULE_CARD_SOFT_LIMIT_BYTES 同值 */
+const DOC_BLOAT_MODULE_CARD_LIMIT = 12 * 1024;
+/** knowledge/uncategorized.md 软上限（字节）——待确认条目应经知识审阅迁移，不该只增不减 */
+const DOC_BLOAT_UNCATEGORIZED_LIMIT = 20 * 1024;
+
+export function detectDocBloat(specRoot) {
+  const dim = { name: 'doc_bloat', label: '文档膨胀（模块卡/知识库读取税）', safe_actions: [] };
+  const findings = [];
+  if (!specRoot || !existsSync(specRoot)) {
+    return { ...dim, findings: ['无可达 specRoot，跳过文档膨胀检测'], pass: true, severity: null };
+  }
+  // 模块卡：docs/<p>/modules/*.md（排除 _module-map.yaml 与 *.changelog.md sidecar）
+  try {
+    for (const proj of readdirSync(join(specRoot, 'docs'), { withFileTypes: true })) {
+      if (!proj.isDirectory()) continue;
+      const modulesDir = join(specRoot, 'docs', proj.name, 'modules');
+      if (!existsSync(modulesDir)) continue;
+      for (const f of readdirSync(modulesDir)) {
+        if (!f.endsWith('.md') || f === '_module-map.yaml' || f.endsWith('.changelog.md')) continue;
+        const size = statSync(join(modulesDir, f)).size;
+        if (size > DOC_BLOAT_MODULE_CARD_LIMIT) {
+          findings.push(`模块卡超软上限 ${DOC_BLOAT_MODULE_CARD_LIMIT / 1024}KB：docs/${proj.name}/modules/${f}（${(size / 1024).toFixed(1)}KB）——子代理每次整读都是读取税`);
+        }
+      }
+    }
+  } catch { /* docs 不可读 → 跳过该项 */ }
+  if (findings.length > 0) {
+    dim.safe_actions.push({ action: '跑 sillyspec modules split-changelog（先 dry-run 预览，确认后 --force）把「变更索引」历史段迁出大卡', risk: 'low' });
+  }
+  // knowledge/uncategorized.md
+  try {
+    const uncPath = join(specRoot, 'knowledge', 'uncategorized.md');
+    if (existsSync(uncPath)) {
+      const size = statSync(uncPath).size;
+      if (size > DOC_BLOAT_UNCATEGORIZED_LIMIT) {
+        findings.push(`knowledge/uncategorized.md 超软上限 ${DOC_BLOAT_UNCATEGORIZED_LIMIT / 1024}KB（${(size / 1024).toFixed(1)}KB）——已确认/已修复条目应迁入专题文件后从待确认清单删除，而非只增不减`);
+        dim.safe_actions.push({ action: 'execute 末步「知识库审阅」把已确认条目归档迁出 uncategorized.md（迁入专题文件后删除原条目）', risk: 'low' });
+      }
+    }
+  } catch { /* knowledge 不可读 → 跳过该项 */ }
+
+  dim.findings = findings;
+  return findings.length === 0
+    ? { ...dim, findings: ['模块卡与知识库体量在软限内'], pass: true, severity: CHECK_SEVERITY.PASSED }
+    : { ...dim, pass: false, severity: CHECK_SEVERITY.WARNING };
+}
 export async function runDoctorDiagnostics({ cwd }) {
   const pointer = resolvePointer(cwd);
   const multiDb = detectMultiDb(cwd, pointer);
@@ -598,8 +649,9 @@ export async function runDoctorDiagnostics({ cwd }) {
         : null;
   const authDb = (multiDb.dbs || []).find((d) => d.role === DB_ROLE.AUTHORITY);
   const executeMismatch = detectExecuteProgressPlanMismatch(authoritySpecDir, authDb);
+  const docBloat = detectDocBloat(authoritySpecDir);
 
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch];
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat];
 
   return {
     dimensions,
@@ -836,6 +888,7 @@ export async function cleanupGhostChanges({ cwd, specDir = null, confirm = false
 
   let db = null;
   const archived = [];
+  const finalized = [];
   const errors = [];
   const skippedNonEmpty = [];
   const removedDirs = [];
@@ -850,9 +903,56 @@ export async function cleanupGhostChanges({ cwd, specDir = null, confirm = false
     if (confirm) {
       const now = new Date().toISOString();
       const stmt = db.prepare("UPDATE changes SET status = 'archived', last_active = ? WHERE name = ? AND status = 'active'");
+      // 终态一致化（坑 manual-archive-desync-status-only，2026-08-21 实证）：手动搬目录到 archive/
+      // 绕过标准归档的变更在此被当幽灵归档——只翻 status 会留「已归档 + current_stage 停留 +
+      // 归档 0/5」的矛盾终态，平台渲染成「进度丢失」。有 archive/ 实体证据的幽灵同步收尾
+      // archive 阶段（current_stage/stages/steps）；目录真丢失（无实体证据）保持 status-only
+      //（收尾=宣称归档完成属伪造，保持可逆的原语义）。步骤名取 stageRegistry 单一真相。
+      const { stageRegistry } = await import('./stages/index.js').catch(() => ({ stageRegistry: null }));
+      const archiveStepNames = Array.isArray(stageRegistry?.archive?.steps)
+        ? stageRegistry.archive.steps.map(s => s.name) : [];
+      const archiveDir = join(changesDir, 'archive');
+      const finalizeTerminal = (name) => {
+        if (archiveStepNames.length === 0) return false;
+        try {
+          const row = db.prepare('SELECT id FROM changes WHERE name = ?').get(name);
+          if (!row) return false;
+          db.prepare("UPDATE changes SET current_stage = 'archive' WHERE id = ?").run(row.id);
+          db.prepare(
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at)
+             VALUES (?, 'archive', 'completed', ?, ?)
+             ON CONFLICT(change_id, stage) DO UPDATE SET status = 'completed', completed_at = excluded.completed_at`
+          ).run(row.id, now, now);
+          const stageRow = db.prepare('SELECT id FROM stages WHERE change_id = ? AND stage = ?').get(row.id, 'archive');
+          if (!stageRow) return false;
+          db.prepare('UPDATE steps SET status = ?, completed_at = ? WHERE stage_id = ?').run('completed', now, stageRow.id);
+          const existing = new Set(
+            db.prepare('SELECT name FROM steps WHERE stage_id = ?').all(stageRow.id).map(r => r.name)
+          );
+          let order = existing.size;
+          const ins = db.prepare(
+            `INSERT INTO steps (stage_id, name, status, completed_at, ordering) VALUES (?, ?, 'completed', ?, ?)`
+          );
+          for (const sn of archiveStepNames) {
+            if (!existing.has(sn)) ins.run(stageRow.id, sn, now, order++)
+          }
+          return true;
+        } catch { return false }
+      };
       for (const n of ghosts) {
         try {
           stmt.run(now, n);
+          // 手动归档证据：changes/archive/ 下有该变更目录 → 一并收尾终态
+          const archivedEvidence = (() => {
+            try {
+              if (!existsSync(archiveDir)) return false;
+              return readdirSync(archiveDir).some(e => e === n && existsSync(join(archiveDir, e, 'plan.md')))
+                || readdirSync(archiveDir).some(e => e.startsWith(n) && existsSync(join(archiveDir, e, 'plan.md')));
+            } catch { return false }
+          })();
+          if (archivedEvidence && finalizeTerminal(n)) {
+            finalized.push(n);
+          }
           archived.push(n);
         } catch (e) {
           errors.push({ name: n, error: e.message });
@@ -886,6 +986,7 @@ export async function cleanupGhostChanges({ cwd, specDir = null, confirm = false
       skipped_nonempty: skippedNonEmpty,
       removed_dirs: removedDirs,
       archived,
+      finalized, // 手动归档型幽灵已同步收尾 archive 阶段终态（坑 manual-archive-desync-status-only）
       errors,
       count: ghosts.length + emptyShells.length,
       active_after: activeAfter,

package/src/endpoint-extractor.js

@@ -160,8 +160,13 @@ export function extractSpringEndpoints(filePath) {
  * @returns {Array<{ method: string, path: string, source: string, line: number }>}
  */
 export function scanBackendEndpoints(dir, opts = {}) {
+  // 排除清单对齐 scanFrontendApiCalls（坑 parity-scan-stale-dirs：.claude/worktrees 陈旧检出
+  // 与各类 build 产物混入端点扫描全是噪音）——backend 侧另含 __pycache__/.gradle/maven target
   const excludePatterns = opts.excludePatterns || [
-    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^\.git$/, /^\.gradle$/,
+    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^venv$/, /^\.git$/, /^\.gradle$/,
+    /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/, /^\.next$/, /^\.nuxt$/,
+    /^\.output$/, /^\.turbo$/, /^\.parcel-cache$/, /^coverage$/,
+    /^\.sillyspec$/, /^\.worktrees$/, /^\.d\.ts$/,
     /^(dist|build|target|out)$/i,
     /test/i,
   ]
@@ -273,7 +278,19 @@ export function extractFrontendApiCalls(filePath) {
  */
 export function scanFrontendApiCalls(dir, opts = {}) {
   const filePattern = opts.filePattern || /\.(ts|tsx|js|jsx)$/
-  const excludePatterns = opts.excludePatterns || [/node_modules/, /\.next/, /dist/, /__tests__/, /\.d\.ts$/]
+  // 排除清单（坑 parity-scan-stale-dirs，2026-08-21 实证：扫进 .claude/worktrees/agent-* 陈旧
+  // 检出与 build 产物，872 条调用全是噪音）——目录名匹配，覆盖：
+  //   版本控制/编辑器：.git .claude（含 worktrees/agent-* 陈旧检出）.vscode .idea .cursor
+  //   构建产物：dist build out .next .nuxt .output .turbo .parcel-cache coverage
+  //   依赖/运行时：node_modules .venv venv target（rust/java）__pycache__
+  //   本工具自身：.sillyspec .sillyspec-platform.json 所在 .worktrees
+  // 文件级：.d.ts 声明、*.min.js / *.bundle.js 压缩产物（正则命中即跳）
+  const excludePatterns = opts.excludePatterns || [
+    /^node_modules$/, /^\.git$/, /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/,
+    /^dist$/, /^build$/, /^out$/, /^\.next$/, /^\.nuxt$/, /^\.output$/, /^\.turbo$/,
+    /^\.parcel-cache$/, /^coverage$/, /^\.venv$/, /^venv$/, /^target$/, /^__pycache__$/,
+    /^\.sillyspec$/, /^\.worktrees$/, /^__tests__$/, /^\.d\.ts$/,
+  ]
 
   const results = []
   if (!existsSync(dir)) return results
@@ -285,6 +302,8 @@ export function scanFrontendApiCalls(dir, opts = {}) {
         if (excludePatterns.some(p => p.test(entry.name))) continue
         walk(full)
       } else if (entry.isFile() && filePattern.test(entry.name)) {
+        if (/\.d\.ts$/.test(entry.name)) continue
+        if (/\.min\.(js|ts)$/.test(entry.name) || /\.bundle\.(js|ts)$/.test(entry.name)) continue
         try {
           results.push(...extractFrontendApiCalls(full))
         } catch {}

package/src/fs-atomic.js

@@ -8,6 +8,7 @@
  * 不经此处的 writeAtomicSync；sillyspec.db 不走原子写改名。
  */
 import { writeFileSync, renameSync, unlinkSync } from 'fs';
+import { randomBytes } from 'node:crypto';
 import { dirname, basename, join } from 'path';
 
 // Windows 上杀毒 / 索引 / IDE 占用文件时，rename 偶发这些错误，短退避重试即可
@@ -58,8 +59,9 @@ export function renameSyncRetry(from, to, retries = 5) {
  */
 export function writeAtomicSync(filePath, content) {
   const dir = dirname(filePath);
-  // pid + 随机段双因子：Windows PID 重用激进，两进程可能撞同 pid，tmp 名碰撞 rename 互相覆盖
-  const rnd = Math.random().toString(36).slice(2, 10);
+  // pid + 随机段双因子：Windows PID 重用激进，两进程可能撞同 pid，tmp 名碰撞 rename 互相覆盖。
+  // crypto 随机源（Math.random 可预测，tmp 名被预猜中有 symlink 预放置理论面）
+  const rnd = randomBytes(6).toString('hex');
   const tmpPath = join(dir, `.${basename(filePath)}.${process.pid}.${rnd}.tmp`);
   writeFileSync(tmpPath, content);
   try {

package/src/git-helper.js

@@ -14,6 +14,69 @@
  */
 import { execFileSync } from 'node:child_process'
 
+/**
+ * git C 风格引号路径解码：`\\` `\"` `\n` `\t` 与 `\NNN` 八进制**原始字节**。
+ * 八进制转义的字节需聚合后按 UTF-8 解码（quotepath 关闭前非 ASCII 整段转义、
+ * 关闭后控制字符路径仍会转义），逐字节单独 toString 会拆出 U+FFFD。
+ * @param {string} s 已去外层引号的内容
+ * @returns {string}
+ */
+export function unquoteGitPath(s) {
+  const parts = []
+  let out = ''
+  let bytes = []
+  const flushText = () => {
+    if (bytes.length) {
+      parts.push(Buffer.from(bytes).toString('utf8'))
+      bytes = []
+    }
+  }
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]
+    if (ch !== '\\') {
+      out += ch
+      continue
+    }
+    const n = s[i + 1]
+    if (n === 'n' || n === 't' || n === '"' || n === '\\') {
+      flushText()
+      out += n === 'n' ? '\n' : n === 't' ? '\t' : n
+      i++
+      continue
+    }
+    const m = /^[0-7]{3}/.exec(s.slice(i + 1, i + 4))
+    if (m) {
+      if (out) {
+        parts.push(out)
+        out = ''
+      }
+      bytes.push(parseInt(m[0], 8))
+      i += 3
+      continue
+    }
+    out += ch // 未知转义保留原样
+  }
+  flushText()
+  if (out) parts.push(out)
+  return parts.join('')
+}
+
+/**
+ * 构造带统一 per-command 配置的 git 参数前缀。
+ * core.quotepath=false：非 ASCII 路径在 porcelain/diff 输出原始 UTF-8 而非 "\346\226\207" 八进制
+ * 转义（中文文件名经 parsePorcelainPath 的 \\(.) 解引会被拆成裸数字拼坏路径）。
+ */
+function buildFullArgs(cwd, args) {
+  return ['-c', `safe.directory=${cwd}`, '-c', 'core.quotepath=false', '-C', cwd, ...args]
+}
+
+// maxBuffer：execFileSync 默认 1MB，untracked 清单/大 diff 超限抛 ENOBUFS——
+// safeGit 吞成 null、调用方 `|| ''` 会把"输出很大"静默变成"输出为空"（补丁漏文件级联）。
+// 32MB 对齐 verify-postcheck 的 diff 读取口径。
+// 256MB（坑 apply-spawnsync-enobufs，2026-08-22 实证：大 diff binary patch 超 32MB 抛
+// ENOBUFS 只能 git merge 绕行）——上限只在真输出那么大时才占用
+const GIT_MAX_BUFFER = 256 * 1024 * 1024
+
 /**
  * 安全执行 git：失败不抛，返回 { value, error } 结构。
  * @param {string} cwd
@@ -29,12 +92,12 @@ import { execFileSync } from 'node:child_process'
  */
 export function safeGit(cwd, args, opts = {}) {
   const { trim = true, timeout = 5000, retryOnTimeout = false } = opts
-  const fullArgs = ['-c', `safe.directory=${cwd}`, '-C', cwd, ...args]
+  const fullArgs = buildFullArgs(cwd, args)
   // 单次尝试：返回 { value, errorObj }（errorObj 为原始 Error 或 null），不在内部格式化 message。
   // 格式化（取首行）推迟到最终返回，避免重试分支重复格式化，并保留原始 code 供重试判定。
   const attempt = (t) => {
     try {
-      let value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout: t, stdio: ['ignore', 'pipe', 'pipe'] })
+      let value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout: t, maxBuffer: GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'pipe'] })
       if (trim) value = value.trim()
       return { value, errorObj: null }
     } catch (e) {
@@ -60,14 +123,16 @@ export function safeGit(cwd, args, opts = {}) {
  */
 export function git(cwd, args, opts = {}) {
   const { trim = true, timeout = 5000, encoding = 'utf8' } = opts
-  const fullArgs = ['-c', `safe.directory=${cwd}`, '-C', cwd, ...args]
-  const value = execFileSync('git', fullArgs, { encoding, timeout, stdio: ['ignore', 'pipe', 'pipe'] })
+  const fullArgs = buildFullArgs(cwd, args)
+  const value = execFileSync('git', fullArgs, { encoding, timeout, maxBuffer: GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'pipe'] })
   if (Buffer.isBuffer(value)) return value
   return trim ? value.trim() : value
 }
 
 /**
  * 静默版 git：内部调 git，失败 catch 返回 null（对齐 worktree 本地 gitQuiet() 语义）。
+ * ENOBUFS（输出超 32MB）不是"无输出"，静默成 null 会让调用方把大输出误当空清单——
+ * 至少 stderr 留一行，不与正常空结果同语义。
  * @param {string} cwd
  * @param {string[]} args
  * @param {{ trim?: boolean, timeout?: number }} [opts]
@@ -76,7 +141,10 @@ export function git(cwd, args, opts = {}) {
 export function gitQuiet(cwd, args, opts = {}) {
   try {
     return git(cwd, args, opts)
-  } catch {
+  } catch (e) {
+    if (e && e.code === 'ENOBUFS') {
+      console.error(`[sillyspec] git 输出超过 32MB 上限被截断：git ${args.join(' ')}`)
+    }
     return null
   }
 }

package/src/hooks/claude-pre-tool-use.cjs

@@ -33,16 +33,18 @@ async function main() {
   let input = ''
   try {
     input = await readStdin()
-  } catch {
-    // 无法读取 stdin → 放行（安全优先于阻断）
+  } catch (e) {
+    // 无法读取 stdin → 放行（安全优先于阻断），但留痕——本 hook 是阶段门禁唯一执行点，
+    // 静默解除全部防护会让故障无从诊断
+    console.error(`[sillyspec-hook] stdin 读取失败（放行）: ${e.message}`)
     process.exit(0)
   }
 
   let parsed
   try {
     parsed = JSON.parse(input)
-  } catch {
-    // 非法 JSON → 放行
+  } catch (e) {
+    console.error(`[sillyspec-hook] stdin JSON 解析失败（放行）: ${e.message}；input 长度 ${input.length}`)
     process.exit(0)
   }
 
@@ -122,4 +124,7 @@ function readStdin() {
   })
 }
 
-main().catch(() => process.exit(0))
+main().catch(e => {
+  console.error(`[sillyspec-hook] 未捕获异常（放行）: ${e && e.message}`)
+  process.exit(0)
+})

package/src/hooks/worktree-guard.js

@@ -18,7 +18,9 @@ import { execFileSync } from 'child_process'
 const WORKTREE_STAGES = ['execute'] // 这些阶段必须在 worktree 里
 
 const FILE_WHITELIST_EXTS = ['.md']
-const FILE_WHITELIST_NAMES = ['package.json', 'tsconfig.json', 'local.yaml', 'local.yml']
+// local.yaml/local.yml 不在白名单：同名文件只允许存在于 .sillyspec/ 下（shouldBlockWrite
+// 规则 0 拦 .sillyspec/ 之外的写入，2026-08-21 root-local-yaml 治理）
+const FILE_WHITELIST_NAMES = ['package.json', 'tsconfig.json']
 
 /** 只读命令（命令名） */
 const READONLY_COMMANDS = new Set([
@@ -175,7 +177,10 @@ function readScanGuard(scanDocInfo, projectRoot) {
     if (!existsSync(p)) continue
     try {
       return JSON.parse(readFileSync(p, 'utf8'))
-    } catch {
+    } catch (e) {
+      // 半截 JSON（写入窗口读到 truncate 中间态等）不能静默当"无 guard"放行覆盖——
+      // stderr 留痕便于诊断；放行语义不变（fail-open 是既定策略，见 DB 路径对照注释）
+      console.error(`[sillyspec hook] scan-guard.json 解析失败（${e.message.split('\n')[0]}）：${p}`)
       return null
     }
   }
@@ -402,6 +407,12 @@ function parseSimpleYaml(content) {
     return trimmed
   }
 
+  // 原型污染防护：local.yaml 是 agent 可写输入。`__proto__:` 顶层标量行赋值被
+  // setter 忽略但 topKey 落在 '__proto__'，随后缩进子键行经原型链读到的是
+  // Object.prototype（typeof 'object' 跳过重建）直接全局污染——危险键整节拒绝，
+  // 既不进结果也不作为子键挂载点。
+  const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
   for (const line of content.split('\n')) {
     const noComment = line.replace(/\s+#.*$/, '')
     const trimmed = noComment.trim()
@@ -413,6 +424,11 @@ function parseSimpleYaml(content) {
       if (!topLevelMatch) continue
       const key = topLevelMatch[1]
       const value = topLevelMatch[2]
+      if (UNSAFE_KEYS.has(key.trim())) {
+        topKey = null
+        childKey = null
+        continue
+      }
       topKey = key
       childKey = null
 
@@ -435,6 +451,7 @@ function parseSimpleYaml(content) {
     if (indent === 2) {
       const childMatch = trimmed.match(/^([^:]+):\s*(.*)$/)
       if (!childMatch) continue
+      if (UNSAFE_KEYS.has(childMatch[1].trim())) continue
       childKey = childMatch[1]
       const value = childMatch[2]
       if (typeof result[topKey] !== 'object' || Array.isArray(result[topKey])) result[topKey] = {}
@@ -498,8 +515,12 @@ function isSingleCommandReadonly(cmd, extraReadonlyCommands = []) {
     return true
   }
 
-  // local.yaml 扩展
-  if (extraReadonlyCommands.includes(cmdName)) return true
+  // local.yaml 扩展：配置面文档化（config-schema），但 local.yaml 本身是 agent 可写路径——
+  // 命中扩展而非内置白名单时 stderr 留痕，提醒人工复核该放行来源（防 agent 预写扩权静默生效）
+  if (extraReadonlyCommands.includes(cmdName)) {
+    console.error(`[sillyspec hook] 放行依据 = local.yaml worktreeHook.readonlyCommands 扩展（${cmdName}），非内置只读白名单`)
+    return true
+  }
 
   // git 只读子命令
   if (cmdName === 'git') {
@@ -681,6 +702,23 @@ export function shouldBlockWrite(filePath, cwd) {
   const projectRoot = findProjectRoot(callerCwd)
   const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(callerCwd, filePath)
 
+  // 0. local.yaml 位置门禁（2026-08-21 root-local-yaml 治理）：local.yaml 只允许存在于
+  //    .sillyspec/ 下。agent 按根目录惯例找/建根级 local.yaml，而 loadLocalConfig 候选链
+  //    真会读它 → 根级副本会遮蔽/分裂真实配置。阶段无关——任何阶段写 .sillyspec/ 之外的
+  //    同名文件一律拦截并指路（真实读配置走 sillyspec config cat）。
+  const yamlBase = path.basename(absPath)
+  if ((yamlBase === 'local.yaml' || yamlBase === 'local.yml')
+    && !absPath.split(path.sep).includes('.sillyspec')) {
+    return {
+      blocked: true,
+      reason: [
+        `local.yaml 只能存在于 .sillyspec/ 目录下（当前目标：${absPath}）。`,
+        `真实配置：${path.join(projectRoot, '.sillyspec', 'local.yaml')}（gitignored，勿在别处建副本）。`,
+        '读配置：sillyspec config cat（自动定位真实路径，worktree 内也解析到主仓）；键清单：sillyspec config schema。',
+      ].join('\n'),
+    }
+  }
+
   // 1. 阶段门禁（直读 sillyspec.db）
   const stage = readCurrentStage(projectRoot) || '(none)'