sillyspec 3.27.12 → 3.28.2

package/.claude/worktrees/sillyspec-data-model-research/src/quicklog.js

@@ -1,852 +0,0 @@
-/**
- * quicklog.js — QUICKLOG 记录的 CLI 接管层
- *
- * 历史问题：QUICKLOG 条目（ql-ID 分配 + 追加）原本由 Agent（LLM）手写
- * （见 src/stages/quick.js 旧 prompt）。两个后果：
- *   1. 漏写静默通过：CLI 只查目录级存在性，agent 漏写仍报「3/3 SAFE」。
- *   2. 并发丢更新：多 quick 会话并发写同一 per-user QUICKLOG 文件，读-改-写非原子，
- *      已有实证（QUICKLOG-qinyi.md 同一 ql-20260604-001-7a4c 出现两次）。
- *
- * 本模块把分配与写入下沉到 CLI 进程内，O_EXCL lockfile 串行化，彻底消除上述问题。
- * 无新 npm 依赖（仅 fs/path/crypto）——匹配项目零 FS 工具依赖的风格。
- */
-import { join, dirname, basename } from 'path'
-import { getRule } from './stage-contract-spec.js'
-import {
-  openSync, closeSync, unlinkSync, statSync, mkdirSync, existsSync,
-  readFileSync, writeFileSync, writeSync, readdirSync, renameSync, appendFileSync, rmSync,
-} from 'fs'
-import { randomBytes } from 'crypto'
-
-const sleep = (ms) => new Promise(r => setTimeout(r, ms))
-
-/**
- * O_EXCL 文件锁。`openSync(lockPath,'wx')` 独占创建并写入持有者唯一 id；已存在则按
- * mtime 判 stale 偷锁（rename 原子抢占 + 内容校验），否则退避重试至超时。
- * CLI 短进程、低频写入，stale 阈值 30s 足够。
- *
- * 偷锁为何用 rename 而非 unlink（2026-08-20 体检 BUG-02）：两进程同偷一把 stale 锁时，
- * 后到者的 unlink 会把先到者刚重建的新锁删掉（TOCTOU）→ 双进程同时进临界区。
- * rename 到唯一名后比对内容：只有"观察时看到的那把锁"才允许删除；偷到并发者
- * 新建的锁则原路放回。残余窗口仅剩"纳秒级三方精确竞争"（放回前 existsSync 检查
- * 与 rename 之间），相比旧实现的必现双进已可忽略。
- * @param {string} lockPath 锁文件路径（建议与被保护文件同目录）
- * @param {() => (any|Promise<any>)} fn 临界区
- * @param {{staleMs?:number, timeoutMs?:number, retryMs?:number, content?:string}} opts
- *   content：锁文件内容（默认 pid-randomId）。供超时报错时展示持有者语义（如 apply 锁写
- *   {pid, changeName}）——仅展示用途，抢占/偷锁逻辑只比对内容一致性不解析语义。
- */
-export async function withFileLock(lockPath, fn, opts = {}) {
-  const { staleMs = 30000, timeoutMs = 10000, retryMs = 50, content = null } = opts
-  mkdirSync(dirname(lockPath), { recursive: true })
-  const start = Date.now()
-  const myId = content || `${process.pid}-${randomBytes(6).toString('hex')}`
-  let fd = null
-  // 抢锁循环
-  while (true) {
-    try {
-      fd = openSync(lockPath, 'wx') // O_EXCL：已存在抛 EEXIST
-      writeSync(fd, myId)
-      break
-    } catch (e) {
-      if (e.code !== 'EEXIST') throw e
-      // 锁已存在：判 stale（持有进程崩溃残留）
-      try {
-        const mtime = statSync(lockPath).mtimeMs
-        if (Date.now() - mtime > staleMs) {
-          try {
-            const observed = readFileSync(lockPath, 'utf8') // 观察到的持有者 id
-            const claim = `${lockPath}.steal-${randomBytes(6).toString('hex')}`
-            renameSync(lockPath, claim) // 原子抢占：并发者只可能有一个 rename 成功
-            if (readFileSync(claim, 'utf8') === observed) {
-              try { unlinkSync(claim) } catch {} // 确实是那把 stale 锁 → 回收
-            } else {
-              // 偷到并发者新建的锁：放回（原位已被占则放弃，先占者保留）
-              let restored = false
-              try { if (!existsSync(lockPath)) { renameSync(claim, lockPath); restored = true } } catch {}
-              if (!restored) { try { unlinkSync(claim) } catch {} }
-            }
-          } catch {}
-          continue
-        }
-      } catch {}
-      if (Date.now() - start > timeoutMs) {
-        throw new Error(`文件锁超时（${timeoutMs}ms）: ${lockPath}`)
-      }
-      await sleep(retryMs)
-    }
-  }
-  try {
-    return await fn()
-  } finally {
-    try { closeSync(fd) } catch {}
-    try { unlinkSync(lockPath) } catch {} // 释放（容忍已不存在）
-  }
-}
-
-// ── 内部工具 ──
-
-function todayStamp(d = new Date()) {
-  return d.getFullYear()
-    + String(d.getMonth() + 1).padStart(2, '0')
-    + String(d.getDate()).padStart(2, '0')
-}
-
-function nowDatetime(d = new Date()) {
-  return todayStamp(d).slice(0, 4) + '-' + todayStamp(d).slice(4, 6) + '-' + todayStamp(d).slice(6, 8)
-    + ' ' + String(d.getHours()).padStart(2, '0') + ':' + String(d.getMinutes()).padStart(2, '0') + ':' + String(d.getSeconds()).padStart(2, '0')
-}
-
-// 描述压成一行、限长，避免破坏 QUICKLOG 条目结构
-export function sanitizeDesc(description) {
-  const s = String(description || '').replace(/[\r\n]+/g, ' ').trim()
-  if (!s) return '(quick 任务)'
-  return s.length > 120 ? s.slice(0, 120) + '…' : s
-}
-
-
-// ── 平台推送（best-effort，2026-08-16-change-center-quick-tab task-06 / D-003）──
-
-// 读 local.yaml platform 段（url+token）。quicklog 不 import sync.js（会拖 ProgressManager
-// 整链），自带同款轻量解析：只取 platform.url / platform.token 两键，与 parseSimpleYaml
-// 同风格（丢注释可接受——只读）。未连接返回 null（合法本地状态，静默跳过）。
-function _readPlatformConfig(specBase) {
-  try {
-    // specBase 即 <cwd>/.sillyspec（或平台 specRoot）；local.yaml 就在 spec 根下
-    const yamlPath = join(specBase, 'local.yaml')
-    if (!existsSync(yamlPath)) return null
-    const lines = readFileSync(yamlPath, 'utf8').split(/\r?\n/)
-    let inPlatform = false
-    const cfg = {}
-    for (const line of lines) {
-      if (!line.trim() || line.trim().startsWith('#')) continue
-      if (!/^\s/.test(line)) inPlatform = line.startsWith('platform:')
-      else if (inPlatform) {
-        const m = line.match(/^\s+(url|token)\s*:\s*(.*)$/)
-        if (m) {
-          let v = m[2].trim()
-          if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) v = v.slice(1, -1)
-          if (v) cfg[m[1]] = v
-        }
-      }
-    }
-    if (!cfg.url || !cfg.token) return null
-    return cfg
-  } catch {
-    return null
-  }
-}
-
-const PUSH_TIMEOUT_MS = 5_000
-
-// 从文件全文提取指定 qlId 的条目块（## 头到下一个 ## 头/文件尾）。null=未命中。
-// 与平台 quicklog_parser.py 同款切分口径（剥 \r），保证 CLI 推送的 raw_block 与平台解析一致。
-function extractRawBlock(content, qlId) {
-  if (!content) return null
-  const lines = content.split('\n')
-  const start = lines.findIndex(l => l.replace(/\r$/, '').startsWith(`## ${qlId} |`))
-  if (start === -1) return null
-  let end = lines.length
-  for (let i = start + 1; i < lines.length; i++) {
-    if (lines[i].replace(/\r$/, '').startsWith('## ')) { end = i; break }
-  }
-  return lines.slice(start, end).map(l => l.replace(/\r$/, '')).join('\n').trimEnd()
-}
-
-// 落盘条目块 → 推送 payload（design §5.3：以落盘终态为准，不从入参拼）。
-// 宽松标签解析对齐平台：全半角冒号、多条状态行取最后、文件行单行/多行 bullet。
-function buildPushPayloadFromRaw(rawBlock, { ql_id, author_raw, status, linked_changes, fallback_title }) {
-  const payload = {
-    ql_id,
-    timestamp: null,
-    title: fallback_title || '(quick 任务)',
-    status,
-    status_note: null,
-    author_raw,
-    linked_changes: Array.isArray(linked_changes) ? linked_changes : [],
-    files: [],
-    body_sections: {},
-    raw_block: rawBlock,
-  }
-  if (!rawBlock) return payload
-  const lines = rawBlock.split('\n')
-  const header = lines[0] || ''
-  const parts = header.split('|').map(s => s.trim())
-  if (parts.length >= 3) {
-    payload.timestamp = parts[1] || null
-    payload.title = parts.slice(2).join('|').trim() || payload.title
-  }
-  // 顶层标签白名单（^ 行首锚定）：D-004@v1 根因块嵌套四子字段（- 现象：/- 根因：/- 护栏：/- 证据： 列表行）
-  // 因「- 」前缀不匹配本正则——它们是根因块正文内的列表行续行，不是新顶层标签，经 lastLabel 挂载
-  // 进 body_sections[根因]（见下方 inFiles 复位注释）。顶层四字段边界解析不受影响（R-03）。
-  const labelRe = /^(状态|关联变更|文件|审计|需求|根因|方案|结果)\s*[：:]\s*(.*)$/
-  const bulletRe = /^-\s+(.*)$/
-  let inFiles = false
-  let inLinked = false
-  let lastLabel = null
-  let lastStatus = null
-  for (const line of lines.slice(1)) {
-    const stripped = line.trim()
-    if (!stripped) { inFiles = false; inLinked = false; continue }
-    const m = stripped.match(labelRe)
-    if (m) {
-      const [, label, value] = m
-      if (label === '状态') lastStatus = value
-      else if (label === '关联变更') { payload.linked_changes = value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean); inLinked = true; inFiles = false }
-      else if (label === '文件') { if (value) payload.files.push(...value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean).map(p => ({ path: p, note: null }))); inFiles = true; inLinked = false }
-      else if (label === '审计') { /* D-8 advisory 行：只进 raw_block 不进结构化段（body_sections 不扩 schema），并阻断续行误挂 */ lastLabel = null; inFiles = false; inLinked = false }
-      // 进入 需求/根因/方案/结果 字段块须关闭 inFiles/inLinked 续行模式（task-07 / D-004@v1）：否则根因块内
-      // 嵌套子字段列表行（- 现象：… 等）会命中下方「文件 bullet」分支被劫进 payload.files，从根因正文截断丢失。
-      else { payload.body_sections[label] = value; lastLabel = label; inFiles = false; inLinked = false }
-      continue
-    }
-    if (bulletRe.test(stripped) && inFiles) {
-      payload.files.push({ path: stripped.replace(/^-\s+/, ''), note: null })
-      continue
-    }
-    if (bulletRe.test(stripped) && inLinked) {
-      payload.linked_changes.push(...stripped.replace(/^-\s+/, '').split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean))
-      continue
-    }
-    if (lastLabel) payload.body_sections[lastLabel] += '\n' + stripped
-  }
-  // 状态以落盘为准（flip 后是「已完成」或「已完成（括注）」）——多条取最后
-  if (lastStatus) {
-    payload.status = lastStatus.startsWith('已完成') ? 'completed'
-      : lastStatus.startsWith('已暂存') ? 'partial_done'
-      : lastStatus.startsWith('进行中') ? 'in_progress'
-      : status
-    const note = lastStatus.match(/（(.+)）$/)
-    payload.status_note = note ? note[1] : null
-  }
-  // 白名单正则对齐平台（^\d{4}-\d{2}-\d{2}- 才进列表，防自由文本进反向区块）
-  payload.linked_changes = payload.linked_changes.filter(c => /^\d{4}-\d{2}-\d{2}-/.test(c))
-  return payload
-}
-
-// 单条推送：payload 字段对齐平台 QuicklogEntryPushRequest（snake_case）。测试经 allocate/complete 间接触发。
-// 任何失败（无配置/网络/非 2xx/超时）静默 warn 一行不抛（FR-02 best-effort，quick 主流程零阻断）。
-async function pushQuicklogEntryToPlatform(specBase, entry) {
-  const cfg = _readPlatformConfig(specBase)
-  if (!cfg) {
-    if (process.env.SILLYSPEC_DEBUG_SYNC) console.warn('[quicklog-push] 未配置 platform 段，跳过推送')
-    return false
-  }
-  const controller = new AbortController()
-  const timer = setTimeout(() => controller.abort(), PUSH_TIMEOUT_MS)
-  try {
-    const res = await fetch(`${cfg.url.replace(/\/$/, '')}/api/quicklog-entries`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${cfg.token}` },
-      body: JSON.stringify(entry),
-      signal: controller.signal,
-    })
-    if (!res.ok) {
-      console.warn(`[quicklog-push] ${entry.ql_id} → ${res.status}（文件链路兜底，不影响本地记录）`)
-      return false
-    }
-    return true
-  } catch (err) {
-    console.warn(`[quicklog-push] ${entry.ql_id} 推送失败: ${err && err.name === 'AbortError' ? '超时' : (err.message || err)}（文件链路兜底）`)
-    return false
-  } finally {
-    clearTimeout(timer)
-  }
-}
-
-// git user.name → 文件名安全形式：白名单保留字母数字._- 与中文等 Unicode 字，
-// 剥路径元字符（/ \ ..）与控制字符。防 QUICKLOG-<user>.md / 锁文件 / 轮转归档穿越写。
-function sanitizeQuicklogUser(user) {
-  const s = String(user || '').replace(/[\\/\r\n\0]/g, '').replace(/\.{2,}/g, '.').trim()
-  if (!s) return ''
-  return s.length > 64 ? s.slice(0, 64) : s
-}
-
-// 从关联变更的 proposal/design 提取首个 # 标题（去「提案书（Proposal）— / 设计文档（Design）—」固定前缀）。
-// 让 quick --linked-changes 启动时（用户常不带 --input）也能拿到语义标题，而非 (quick 任务) 占位。
-// 读不到任何标题返回 ''（调用方再回退占位符，保持向后兼容）。
-export function deriveTitleFromLinkedChange(specBase, change) {
-  if (!change) return ''
-  for (const f of ['proposal.md', 'design.md']) {
-    let content
-    try { content = readFileSync(join(specBase, 'changes', change, f), 'utf8') } catch { continue }
-    const m = content.match(/^#\s+(.+?)\s*$/m)
-    if (!m) continue
-    let raw = m[1].trim()
-    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc。
-    // 固定前缀显式剥（坑 linked-task-placeholder-title，2026-08-22 实证：标题「# 提案书（Proposal）:
-    // xxx」或「# 提案书（Proposal）」无破折号时 dash 匹配失败，整串前缀落进 tasks.md 追加行）——
-    // 先剥固定模板词（含全/半角冒号分隔形态），再剥破折号；剥完为空（纯模板标题）继续找下一文档
-    for (const prefix of [/^提案书（Proposal）\s*[：:—\-]?\s*/, /^设计文档（Design）\s*[：:—\-]?\s*/, /^Proposal\s*[：:—\-]?\s*/i, /^Design\s*[：:—\-]?\s*/i]) {
-      raw = raw.replace(prefix, '').trim()
-    }
-    if (!raw) continue
-    const dash = raw.match(/[—-]\s*(.+)$/)
-    const title = dash ? dash[1].trim() : raw
-    if (title) return title
-  }
-  return ''
-}
-
-// 从 quick step3 --output 四字段提取「需求：」摘要，用于翻完成时刷新标题行
-// （覆盖启动时的占位/弱标题）。提取失败返回 ''（不刷新）。
-export function extractTitleFromResult(result) {
-  if (!result) return ''
-  const m = String(result).match(/需求：([^\n\r]*?)(?:\s+根因：|$)/)
-  if (!m) return ''
-  let t = m[1].replace(/[，。；,;].*$/, '').trim() // 截到首个标点，取核心句
-  if (!t) return ''
-  if (t.length > 80) t = t.slice(0, 80) + '…'
-  return t
-}
-
-function sanitizeResult(resultText) {
-  // 保留换行：结果块支持字段化结构（需求：/根因：/方案：/结果：...）。多行时 flipEntryInContent
-  // 写成字段块（追加在「状态：」行下方），不是单条「结果：<长行>」。仅去首尾空白。
-  return String(resultText || '').trim()
-}
-
-// ── quick step3 --file-notes 旁路通道 ──
-// flag 在 command.js 解析（--file-notes），completeQuicklogEntry 在 quick 收尾时消费。
-// 不经 completeStep → handleQuickStageCompletion → completeQuicklogEntry 三层透传（会扩 3 处签名，
-// 且 quick 收尾路径是多 agent 并发改热点）；用 per-process setter，CLI 单进程生命周期内有效，
-// completeQuicklogEntry 读后即清。无 --file-notes 时为 '' → 回退 changedFiles 单行（向后兼容）。
-let _pendingFileNotes = ''
-export function setQuickFileNotes(raw) { _pendingFileNotes = raw == null ? '' : String(raw) }
-export function getQuickFileNotes() { return _pendingFileNotes }
-
-/**
- * 解析 --file-notes 原文 → [{path, note}]。
- * 格式：「path1::括注1 || path2::括注2」——`||` 分隔条目，`::` 分隔路径与括注（首个 `::` 为界，
- * 括注内含 `::` 不误切）；路径反斜杠归一正斜杠（匹配 git 路径风格）。无 `::` 的段 → note=''。
- * 空 / 全空段 → []（调用方回退 changedFiles 单行）。导出供测试 + 未来直接调用。
- */
-export function parseFileNotes(raw) {
-  if (!raw) return []
-  // note 单行化 + 限长：bullet 是「数组元素内嵌 \n」落盘（flipEntryInContent），note 带换行会伪造
-  // QUICKLOG 条目结构（\n## ql-… 可伪造后续条目头）。与 sanitizeDesc 同风格。
-  const sanitizeNote = (n) => n.replace(/[\r\n]+/g, ' ').trim().slice(0, 200)
-  return String(raw)
-    .split('||')
-    .map((seg) => {
-      const s = seg.trim()
-      if (!s) return null
-      const idx = s.indexOf('::')
-      const path = (idx === -1 ? s : s.slice(0, idx)).replace(/\\/g, '/').trim()
-      const note = idx === -1 ? '' : sanitizeNote(s.slice(idx + 2))
-      return path ? { path, note } : null
-    })
-    .filter(Boolean)
-}
-
-// 结果块必填字段（quick step3 --done --output 的结构化结果模板，见 src/stages/quick.js）。
-// 4 个必填字段标签从 manifest 同源(stage-contract-spec.js quick.result-labels),prompt 事前契约与本校验单源。
-const RESULT_REQUIRED_LABELS = getRule('quick.result-labels').data.literals
-
-/**
- * quick step3 结果摘要结构校验（确定性：只查「必填字段是否都在」，不判内容质量——
- * 内容好坏属语义软判定，不归 CLI）。对齐 docs/sillyspec/quick-done-quicklog-duplicate-status-line
- * 的第二诉求：--output 不自动展开丰富格式时，用约束模板 + 结构校验保证 QUICKLOG 记录完整。
- * @param {string} text --done --output 原文
- * @returns {{ ok: boolean, missing: string[] }} ok=true 通过；missing=缺失的字段名列表
- */
-export function validateQuickResult(text) {
-  // 子串包含判定：根因块含嵌套四子字段列表行（- 现象：… 等，task-07 / D-004@v1 合法形态）时，
-  // 顶层四标签仍须齐备（模板契约），嵌套行不影响判定（「- 」前缀不构成顶层标签，亦不缺字段）。
-  const missing = RESULT_REQUIRED_LABELS.filter(label => !String(text || '').includes(label))
-  return { ok: missing.length === 0, missing }
-}
-
-function escapeRe(s) {
-  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
-function listQuicklogFiles(quicklogDir) {
-  try {
-    return readdirSync(quicklogDir).filter(f => f.endsWith('.md') && f.startsWith('QUICKLOG'))
-  } catch {
-    return []
-  }
-}
-
-// 原子写：同目录临时文件 + rename 覆盖。reader 不持锁（agent cat / dashboard 轮询），
-// 若直接 writeFileSync 覆盖整文件，reader 会在 truncate→write 间隙读到空/半截（reader-writer 竞态）。
-// rename 同文件系统内原子（POSIX rename / Win MoveFileEx REPLACE_EXISTING），
-// reader 永远看到完整旧版或完整新版，绝不读半截。
-// Windows 差异：rename 覆盖「正被另一进程读取的目标」会抛 EPERM/EBUSY（POSIX 无此问题）。
-// reader 句柄是瞬时的，故对占用类错误做异步重试+退避；非占用错误立即抛。
-async function writeAtomic(filePath, content, opts = {}) {
-  const { retries = 100, baseDelayMs = 5, maxDelayMs = 100 } = opts
-  const tmp = join(dirname(filePath), basename(filePath) + '.tmp-' + process.pid + '-' + randomBytes(4).toString('hex')) // 随机段：Windows PID 重用激进，仅 pid 会撞名（对齐 fs-atomic.js 的同款修复）
-  writeFileSync(tmp, content) // 同目录 = 同文件系统，rename 才原子（跨 fs 会退化 copy+delete）
-  for (let attempt = 0; ; attempt++) {
-    try {
-      renameSync(tmp, filePath)
-      return
-    } catch (e) {
-      const retryable = e.code === 'EBUSY' || e.code === 'EPERM' || e.code === 'EACCES'
-      if (!retryable || attempt >= retries) {
-        try { unlinkSync(tmp) } catch {}
-        throw e
-      }
-      await sleep(Math.min(baseDelayMs * (attempt + 1), maxDelayMs)) // 线性退避，让出 loop
-    }
-  }
-}
-
-// 扫描所有 QUICKLOG-*.md（含轮转归档）当天最大 NNN + 已用 XXXX 后缀集
-function scanExisting(quicklogDir, today) {
-  let maxSeq = 0
-  const usedSuffix = new Set()
-  const re = /^## ql-(\d{8})-(\d{3})-([0-9a-fA-F]{4})\b/gm
-  // E22c：轮转归档按文件名日期过滤——归档名 = QUICKLOG-<user>-<YYYY-MM-DD>.md（最后条目日期），
-  // 归档内全部条目 ≤ 名内日期；名内日期早于今天的归档不可能含当日条目，跳过读取
-  // （O(全历史归档) → O(当日文件)，consumer 已 10 归档文件 756KB 时免全量扫描）。
-  const todayDashed = today.length === 8 ? `${today.slice(0, 4)}-${today.slice(4, 6)}-${today.slice(6, 8)}` : today
-  for (const f of listQuicklogFiles(quicklogDir)) {
-    const dm = f.match(/-(\d{4}-\d{2}-\d{2})\.md$/)
-    if (dm && dm[1] < todayDashed) continue // 早于今天的归档，必无当日条目
-    let content = ''
-    try { content = readFileSync(join(quicklogDir, f), 'utf8') } catch { continue }
-    let m
-    re.lastIndex = 0
-    while ((m = re.exec(content)) !== null) {
-      if (m[1] === today) {
-        maxSeq = Math.max(maxSeq, parseInt(m[2], 10))
-        usedSuffix.add(m[3].toLowerCase())
-      }
-    }
-  }
-  return { maxSeq, usedSuffix }
-}
-
-// >500 行则轮转：rename QUICKLOG-<user>.md → QUICKLOG-<user>-<最后记录日期>.md
-async function rotateIfNeeded(userFile, gitUser) {
-  if (!existsSync(userFile)) return
-  const content = readFileSync(userFile, 'utf8')
-  const lines = content.split('\n')
-  if (lines.length <= 500) return
-  let lastDate = null
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const m = lines[i].match(/^## ql-(\d{8})-/)
-    if (m) { lastDate = m[1]; break }
-  }
-  const dateStr = lastDate
-    ? `${lastDate.slice(0, 4)}-${lastDate.slice(4, 6)}-${lastDate.slice(6, 8)}`
-    : nowDatetime().slice(0, 10)
-  const archiveFile = join(dirname(userFile), `QUICKLOG-${sanitizeQuicklogUser(gitUser) || 'unknown'}-${dateStr}.md`)
-  // 同日已轮转过：两步各自原子化（append+clear 无法单原子，reader 容忍中间态——见 writeAtomic 注释）
-  if (existsSync(archiveFile)) {
-    const existing = readFileSync(archiveFile, 'utf8')
-    await writeAtomic(archiveFile, existing + content)
-    await writeAtomic(userFile, '')
-  } else {
-    renameSync(userFile, archiveFile)
-  }
-  // echo 轮转：归档文件是 git 跟踪的新文件，提交时带上（勿漏，否则旧 ql 条目只在本地）
-  console.log(`🔄 QUICKLOG 已轮转（>500 行）：${basename(userFile)} → ${basename(archiveFile)}（提交时带上归档文件，勿漏）`)
-}
-
-function tasksPath(specBase, change) {
-  return join(specBase, 'changes', change, 'tasks.md')
-}
-
-// 追加未勾选 task；幂等（已含同 qlId 则跳过）。
-// 关联变更目录不存在（笔误 / 未建 / 仅作标签关联）→ 不 fabricate stub 目录（历史坑 quick-change-phantom：
-// mkdirSync 硬造 changes/<名>/tasks.md，致 quick --done 边界审计自造自拦 BLOCK）。关联仍记入
-// QUICKLOG「关联变更」行（allocateQuicklogEntry 独立写入，不依赖本函数）。
-// 体检 BUG-17：tasks.md 是跨用户共享文件——QUICKLOG 按 <user> 分锁只串行化同用户会话，
-// 用户 A 勾选与用户 B 追加跨用户并发时须按目标文件加锁，否则读-改-写互相覆盖。
-function tasksLockPath(p) {
-  return p + '.tasklock'
-}
-
-async function appendTaskCheckbox(specBase, change, qlId, desc) {
-  const dir = join(specBase, 'changes', change)
-  if (!existsSync(dir)) return
-  const p = tasksPath(specBase, change)
-  await withFileLock(tasksLockPath(p), () => {
-    let content = existsSync(p) ? readFileSync(p, 'utf8') : ''
-    if (content.includes(qlId)) return
-    const prefix = content && !content.endsWith('\n') ? '\n' : ''
-    appendFileSync(p, `${prefix}- [ ] ${qlId} ${desc}\n`)
-  })
-}
-
-// 勾选该 qlId 对应 task：- [ ] → - [x]（同 BUG-17：按 tasks.md 文件锁串行化跨用户读-改-写）
-async function checkTaskCheckbox(specBase, change, qlId) {
-  const p = tasksPath(specBase, change)
-  if (!existsSync(p)) return
-  await withFileLock(tasksLockPath(p), async () => {
-    let content = readFileSync(p, 'utf8')
-    const re = new RegExp(`- \\[ \\] (${escapeRe(qlId)})`)
-    content = content.replace(re, '- [x] $1')
-    await writeAtomic(p, content)
-  })
-}
-
-// 就地翻某 qlId 条目：状态进行中→已完成，追加结果行
-// CRLF 修复（缺陷 quick-done-quicklog-duplicate-status-line）：QUICKLOG 在 Windows 下
-// 可能是 CRLF，split('\n') 后每行带 \r。原代码 `lines[i] === '状态：进行中'` 精确匹配
-// 恒失败 → 走 splice「兜底插入」→ 条目内同时出现「状态：已完成」+「状态：进行中」。
-// 状态行匹配与「已完成」判断统一用行首前缀匹配，容忍行尾 \r；写入保持 CRLF 不扩大改动。
-// 单行四字段（需求：/根因：/方案：/结果：）切段。先按「字段边界」严格扫描：真实标签 = 上一标签之后首次
-// 出现的、前导是串首/空白/句末标点（。；！？）的对应标签——字段正文引用标签字样（根因写「双层「结果：」
-// 前缀」或正则 split(/(?=需求：|根因：|方案：|结果：)/)）因前导是「/|( 等非边界字符而跳过。严格失败
-// （如真实标签前导是「，」这类弱标点）退回宽松顺序扫描（上一标签之后首次出现）。缺标签返回 null → 落单行
-// 兜底（--done 契约校验仍会拦缺字段）。残余边界：正文引用标签且前导恰好是空白/句末标点时仍可能错位。
-// task-07 / D-004@v1 声明：本切分只作用于「单行四字段压缩归一」路径，嵌套四子字段（- 现象：/- 根因：/
-// - 护栏：/- 证据： 列表行）必须以多行列表行形态写入根因块正文——按序扫描先命中顶层「根因：」标签，
-// 其后的嵌套「- 根因：」等字样落在根因字段正文内不构成新边界，无需改动三个边界函数即天然兼容（Grill C-15）。
-function isFieldBoundary(body, idx) {
-  if (idx <= 0) return true
-  const prev = body[idx - 1]
-  return /\s/.test(prev) || '。；！？'.includes(prev)
-}
-function findBoundaryLabel(body, label, from) {
-  let idx = body.indexOf(label, from)
-  while (idx !== -1 && !isFieldBoundary(body, idx)) {
-    idx = body.indexOf(label, idx + label.length)
-  }
-  return idx
-}
-function scanFields(body, findLabel) {
-  const labels = ['需求：', '根因：', '方案：', '结果：']
-  const positions = []
-  let cursor = 0
-  for (const label of labels) {
-    const idx = findLabel(body, label, cursor)
-    if (idx === -1) return null
-    positions.push(idx)
-    cursor = idx + label.length
-  }
-  return positions.map((start, i) => {
-    const end = i + 1 < positions.length ? positions[i + 1] : body.length
-    return body.slice(start, end).trim()
-  })
-}
-function splitSingleLineFields(body) {
-  return scanFields(body, findBoundaryLabel) ?? scanFields(body, (b, l, f) => b.indexOf(l, f))
-}
-
-function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes = [], auditNotes = []) {
-  const lines = content.split('\n')
-  const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
-  if (startIdx === -1) return null
-  // 翻完成时若能从结果提取「需求：」摘要，刷新标题行（覆盖启动时的占位/弱标题）
-  const newTitle = extractTitleFromResult(result)
-  if (newTitle) {
-    const headerCore = lines[startIdx].match(/^(## \S+ \| [^|]+ \| )/)
-    if (headerCore) lines[startIdx] = headerCore[1] + newTitle
-  }
-  let endIdx = lines.length
-  for (let i = startIdx + 1; i < lines.length; i++) {
-    if (lines[i].startsWith('## ')) { endIdx = i; break }
-  }
-  let hasResult = false
-  let flipped = false
-  for (let i = startIdx + 1; i < endIdx; i++) {
-    if (/^状态：进行中\r?$/.test(lines[i])) { lines[i] = '状态：已完成'; flipped = true }
-    if (lines[i].startsWith('结果：')) hasResult = true
-    // 文件行落盘：--file-notes 优先（多行 bullet 带括注），否则回填审计到的实际改动文件单行，
-    // 都空则不动（保持「（见实际改动）」）。bullet 用「数组元素内嵌 \n」写——lines.join('\n') 展平为
-    // 多行，数组长度不变 → 与下方状态/结果 splice 的索引完全解耦（changedFiles 单行同理原地替换）。
-    if (lines[i].startsWith('文件：')) {
-      if (fileNotes.length > 0) {
-        const bullets = fileNotes.map((n) => `- ${n.path}${n.note ? `（${n.note}）` : ''}`)
-        lines[i] = `文件：\n${bullets.join('\n')}`
-      } else if (changedFiles.length > 0) {
-        lines[i] = `文件：${changedFiles.join(', ')}`
-      }
-    }
-  }
-  if (!flipped && !lines.slice(startIdx, endIdx).some(l => /^状态：已完成\r?$/.test(l))) {
-    // 无状态行（异常），插一条已完成
-    lines.splice(startIdx + 1, 0, '状态：已完成')
-    endIdx += 1
-  }
-  if (result && !hasResult) {
-    // quick step3 --output 常被压成单行「需求：…根因：…方案：…结果：…」（agent 未加换行），
-    // 直接落盘会得到双层前缀「结果：需求：…结果：…」。把单行四字段归一为多行字段块，省 agent 手工
-    // 拆行精修（prompt-control-debt quick-①）。多行 / 单句结果不受影响。
-    let body = result
-    if (!/\r?\n/.test(body) && /^需求：/.test(body)) {
-      // 单行四字段归一为多行。不能 split(/(?=需求：|根因：|方案：|结果：)/)——正文引用字段标签字样
-      // （如根因里写「双层「结果：」前缀」）会被任意位置误切。改按序扫描：真实标签 = 上一标签之后
-      // 首次出现，字段正文引用更靠后的标签不误断（quick-① 2026-08-04 实证补丁）。缺标签返回 null
-      // → 落单行兜底（--done 契约校验仍会拦缺字段）。
-      const segs = splitSingleLineFields(body)
-      if (segs) body = segs.join('\n')
-    }
-    // 多行结果（结构化 需求/根因/方案/结果 字段块）：逐行插入为独立字段行。
-    // 根因块嵌套四子字段（- 现象：/- 根因：/- 护栏：/- 证据： 列表行，D-004@v1 postmortem 形态）属
-    // 根因块正文：在此随多行结果逐行原样落盘（带「- 」前缀、保序含换行），不被字段边界扫描误切——
-    // 单行归一切分只认「- 」前缀之外的需求：/根因：/方案：/结果： 标签，嵌套行天然不参与边界判定。
-    // 单行结果：保持「结果：<一句话>」一行，向后兼容简单用例。
-    const resultLines = /\r?\n/.test(body)
-      ? body.split(/\r?\n/).filter(l => l.trim() !== '')
-      : [`结果：${body}`]
-    // 结果块属本条目：从 endIdx 往前跳过本条目尾部空行，在最后一个非空行之后插入。
-    // 否则结果块会落在尾空行「之后」，与下一条目标题紧贴（缺空行分隔），且被空行从本条目
-    // 「文件：」行隔开——视觉上像属于下一条目（用户实证多条目 QUICKLOG 间距 bug）。
-    let insertAt = endIdx
-    while (insertAt - 1 > startIdx && lines[insertAt - 1].trim() === '') insertAt--
-    lines.splice(insertAt, 0, ...resultLines)
-    // 兜底：结果块之后、下一个 ## 标题之间若无空行（条目原本无尾空行 / 轮转归档手改等），补一个。
-    const after = insertAt + resultLines.length
-    if (after < lines.length && lines[after].startsWith('## ')) {
-      lines.splice(after, 0, '')
-    }
-  }
-  // D-8 落盘（2026-08-18 修）：advisory 审计行（文档欠账 / 引用失效）写入条目尾部——修复
-  // quick-audit「欠账已记录（QUICKLOG reasons）」的不实承诺（原先纯 console 打印，事后不可审计；
-  // 两周实测需要分母：信号触发次数必须可追溯）。幂等：条目内已有 审计： 行则不重复写（--done 重跑安全）。
-  // 位置：结果块之后 / 条目尾部（重算边界，不吃上方 splice 的陈旧索引）。
-  if (auditNotes.length > 0) {
-    let entryEnd = -1
-    for (let i = startIdx + 1; i < lines.length; i++) {
-      if (lines[i].startsWith('## ')) { entryEnd = i; break }
-    }
-    if (entryEnd === -1) entryEnd = lines.length
-    if (!lines.slice(startIdx, entryEnd).some((l) => l.startsWith('审计：'))) {
-      let insertAt = entryEnd
-      while (insertAt - 1 > startIdx && lines[insertAt - 1].trim() === '') insertAt--
-      lines.splice(insertAt, 0, ...auditNotes.map((n) => `审计：${n}`))
-    }
-  }
-  return lines.join('\n')
-}
-
-// ── 对外 API ──
-
-/**
- * 分配 ql-ID 并写「进行中」条目 + 关联 tasks.md。持锁、当天唯一。
- * @returns {Promise<{qlId: string}>}
- */
-export async function allocateQuicklogEntry(specBase, gitUser, { description, linkedChanges = [], allowedFiles = [] } = {}) {
-  const quicklogDir = join(specBase, 'quicklog')
-  mkdirSync(quicklogDir, { recursive: true })
-  // git user.name 无字符限制，可含 / \ .. 等路径元字符（git config 或 .git/config 可控）——
-  // 白名单消毒防穿越写（QUICKLOG-<user>.md / 锁文件 / 轮转归档三处拼接），与 assertSafeChangeName 同风格
-  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
-  const userFile = join(quicklogDir, `QUICKLOG-${user}.md`)
-  const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
-  const desc = sanitizeDesc(description)
-  const linked = Array.isArray(linkedChanges) ? linkedChanges : []
-  const files = Array.isArray(allowedFiles) ? allowedFiles : []
-  const today = todayStamp()
-
-  return await withFileLock(lockPath, async () => {
-    const { maxSeq, usedSuffix } = scanExisting(quicklogDir, today)
-    const nextSeq = maxSeq + 1
-    // XXXX 4 位 hex 随机后缀（消歧；NNN 已在锁内顺序分配保证唯一，此处仅 belt-and-suspenders）
-    let suffix
-    let guard = 0
-    do {
-      suffix = randomBytes(2).toString('hex')
-      guard++
-    } while (usedSuffix.has(suffix) && guard < 100)
-
-    await rotateIfNeeded(userFile, user)
-
-    const qlId = `ql-${today}-${String(nextSeq).padStart(3, '0')}-${suffix}`
-    const entry = [
-      '',
-      `## ${qlId} | ${nowDatetime()} | ${desc}`,
-      '状态：进行中',
-      `关联变更：${linked.length > 0 ? linked.join(', ') : '（无）'}`,
-      `文件：${files.length > 0 ? files.join(', ') : '（见实际改动）'}`,
-      '',
-    ].join('\n')
-    appendFileSync(userFile, entry)
-
-    for (const c of linked) await appendTaskCheckbox(specBase, c, qlId, desc)
-
-    // 平台推送（task-06 / FR-02 / D-003）：锁外语义等同（推送不回写本地），但放锁内
-    // 保证「分配即推送」顺序一致；best-effort 失败不影响返回。
-    await pushQuicklogEntryToPlatform(specBase, {
-      ql_id: qlId,
-      timestamp: nowDatetime(),
-      title: desc,
-      status: 'in_progress',
-      status_note: null,
-      author_raw: user,
-      // 白名单正则对齐平台（^\d{4}-\d{2}-\d{2}- 才进列表；原文在 raw_block 不丢）
-      linked_changes: linked.filter(c => /^\d{4}-\d{2}-\d{2}-/.test(c)),
-      files: files.map(f => ({ path: f, note: null })),
-      body_sections: {},
-      raw_block: entry,
-    }).catch(() => {}) // pushQuicklogEntryToPlatform 自身已吞错；双保险防未来改动破坏 best-effort 契约
-
-    return { qlId }
-  })
-}
-
-/**
- * 翻某 qlId 条目为「已完成」+ 追加结果 + 勾选关联 tasks.md。持锁。
- */
-export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultText = '', linkedChanges = [], changedFiles = [], auditNotes = [] } = {}) {
-  const quicklogDir = join(specBase, 'quicklog')
-  // 与 allocateQuicklogEntry 同源消毒：锁文件路径含 user（防穿越写，两入口必须一致否则锁不上同一文件）
-  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
-  const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
-  const result = sanitizeResult(resultText)
-  const linked = Array.isArray(linkedChanges) ? linkedChanges : []
-  // 实际改动文件（调用方 complete-handlers 已用 isQuickMetadata 过滤 quick 自身元数据）。空 → 不动文件行。
-  const realFiles = Array.isArray(changedFiles) ? changedFiles.filter(Boolean) : []
-  // --file-notes（command.js 经 setQuickFileNotes 注入）：有则文件行写多行 bullet 带括注。
-  // 读后即清（per-process，防残留跨调用）。flipEntryInContent 优先用 fileNotes，空则回退 realFiles。
-  const fileNotes = parseFileNotes(_pendingFileNotes)
-  _pendingFileNotes = ''
-
-  await withFileLock(lockPath, async () => {
-    // 条目可能在主文件或轮转归档中
-    let updatedContent = null
-    let updatedFile = null
-    for (const f of listQuicklogFiles(quicklogDir)) {
-      const filePath = join(quicklogDir, f)
-      let content = ''
-      try { content = readFileSync(filePath, 'utf8') } catch { continue }
-      const updated = flipEntryInContent(content, qlId, result, realFiles, fileNotes,
-        Array.isArray(auditNotes) ? auditNotes.filter((n) => typeof n === 'string' && n.trim() !== '') : [])
-      if (updated !== null) {
-        await writeAtomic(filePath, updated) // 命中处原子落盘（只改含目标条目的那一个文件）
-        updatedContent = updated
-        updatedFile = filePath
-        break
-      }
-    }
-    for (const c of linked) await checkTaskCheckbox(specBase, c, qlId)
-
-    // 平台推送（task-06 / FR-02 / D-003）：**以落盘终态为准**读回条目组装 payload
-    // （design §5.3：翻完成时标题行被 extractTitleFromResult 刷新，推送须与落盘一致，
-    // 不能用入参拼——标题/结果块/文件行都会在 flipEntryInContent 中重写）。
-    const rawBlock = extractRawBlock(updatedContent, qlId)
-    await pushQuicklogEntryToPlatform(specBase, buildPushPayloadFromRaw(rawBlock, {
-      ql_id: qlId,
-      author_raw: user,
-      status: 'completed',
-      linked_changes: linked,
-    })).catch(() => {})
-  })
-}
-
-/**
- * 查某 qlId 条目是否存在（只读，跨所有 QUICKLOG-*.md）。
- */
-export function findQuicklogEntry(specBase, gitUser, qlId) {
-  const quicklogDir = join(specBase, 'quicklog')
-  if (!existsSync(quicklogDir)) return false
-  const header = `## ${qlId} |`
-  for (const f of listQuicklogFiles(quicklogDir)) {
-    let content = ''
-    try { content = readFileSync(join(quicklogDir, f), 'utf8') } catch { continue }
-    if (content.includes(header)) return true
-  }
-  return false
-}
-
-/**
- * 取消一个 quick 会话（2026-08-21 agent-手工产出审计第四批 C-2，`run quick --cancel` 数据源）。
- *
- * 误启动/放弃的 quick 会话此前无取消出口：QUICKLOG「进行中」条目 + 关联变更 tasks.md 挂载行
- * + .runtime/quick-sessions/<id>/ 永久残留，doctor --cleanup-ghosts 只清 db 幽灵行不清这三处。
- * 本函数做 allocateQuicklogEntry 的反操作（三步全是已有函数的反面）：
- *   1. QUICKLOG 条目状态翻「已取消」（非删除——保留痕迹可审计，与 doctor 宁漏勿杀口径一致）
- *   2. tasks.md 里该 qlId 的挂载行整行移除（未勾的空壳行，勾了说明实际做了工作 → 拒绝取消）
- *   3. 会话 guard 目录删除（quick-sessions/<sessionId>/，含 guard.json）
- *   4. current-quick-run-id 若指向本会话则删除（防后续 --done fallback 命中死会话）
- * db 侧 change 行由调用方 unregisterChange（quick 会话行，非真实变更）。
- *
- * fail-closed：已翻「已完成」的条目拒绝取消（那是真实工作）；tasks.md 挂载行已勾选同样拒绝。
- *
- * @param {{ specBase: string, gitUser: string, qlId: string, sessionId: string|null }} opts
- * @returns {Promise<{ ok: boolean, reason?: string, quicklogFile?: string, removedTaskRows: string[] }>}
- */
-export async function cancelQuickSession({ specBase, gitUser, qlId, sessionId = null }) {
-  if (!qlId) return { ok: false, reason: '缺 qlId（--change <quick-会话ID> 或 --ql <ql-xxx>）' }
-  const quicklogDir = join(specBase, 'quicklog')
-  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
-  const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
-
-  // 1. QUICKLOG 翻「已取消」：找到条目，校验未完成，就地改状态行
-  let quicklogFile = null
-  let flipped = false
-  await withFileLock(lockPath, async () => {
-    // 用户文件缺失时扫全部 QUICKLOG 文件（条目可能在别的 user 文件里，如 CI 场景 user 漂移）
-    const files = existsSync(join(quicklogDir, `QUICKLOG-${user}.md`))
-      ? [`QUICKLOG-${user}.md`]
-      : listQuicklogFiles(quicklogDir)
-    for (const f of files) {
-      const p = join(quicklogDir, f)
-      const content = existsSync(p) ? readFileSync(p, 'utf8') : ''
-      if (!content.includes(`## ${qlId} |`)) continue
-      quicklogFile = p
-      const lines = content.split('\n')
-      const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
-      let endIdx = lines.length
-      for (let i = startIdx + 1; i < lines.length; i++) {
-        if (lines[i].startsWith('## ')) { endIdx = i; break }
-      }
-      for (let i = startIdx + 1; i < endIdx; i++) {
-        if (/^状态：已完成/.test(lines[i])) {
-          throw new Error(`${qlId} 已完成（真实工作记录），拒绝取消；如需修正请手改 QUICKLOG`)
-        }
-      }
-      for (let i = startIdx + 1; i < endIdx; i++) {
-        if (/^状态：进行中/.test(lines[i])) {
-          lines[i] = '状态：已取消'
-          flipped = true
-          break
-        }
-      }
-      if (flipped) {
-        const eol = content.includes('\r\n') ? '\r\n' : '\n'
-        writeFileSync(p, lines.join(eol === '\r\n' ? '\r\n' : '\n'))
-      }
-      break
-    }
-  })
-  if (!quicklogFile) return { ok: false, reason: `未在任何 QUICKLOG 文件找到条目 ${qlId}` }
-  if (!flipped) return { ok: false, reason: `${qlId} 状态行异常（非进行中也非已完成），请手查 QUICKLOG` }
-
-  // 2. tasks.md 挂载行移除（所有活跃变更统一扫——allocate 时可能挂多个关联变更）
-  const removedTaskRows = []
-  const changesRoot = join(specBase, 'changes')
-  if (existsSync(changesRoot)) {
-    for (const c of readdirSync(changesRoot, { withFileTypes: true })) {
-      if (!c.isDirectory() || c.name === 'archive') continue
-      const tp = tasksPath(specBase, c.name)
-      if (!existsSync(tp)) continue
-      await withFileLock(tasksLockPath(tp), () => {
-        const content = readFileSync(tp, 'utf8')
-        if (!content.includes(qlId)) return
-        const lines = content.split('\n')
-        const kept = lines.filter(l => {
-          const m = l.match(/^[-*]\s*\[([ xX])\]\s*(\S+)/)
-          if (m && m[2] === qlId) {
-            if (m[1] !== ' ') throw new Error(`${c.name}/tasks.md 的 ${qlId} 行已勾选（实际做了工作），拒绝取消`)
-            removedTaskRows.push(`${c.name}/tasks.md`)
-            return false
-          }
-          return true
-        })
-        if (kept.length !== lines.length) {
-          const eol = content.includes('\r\n') ? '\r\n' : '\n'
-          writeFileSync(tp, kept.join(eol === '\r\n' ? '\r\n' : '\n'))
-        }
-      })
-    }
-  }
-
-  // 3+4. 会话目录与 current marker
-  if (sessionId) {
-    try { rmSync(join(specBase, '.runtime', 'quick-sessions', sessionId), { recursive: true, force: true }) } catch {}
-    const marker = join(specBase, '.runtime', 'current-quick-run-id')
-    try {
-      if (existsSync(marker) && readFileSync(marker, 'utf8').trim() === sessionId) unlinkSync(marker)
-    } catch {}
-  }
-
-  return { ok: true, quicklogFile, removedTaskRows }
-}