sillyspec 3.26.7 → 3.26.9

package/src/run/shared.js

@@ -11,8 +11,9 @@
  *     本模块仅 re-export，run/ 层现有调用方路径与行为不变。
  */
 import { basename, join, resolve, dirname, sep } from 'node:path'
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
+import os from 'node:os'
 
 // safeGit 收口至 src/git-helper.js：import 建本地词法绑定（本模块内部 L128/130/431 调用）+
 // re-export 供 run/ 层现有调用方继续从 shared.js 引用（pure re-export 不建本地绑定，会致内部 ReferenceError）。
@@ -94,6 +95,9 @@ export function resolvePromptIncludes(text) {
 
 /**
  * 找 .sillyspec 祖先目录：用户指定 specDir 优先，否则从 cwd 向上找。
+ * home 拒绝守卫：home 下的 .sillyspec 恒不命中——历史污染源（smoke 测试在 home 下临时目录
+ * 跑 CLI，_ensureDB 读路径即建库，~/.sillyspec 长出一整套平行进度库后，任何 home 子目录
+ * 跑命令都会向上撞它，污染自我延续）。撞 home 即停，回退 cwd/.sillyspec（子目录自建）。
  * @param {string} cwd
  * @param {object} [opts]
  * @param {string} [opts.specDir] - 用户指定的 specDir（通过 --spec-dir 或 --spec-root）
@@ -101,10 +105,15 @@ export function resolvePromptIncludes(text) {
  */
 export function resolveSpecDir(cwd, opts = {}) {
   if (opts.specDir) return resolve(opts.specDir)
+  const home = os.homedir()
   let dir = resolve(cwd)
   while (true) {
-    const candidate = join(dir, '.sillyspec')
-    if (existsSync(candidate)) return candidate
+    // home 拒绝守卫：cwd 本身就在 home 下（含恰好在 home 跑命令）时，home 层不匹配 .sillyspec，
+    // 继续向上只会离项目更远（home 的父目录不可能有真项目 .sillyspec），直接回退 cwd/.sillyspec。
+    if (dir !== home) {
+      const candidate = join(dir, '.sillyspec')
+      if (existsSync(candidate)) return candidate
+    }
     const parent = dirname(dir)
     if (parent === dir) break
     dir = parent
@@ -301,6 +310,84 @@ export function resolveQuickSessionsDir(platformOpts, localSpecBase) {
   return join(resolveRuntimeRoot(platformOpts, localSpecBase), 'quick-sessions')
 }
 
+/**
+ * 平台指针三写（单一数据源，runCommand scan 与 cmdInit 平台模式共用）。
+ *
+ * 写三处：
+ *   1. <specRoot>/.runtime/platform-scan.json — 主持久化文件（后续 run/--done 恢复）
+ *   2. <cwd>/.sillyspec-platform.json — 轻量恢复指针（供裸调——不带 --spec-root——找回 specDir）
+ *   3. <cwd>/.sillyspec-platform-managed — 平台接管声明（无过期，独立于指针生命周期；
+ *      指针被 cleanup/STALE 清理后它仍在，resolvePlatformSpecDir/runCommand 恢复链靠它
+ *      fail-closed 防静默落本地库。唯一删除路径 = platform disconnect）
+ *
+ * status 字段语义（POINTER_STATUS）：
+ *   - init 落盘时传 status: 'active'（已接入未 scan，24h STALE 清理不作用于它）
+ *   - scan 完成时 complete-handlers 升级为 'scan_completed'
+ *   - 不传 status 则省略（与 runCommand 历史行为一致）
+ *
+ * 写失败静默（不阻断主流程），返回 true/false 供调用方决定是否提示。
+ *
+ * @param {string} cwd - 恢复指针落盘目录（= 调用方命令的 cwd，通常为项目根）
+ * @param {object} platformOpts - { specRoot, runtimeRoot?, workspaceId?, scanRunId? }
+ * @param {object} [extra] - 追加字段（如 { status: 'active' }，只进指针/主文件不进声明）
+ * @returns {boolean} 是否全部写入成功
+ */
+export const PLATFORM_MANAGED_FILENAME = '.sillyspec-platform-managed'
+
+export function writePlatformPointer(cwd, platformOpts, extra = {}) {
+  if (!platformOpts || (!platformOpts.specRoot && !platformOpts.runtimeRoot)) return false
+  const payload = {
+    specRoot: platformOpts.specRoot || null,
+    runtimeRoot: platformOpts.runtimeRoot || null,
+    workspaceId: platformOpts.workspaceId || null,
+    scanRunId: platformOpts.scanRunId || null,
+    savedAt: new Date().toISOString(),
+    ...extra,
+  }
+  // 声明文件字段集独立于指针 payload（D-E@v2 四字段：无 status/savedAt/scanRunId——
+  // 声明语义是"项目归平台管"这一持久事实，非 scan 会话状态）
+  const declaration = {
+    managed: true,
+    specRoot: platformOpts.specRoot || null,
+    workspaceId: platformOpts.workspaceId || null,
+    declaredAt: new Date().toISOString(),
+  }
+  try {
+    mkdirSync(join(platformOpts.specRoot, '.runtime'), { recursive: true })
+    writeFileSync(join(platformOpts.specRoot, '.runtime', 'platform-scan.json'), JSON.stringify(payload, null, 2) + '\n')
+    writeFileSync(join(cwd, '.sillyspec-platform.json'), JSON.stringify(payload, null, 2) + '\n')
+    writeFileSync(join(cwd, PLATFORM_MANAGED_FILENAME), JSON.stringify(declaration, null, 2) + '\n')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 读平台接管声明（读侧宽容：任何异常情况返回 null = 视同无声明，不抛错）。
+ * 供 resolvePlatformSpecDir / runCommand 恢复链 / doctor 诊断三处消费。
+ *
+ * @param {string} cwd - 项目根（声明查找目录）
+ * @returns {{managed:true, specRoot, workspaceId, declaredAt}|null}
+ *   文件不存在 / JSON 损坏 / managed 非 true → null
+ */
+export function checkPlatformManaged(cwd) {
+  const p = join(resolve(cwd), PLATFORM_MANAGED_FILENAME)
+  if (!existsSync(p)) return null
+  try {
+    const decl = JSON.parse(readFileSync(p, 'utf8'))
+    if (!decl || decl.managed !== true) return null
+    return {
+      managed: true,
+      specRoot: decl.specRoot || null,
+      workspaceId: decl.workspaceId || null,
+      declaredAt: decl.declaredAt || null,
+    }
+  } catch {
+    return null
+  }
+}
+
 /**
  * 统一查找变更目录（与 progress.js 的变更检测逻辑一致）。
  */
@@ -494,8 +581,90 @@ export function isQuickMetadata(p, linkedChanges = []) {
  * quick 完成审计：对比 baseline 与实际变更。
  * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number }}
  */
+/**
+ * D-8 O-1 模块归属（2026-08-15 docs-signals-o12）：quick 欠账 hint 从"改了 N 文件"升级为
+ * "涉及哪些模块卡"。只做归属（matchFilesToModules 纯函数零 git），不算 behind——对账是
+ * execute Wave [docs-debt] 的职责（design D-001 轻量边界）。map 缺失/解析空/异常 → 空数组
+ * 降级（hint 仍打，modules 省略），不报错不阻断。
+ * 动态 import docs-debt.js/modules.js：prompt.js 已静态 import shared（本模块），静态互引成 ESM 环。
+ */
+async function matchQuickModules(srcChanged, specBase, projectName) {
+  if (!specBase || !projectName || srcChanged.length === 0) return []
+  try {
+    const { join } = await import('node:path')
+    const { existsSync: ex, readFileSync: rf } = await import('node:fs')
+    const mapPath = join(specBase, 'docs', projectName, 'modules', '_module-map.yaml')
+    if (!ex(mapPath)) return []
+    const { parseModuleMapSimple } = await import('../modules.js')
+    const idx = parseModuleMapSimple(rf(mapPath, 'utf8'))
+    if (!idx || Object.keys(idx).length === 0) return []
+    const { matchFilesToModules } = await import('../docs-debt.js')
+    const cardsDir = join(specBase, 'docs', projectName, 'modules')
+    const { byModule } = matchFilesToModules(srcChanged, idx, { cardsDir })
+    return [...byModule.entries()].map(([id, e]) => ({ id, doc: e.doc }))
+  } catch {
+    return []
+  }
+}
+
+// ── task-03（2026-08-16-state-split-fixes）: 活文档漂移提示辅助 ──
+// 背景：platform-interface-map.md 等活文档持续维护 src 主入口的 file:line 映射；并行会话改
+// src/ 后引用行号静默失效，docs gate 只能事后拦到别人的流程上。审计（auditQuickCompletion）
+// 当场检测「本次改动的 src 文件是否被活文档引用」并提示（advisory 不阻断，docs gate 语义不变）。
+
+/** 缺省活文档：src 主入口 ↔ 文档接口映射（file:line 锚点密度最高的持续维护文档）。 */
+export const DEFAULT_LIVING_DOC = 'docs/sillyspec/platform-interface-map.md'
+
+/**
+ * 解析活文档集合：local.yaml `docs-check.living-docs` 列表【只追加不覆盖】缺省集合。
+ * 与 docs-check.paths 的覆盖语义刻意不同——paths 是扫描范围（配了即整体替换缺省），
+ * living-docs 是监控点登记（配了是加哨兵，不该把缺省监控点挤掉）。读配置走本模块现成的
+ * readLocalYamlRaw + js-yaml 动态 import（readDocsCheckConfig 不回 living-docs 键；动态
+ * import 与上方 docs-check 的隔离约定一致）；坏 YAML / 非数组 / 读失败 → 仅缺省。
+ * @param {string} cwd 仓库根（local.yaml 在 <cwd>/.sillyspec/local.yaml）
+ * @returns {Promise<string[]>} 去重后的活文档相对路径（仓库根相对 POSIX）
+ */
+export async function resolveLivingDocs(cwd) {
+  let configured = []
+  const raw = readLocalYamlRaw(cwd)
+  if (raw) {
+    try {
+      const mod = await import('js-yaml')
+      const yamlLoad = mod.load || mod.default?.load
+      const doc = yamlLoad(raw)
+      const dc = doc && typeof doc === 'object' ? doc['docs-check'] : null
+      const ld = dc && typeof dc === 'object' ? dc['living-docs'] : null
+      if (Array.isArray(ld)) configured = ld.filter((s) => typeof s === 'string' && s.trim() !== '')
+    } catch { /* 坏 YAML → 忽略配置，仅缺省 */ }
+  }
+  return [...new Set([DEFAULT_LIVING_DOC, ...configured])]
+}
+
+/**
+ * 纯函数：活文档引用的源码文件与本次改动的 src/ 文件求交。
+ * 匹配口径对齐 docs-check resolveCandidates 的三形态（纯路径比对，不查盘）：
+ *   ①仓库根相对：changed === ref（如 src/a.js）
+ *   ②src 内部相对：changed === 'src/' + ref（如 run/b.js → src/run/b.js）
+ *   ③裸名/中缀后缀：changed.endsWith('/' + ref)（如 b.js；前导斜杠防 aa.js 被引用 a.js 误吃）
+ * changedFiles 口径 = git status porcelain 归一后的仓库根相对 POSIX 路径（parsePorcelainPath 产物）。
+ * 同名多文件时后缀形态可能多报——与 docs-check 多候选宽容同向，advisory 仅提示可接受。
+ * @param {string[]} srcChangedFiles changedFiles 中 src/ 前缀的文件
+ * @param {Array<{file: string}>} refs collectDocRefs(md) 产物（只用 .file）
+ * @returns {string[]} 命中的 srcChangedFiles 子集（去重保序）
+ */
+export function matchLivingDocRefs(srcChangedFiles, refs) {
+  const hit = new Set()
+  for (const c of srcChangedFiles) {
+    if (refs.some((r) => r && typeof r.file === 'string' &&
+      (c === r.file || c === 'src/' + r.file || c.endsWith('/' + r.file)))) {
+      hit.add(c)
+    }
+  }
+  return [...hit]
+}
+
 export async function auditQuickCompletion(cwd, guard, options = {}) {
-  const { baselineFiles, allowedFiles = [], allowNew = false, forceBaseline = false, allowDelete = false } = guard
+  const { baselineFiles, allowedFiles = [], allowNew = false, forceBaseline = false, allowDelete = false, specBase = null, projectName = null } = guard
   const { isConfirm } = options
   // stagedTotal：当前所有非 quick 元数据的未提交条目（含前序 baseline 残留）。
   // 与 changedFiles（扣 baseline 后的本轮新增）区分，供审计文案同时展示「本轮新增 vs 累计暂存」，
@@ -644,6 +813,70 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       }
     } catch {}
 
+    // D-8 文档欠账显性化（advisory）：本次改动含源码文件但不含任何文档文件 → 打标记 warn。
+    // quick 是低摩擦通道（不强制文档同步），但欠账要显性化——72% 流量 86% 不动文档是系统性欠账
+    // 主通道（doc-consistency-debt D-8）。不阻断不改 status，只 warn + 记 reasons 供 QUICKLOG 追溯。
+    const isDocFile = (f) =>
+      f.endsWith('.md') || f.endsWith('.yaml') || f.endsWith('.yml') ||
+      f.startsWith('docs/') || f.startsWith('.sillyspec/docs/')
+    const srcChanged = result.changedFiles.filter(f => !isDocFile(f) && !isQuickMetadata(f, guard.linkedChanges))
+    const docChanged = result.changedFiles.filter(isDocFile)
+    if (srcChanged.length > 0 && docChanged.length === 0) {
+      result.reasons.push(`本次未同步模块文档（${srcChanged.length} 个源码文件改动，无文档文件）`)
+      result.docSyncHint = { touchedSource: srcChanged.length, docFiles: [], modules: await matchQuickModules(srcChanged, specBase, projectName) }
+    } else if (srcChanged.length > 0 && docChanged.length > 0) {
+      result.docSyncHint = { touchedSource: srcChanged.length, docFiles: docChanged }
+    }
+
+    // docs check advisory（doc-consistency-debt D-6 后续）：本次改动的 .md 文档跑 file:line
+    // 引用校验，失效即 warn + reasons——检测能力落地后欠账只涨不跌的最后一公里。只查本次
+    // changedFiles 的文档（归因到本次改动），不扫全仓历史欠账（那是存量问题，quick 不背锅）。
+    // 排除删除文件（troubleshooting #9）：删除的 .md 不在盘，runDocsCheck 只会报「文档不存在」
+    // 假失效——删除语义归 --allow-delete 管，无引用校验可言（并行会话的删除尤其不该归属本会话）。
+    // docs-check 是 IO 面（walkGlob/existsSync），动态 import 隔离；任何异常 fail-open 只跳过。
+    const deletedSet = new Set(result.deletedFiles)
+    const mdChanged = result.changedFiles.filter((f) => f.endsWith('.md') && !deletedSet.has(f) && !isQuickMetadata(f, guard.linkedChanges))
+    if (mdChanged.length > 0) {
+      try {
+        const { runDocsCheck } = await import('../docs-check.js')
+        const dc = runDocsCheck({ projectRoot: cwd, docs: mdChanged })
+        if (!dc.ok) {
+          result.reasons.push(`本次改动文档含 ${dc.invalid.length} 处失效 file:line 引用（sillyspec docs check 可复现）`)
+          result.docsCheckHint = { invalid: dc.invalid.length, total: dc.total }
+          if (result.status === 'safe') result.status = 'warning'
+        }
+      } catch { /* docs-check 不可用（老版本包等）→ 静默跳过，不阻断 quick */ }
+    }
+
+    // task-03: 活文档漂移提示（advisory，不阻断不改 status，docs gate 语义不变）。
+    // 方向与上方 docsCheckHint 相反：那是「本次改的文档引用失效吗」，这是「本次改的 src 被活文档
+    // 引用吗」——并行会话改 src/ 主入口后 platform-interface-map.md 的 file:line 行号静默失效，
+    // gate 事后拦到别人流程上；审计当场命中交集即提示顺手跑 docs check。fail-open：活文档
+    // 缺失/读失败/collectDocRefs 不可用 → 静默跳过（不误报不阻断）。
+    const srcChangedFiles = result.changedFiles.filter((f) => f.startsWith('src/') && !deletedSet.has(f))
+    if (srcChangedFiles.length > 0) {
+      try {
+        const { collectDocRefs } = await import('../docs-check.js')
+        const livingDocs = await resolveLivingDocs(cwd)
+        const files = []
+        const docs = []
+        for (const docRel of livingDocs) {
+          let md
+          try { md = readFileSync(join(cwd, docRel), 'utf8') } catch { continue } // 活文档缺失/读失败 → 跳过
+          const hit = matchLivingDocRefs(srcChangedFiles, collectDocRefs(md))
+          if (hit.length > 0) {
+            files.push(...hit)
+            docs.push(docRel)
+          }
+        }
+        if (files.length > 0) {
+          const uniqFiles = [...new Set(files)]
+          result.docsCheckHint = { ...(result.docsCheckHint || {}), livingDocDrift: { files: uniqFiles, docs, total: srcChangedFiles.length } }
+          result.reasons.push(`活文档引用漂移: 改动 ${uniqFiles.length} 个文件被活文档引用（${docs.join(', ')}）`)
+        }
+      } catch { /* collectDocRefs 不可用 → 静默跳过 */ }
+    }
+
     // task-02: 同文件并发检测——allowedFile 在 baseline（他者改过）且当前 hash ≠ step1 hash（我也改了）
     // → commit 整文件 pathspec 会夹带他者 hunk，warn 给分离指引（advisory，不阻断，D-002）
     if (allowedFiles.length > 0 && guard.allowedFilesHash) {
@@ -784,6 +1017,35 @@ export function aggregateDeclaredRepos(planContent) {
   return Array.from(seen)
 }
 
+/**
+ * 坑7 补扫：读 tasks/task-NN.md 独立卡片，拼成可被 aggregateDeclaredRepos 的 frontmatter
+ * 正则识别的文本（每张卡内容原样拼接，卡内容自带的 ---\n…\n--- frontmatter 会被同一正则命中）。
+ *
+ * plan 阶段标准产出形态是 plan.md 内联卡片块 + tasks/ 独立卡片双写，但实际执行中 plan.md
+ * 可能只留 checkbox 行（卡片全在 tasks/）——此时 plan.md 聚合不到跨仓 repo，跨仓 review
+ * 误报伪造。本函数读 tasks/ 目录兜底，任一文件读失败跳过（fail-open，兜底源不引入新阻断）。
+ *
+ * @param {string} specDir - spec 根（change 目录的父级）
+ * @param {string} changeName
+ * @returns {string} 拼接文本（无 tasks/ 或全空 → ''，plan.md 原行为零回归）
+ */
+function collectTaskCardReposFallback(specDir, changeName) {
+  const tasksDir = join(specDir, 'changes', changeName, 'tasks')
+  if (!existsSync(tasksDir)) return ''
+  let merged = ''
+  for (const f of readdirSync(tasksDir)) {
+    if (!/^task-\d+\.md$/i.test(f)) continue
+    const p = join(tasksDir, f)
+    // CRLF 卡片：\r?\n 容差在 aggregateDeclaredRepos 正则里，这里只管拼接不归一
+    try {
+      merged += '\n' + readFileSync(p, 'utf8') + '\n'
+    } catch {
+      // 单文件读失败跳过——兜底源缺失不该阻断主聚合
+    }
+  }
+  return merged
+}
+
 /**
  * 构造或取进程级 MultiRepoContext 单例（D-013 G2）。
  *
@@ -835,7 +1097,13 @@ export async function getOrCreateMultiRepoContext({ cwd, changeName, platformOpt
   }
 
   // 聚合 declaredRepos（扫 plan.md task 卡片 repo:）+ 读 local.yaml repos: 段
-  const declaredRepos = aggregateDeclaredRepos(planContent)
+  // 坑7 兼扫 tasks/task-NN.md：plan 阶段把卡片写到 tasks/、plan.md 只留 checkbox 行时，
+  // plan.md 内联 frontmatter 聚合不到跨仓 repo → ctx 不含跨仓 entry → 跨仓 review 退回主仓
+  // gitDir 校验，误报「base 不是真实 commit — 疑似伪造」（真实 commit 在跨仓仓可达）。
+  // 两源并入同一聚合：plan.md 内联块（原行为，零回归）+ tasks/ 独立卡片（坑7 补扫）。
+  const declaredRepos = aggregateDeclaredRepos(
+    planContent + collectTaskCardReposFallback(specDir, changeName)
+  )
   const repoRegistry = parseRepoRegistry(readLocalYamlRaw(cwd))
 
   // 构造 WorktreeManager（主仓 meta 读取；与 getStageSteps 同源范式）

package/src/run/stage.js

@@ -25,6 +25,7 @@ import { outputStep } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
 import { createHash } from 'node:crypto'
 import { checkTransition } from '../stage-contract.js'
+import { AUXILIARY_STAGES } from '../constants.js'
 import { completeStageGates } from './gates.js'
 
 export async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
@@ -107,6 +108,15 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     } catch {}
     if (!currentExecuteRunId) {
       currentExecuteRunId = generateExecuteRunId()
+      // D-001#1 主写入点：mkdir execute-runs/<runId>/tasks 先于 marker（不变量：marker 在则目录在，
+      // archive 完成度扫描/漂移兜底不再落到「有 marker 无目录」的空 run）。失败直接 throw——execute
+      // 启动即失败优于事后 review 错配（调用方 runCommand 冒到 CLI 顶层 exit 1，给出修复指引）。
+      try {
+        mkdirSync(join(runtimeRoot, 'execute-runs', currentExecuteRunId, 'tasks'), { recursive: true })
+      } catch (e) {
+        throw new Error(`execute run 目录创建失败（${join(runtimeRoot, 'execute-runs', currentExecuteRunId)}）: ${e.message}；` +
+          `请检查该路径是否为普通文件/只读，清理后重跑（sillyspec run execute --change ${changeName} --skip-approval）`)
+      }
       writeFileSync(runIdFile, currentExecuteRunId + '\n')
     }
   }
@@ -125,8 +135,12 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
   }
 
   // 用户显式调用 sillyspec run <stage>：把它标记为当前阶段
+  // （D-003@v1：auxiliary 阶段不写 currentStage，避免 scan/quick/explore/archive/status/doctor
+  //   执行后污染主流程当前阶段；lastActive 心跳与 pm._write/triggerSync 照常）
   if (progress.currentStage !== stageName) {
-    progress.currentStage = stageName
+    if (!AUXILIARY_STAGES.includes(stageName)) {
+      progress.currentStage = stageName
+    }
     progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
     pm._write(cwd, progress, changeName)
     triggerSync(cwd, changeName, platformOpts)
@@ -375,6 +389,8 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         // 阶段完成收尾共享管线（noAI 末步核心修复 S1：plan postcheck independent-tier review verdict=fail /
         // 平台 scan manifest 此前被绕过）。gate 失败已 rollback 为 in-progress，early-return（不 fall through 到末尾 return）。
         const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText: null })
+        // task-04 / A5：gate 失败（stageCompleted===false）设进程退出码 1（与 completeStep/continueStep 同语义）。
+        if (_stageGatesResult?.stageCompleted === false) process.exitCode = 1
         if (_stageGatesResult) return _stageGatesResult
         // gate 全过：persist completed（task-02 移后；此处无 triggerSync，与同文件 noAI 末步语义一致）。
         pm._write(cwd, progress, changeName)