sillyspec 3.29.5 → 3.30.0

package/src/machine-interface.js

@@ -22,6 +22,7 @@ import { resolveRuntimeRoot } from './run/shared.js';
 import { runValidators, checkTransition, checkExecuteCodeEvidence } from './stage-contract.js';
 import { validateTaskReviews, resolveLatestExecuteRunId } from './task-review.js';
 import { runVerifyTestCheck } from './verify-postcheck.js';
+import { computeGateFingerprint, lookupGreenCache, storeGreenCache, greenCacheNotice } from './run/green-cache.js';
 import { checkCode } from './diagnostic-codes.js';
 
 // ============ 退出码常量（D-004@v1）============
@@ -116,7 +117,31 @@ export function buildEnvelope({
  *   让两函数按 ctx 切跨仓 gitDir / per-repo cwd。null 时两函数按既有单仓行为零回归。
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
-export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor, ctx = null } = {}) {
+/**
+ * verify 门禁 check 的绿结果缓存包装（R8 对撞修复 2026-09-23，实现见 src/run/green-cache.js）。
+ * 同指纹（HEAD+代码脏面+local.yaml）近期真跑的绿结果复用：命中 → synth(hit) 合成等价结果
+ * （带 cached 披露字段，调用方进 warnings——「结果是真的、本次没跑」必须明示）；未命中 →
+ * 真跑，status==='passed' 时写缓存。fail-open：无根/指纹失败/缓存异常一律回退真跑（零回归）。
+ */
+function greenCachedCheck({ kind, greenRoot, cwd, specBase, changeName }, runReal, synth) {
+  if (!greenRoot) return runReal();
+  let fingerprint = null;
+  try { fingerprint = computeGateFingerprint({ cwd, specBase }); } catch { fingerprint = null; }
+  if (!fingerprint) return runReal();
+  const scope = `change:${changeName}`;
+  let hit = null;
+  try { hit = lookupGreenCache({ runtimeRoot: greenRoot, scope, kind, fingerprint }); } catch { hit = null; }
+  if (hit) return synth(hit);
+  const result = runReal();
+  try {
+    if (result && result.status === 'passed') {
+      storeGreenCache({ runtimeRoot: greenRoot, scope, kind, fingerprint, result: { status: 'passed', exitCode: result.exitCode ?? 0, mode: result.mode ?? null } });
+    }
+  } catch { /* best-effort 写缓存 */ }
+  return result;
+}
+
+export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor, ctx = null, full = false } = {}) {
   const specRoot = specBase || resolveSpecDir(cwd);
   // A4：pm 用 specRoot（而非默认 resolveSpecDir(cwd)）——--spec-dir/平台模式下 specBase 是真实
   // specDir，默认解析会指向本地孤儿库，与下方 planContent/changeDir 的 specRoot 两套事实源混拼。
@@ -288,8 +313,14 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
 
     // ── d. verify 阶段追加 verify-test（CLI 实测 local.yaml commands.test）──
     if (stage === 'verify') {
-      const vt = runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx });
+      // 绿缓存根：与 runtimeRoot 解析同源（drift 锚主仓口径）；解析失败 null → 不缓存不命中
+      let greenRoot = null;
+      try { greenRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot); } catch { greenRoot = null; }
+      const vt = greenCachedCheck({ kind: 'test', greenRoot, cwd, specBase: specRoot, changeName },
+        () => runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx }),
+        (hit) => ({ status: 'passed', exitCode: 0, durationMs: 0, resultPath: null, mode: null, fallbackReason: null, exemptedCount: 0, cached: true, reason: greenCacheNotice(hit, 'verify-test') }));
       const vtWarnings = [];
+      if (vt.cached) vtWarnings.push(vt.reason);
       if (vt.status === 'skipped') {
         vtWarnings.push(`⚠️ verify-test SKIPPED — gate 未核验测试（${vt.reason || 'local.yaml 未配置 commands.test 或显式无测试'}）。本次 gate 结论不含测试客观核验，driver 不应据 exit 0 判定测试通过；integration-critical 变更应在 verify 阶段降级 FAIL`);
       }
@@ -311,6 +342,7 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
         warnings: vtWarnings,
         data: {
           status: vt.status,
+          cached: vt.cached === true,
           exitCode: vt.exitCode,
           durationMs: vt.durationMs,
           resultPath: vt.resultPath,
@@ -327,7 +359,9 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
       // 不一致时以 --done 为准。lint 未配置/不可跑 → informational，不阻断只读查询。
       try {
         const { runVerifyLintCheck, triageLintOwnership, resolveVerifyChangedFiles } = await import('./verify-postcheck.js');
-        const lc = runVerifyLintCheck({ cwd, specBase: specRoot });
+        const lc = greenCachedCheck({ kind: 'lint', greenRoot, cwd, specBase: specRoot, changeName },
+          () => runVerifyLintCheck({ cwd, specBase: specRoot }),
+          (hit) => ({ status: 'passed', exitCode: 0, durationMs: 0, failureFiles: [], cached: true, reason: greenCacheNotice(hit, 'verify-lint') }));
         if (lc.status === 'skipped') {
           checks.push({
             id: 'verify-lint',
@@ -341,6 +375,7 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
           const lcWarnings = [
             '口径说明：gate verify 的 lint 在工作树直跑；verify --done 的 lint 在隔离快照（HEAD+归属文件 overlay）跑——两口径不一致时以 --done 为准。',
           ];
+          if (lc.cached) lcWarnings.push(lc.reason);
           let ownership = null;
           let lintOk = lc.status !== 'failed';
           if (lc.status === 'failed') {
@@ -359,6 +394,7 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
             warnings: lcWarnings,
             data: {
               status: lc.status,
+              cached: lc.cached === true,
               exitCode: lc.exitCode,
               durationMs: lc.durationMs,
               ownership: ownership ? ownership.verdict : null,
@@ -378,6 +414,65 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
       }
     }
 
+    // ── e. --full 只读预检档（P1 / FR-01 / D-002@batch3，2026-09-21-r5-efficiency-batch3 task-03）──
+    // 覆盖 --done 独有的贵门（batch2 实证四类盲区：reconcile 两轮/stage review 缺失各吃一整 agent
+    // 回合）：①target_files reconcile 只读跑（reconcileTargetFiles 纯计算不落盘，--done 的写结果
+    // 文件在其调用方）；②stage review 在场探测（marker+review.json——缺则报预期路径，同 --done
+    // Stage Review Gate 口径，只报缺不生成）。全只读零副作用；未传 full 零行为变化。
+    if (full && (stage === 'verify' || stage === 'execute')) {
+      // e1. reconcile（verify --done 的 target_files 对账门）
+      if (stage === 'verify') {
+        try {
+          const { reconcileTargetFiles } = await import('./verify-postcheck.js');
+          const rec = reconcileTargetFiles({ cwd, specBase: specRoot, changeName });
+          const recOk = rec.status !== 'missing_declared';
+          checks.push({
+            id: 'full-target-files-reconcile',
+            code: checkCode('full-target-files-reconcile') || 'full_target_files_reconcile',
+            ok: recOk,
+            errors: !recOk
+              ? (rec.missing || []).map((m) => `task-${m.task || '?'}: ${m.path} 声明未做（②类计划落空）——补做交付或按声明修正通道改卡（与 review 结论一致）`)
+              : [],
+            warnings: (rec.undeclared || []).length > 0
+              ? [`${(rec.undeclared || []).length} 个未声明文件（warning 级，${(rec.undeclared || []).slice(0, 3).map((u) => u.path).join('、')}${(rec.undeclared || []).length > 3 ? ' 等' : ''}）——并行会话归因噪音或漏声明，verify 报告须裁决`]
+              : [],
+            data: { status: rec.status, matched: (rec.matched || []).length, missing: (rec.missing || []).length, undeclared: (rec.undeclared || []).length },
+          });
+        } catch (e) {
+          checks.push({
+            id: 'full-target-files-reconcile',
+            code: 'full_target_files_reconcile',
+            ok: true,
+            informational: true,
+            warnings: [`--full reconcile 检查装配失败（fail-open）: ${e && e.message ? e.message : e}`],
+          });
+        }
+      }
+      // e2. stage review 在场探测（verify/execute --done 的 Stage Review Gate）
+      try {
+        const { getLatestStageReviewRunId } = await import('./stage-review.js');
+        const rrRoot = runtimeRoot || join(specRoot, '.runtime');
+        const runId = getLatestStageReviewRunId(rrRoot, stage, changeName);
+        checks.push({
+          id: 'full-stage-review',
+          code: checkCode('full-stage-review') || 'full_stage_review_missing',
+          ok: !!runId,
+          errors: !runId
+            ? [`缺 ${stage} 阶段的 stage review.json（tier=independent 要求独立审查产出）——--done 将被 Stage Review Gate 拦；可先 sillyspec register-stage-review --change ${changeName} --stage ${stage} 生成骨架再填（降级条款照 review.json reviewerNotes 首行留痕）`]
+            : [],
+          data: { runId: runId || null },
+        });
+      } catch (e) {
+        checks.push({
+          id: 'full-stage-review',
+          code: 'full_stage_review_missing',
+          ok: true,
+          informational: true,
+          warnings: [`--full stage review 探测装配失败（fail-open）: ${e && e.message ? e.message : e}`],
+        });
+      }
+    }
+
     // ── 综合结论：所有非 informational check 均 ok ──
     const ok = checks.filter((c) => !c.informational).every((c) => c.ok);
     const exitCode = ok ? EXIT_OK : EXIT_BLOCKED;
@@ -519,9 +614,14 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot,
 
       // ── b. verify-test：真实执行测试命令并取证 ──
       case 'verify-test': {
-        const vt = runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx });
+        let greenRoot = null;
+        try { greenRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot); } catch { greenRoot = null; }
+        const vt = greenCachedCheck({ kind: 'test', greenRoot, cwd, specBase: specRoot, changeName },
+          () => runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx }),
+          (hit) => ({ status: 'passed', exitCode: 0, durationMs: 0, resultPath: null, mode: null, fallbackReason: null, exemptedCount: 0, cached: true, reason: greenCacheNotice(hit, 'verify-test') }));
         data = {
           status: vt.status,
+          cached: vt.cached === true,
           exitCode: vt.exitCode,
           durationMs: vt.durationMs,
           resultPath: vt.resultPath,
@@ -530,7 +630,9 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot,
         };
         ok = vt.status !== 'failed';
         errors = vt.status === 'failed' ? [`测试失败: ${vt.reason || ''}`] : [];
-        warnings = vt.status === 'skipped'
+        warnings = vt.cached
+          ? [vt.reason]
+          : vt.status === 'skipped'
           ? ['测试被跳过']
           : (vt.mode === 'full' && vt.fallbackReason)
             ? [`⚠️ verify-test 跑的是全量 commands.test（${vt.fallbackReason}）；失败可能含未变更模块的预存错误`]

package/src/mcp-server.js

@@ -93,6 +93,7 @@ function runCli(cliArgs) {
       cwd: process.cwd(),
       env: process.env,
       stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
     })
     let out = ''
     let err = ''

package/src/module-resolve.js

@@ -78,8 +78,10 @@ export function collectModuleMaps({ cwd, specBase }) {
 /**
  * 路径归一：反斜杠→正斜杠，剥尾部 glob（/** 与 /*）与目录斜杠。
  * `backend/**` / `backend/` / `backend` → `backend`。
+ * （导出供 flow-parity.reconcileModuleDocs 复用——2026-09-27-thin-module-scope-persist：
+ * 模块对账与模块卡解析同一归一口径，防两处漂移）
  */
-function normalizeMapPath(raw) {
+export function normalizeMapPath(raw) {
   return String(raw).replace(/\\/g, '/').replace(/\/\*\*$/, '').replace(/\/\*$/, '').replace(/\/$/, '')
 }
 

package/src/preview-progress.js

@@ -0,0 +1,160 @@
+/**
+ * preview-progress.js — watcher 预览进度账本写路径（2026-09-23-watcher-preview-progress task-02）。
+ *
+ * 职责：把 watcher 快照的阶段级推断态投影为 progress 库 stages 预览行（authority='watcher'）。
+ * 设计契约（decisions D-004/D-005，design §3）：
+ *   - 粒度=阶段级（工件签名→progress 阶段映射；steps 级不投影，D-004）；
+ *   - 写纪律=短连接（open→写→close）+ 自带 PRAGMA busy_timeout（连接级，openDatabase 不自动——
+ *     影子审查 gap①）+ 存在性条件进 SQL + maxRows 写放大护栏 + 全程 fail-open（任何异常返回 false，
+ *     绝不影响 watcher 事件流主循环）。WHERE 认领语义（D-005@v2 执行期修正：initChange 预建
+ *     全套 cli/pending 行，纯 authority='watcher' 条件永远空转）：watcher 行可自刷；**CLI 从未
+ *     触碰的 pending 行（status='pending' 且 started_at IS NULL）可被预览认领**（flip 为 watcher，
+ *     语义无损——pending 空行不含 CLI 任何 authored 信息）；CLI 已触碰行（started/completed/
+ *     reopened）SQL 层不可中招；CLI --done 归章（task-01 fail① 修复）把认领行收回 cli。
+ *   - archived 拍不投影（终态只认 CLI）。
+ * 读侧出口在 progress.js readPreviewProgress（task-03）；读侧保险丝在 progress.js 读方法（task-01）。
+ */
+import { join } from 'node:path'
+import { openDatabase } from './db-engine.js'
+
+/** 工件签名 → progress 阶段映射（纯静态；watcher 快照 files 的键为工件基名）。 */
+export const PREVIEW_STAGE_SOURCES = {
+  brainstorm: ['proposal.md', 'requirements.md', 'decisions.md', 'design.md'],
+  plan: ['plan.md'],
+  execute: ['tasks.md'],
+  verify: ['verify-result.md', 'verify-facts.json'],
+}
+
+/**
+ * 纯函数：快照差分 → 阶段级预览行集合。
+ * @param {{ ts:number, archived:boolean, files?:Object }} snapshot 当前拍
+ * @param {{ files?:Object }=} prevSnapshot 上一拍（缺省全量视角）
+ * @returns {{ stage:string, status:'in-progress', startedAt:string, evidence:Object }[]}
+ *   evidence = { ts, files: 命中的工件清单, changed: 本拍有无内容变化（差分信号） }
+ */
+export function projectPreviewStages({ snapshot, prevSnapshot = null } = {}) {
+  if (!snapshot || snapshot.archived) return []
+  const files = snapshot.files || {}
+  const prevFiles = (prevSnapshot && prevSnapshot.files) || {}
+  const rows = []
+  for (const [stage, sources] of Object.entries(PREVIEW_STAGE_SOURCES)) {
+    const hit = sources.filter((k) => Object.prototype.hasOwnProperty.call(files, k))
+    if (hit.length === 0) continue
+    const changed = hit.some((k) => {
+      const a = files[k]; const b = prevFiles[k]
+      if (b === undefined) return true // 出现
+      return JSON.stringify(a) !== JSON.stringify(b) // 内容变化（checked 增/键值漂移）
+    })
+    rows.push({
+      stage,
+      status: 'in-progress',
+      startedAt: new Date(snapshot.ts || Date.now()).toISOString(),
+      evidence: { ts: snapshot.ts || null, files: hit, changed },
+    })
+  }
+  return rows
+}
+
+/**
+ * 短连接写入预览行（best-effort，全程 fail-open）。
+ * @returns {boolean} true=至少尝试写入（库在/变更注册）；false=跳过（库缺失/变更未注册/异常）
+ */
+export function writePreviewStages({ specDir, changeName, rows, maxRows = 8 } = {}) {
+  if (!specDir || !changeName || !Array.isArray(rows) || rows.length === 0) return false
+  let db = null
+  try {
+    db = openDatabase(join(specDir, '.runtime', 'sillyspec.db'), {})
+    // 连接级 PRAGMA（影子审查 gap①）：openDatabase 不自动带，缺省 0 = 撞锁立即 BUSY
+    db.exec('PRAGMA busy_timeout = 5000')
+    const changeRow = db.prepare('SELECT id FROM changes WHERE name = ?').get(changeName)
+    if (!changeRow) return false // 变更未注册（未跑过任何阶段）——无从挂预览，安静跳过
+    const cid = changeRow.id
+    const stmt = db.prepare(
+      `INSERT INTO stages (change_id, stage, status, started_at, authority, preview_evidence)
+       VALUES (?, ?, ?, ?, 'watcher', ?)
+       ON CONFLICT(change_id, stage) DO UPDATE SET
+         status = excluded.status,
+         started_at = COALESCE(stages.started_at, excluded.started_at),
+         preview_evidence = excluded.preview_evidence,
+         authority = 'watcher'
+       WHERE stages.authority = 'watcher'
+          OR (stages.authority = 'cli' AND stages.status = 'pending' AND stages.started_at IS NULL)`
+    )
+    for (const r of rows.slice(0, maxRows)) {
+      stmt.run(cid, r.stage, r.status, r.startedAt, JSON.stringify(r.evidence || {}))
+    }
+    return true
+  } catch {
+    return false // fail-open：锁竞争/库损坏/迁移未达——事件流不受影响，下轮重投影
+  } finally {
+    if (db) { try { db.close() } catch { /* 关闭失败不放大 */ } }
+  }
+}
+
+/** 步骤级工件映射：变更工件基名 → (阶段, 步骤名) 的对应——watcher 步骤节拍的数据源。 */
+export const PREVIEW_STEP_SOURCES = {
+  'proposal.md': { stage: 'brainstorm', step: '写设计文档并自审' },
+  'requirements.md': { stage: 'brainstorm', step: '写设计文档并自审' },
+  'design.md': { stage: 'brainstorm', step: '写设计文档并自审' },
+  'decisions.md': { stage: 'brainstorm', step: '写设计文档并自审' },
+  'plan.md': { stage: 'plan', step: '生成分级计划' },
+  'verify-result.md': { stage: 'verify', step: '输出验证报告' },
+  'verify-facts.json': { stage: 'verify', step: '输出验证报告' },
+  'module-impact.md': { stage: 'archive', step: 'extract-module-impact 与归档语义收尾' },
+}
+
+/**
+ * 纯函数：快照差分 → 步骤级预览行集合（预览账本 v2，D-004 兑现）。
+ * 粒度=工件信号可映射的步骤（tasks.md 勾选→execute 逐任务步不可靠映射，不做——纯思考
+ * 型步骤由 --done 批量自述，burst 已支持）。返回行带 stage+step 双键。
+ */
+export function projectPreviewSteps({ snapshot, prevSnapshot = null } = {}) {
+  if (!snapshot || snapshot.archived) return []
+  const files = snapshot.files || {}
+  const prevFiles = (prevSnapshot && prevSnapshot.files) || {}
+  const rows = []
+  for (const [fname, target] of Object.entries(PREVIEW_STEP_SOURCES)) {
+    if (!Object.prototype.hasOwnProperty.call(files, fname)) continue
+    const changed = prevFiles[fname] === undefined || JSON.stringify(files[fname]) !== JSON.stringify(prevFiles[fname])
+    rows.push({
+      stage: target.stage,
+      step: target.step,
+      status: 'in-progress',
+      startedAt: new Date(snapshot.ts || Date.now()).toISOString(),
+      evidence: { ts: snapshot.ts || null, file: fname, changed },
+    })
+  }
+  return rows
+}
+
+/**
+ * 写步骤级预览行（短连接，fail-open）：steps 表 authority='watcher'，仅当该步骤
+ * 不存在或也是 watcher 行时写入（CLI 步骤行不可中招）。
+ */
+export function writePreviewSteps({ specDir, changeName, rows, maxRows = 12 } = {}) {
+  if (!specDir || !changeName || !Array.isArray(rows) || rows.length === 0) return false
+  let db = null
+  try {
+    db = openDatabase(join(specDir, '.runtime', 'sillyspec.db'), {})
+    db.exec('PRAGMA busy_timeout = 5000')
+    const changeRow = db.prepare('SELECT id FROM changes WHERE name = ?').get(changeName)
+    if (!changeRow) return false
+    const cid = changeRow.id
+    const stageStmt = db.prepare("SELECT id FROM stages WHERE change_id = ? AND stage = ? AND (authority = 'watcher' OR authority = 'cli' OR authority IS NULL)")
+    const insStmt = db.prepare(
+      `INSERT INTO steps (stage_id, name, status, completed_at, ordering, authority, preview_evidence)
+       VALUES (?, ?, 'in-progress', NULL, 0, 'watcher', ?)
+       ON CONFLICT DO NOTHING`
+    )
+    for (const r of rows.slice(0, maxRows)) {
+      const stageRow = stageStmt.get(cid, r.stage)
+      if (!stageRow) continue // 阶段行不在场——CLI 尚未进入该阶段，不预建
+      insStmt.run(stageRow.id, r.step, JSON.stringify(r.evidence || {}))
+    }
+    return true
+  } catch {
+    return false
+  } finally {
+    if (db) { try { db.close() } catch {} }
+  }
+}

package/src/progress/change-registry.js

@@ -613,9 +613,9 @@ export class ChangeRegistry {
         const row = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
         if (row) {
           sqlDb.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`
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, authority)
+             VALUES (?, 'archive', 'completed', ?, ?, 'cli')
+             ON CONFLICT(change_id, stage) DO UPDATE SET status = 'completed', completed_at = excluded.completed_at, authority = 'cli'`
           ).run(row.id, now, now);
           const stageRow = sqlDb.prepare(
             'SELECT id FROM stages WHERE change_id = ? AND stage = ?'
@@ -638,6 +638,14 @@ export class ChangeRegistry {
           }
         }
       }
+      // 预览账本 GC（2026-09-23-watcher-preview-progress task-04 / FR-06）：归档收尾清 watcher
+      // 预览行（steps 随 stages 的 ON DELETE CASCADE 级联自动清）。fail-open：失败 warn 不阻断归档。
+      try {
+        const prow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
+        if (prow) sqlDb.prepare("DELETE FROM stages WHERE change_id = ? AND authority = 'watcher'").run(prow.id);
+      } catch (e) {
+        console.warn(`⚠️ 预览行 GC 失败（fail-open 不阻断归档）：${(e && e.message) || e}`);
+      }
       // 本地脏度（D-013 / task-04）：归档也是本地状态推进
       this.pm._touchLocalModified(cwd, changeName, now);
     });

package/src/progress/shared.js

@@ -27,8 +27,9 @@ export const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', '
 export const MAIN_FLOW_ORDER = ['brainstorm', 'plan', 'execute', 'verify', 'archive'];
 
 // progress 数据版本（v3 = SQLite；v4 = changes 加 base_ts / 本地脏度两列，platform-sync §8；
-// v6 = changes 加 owner_session 所有权列，2026-09-14-change-ownership-guards D-005@v1）
-export const CURRENT_VERSION = 6;
+// v6 = changes 加 owner_session 所有权列，2026-09-14-change-ownership-guards D-005@v1；
+// v8 = 出生阶段 'scan'→'brainstorm' + 存量出生默认行迁移，2026-09-27-change-birth-stage-brainstorm）
+export const CURRENT_VERSION = 8;
 
 // 滞留提示阈值（天，2026-08-30 用户反馈②：7 个「代码全落地但流程没收口」的变更挂 38 天
 // 无人发现）：活跃变更 last_active 距今超该天数且流程未收口（archive 未完成）时，progress

package/src/progress.js

@@ -15,6 +15,7 @@ import { join, basename, dirname, resolve, sep } from 'path';
 import { tmpdir, hostname } from 'os';
 import { writeAtomicSync } from './fs-atomic.js';
 import { DB } from './db.js';
+import { openDatabase } from './db-engine.js';
 import { checkExecuteCodeEvidence } from './stage-contract.js';
 import { ConsistencyDoctor } from './progress/consistency-doctor.js';
 import { ChangeRegistry } from './progress/change-registry.js';
@@ -270,6 +271,36 @@ const CHANGES_SUBDIR = 'changes';
 
 // ── ProgressManager ──
 
+/**
+ * 预览进度读出口（2026-09-23-watcher-preview-progress task-03 / FR-04）：
+ * 读 watcher 预览行（authority='watcher'，读侧保险丝之外的显式出口）+ evidence 解析。
+ * 纯只读短连接；库缺失/变更未注册/异常 → { exists:false, stages:[] }（fail-open）。
+ */
+export function readPreviewProgress(specDir, changeName) {
+  if (!specDir || !changeName) return { exists: false, stages: [] }
+  let db = null
+  try {
+    db = openDatabase(join(specDir, '.runtime', 'sillyspec.db'), { readOnly: true })
+    const changeRow = db.prepare('SELECT id FROM changes WHERE name = ?').get(changeName)
+    if (!changeRow) return { exists: false, stages: [] }
+    const rows = db.prepare(
+      "SELECT stage, status, started_at, preview_evidence FROM stages WHERE change_id = ? AND authority = 'watcher' ORDER BY stage"
+    ).all(changeRow.id)
+    return {
+      exists: true,
+      stages: rows.map((r) => {
+        let evidence = null
+        try { evidence = r.preview_evidence ? JSON.parse(r.preview_evidence) : null } catch { evidence = null }
+        return { stage: r.stage, status: r.status, startedAt: r.started_at, evidence }
+      }),
+    }
+  } catch {
+    return { exists: false, stages: [] }
+  } finally {
+    if (db) { try { db.close() } catch { /* 只读关闭失败不放大 */ } }
+  }
+}
+
 export class ProgressManager {
   /** 模块级 DB 连接池：Map<dbPath, DB>（SEC-09/PERF-10，见 _ensureDB 注释） */
   static _dbPool = new Map();
@@ -401,7 +432,7 @@ export class ProgressManager {
     const { id: changeId, name: cName, current_stage: currentStage, no_worktree: noWorktree, last_active: lastActive } = changeRow;
 
     // 2. 从 stages 表获取所有阶段（含 revision 列）
-    const stageRows = sqlDb.prepare('SELECT id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason FROM stages WHERE change_id = ? ORDER BY id').all(changeId);
+    const stageRows = sqlDb.prepare(`SELECT id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason FROM stages WHERE change_id = ? AND (authority = 'cli' OR authority IS NULL) ORDER BY id`).all(changeId);
     const stageMap = {};
     const stageIds = [];
     for (const row of stageRows) {
@@ -420,7 +451,7 @@ export class ProgressManager {
     if (stageIds.length > 0) {
       const placeholders = stageIds.map(() => '?').join(',');
       const stepRows = sqlDb.prepare(
-        `SELECT stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`
+        `SELECT stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds FROM steps WHERE stage_id IN (${placeholders}) AND (authority = 'cli' OR authority IS NULL) ORDER BY stage_id, ordering`
       ).all(...stageIds);
       // 按阶段分组步骤
       for (const row of stepRows) {
@@ -490,7 +521,9 @@ export class ProgressManager {
     }
 
     const result = {
-      _version: 6,
+      // 版本单一源（2026-09-27-change-birth-stage-brainstorm 收敛）：此前是字面量 6，
+      // v7 bump（watcher-preview-progress）漏改此处成「四处一致」之外的第五处漂移。
+      _version: CURRENT_VERSION,
       project: projectName,
       currentChange: cName,
       currentStage: currentStage || '',
@@ -572,7 +605,14 @@ export class ProgressManager {
 
     // 3. stages（该 change 下，用 change_name+stage 表达外键）
     const stageRows = sqlDb.prepare(
-      `SELECT id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason
+      // 权威视图渲染（D-007 钉，2026-09-23-watcher-preview-progress task-05）：被 watcher 认领的行
+      // 在平台载荷里按其 CLI 已知态（pending/未起止）投影——载荷与无预览的干净态逐字节一致，
+      // 不因预览认领缺行（隔离钉 T1 实证：纯过滤会整行剔除该阶段）。
+      `SELECT id, stage,
+         CASE WHEN authority = 'watcher' THEN 'pending' ELSE status END AS status,
+         CASE WHEN authority = 'watcher' THEN NULL ELSE started_at END AS started_at,
+         CASE WHEN authority = 'watcher' THEN NULL ELSE completed_at END AS completed_at,
+         revision, reopened_from_step, reopened_at, stale_reason
        FROM stages WHERE change_id = ? ORDER BY id`
     ).all(changeId);
     const stageJson = stageRows.map(r => ({
@@ -596,7 +636,7 @@ export class ProgressManager {
       const stepRows = sqlDb.prepare(
         `SELECT stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options,
                 wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds
-         FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`
+         FROM steps WHERE stage_id IN (${placeholders}) AND (authority = 'cli' OR authority IS NULL) ORDER BY stage_id, ordering`
       ).all(...stageIds);
       stepJson = stepRows.map(r => ({
         change_name: changeRow.name,
@@ -921,8 +961,8 @@ export class ProgressManager {
         for (const [stageName, stageData] of Object.entries(data.stages)) {
           // UPSERT stages 行（含 revision 列）
           sqlDb.prepare(
-            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason, authority)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'cli')
              ON CONFLICT(change_id, stage) DO UPDATE SET
                status = excluded.status,
                started_at = excluded.started_at,
@@ -930,7 +970,8 @@ export class ProgressManager {
                revision = COALESCE(excluded.revision, stages.revision),
                reopened_from_step = excluded.reopened_from_step,
                reopened_at = excluded.reopened_at,
-               stale_reason = excluded.stale_reason`
+               stale_reason = excluded.stale_reason,
+               authority = 'cli'`
           ).run(changeId, stageName, stageData.status || 'pending', stageData.startedAt || null, stageData.completedAt || null,
              stageData.revision || 0, stageData.reopenedFromStep || null, stageData.reopenedAt || null, stageData.staleReason || null);
 
@@ -1125,10 +1166,12 @@ export class ProgressManager {
       // 检查变更是否已存在
       const existing = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
       if (existing === undefined) {
-        // 插入 changes 行
+        // 插入 changes 行。出生阶段=brainstorm（2026-09-27 用户裁定「起步就是头脑风暴」）：
+        // scan 是 auxiliary（shared.js AUXILIARY_STAGES 语义），从未是变更主流程起点；
+        // 旧默认 'scan' 让 thin/quick 等不进主流程的变更全生命周期显示「🔍 代码扫描」误导。
         sqlDb.prepare(
           `INSERT INTO changes (name, current_stage, status, created_at, last_active, title, quicklog_id)
-           VALUES (?, 'scan', 'active', ?, ?, ?, ?)`
+           VALUES (?, 'brainstorm', 'active', ?, ?, ?, ?)`
         ).run(changeName, now, now, meta.title || null, meta.quicklogId || null);
       }
 
@@ -1203,7 +1246,7 @@ export class ProgressManager {
           const sqlDb = db.getDb();
           const now = new Date().toISOString();
           const ins = sqlDb.prepare(
-            `INSERT OR IGNORE INTO changes (name, current_stage, status, created_at, last_active) VALUES (?, 'scan', 'active', ?, ?)`
+            `INSERT OR IGNORE INTO changes (name, current_stage, status, created_at, last_active) VALUES (?, 'brainstorm', 'active', ?, ?)`
           ).run(changeName, now, now);
           const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
           if (changeRow !== undefined) {
@@ -1468,7 +1511,7 @@ export class ProgressManager {
 
     // 3. stages
     const stageRows = sqlDb.prepare(
-      'SELECT id, stage, status, started_at, completed_at, revision FROM stages WHERE change_id = ? ORDER BY id'
+      `SELECT id, stage, status, started_at, completed_at, revision FROM stages WHERE change_id = ? AND (authority = 'cli' OR authority IS NULL) ORDER BY id`
     ).all(changeId);
 
     const stages = {};
@@ -1481,7 +1524,7 @@ export class ProgressManager {
     if (stageRows.length > 0) {
       const placeholders = stageRows.map(() => '?').join(', ');
       const allStepRows = sqlDb.prepare(
-        `SELECT stage_id, name, status, output, completed_at FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`
+        `SELECT stage_id, name, status, output, completed_at FROM steps WHERE stage_id IN (${placeholders}) AND (authority = 'cli' OR authority IS NULL) ORDER BY stage_id, ordering`
       ).all(...stageRows.map(r => r.id));
       for (const sr of allStepRows) {
         if (!stepsByStage.has(sr.stage_id)) stepsByStage.set(sr.stage_id, []);