sillyspec 3.26.13 → 3.26.15

package/src/docs-check.js

@@ -388,8 +388,8 @@ export function runDocsCheck(opts) {
           reason: repoPrefix + (candidateFails.length > 1 ? `多候选全失败 → ${candidateFails.join(' | ')}` : candidateFails[0]),
           // 建议行号（--suggest）：token 在首个候选文件的全量命中行，供人工确认改锚——不自动改文件
           suggest: suggestLines(candidates, tokens),
-          // 修复分类（--fix 判定依据）：全量候选 token 命中统计，唯一命中才 fixable（D-006 保守默认）
-          fix: classifyFix(candidates, tokens),
+          // 修复分类（--fix 判定依据）：全量候选 token 命中打分——唯一命中或选优严格领先可自动重锚
+          fix: classifyFix(candidates, tokens, r.start),
         })
       }
     }
@@ -415,34 +415,70 @@ function suggestLines(candidates, tokens) {
 
 /**
  * 修复分类（--fix 判定依据）：对 resolveCandidates 全量候选跑 token 命中统计，跨候选合并行号后——
- *   唯一命中 → fixable=true + newLine（自动重锚唯一解）；无 token / 零命中 / 多命中 → needs-manual。
+ *   唯一命中 → fixable=true + newLine（自动重锚唯一解）；
+ *   多命中 → 打分选优（2026-08-21 docs-ref-auto-pick，替代 D-006 一律人工）：top1 严格优于
+ *   top2（分数差 > 0）自动重锚，同分仍人工。实证：一次大改 34 处漂移只有 2 处唯一命中，
+ *   32 处人工逐个挑——多命中不代表歧义，行号漂移多为单次编辑的单调位移。
+ * 打分信号（全部来自现有数据，不新增 IO）：
+ *   - 距离：|命中行 - 文档旧行号|（权重封顶 400）——最近的命中大概率是原锚点漂移后的位置
+ *   - 定义行模式 +50：function/const/let/class/def/export 关键词**紧跟** token（引用锚通常指
+ *     定义起始行而非调用点；「keyword 后 60 字符内出现」的宽松口径会把调用点误判为定义）
+ *   - 注释行 -30（// * # -- 开头）
+ *   - 含最长 token（点分整串）+10，优于只含拆段
  * 与 suggestLines 的差异：suggest 只查首个候选（candidates[0]），本函数查全量候选（design §12 自审存疑 +
  * R-01——多候选同名文件场景下防止定位到另一文件的同名符号）。合并口径按「去重后的行号集合」：
  * 重锚写回的目标是行号，多个候选命中同一行号仍是唯一改写目标。
  * 纯增量分类，不参与层1/层2 判定（D-004 兼容红线）。
  * @param {string[]} candidates resolveCandidates 返回的全量候选绝对路径
  * @param {string[]} tokens 层2 提取的期望 token（keywordAssert=false 时为空数组）
+ * @param {number|null} [refStart] 文档引用的旧行号（打分用距离信号；范围引用取 start）
  * @returns {{ fixable: boolean, newLine?: number, reason: string }}
  */
-function classifyFix(candidates, tokens) {
+function escapeReLocal(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function classifyFix(candidates, tokens, refStart = null) {
   if (tokens.length === 0) {
     return { fixable: false, reason: '无 token 符号线索（纯位置引用或关键词断言关闭），无法自动定位' }
   }
-  const hitLines = new Set()
+  const longest = tokens.reduce((a, b) => (b.length > a.length ? b : a), '')
+  const defToken = longest.includes('.') ? longest.split('.').pop() : longest
+  const defRe = new RegExp(`(?:export\\s+)?(?:async\\s+)?(?:function|const|let|class|def)\\s+${escapeReLocal(defToken)}\\b`)
+  const byLine = new Map()
   for (const candAbs of candidates) {
     const lines = readLines(candAbs)
     if (lines === null) continue
-    lines.forEach((l, i) => { if (tokens.some((t) => l.includes(t))) hitLines.add(i + 1) })
+    lines.forEach((l, i) => {
+      if (!tokens.some((t) => l.includes(t))) return
+      const lineNo = i + 1
+      let score = 0
+      if (/^(\/\/|\*|#|--)/.test(l.trim())) score -= 30
+      if (defRe.test(l)) score += 50
+      if (l.includes(longest)) score += 10
+      if (refStart != null && Number.isFinite(refStart)) score -= Math.min(Math.abs(lineNo - refStart), 400)
+      // 同一行跨候选取最高分（合并口径不变：重锚目标是行号）
+      if (score > (byLine.get(lineNo) ?? -Infinity)) byLine.set(lineNo, score)
+    })
   }
-  if (hitLines.size === 0) {
+  if (byLine.size === 0) {
     return { fixable: false, reason: 'token 在全量候选文件零命中，无法自动定位' }
   }
-  if (hitLines.size === 1) {
-    return { fixable: true, newLine: [...hitLines][0], reason: 'token 在全量候选唯一命中，可自动重锚' }
+  if (byLine.size === 1) {
+    return { fixable: true, newLine: [...byLine.keys()][0], reason: 'token 在全量候选唯一命中，可自动重锚' }
+  }
+  const ranked = [...byLine.entries()].sort((a, b) => (b[1] - a[1]) || (a[0] - b[0]))
+  const [topLine, topScore] = ranked[0]
+  const [runLine, runScore] = ranked[1]
+  if (topScore > runScore) {
+    return {
+      fixable: true,
+      newLine: topLine,
+      reason: `多命中自动选优：picked=${topLine}（${topScore} 分）runnerUp=${runLine}（${runScore} 分，严格落后才自动改）`,
+    }
   }
-  const sorted = [...hitLines].sort((a, b) => a - b)
-  const shown = sorted.slice(0, 8).join('、') + (sorted.length > 8 ? '…' : '')
-  return { fixable: false, reason: `token 多处命中（候选行号：${shown}），歧义需人工确认（D-006 保守默认）` }
+  const shown = ranked.slice(0, 8).map(([l]) => l).join('、') + (ranked.length > 8 ? '…' : '')
+  return { fixable: false, reason: `token 多处命中且最优两行同分（候选行号：${shown}），歧义需人工确认（D-006 保守默认）` }
 }
 
 /**

package/src/doctor-diagnostics.js

@@ -836,6 +836,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 +851,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 +934,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/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([
@@ -681,6 +683,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)'