sillyspec 3.29.5 → 3.31.0

package/src/timeline.js

@@ -0,0 +1,218 @@
+/**
+ * timeline.js — 变更合成时间线（2026-09-26-watcher-timeline）。
+ *
+ * 只读合成器：watcher 事件流（jsonl）× tasks.md 勾选行 × git 提交锚 → 人类可读时间线。
+ * 轻量变更无阶段 --done 步骤面（平台 UI 时间线只覆盖完整流程），本模块把既有留痕事后
+ * 合成——零新落盘、零协议负担。CLI 出口：sillyspec watcher timeline --change <名>
+ * （index.js watcher case，与 alerts 同族只读）。
+ *
+ * 纯度口径：本文件全部纯函数（git 经 gitLook 注入面，测试零真仓）；I/O 与退出码归接线层。
+ * 诚实面（FR-04）：事件流 task-done 只记计数不记任务 id——勾选时刻按翻格顺序推断，表头
+ * 显式「≈」，计数链断裂标「推断不可用」；提交 hash 不可解析只显 hash 并标注。
+ */
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { aggregateStageTiming } from './watcher.js';
+
+/** tasks.md 勾选行解析：`- [x] task-01: 描述` / `- [ ] task-02 无冒号描述`。 */
+export function parseTaskLines(tasksMd) {
+  const out = [];
+  for (const line of String(tasksMd || '').split(/\r?\n/)) {
+    const m = /^[-*] \[( |x|X)\] (task-\d+):?[ \t]*(.*)$/.exec(line);
+    if (m) out.push({ id: m[2], checked: m[1].toLowerCase() === 'x', desc: m[3].trim() });
+  }
+  return out;
+}
+
+/**
+ * 翻格顺序推断（FR-04）：task-done（stage='tasks'）事件序列 → 每任务序号的勾选时刻。
+ * 计数链衔接（from === 游标）才赋值；**中段**断裂（from ≠ 游标）标 broken 并停止赋值。
+ * 尾部未覆盖（链完整但拍数少于任务数——在途变更未勾完）不标 broken（2026-09-26-watcher-timeline-p2
+ * 语义收窄：那是自然态不是断裂；「已勾任务缺时刻」由渲染层按事实单独标注）。
+ * @returns {{times:(number|null)[], broken:boolean}} times 按任务序号索引；未推断到 = null。
+ */
+export function inferFlipTimes(events, total) {
+  const times = new Array(Math.max(0, total || 0)).fill(null);
+  let cursor = 0;
+  let broken = false;
+  for (const e of events || []) {
+    if (!e || e.kind !== 'task-done' || (e.stage && e.stage !== 'tasks')) continue;
+    const m = /^checked (\d+)→(\d+)$/.exec(String(e.detail || ''));
+    if (!m) continue;
+    const from = Number(m[1]);
+    const to = Number(m[2]);
+    if (from !== cursor) { broken = true; break; }
+    for (let i = from; i < to && i < times.length; i++) times[i] = e.ts;
+    cursor = to;
+  }
+  return { times, broken };
+}
+
+/** 提交消息里的 task token 清单（去重保序）。 */
+function tokensOf(text) {
+  const out = [];
+  for (const t of String(text || '').match(/task-\d+(?!\d)/g) || []) {
+    if (!out.includes(t)) out.push(t);
+  }
+  return out;
+}
+
+/**
+ * 提交锚解析：事件流 kind=commit 的短 hash → gitLook 解析出主题/时间/token。
+ * @param {Function} gitLook (hash) => null | {hash, dateISO, message}（注入面，接线层包 gitQuiet）
+ * @returns {Array<{hash, ts, subject, tokens, resolvable}>} ts 取事件观测时刻（git 日期仅存证）。
+ */
+export function resolveCommitAnchors(events, gitLook) {
+  const out = [];
+  for (const e of events || []) {
+    if (!e || e.kind !== 'commit' || !e.detail) continue;
+    const hash = String(e.detail).trim();
+    let info = null;
+    try { info = gitLook ? gitLook(hash) : null; } catch { info = null; }
+    out.push({
+      hash,
+      ts: e.ts,
+      subject: info ? String(info.message || '').split(/\r?\n/)[0] : null,
+      tokens: info ? tokensOf(info.message) : [],
+      resolvable: Boolean(info),
+    });
+  }
+  return out;
+}
+
+/** 本地 HH:MM:SS（与 watcher alerts fmtLocal 同风格，供渲染层一致时间面）。 */
+function fmtHMS(ts) {
+  const d = new Date(Number(ts));
+  if (Number.isNaN(d.getTime())) return String(ts);
+  const p = (n) => String(n).padStart(2, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+
+const clip = (s, n) => {
+  const t = String(s ?? '');
+  return t.length > n ? t.slice(0, Math.max(0, n - 1)) + '…' : t;
+};
+
+/** 事件 → 时间轴行文本（图标+标签+剪裁 detail；提交行拼 subject）。 */
+function eventRow(e, anchors) {
+  const icon = { file: '📄', 'file-update': '📝', 'task-done': '✅', commit: '🔀', verify: '🔬', warning: '⚠️', archived: '📦' }[e.kind] || '·';
+  let label = e.detail || '';
+  if (e.kind === 'commit') {
+    const a = anchors.find((x) => x.hash === String(e.detail).trim());
+    label = a && a.resolvable
+      ? `${e.detail}  ${clip(a.subject, 56)}`
+      : `${e.detail}（subject 不可解析——hash 失联/他仓）`;
+  } else if (e.kind === 'warning') {
+    label = `${e.rule || 'warning'}  ${clip(e.detail, 64)}`;
+  } else {
+    label = clip(e.detail, 72);
+  }
+  return `${fmtHMS(e.ts)}  ${icon} ${label}`;
+}
+
+/** 秒数 → 人类可读时长（<60s 秒、<60h 分、以上时分）。 */
+function fmtDur(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}min`;
+  return `${Math.floor(m / 60)}h${m % 60}min`;
+}
+
+/**
+ * 合成渲染（纯函数，接线层 console.log）。
+ * @param {object} args
+ * @param {string} args.change 变更名
+ * @param {Array} args.events 事件流（readWatcherEvents.events）
+ * @param {Array|null} args.tasks parseTaskLines 产物（null=任务面缺失）
+ * @param {Array} args.anchors resolveCommitAnchors 产物
+ * @param {number|null} args.birthTs 诞生锚（工件 frontmatter created_at 毫秒；null=缺）
+ * @param {string|null} args.tier flow-state tier（null=缺/未知）
+ */
+export function renderTimeline({ change, events, tasks, anchors, birthTs, tier }) {
+  const L = [];
+  L.push(`📅 ${change} — 合成时间线（${tier || 'tier 未知'}｜事件流 × tasks.md × git 提交锚）`);
+  L.push('');
+  L.push('── 事件时间轴 ──');
+  if (birthTs != null) L.push(`${fmtHMS(birthTs)}  🁢 变更诞生（工件 frontmatter created_at）`);
+  if (!events || events.length === 0) L.push('（无事件——watcher 未观测到活动）');
+  for (const e of events || []) L.push(eventRow(e, anchors));
+
+  if (tasks) {
+    L.push('');
+    L.push('── 任务面（勾选时刻 ≈ 顺序推断｜tasks.md 描述行 × 提交锚）──');
+    const { times, broken } = inferFlipTimes(events, tasks.length);
+    if (broken) L.push('（计数链中段断裂——断裂点后勾选时刻推断不可用，标 ?）');
+    if (tasks.some((t, i) => t.checked && times[i] == null)) L.push('（已勾任务缺推断时刻——观测盲窗/水位丢失，标 ?）');
+    for (let i = 0; i < tasks.length; i++) {
+      const t = tasks[i];
+      const when = t.checked
+        ? (times[i] != null ? `≈${fmtHMS(times[i])}` : '?')
+        : '未勾';
+      const anchor = anchors.filter((a) => a.tokens.includes(t.id)).sort((a, b) => a.ts - b.ts)[0];
+      const ev = anchor ? anchor.hash : (t.checked ? '无提交锚⚠️' : '—');
+      L.push(`${t.id}  ${when.padEnd(10)}  ${clip(t.desc, 44).padEnd(46)}${ev}`);
+    }
+  } else {
+    L.push('');
+    L.push('── 任务面缺失（change 目录无 tasks.md——活跃/归档双路径均未命中）──');
+  }
+
+  const evN = (events || []).length;
+  const commits = anchors.length;
+  const lastTs = evN > 0 ? events[events.length - 1].ts : birthTs;
+  const wall = birthTs != null && lastTs != null ? Math.max(0, lastTs - birthTs) : null;
+  const done = tasks ? tasks.filter((t) => t.checked).length : null;
+  const stages = aggregateStageTiming(events || []);
+  L.push('');
+  L.push(`墙钟：${wall != null ? fmtDur(wall) : '未知'}｜事件 ${evN} 条｜提交 ${commits}｜${tasks ? `任务 ${done}/${tasks.length} 勾选` : '任务面缺失'}`);
+  if (stages.length > 0) {
+    L.push(`阶段墙钟：${stages.map((s) => `${s.stage} ${fmtDur(s.durationMs)}`).join('｜')}`);
+  }
+  L.push('注：观测起点≠诞生时刻（watcher 后拉起/单飞锁盲窗）；勾选时刻为顺序推断（事件不记任务 id）；描述行含机器稿截断。');
+  return L.join('\n');
+}
+
+/**
+ * 归档烤制文本（2026-09-28-archive-timeline-bake）：快照头注记 + renderTimeline 全文。
+ * 事件流机本位（.runtime gitignore），本快照随归档包进 git 跨机可读；watcher 终拍可能晚于
+ * 烤制落盘——诚实注记而非数据错误。eventsCopySkipped=副本未随包形态（尺寸超帽或读源失败，
+ * 评审 P3-1：注记必须与实际产出一致，不虚报副本在场）。
+ */
+export function renderBakedTimeline({ change, events, tasks, anchors, birthTs, tier, bakedAtIso, eventsCopySkipped = false }) {
+  const head = [
+    `# 合成时间线快照 — ${change}`,
+    '',
+    `> 烤制于归档链（${bakedAtIso}）：事件流机本位（.runtime gitignore），本快照随归档包进 git 跨机可读。`,
+    '> 末尾事件（含「目录已移入 archive」终拍）可能晚于烤制未入快照；勾选时刻为顺序推断（≈）。',
+    eventsCopySkipped
+      ? '> 原始事件副本未随包（尺寸超帽或读源失败）——细粒度复核回本机 .runtime 或平台 observation 事件面。'
+      : '> 原始事件副本：本目录 watcher-events.jsonl（时点快照）。',
+    '',
+  ]
+  return head.join('\n') + renderTimeline({ change, events, tasks, anchors, birthTs, tier })
+}
+
+/** change 目录双路径探测（活跃 > 归档）+ tasks.md 读取 → {changeDir, tasksMd}（缺 tasksMd=null）。 */
+export function loadChangeTasks(specBase, change) {
+  const active = join(specBase, 'changes', change);
+  const archived = join(specBase, 'changes', 'archive', change);
+  const dir = [active, archived].find((d) => { try { return readFileSync(join(d, 'tasks.md'), 'utf8') != null } catch { return false } });
+  if (!dir) return { changeDir: null, tasksMd: null };
+  return { changeDir: dir, tasksMd: readFileSync(join(dir, 'tasks.md'), 'utf8') };
+}
+
+/** 诞生锚：change 目录工件 frontmatter created_at（requirements > proposal > design > tasks）。 */
+export function readBirthTs(changeDir) {
+  if (!changeDir) return null;
+  for (const f of ['requirements.md', 'proposal.md', 'design.md', 'tasks.md']) {
+    try {
+      const m = /^created_at:\s*(\S+)/m.exec(readFileSync(join(changeDir, f), 'utf8'));
+      const t = m ? Date.parse(m[1]) : Number.NaN;
+      if (Number.isFinite(t)) return t;
+    } catch { /* 缺件续查 */ }
+  }
+  return null;
+}
+
+export default { parseTaskLines, inferFlipTimes, resolveCommitAnchors, renderTimeline, renderBakedTimeline, loadChangeTasks, readBirthTs };

package/src/ui-visual.js

@@ -0,0 +1,175 @@
+/**
+ * ui-visual —— UI 视觉变更的「过程引导 + 收口痕迹对账」（2026-09-27-ui-visual-guidance）。
+ *
+ * 背景教训（平台仓 2026-09-26-core-pages-visual-redesign 实证）：视觉保真度在流程里零承接
+ * ——design 写明截图走查硬门，verify 以「代码级佐证」降级放行仍 PASS，差距部署后才被肉眼
+ * 发现。本模块补两件事（收口不产新证据，只验在场）：
+ *   ① flow start 引导前置：检测 --input 触及前端页面或 UI → 输出「UI 变更执行须知」
+ *      （改前确认视觉基准、边改边渲染对照、证据随手落变更目录 visual-evidence.md、
+ *      视觉降级须用户裁决留痕）——agent 开工即知规程，不是收口才被告知；
+ *   ② verify「UI 视觉证据」分级探针：UI 触达变更收口时验证据在场性——
+ *      缺 visual-evidence.md → 默认 ⚠️ 警告（local.yaml ui_visual_gate: warn|error|off，
+ *      默认 warn）；design/requirements 声明视觉降级而无用户裁决留痕 → 恒 ❌ error
+ *      （仅 off 豁免）——堵 D-004 型静默降级。
+ *
+ * 仓中立：不硬编码任何特定仓的路径或命令（须知指引通用口径：原型、黄金页或现有截图均可为基准）。
+ * 检测为纯函数；探针只读变更目录内文件，fail-soft 同探针 8-11 先例。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const UI_VISUAL_PROBE_HEADING = '#### 探针 12：UI 视觉证据（分级门）'
+export const UI_EVIDENCE_FILENAME = 'visual-evidence.md'
+
+/* ── 检测启发式（正反例单测锁定；误判面=默认档一行警告，误漏面由文件面扩展名兜底）── */
+
+const UI_TOUCH_PATTERNS = [
+  /页面/, /前端/, /\bUI\b/i, /视觉/, /样式/, /界面/, /布局/, /主题色/, /配色/,
+  /\.tsx?\b/, /\.jsx\b/, /\.vue\b/, /\.svelte\b/, /\.css\b/, /\.scss\b/, /\.html\b/,
+  /组件/, /原型/, /截图/, /渲染/,
+]
+
+/** input/规约文本是否触及前端页面或 UI（关键词启发式，≥1 命中即算）。 */
+export function detectUiTouch(text) {
+  if (!text || typeof text !== 'string') return false
+  return UI_TOUCH_PATTERNS.some((re) => re.test(text))
+}
+
+/** 声明文件面是否含前端产物文件（design 清单路径扩展名口径——input 漏检的兜底源）。 */
+export function detectUiTouchInPaths(paths) {
+  if (!Array.isArray(paths)) return false
+  return paths.some((p) =>
+    /\.(tsx|jsx|vue|svelte|css|scss|less|html)$/i.test(String(p).replace(/^NEW:\s*/, '')),
+  )
+}
+
+/* ── flow start 须知（仓中立；证据约定与探针同源）── */
+
+export function buildUiGuidanceLines() {
+  return [
+    `🎨 UI 变更执行须知（本变更触及前端页面或 UI——检测命中即插入，advisory 引导非门禁）：`,
+    `   1. 改前确认视觉基准：原型产物、黄金页或该页现有截图——没有基准的「改好看」无法验收；`,
+    `   2. 边改边渲染对照：每完成一个页面任务单元就渲染实页与基准并排比对，差异清零再勾任务；`,
+    `   3. 证据随手落盘：对照截图与结论逐页记入变更目录 ${UI_EVIDENCE_FILENAME}（干活时顺手写，收口只验在场）；`,
+    `   4. 视觉降级须用户裁决留痕：执行中因约束对不齐基准而降级（结构收敛、范围缩小、样式统一级）`,
+    `      必须带对比截图停下找用户签字，裁决记录写进 ${UI_EVIDENCE_FILENAME}（含「用户裁决」字样段）——`,
+    `      静默降级会在收口被「UI 视觉证据」探针硬拦（error 门）。`,
+  ]
+}
+
+/* ── 分级探针 ── */
+
+/** local.yaml 读 ui_visual_gate（warn|error|off，默认 warn；CRLF 容错——手写行扫描器坑先例）。 */
+export function readUiVisualGate(specBase) {
+  try {
+    const raw = readFileSync(join(specBase, 'local.yaml'), 'utf8')
+    const m = raw.match(/^\s*ui_visual_gate\s*:\s*['\"]?(warn|error|off)['\"]?\s*$/m)
+    return m ? m[1] : 'warn'
+  } catch {
+    return 'warn'
+  }
+}
+
+const DOWNGRADE_LINE = /(降级|样式统一级|partial)/
+const VISUAL_LINE = /(视觉|UI|页面|样式|界面)/
+
+/** design/requirements 是否声明「视觉降级」（同行共现口径——行级命中防跨行误配；runUiVisualProbe 内部消费）。 */
+function detectVisualDowngrade(designText, requirementsText) {
+  for (const t of [designText, requirementsText]) {
+    if (!t) continue
+    for (const line of t.split(/\r?\n/)) {
+      if (DOWNGRADE_LINE.test(line) && VISUAL_LINE.test(line)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * UI 视觉证据探针（只读变更目录；fail-soft 由调用方 catch 兜底）。
+ * level 三态：error（降级无裁决留痕，或 gate=error 且缺证据）→ 收口阻断；
+ * warn（默认档缺证据）→ advisory 警告；ok（证据在场，或降级但有裁决留痕）。
+ */
+export function runUiVisualProbe({ changeDir, gate = 'warn' }) {
+  const read = (name) => {
+    try { return readFileSync(join(changeDir, name), 'utf8') } catch { return '' }
+  }
+  const designText = read('design.md')
+  const requirementsText = read('requirements.md')
+  const proposalText = read('proposal.md')
+  const evidenceText = read(UI_EVIDENCE_FILENAME)
+  const decisionsText = read('decisions.md')
+
+  const declaredPaths = extractQuotedPaths(designText)
+  const uiTouched =
+    detectUiTouch(`${proposalText}\n${requirementsText}`) ||
+    detectUiTouchInPaths(declaredPaths)
+
+  if (gate === 'off') {
+    return { applicable: false, uiTouched, level: 'ok', notes: ['ui_visual_gate=off——探针关闭（含降级硬规则）'] }
+  }
+  if (!uiTouched) {
+    return { applicable: false, uiTouched: false, level: 'ok', notes: [] }
+  }
+
+  const evidencePresent = evidenceText.trim().length > 0
+  const downgradeDeclared = detectVisualDowngrade(designText, requirementsText)
+  const rulingPresent = evidenceText.includes('用户裁决') || decisionsText.includes('用户裁决')
+
+  let level = 'ok'
+  const notes = []
+  if (downgradeDeclared && !rulingPresent) {
+    level = 'error'
+    notes.push('design/requirements 存在视觉降级声明而变更目录无用户裁决留痕（visual-evidence.md 或 decisions.md 含「用户裁决」）——静默降级禁止收口')
+  } else if (!evidencePresent) {
+    level = gate === 'error' ? 'error' : 'warn'
+    notes.push(`变更目录缺 ${UI_EVIDENCE_FILENAME}（渲染对照证据应在执行时随手落盘——收口只验在场不产新证据）`)
+  } else if (downgradeDeclared && rulingPresent) {
+    notes.push('视觉降级已带用户裁决留痕')
+  }
+
+  return {
+    applicable: true,
+    uiTouched: true,
+    evidencePresent,
+    downgradeDeclared,
+    rulingPresent,
+    level,
+    notes,
+  }
+}
+
+/** design 文件变更清单行的路径粗提（反引号/裸路径行——探针侧仅作 UI 扩展名兜底命中，不追求全解）。 */
+function extractQuotedPaths(designText) {
+  if (!designText) return []
+  const paths = []
+  for (const m of designText.matchAll(/`([^`]+)`/g)) {
+    if (/[\\/]/.test(m[1])) paths.push(m[1])
+  }
+  for (const line of designText.split(/\r?\n/)) {
+    const t = line.trim()
+    const m = t.match(/^(?:修改|新增|删除|NEW:)?\s*((?:frontend|src|web|app|client|ui)\b[\\/][^\s|]+)/i)
+    if (m) paths.push(m[1])
+  }
+  return paths
+}
+
+/** 探针 12 段渲染（renderProbe11Lines 同构：不适用 / ❌ error / ⚠️ warn / ✅ ok + 口径注记）。 */
+export function renderUiVisualProbeLines(p12) {
+  const L = [UI_VISUAL_PROBE_HEADING]
+  if (!p12 || !p12.applicable) {
+    L.push(`- 不适用（${p12 && p12.uiTouched ? 'ui_visual_gate=off' : '非 UI 触达变更（input/声明文件面均未命中）——零打扰'}）`)
+    for (const n of (p12 && p12.notes) || []) L.push(`- ℹ️ ${n}`)
+    return L
+  }
+  L.push('<!-- 口径注记：在场性检查非语义审计——只验 visual-evidence.md 存在非空与降级裁决留痕，不判对照结论对错（语义面归 verify-result 人工判断层）。证据应在执行时按 flow start「UI 变更执行须知」随手产生；本探针不要求收口现做。分级：缺证据默认 ⚠️（local.yaml ui_visual_gate=error 升阻断）；视觉降级无「用户裁决」留痕恒 ❌（off 豁免）。 -->')
+  if (p12.level === 'error') {
+    for (const n of p12.notes) L.push(`- ❌ ${n}`)
+    L.push('  - 修复：补渲染对照证据到 visual-evidence.md；降级项补用户裁决留痕（含「用户裁决」字样段）后重跑收口')
+  } else if (p12.level === 'warn') {
+    for (const n of p12.notes) L.push(`- ⚠️ ${n}`)
+  } else {
+    L.push(`- ✅ UI 视觉证据在场（${UI_EVIDENCE_FILENAME} 非空${p12.downgradeDeclared ? '，降级带用户裁决留痕' : ''}）`)
+    for (const n of p12.notes || []) L.push(`- ℹ️ ${n}`)
+  }
+  return L
+}

package/src/verify-draft.js

@@ -0,0 +1,214 @@
+/**
+ * verify-draft.js — verify 填槽制（r5l-forensic-verdict 方案 3 / 评审护栏#2，v2 件二）。
+ *
+ * 背景（R5-L 桶②）：verify-result.md 被读写 14 次、每次 python-heredoc 整份回填一次全量重发
+ * （两次各挂起 7 分钟）；模板 29KB 里 CLI 已能机械预填大部分。--draft 模式把四节 CLI 可算部分
+ * 预填成完整句子（任务完成度 summarizeTaskCompletion / 风险等级 resolveChangeRisk（detectChangeRisk
+ * 散文词表已退役 D-008）/ 测试结果 P2 test-ledger→质量扫描记录（与 verify 门对账同源同优先级）/
+ * 决策追踪 buildDecisionChainMatrix），agent 只填三处显式 <!--AGENT:--> 槽——工作流收敛为
+ * draft→填槽→复核，verify-result 读写 ≤3 次。
+ *
+ * 承重件 = --done 篡改门禁（护栏#2：守卫必须是验收侧的机制，永远不是生成侧的劝说）：
+ *   - 机器预填段以 MACHINE-DRAFT begin/end 注释对包裹，begin 标记内嵌该段内容的 sha256；
+ *   - sidecar（.runtime/verify-draft-<change>.json）记录各段哈希与生成时点；
+ *   - verify --done 对账（checkDraftIntegrity）：标记被删 / 内容哈希失配 → 阻断回滚——
+ *     heredoc 整份重写会同时破坏两者，无论 Write 可用与否均免疫（机制修法，不依赖劝说）；
+ *   - 确要改机器段：`verify-probes --change <名> --amend-draft` 重锚哈希并留痕
+ *     （sidecar amendments 审计：时点 + 改动段清单）。
+ *
+ * 信任边界：sidecar 与骨架同在 agent 可写空间，伪造需主动协同造假——与 verify-facts.json /
+ * 质量扫描记录同级威胁模型（本门拦的是 heredoc 习惯性整份重写与意外覆盖，不是对抗性攻击）。
+ * 纯 --init（无 --draft）路径零变化；无 sidecar → 门禁 not-applicable（存量变更零红）。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { writeAtomicSync } from './fs-atomic.js'
+// 三件套原语消费方化（R7 切片三 task-04）：标记格式/指纹/三态判定/重锚的机械半边在本模块，
+// verify-draft 保留 verify-result 专有面（骨架正则/槽契约/sidecar 路径）与全部既有导出签名。
+import { bodyHash, wrapSection, verifyMarkers, reanchorText } from './machine-draft.js'
+
+const sha256 = bodyHash
+
+const AMEND_CMD = 'sillyspec verify-probes --change <变更名> --amend-draft'
+
+/** sidecar 路径（.runtime 下，与质量扫描记录/探针回执同族） */
+export function verifyDraftSidecarPath(runtimeRoot, changeName) {
+  return join(runtimeRoot, `verify-draft-${changeName}.json`)
+}
+
+/**
+ * 构建机器段：四节 CLI 可算部分的完整句子（纯函数——材料由调用方备齐，可测）。
+ * 各段 key 稳定（指纹与 sidecar 对账键）；材料缺不到时给「降级说明句」而非空段——
+ * 机器段的降级也要是完整句子（读报告的人不需要反查工具行为）。
+ */
+export function buildDraftSections({ summarize, risk, testResult, decisionChain }) {
+  const sections = []
+  // ── 任务完成度（summarizeTaskCompletion 同源）──
+  sections.push({
+    key: 'task-completion',
+    body: [
+      summarize.report,
+      `- 总任务：${summarize.total}；已完成（review verdict 口径）：${summarize.completed}`,
+      summarize.pending && summarize.pending.length > 0
+        ? `- 未完成：${summarize.pending.map((p) => `${p.id}（${p.reason || '未勾'}）`).join('、')}`
+        : '- 未完成：无',
+    ].filter(Boolean).join('\n'),
+  })
+  // ── 变更风险等级（resolveChangeRisk 同源，evaluateConclusionDraft 先例口径）──
+  sections.push({
+    key: 'risk-level',
+    body: risk
+      ? [
+          `- 机器判级：tier=${risk.tier}${risk.explicit ? `（design.md 显式声明 = ${risk.level}——显式声明已入判定）` : '（design.md 无显式 risk_level 声明）'}`,
+          risk.evidenceRequired
+            ? `- ⚠️ 命中 evidence:true 声明危险面（${(risk.hitPrefixes || []).join('、')}）——integration/deployment-critical 档：需集成证据链（回执槽 + Runtime Evidence），下方「集成验证回执」为例外人工槽`
+            : '- 未命中 evidence:true 声明危险面——无集成证据链硬要求（「集成验证回执」节机器判「无」）',
+          '- 判级输入：design 文件清单 × blast 声明（同 verify 门 evaluateConclusionDraft 口径；判定被新事实推翻时在「审查叙述」槽说明）',
+        ].join('\n')
+      : '- 机器判级降级：无法解析 design 文件清单/blast 声明（无 design.md 或清单为空）——按审查叙述确认实际等级（局部修补通常 doc-only / unit-sufficient）',
+  })
+  // ── 测试结果（P2 账本 → 质量扫描记录，与 verify 门对账同源同优先级）──
+  sections.push({
+    key: 'test-result',
+    body: testResult
+      ? [
+          `- ${testResult.source === 'ledger' ? '♻️ P2 三键账本复用（代码×测试面×环境全等）' : '♻️ noAI 质量扫描实测记录复用（代码指纹匹配）'}：\`${testResult.command}\` — ${testResult.status === 'passed' ? '通过' : testResult.status}`,
+          `- 实测于 ${testResult.ranAt}${testResult.durationMs != null ? `，耗时 ${Math.round(testResult.durationMs / 1000)}s` : ''}${testResult.total != null ? `，${testResult.total} 断言` : ''}`,
+          '- verify `--done` 门与本文对账同源（P2 账本 > 扫描记录 > 亲跑）——正文与门结论冲突时以门为准并在此说明差异',
+        ].join('\n')
+      : '- 本 draft 生成时点无 P2 账本/质量扫描记录（verify 步「运行测试和质量扫描」尚未跑）——该步实测后门对账自动落账，此处以门结论为准（无需手改本段）',
+  })
+  // ── 决策追踪（buildDecisionChainMatrix 机械半边）──
+  sections.push({
+    key: 'decision-chain',
+    body: decisionChain && decisionChain.rows && decisionChain.rows.length > 0
+      ? [
+          `- 决策链机械半边：${decisionChain.decisionCount} 条决策 × ${decisionChain.taskCount} 张 task 卡（D→FR→Task 自 decisions.md × tasks/*.md frontmatter 构建）`,
+          '| 决策 ID | FR | Task | Evidence | 状态 |',
+          '|---|---|---|---|---|',
+          ...decisionChain.rows,
+          '- Evidence / 状态两列是人工判断（机器不代笔）——逐格复核，未闭环行在「审查叙述」槽标注风险',
+        ].join('\n')
+      : '- 本变更无 decisions.md（或零决策条目）——决策追踪无机器面对账，如执行期做过真实取舍在「审查叙述」槽说明',
+  })
+  return sections
+}
+
+/** 段 key → 骨架标题关键词（骨架标题行包含这些词即命中该段） */
+function sectionKeyword(key) {
+  switch (key) {
+    case 'task-completion': return '任务完成度'
+    case 'risk-level': return '变更风险等级'
+    case 'test-result': return '测试结果'
+    case 'decision-chain': return '决策追踪矩阵'
+    default: return key
+  }
+}
+
+/**
+ * draft 化主入口：骨架文本 → draft 文本（机器段替换 + 三 AGENT 槽标注 + 顶部模式横幅）。
+ * 纯文本变换（落盘与 sidecar 归 applyDraftMode）。
+ * @returns {{ text: string, applied: string[], slots: number }}
+ */
+export function transformSkeletonToDraft(skeletonText, sections) {
+  let text = skeletonText
+  const applied = []
+  for (const sec of sections) {
+    const kw = sectionKeyword(sec.key)
+    const headRe = new RegExp(`^(## [^\\n]*${kw}[^\\n]*\\n)([\\s\\S]*?)(?=^## |\\n*$)`, 'm')
+    const m = text.match(headRe)
+    if (!m) continue
+    const body = m[2]
+    // 幂等闸：段内已有 MACHINE-DRAFT 标记或已非 TODO 占位（手写正文）→ 不动
+    if (body.includes('MACHINE-DRAFT:')) continue
+    if (!/<!--TODO|<待填|<!-- 结论=|<!--\s*无 cannot_verify/.test(body)) continue
+    const wrapped = wrapSection({ key: sec.key, body: sec.body, amendCmd: AMEND_CMD })
+    text = text.slice(0, m.index) + m[1] + wrapped + text.slice(m.index + m[0].length)
+    applied.push(sec.key)
+  }
+  // 三 AGENT 槽标注（幂等：已有标注零改动）——结论枚举槽行契约不动（gate 消费面）
+  if (!text.includes('<!--AGENT:')) {
+    text = text
+      .replace(/(结论枚举：`<待填：三选一>`)/, '<!--AGENT:槽1/3 结论枚举——替换上行占位，槽行格式勿改（gate 判定消费面） -->\n$1')
+      .replace(/(\| <待填：env-blocked \/ manual-acceptance \/ db-script \/ other> \| <待填：移交条目> \| <待填：复跑\/验收条件> \|)/, '<!--AGENT:槽2/3 移交项——按需增行；结论=PASS/FAIL 时本表写「无」 -->\n$1')
+      .replace(/(## 设计一致性 \[层：人工判断\]\n)(<!--TODO[^>]*-->)/, '$1<!--AGENT:槽3/3 审查叙述——设计偏差（无偏差显式写「一致」）+ 技术债务叙述（探针 1 统计已机器预填在「技术债务」节）；替换下方 TODO 注释为正文 -->\n$2')
+  }
+  // 顶部横幅（draft 模式可见性：读写 ≤3 次的工作流说明——机制不带劝说，只说事实）
+  if (!text.includes('<!-- VERIFY-DRAFT-MODE -->') && applied.length > 0) {
+    const banner = [
+      '<!-- VERIFY-DRAFT-MODE -->',
+      '> **填槽模式**：机器段（MACHINE-DRAFT 标记包裹，篡改会被 --done 拒收）之外，你只填三处',
+      '> AGENT 槽：①结论枚举 ②移交项 ③审查叙述。工作流 = 本 draft → 填槽 → `--done` 复核，',
+      '> verify-result 读写 ≤3 次。改机器段唯一通道：`' + AMEND_CMD + '`（留痕重锚）。',
+      '',
+    ].join('\n')
+    text = text.replace(/(^# [^\n]*\n)/, `$1\n${banner}`)
+  }
+  return { text, applied, slots: 3 }
+}
+
+/**
+ * draft 模式落盘 + sidecar 记账（--init --draft 消费）。
+ * @returns {{ applied: string[], sidecarPath: string }|null} 无可替换段（非骨架态/已 draft）→ null
+ */
+export function applyDraftMode({ mdPath, changeName, runtimeRoot, sections }) {
+  let text
+  try { text = readFileSync(mdPath, 'utf8') } catch { return null }
+  const { text: next, applied } = transformSkeletonToDraft(text, sections)
+  if (applied.length === 0) return null
+  try {
+    writeAtomicSync(mdPath, next)
+  } catch (e) {
+    console.warn(`⚠️ verify draft 落盘失败（fail-soft，骨架保持原态）: ${e && e.message ? e.message : e}`)
+    return null
+  }
+  const sidecar = { schemaVersion: 1, change: changeName, generatedAt: new Date().toISOString(), sections: {}, amendments: [] }
+  for (const sec of sections) {
+    if (applied.includes(sec.key)) sidecar.sections[sec.key] = { hash: sha256(sec.body) }
+  }
+  const sidecarPath = verifyDraftSidecarPath(runtimeRoot, changeName)
+  try { writeAtomicSync(sidecarPath, JSON.stringify(sidecar, null, 2) + '\n') } catch { /* sidecar 失败 → 门禁 not-applicable（降级放行，不阻断） */ }
+  return { applied, sidecarPath }
+}
+
+/**
+ * --done 篡改门禁（承重件，验收侧）：sidecar 在案时逐段对账。
+ * @returns {{ applicable: boolean, ok: boolean, violations: string[] }}
+ *   not-applicable（无 sidecar）→ 放行（存量/非 draft 变更零红）；
+ *   违规 = 标记被删（含整段删除）/ 内容哈希失配（整份重写必中）。
+ */
+export function checkDraftIntegrity({ mdPath, changeName, runtimeRoot }) {
+  const sidecarPath = verifyDraftSidecarPath(runtimeRoot, changeName)
+  let sidecar = null
+  try { sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8')) } catch { return { applicable: false, ok: true, violations: [] } }
+  if (!sidecar || sidecar.schemaVersion !== 1 || !sidecar.sections) return { applicable: false, ok: true, violations: [] }
+  let text = ''
+  try { text = readFileSync(mdPath, 'utf8') } catch {
+    return { applicable: true, ok: false, violations: ['verify-result.md 不可读（draft sidecar 在案）'] }
+  }
+  const violations = verifyMarkers({ text, sections: sidecar.sections, amendCmd: AMEND_CMD })
+  return { applicable: true, ok: violations.length === 0, violations }
+}
+
+/**
+ * --amend-draft：对 md 中现存标记段按**当前内容**重锚哈希（标记与 sidecar 同步刷新），
+ * sidecar 追加 amendment 审计（时点 + 段清单）。返回重锚段键（空 = 无可重锚标记）。
+ */
+export function amendDraftMarkers({ mdPath, changeName, runtimeRoot }) {
+  let text
+  try { text = readFileSync(mdPath, 'utf8') } catch { return [] }
+  const { text: next, keys, contentByKey } = reanchorText({ text, amendCmd: AMEND_CMD })
+  if (keys.length === 0) return []
+  try { writeAtomicSync(mdPath, next) } catch (e) {
+    console.warn(`⚠️ amend-draft 重锚落盘失败: ${e && e.message ? e.message : e}`)
+    return []
+  }
+  // sidecar：合并既有 + amendment 审计
+  const sidecarPath = verifyDraftSidecarPath(runtimeRoot, changeName)
+  let sidecar = { schemaVersion: 1, change: changeName, generatedAt: new Date().toISOString(), sections: {}, amendments: [] }
+  try { sidecar = { ...sidecar, ...JSON.parse(readFileSync(sidecarPath, 'utf8')) } } catch { /* 无既有 → 新立 */ }
+  for (const k of keys) sidecar.sections[k] = { hash: sha256(contentByKey[k]) }
+  sidecar.amendments = [...(sidecar.amendments || []), { at: new Date().toISOString(), keys }]
+  try { writeAtomicSync(sidecarPath, JSON.stringify(sidecar, null, 2) + '\n') } catch { /* 审计失败不回滚重锚 */ }
+  return keys
+}