sillyspec 3.23.8 → 3.23.9

package/.claude/skills/sillyspec-commit/SKILL.md

@@ -42,6 +42,9 @@ USER=$(git config user.name 2>/dev/null || echo "default")
 cat .sillyspec/quicklog/QUICKLOG-${USER}.md 2>/dev/null
 # 同时扫描活跃变更目录下的归属 quicklog
 for dir in .sillyspec/changes/*/quicklog/*.md; do [ -f "$dir" ] && cat "$dir"; done 2>/dev/null
+# 注：QUICKLOG 现由 CLI 接管写入（src/quicklog.js），描述取 quick 启动的任务参数、
+# 结果取 step3 --output 一句话，粒度可能较粗；条目仍含 标题|时间|描述 + 状态 + 结果 结构，
+# 可直接读取。描述过泛时结合 diff stat 与 tasks.md 补充语义。
 
 来源 B — tasks.md（execute 产生的修改）：
 LATEST=$(ls -d .sillyspec/changes/*/ 2>/dev/null | grep -v archive | tail -1)

package/.claude/skills/sillyspec-quick/SKILL.md

@@ -14,7 +14,7 @@ description: 用于明确、低风险、范围很小的直接任务。适合用
 
 quick 阶段的 `--change` 语义是「关联变更」**且会触发步骤重置**，**不要用 `--change` 来指定关联变更**。多活跃变更时改用：
 
-- `--linked-changes none`：不关联，仅记 QUICKLOG
+- `--linked-changes none`：不关联，仅记 QUICKLOG（CLI 启动时写入）
 - `--linked-changes a,b`：显式关联到变更 a、b
 - `--non-interactive`：CI/脚本环境，默认不关联（避免交互 prompt 崩溃）
 
@@ -78,7 +78,7 @@ sillyspec run quick --files src/phone.ts,src/phone.test.ts
 - **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
 - quick 直接在主工作区改代码（不创建 worktree），范围必须小且明确
 - 完成后立即 `--done`，不跳过
-- step 1 会创建 `.sillyspec/quicklog/QUICKLOG-<user>.md` 记录（理解任务时），完成前 CLI 会校验它存在
+- QUICKLOG 记录由 **CLI 接管**：启动时 CLI 自动分配 ql-ID 并在 `.sillyspec/quicklog/QUICKLOG-<user>.md` 写「进行中」条目（含关联变更 tasks.md），完成时 CLI 自动翻「已完成」并勾选 task。**你无需手写 QUICKLOG / tasks.md**，只需用注入的 `<quicklog-id>` 在模块文档变更索引引用
 - **禁止**在没有运行 CLI 的情况下自行决定流程
 
 ## 用户指令

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.23.8",
+  "version": "3.23.9",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/quicklog.js

@@ -0,0 +1,306 @@
+/**
+ * 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 {
+  openSync, closeSync, unlinkSync, statSync, mkdirSync, existsSync,
+  readFileSync, writeFileSync, readdirSync, renameSync, appendFileSync,
+} from 'fs'
+import { randomBytes } from 'crypto'
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms))
+
+/**
+ * O_EXCL 文件锁。`openSync(lockPath,'wx')` 独占创建；已存在则按 mtime 判 stale 偷锁，
+ * 否则退避重试至超时。CLI 短进程、低频写入，stale 阈值 30s 足够。
+ * @param {string} lockPath 锁文件路径（建议与被保护文件同目录）
+ * @param {() => (any|Promise<any>)} fn 临界区
+ * @param {{staleMs?:number, timeoutMs?:number, retryMs?:number}} opts
+ */
+export async function withFileLock(lockPath, fn, opts = {}) {
+  const { staleMs = 30000, timeoutMs = 10000, retryMs = 50 } = opts
+  mkdirSync(dirname(lockPath), { recursive: true })
+  const start = Date.now()
+  let fd = null
+  // 抢锁循环
+  while (true) {
+    try {
+      fd = openSync(lockPath, 'wx') // O_EXCL：已存在抛 EEXIST
+      break
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e
+      // 锁已存在：判 stale（持有进程崩溃残留）
+      try {
+        const mtime = statSync(lockPath).mtimeMs
+        if (Date.now() - mtime > staleMs) {
+          try { unlinkSync(lockPath) } catch {} // 偷 stale 锁后重试
+          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 条目结构
+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
+}
+
+function sanitizeResult(resultText) {
+  const s = String(resultText || '').replace(/\n\s*\n/g, ' ').replace(/\r?\n/g, ' ').trim()
+  return s
+}
+
+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)
+  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
+  for (const f of listQuicklogFiles(quicklogDir)) {
+    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-${gitUser}-${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)
+  }
+}
+
+function tasksPath(specBase, change) {
+  return join(specBase, 'changes', change, 'tasks.md')
+}
+
+// 追加未勾选 task；幂等（已含同 qlId 则跳过）
+function appendTaskCheckbox(specBase, change, qlId, desc) {
+  const dir = join(specBase, 'changes', change)
+  mkdirSync(dir, { recursive: true })
+  const p = tasksPath(specBase, change)
+  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]
+async function checkTaskCheckbox(specBase, change, qlId) {
+  const p = tasksPath(specBase, change)
+  if (!existsSync(p)) return
+  let content = readFileSync(p, 'utf8')
+  const re = new RegExp(`- \\[ \\] (${escapeRe(qlId)})`)
+  content = content.replace(re, '- [x] $1')
+  await writeAtomic(p, content)
+}
+
+// 就地翻某 qlId 条目：状态进行中→已完成，追加结果行
+function flipEntryInContent(content, qlId, result) {
+  const lines = content.split('\n')
+  const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
+  if (startIdx === -1) return null
+  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 (lines[i] === '状态：进行中') { lines[i] = '状态：已完成'; flipped = true }
+    if (lines[i].startsWith('结果：')) hasResult = true
+  }
+  if (!flipped && !lines.slice(startIdx, endIdx).includes('状态：已完成')) {
+    // 无状态行（异常），插一条已完成
+    lines.splice(startIdx + 1, 0, '状态：已完成')
+    endIdx += 1
+  }
+  if (result && !hasResult) {
+    lines.splice(endIdx, 0, `结果：${result}`)
+  }
+  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 })
+  const user = 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) appendTaskCheckbox(specBase, c, qlId, desc)
+
+    return { qlId }
+  })
+}
+
+/**
+ * 翻某 qlId 条目为「已完成」+ 追加结果 + 勾选关联 tasks.md。持锁。
+ */
+export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultText = '', linkedChanges = [] } = {}) {
+  const quicklogDir = join(specBase, 'quicklog')
+  const lockPath = join(quicklogDir, `.QUICKLOG-${(gitUser || 'unknown')}.md.lock`)
+  const result = sanitizeResult(resultText)
+  const linked = Array.isArray(linkedChanges) ? linkedChanges : []
+
+  await withFileLock(lockPath, async () => {
+    // 条目可能在主文件或轮转归档中
+    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)
+      if (updated !== null) {
+        await writeAtomic(filePath, updated) // 命中处原子落盘（只改含目标条目的那一个文件）
+        break
+      }
+    }
+    for (const c of linked) await checkTaskCheckbox(specBase, c, qlId)
+  })
+}
+
+/**
+ * 查某 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
+}

package/src/run.js

@@ -11,6 +11,7 @@ import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
 import { ProgressManager } from './progress.js'
 import { SCAN_STATUS, POINTER_STATUS, isPointerCorrupted } from './constants.js'
+import { allocateQuicklogEntry, completeQuicklogEntry, findQuicklogEntry } from './quicklog.js'
 import { checkbox } from '@inquirer/prompts'
 
 /**
@@ -721,6 +722,19 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   if (changeName && promptText.includes('<quick-session-id>')) {
     promptText = promptText.replace(/<quick-session-id>/g, changeName)
   }
+  // 替换 <quicklog-id> 占位符（quick 阶段：从 session guard.json 读 CLI 分配的 ql-ID，
+  // 供 agent 在模块文档变更索引等处引用）
+  if (promptText.includes('<quicklog-id>')) {
+    const specBaseQl = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    let qlIdVal = ''
+    try {
+      const sessionGuardFile = join(specBaseQl, '.runtime', 'quick-sessions', changeName, 'guard.json')
+      if (existsSync(sessionGuardFile)) {
+        qlIdVal = JSON.parse(readFileSync(sessionGuardFile, 'utf8')).quicklogId || ''
+      }
+    } catch {}
+    promptText = promptText.replace(/<quicklog-id>/g, qlIdVal || '(未分配)')
+  }
   // 替换 <linked-changes> 占位符（quick 阶段：从 .runtime/quick-sessions/<sessionId>/guard.json 读关联变更）
   if (promptText.includes('<linked-changes>')) {
     const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
@@ -1740,7 +1754,7 @@ export async function runCommand(args, cwd, specDir = null) {
   }
 
   // 默认：输出当前步骤
-  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline, isForceRescan, linkedChanges })
+  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline, isForceRescan, linkedChanges, taskDescription: inputText })
 }
 
 /**
@@ -2000,45 +2014,67 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
     console.log(`🔄 ${stageName} 阶段已自动重置，重新开始。\n`)
   }
 
-  // quick 阶段：记录 baselineFiles
-  if (stageName === 'quick' && !progress.quickGuard) {
+  // quick 阶段：记录 baselineFiles + 分配 ql-ID（CLI 接管 QUICKLOG 写入）
+  // 幂等判据是 session guard.json 文件（跨进程可靠），不是 progress.quickGuard
+  // （D-003@v1：顶层 quickGuard 不跨进程持久化；agent 在 step 间用 `run quick` 取下一步
+  // prompt 时每个新进程都进此块，按文件判幂等才不会重复分配 ql-ID / 重复写条目）。
+  if (stageName === 'quick') {
+    const sessionGuardDir = join(specBase, '.runtime', 'quick-sessions', changeName)
+    const guardFile = join(sessionGuardDir, 'guard.json')
+    let existingGuard = null
     try {
-      const { execSync } = await import('child_process')
-      const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
-      // 记录全部预存脏文件（含 untracked + .sillyspec/ 路径）。quick 会话期间自身写入的元数据
-      // （quicklog/.runtime/modules/_module-map 等）由 auditQuickCompletion 的 isQuickMetadata 精确豁免，
-      // 不需要这里粗放过滤 .sillyspec/——旧过滤致预存 untracked .sillyspec/changes/ 不进 baseline，
-      // 却在 audit 被当「危险(.sillyspec/)+新增」误判永久 blocked（ql-20260713-002-7628 修复）。
-      const baselineFiles = gitStatus
-        .trim().split('\n').filter(Boolean)
-        .map(line => line.slice(3).trim())
-      const allowedFiles = quickOpts?.quickFiles || []
-      const allowNew = quickOpts?.isAllowNew || false
-      const forceBaseline = quickOpts?.isForceBaseline || false
-      progress.quickGuard = {
-        sessionId: changeName,
-        name_zh: '快速任务守卫',
-        baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
-        baselineFiles,
-        allowedFiles,
-        allowNew,
-        forceBaseline,
-        linkedChanges: Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : [],
-        startedAt: new Date().toISOString(),
+      if (existsSync(guardFile)) existingGuard = JSON.parse(readFileSync(guardFile, 'utf8'))
+    } catch {}
+    if (existingGuard) {
+      // 跨进程重入：复用已分配的 ql-ID，跳过 baseline 重捕与分配（幂等）
+      progress.quickGuard = existingGuard
+    } else {
+      try {
+        const { execSync } = await import('child_process')
+        const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
+        // 记录全部预存脏文件（含 untracked + .sillyspec/ 路径）。quick 会话期间自身写入的元数据
+        // （quicklog/.runtime/modules/_module-map 等）由 auditQuickCompletion 的 isQuickMetadata 精确豁免，
+        // 不需要这里粗放过滤 .sillyspec/——旧过滤致预存 untracked .sillyspec/changes/ 不进 baseline，
+        // 却在 audit 被当「危险(.sillyspec/)+新增」误判永久 blocked（ql-20260713-002-7628 修复）。
+        const baselineFiles = gitStatus
+          .trim().split('\n').filter(Boolean)
+          .map(line => line.slice(3).trim())
+        const allowedFiles = quickOpts?.quickFiles || []
+        const allowNew = quickOpts?.isAllowNew || false
+        const forceBaseline = quickOpts?.isForceBaseline || false
+        const linkedChanges = Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : []
+        // CLI 接管：分配 ql-ID + 写 QUICKLOG「进行中」条目 + 关联 tasks.md（持锁、当天唯一）
+        const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
+        const { qlId } = await allocateQuicklogEntry(specBase, gitUser, {
+          description: quickOpts?.taskDescription || '',
+          linkedChanges,
+          allowedFiles,
+        })
+        progress.quickGuard = {
+          sessionId: changeName,
+          name_zh: '快速任务守卫',
+          baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
+          baselineFiles,
+          allowedFiles,
+          allowNew,
+          forceBaseline,
+          linkedChanges,
+          quicklogId: qlId,
+          startedAt: new Date().toISOString(),
+        }
+        // 写入 .runtime/quick-sessions/<sessionId>/guard.json 供 worktree-guard hook 读取
+        // （D-002：按 session 存，多会话各自 guard 不互覆盖。runStage 作用域内 sessionId == changeName == quick-<uuid8>，见 §4.4/4.5）
+        mkdirSync(sessionGuardDir, { recursive: true })
+        writeFileSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
+        const parts = [`${baselineFiles.length} 个已有脏文件`]
+        if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
+        if (allowNew) parts.push('允许新增文件')
+        console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
+        console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
+        await pm._write(cwd, progress, changeName)
+      } catch (e) {
+        console.warn(`⚠️ baseline 记录失败: ${e.message}`)
       }
-      // 写入 .runtime/quick-sessions/<sessionId>/guard.json 供 worktree-guard hook 读取
-      // （D-002：按 session 存，多会话各自 guard 不互覆盖。runStage 作用域内 sessionId == changeName == quick-<uuid8>，见 §4.4/4.5）
-      const sessionGuardDir = join(specBase, '.runtime', 'quick-sessions', changeName)
-      mkdirSync(sessionGuardDir, { recursive: true })
-      const guardFile = join(sessionGuardDir, 'guard.json')
-      writeFileSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
-      const parts = [`${baselineFiles.length} 个已有脏文件`]
-      if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
-      if (allowNew) parts.push('允许新增文件')
-      console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
-      await pm._write(cwd, progress, changeName)
-    } catch (e) {
-      console.warn(`⚠️ baseline 记录失败: ${e.message}`)
     }
   }
 
@@ -3011,61 +3047,96 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       if (steps[wsIdx].waitReason) console.log(`   原因：${steps[wsIdx].waitReason}`)
       return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
     }
-    // quick 阶段完成前强制检查 quicklog 是否创建
+    // quick 收尾：强校验 QUICKLOG 条目 + 翻状态 + 勾 tasks.md（CLI 接管）
     if (stageName === 'quick') {
-      const quicklogDir = join(specBase, 'quicklog')
-      const hasQuicklog = existsSync(quicklogDir) && readdirSync(quicklogDir).some(f => f.endsWith('.md') && f.startsWith('QUICKLOG'))
-      if (!hasQuicklog) {
-        console.error(`\n❌ quick 阶段完成校验失败：未检测到 QUICKLOG 记录文件。`)
-        console.error(`   step 2 要求创建 quicklog 记录，但文件不存在。`) 
-        console.error(`   请先创建 quicklog 记录再 --done。`)
-        return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
-      }
-      // §4.6 quick 收尾：从 session guard.json 读 guard（不依赖 progress.quickGuard）。
+      // §4.6 从 session guard.json 读 guard（不依赖 progress.quickGuard）。
       // D-003@v1：progress._write 不持久化顶层 quickGuard，跨进程 --done 时读出的 progress 无 quickGuard，
       // 若仍用 if (progress.quickGuard) 驱动收尾会整体跳过，导致 .runtime/quick-sessions/<sessionId>/ 残留僵尸。
       // 改为从文件读 guard：优先 session 目录 guard.json，回退旧单文件 quick-guard.json（task-03 前兼容）。
       // sessionId == changeName == quick-<uuid8>（completeStep 作用域内 changeName 已解构自 options）。
-      {
-        const runtimeBase = platformOpts.runtimeRoot || join(specBase, '.runtime')
-        const sessionGuardFile = join(runtimeBase, 'quick-sessions', changeName, 'guard.json')
-        const legacyGuardFile = join(specBase, '.runtime', 'quick-guard.json')
-        let guard = null
-        try {
-          guard = existsSync(sessionGuardFile)
-            ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
-            : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
-        } catch {}
-        if (guard) {
-          // --done 的 --force-baseline/--allow-new 并入 guard（与 step1 持久化值取或）。
-          // 修复 ql-20260713-002-7628：旧代码解析了这两个 flag 但只传 {isConfirm} 给审计，
-          // 致 --done --force-baseline 静默无效、用户被误导「重跑 --confirm」也无法解锁。
-          const mergedGuard = {
-            ...guard,
-            forceBaseline: guard.forceBaseline || isForceBaseline,
-            allowNew: guard.allowNew || isAllowNew,
-          }
-          const review = await auditQuickCompletion(cwd, mergedGuard, { isConfirm: confirm })
-          printQuickAuditReview(review)
-          if (review.status === 'blocked') {
-            steps[currentIdx].status = 'pending'
-            steps[currentIdx].completedAt = null
-            if (outputText) steps[currentIdx].output = null
-            process.exit(1)
-          }
-          progress.lastQuickReview = review
+      const runtimeBase = platformOpts.runtimeRoot || join(specBase, '.runtime')
+      const sessionGuardFile = join(runtimeBase, 'quick-sessions', changeName, 'guard.json')
+      const legacyGuardFile = join(specBase, '.runtime', 'quick-guard.json')
+      let guard = null
+      try {
+        guard = existsSync(sessionGuardFile)
+          ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
+          : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
+      } catch {}
+
+      // 强校验 / 收尾：本会话必须有一条真实 QUICKLOG 条目（治「报 SAFE 但漏写」bug）。
+      // guard 缺失（brownfield：新代码前启动的会话）不阻断——兜底补写一条记录，保住「完成必有记录」不变量。
+      const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
+      let qlId = guard?.quicklogId || null
+      const linkedChanges = Array.isArray(guard?.linkedChanges) ? guard.linkedChanges : []
+
+      // 审计：仅在有 guard 时跑（brownfield 无 guard 跳过，兼容 D-003 brownfield 行为）。
+      if (guard) {
+        // --done 的 --force-baseline/--allow-new 并入 guard（与 step1 持久化值取或）。
+        // 修复 ql-20260713-002-7628：旧代码解析了这两个 flag 但只传 {isConfirm} 给审计，
+        // 致 --done --force-baseline 静默无效、用户被误导「重跑 --confirm」也无法解锁。
+        const mergedGuard = {
+          ...guard,
+          forceBaseline: guard.forceBaseline || isForceBaseline,
+          allowNew: guard.allowNew || isAllowNew,
+        }
+        const review = await auditQuickCompletion(cwd, mergedGuard, { isConfirm: confirm })
+        printQuickAuditReview(review)
+        if (review.status === 'blocked') {
+          steps[currentIdx].status = 'pending'
+          steps[currentIdx].completedAt = null
+          if (outputText) steps[currentIdx].output = null
+          process.exit(1)
         }
-        // 清理：guard 命中与缺失两种情况都执行（guard 缺失 → 跳过审计，仅清理不抛错）。
-        // rmSync {recursive,force} / unlinkSync 都容忍文件不存在（brownfield）。
+        progress.lastQuickReview = review
+      }
+
+      if (!qlId) {
+        // 无 ql-ID（guard 缺失或 brownfield 无 quicklogId）：补分配后立即完成，不阻断。
         try {
-          const { unlinkSync } = await import('fs')
-          if (changeName) {
-            const sessionDir = join(runtimeBase, 'quick-sessions', changeName)
-            rmSync(sessionDir, { recursive: true, force: true })
-          }
-          if (existsSync(legacyGuardFile)) unlinkSync(legacyGuardFile)
-        } catch {}
+          const alloc = await allocateQuicklogEntry(specBase, gitUser, {
+            description: guard?.taskDescription || '(补分配)',
+            linkedChanges,
+            allowedFiles: Array.isArray(guard?.allowedFiles) ? guard.allowedFiles : [],
+          })
+          qlId = alloc.qlId
+          console.log(`📝 QUICKLOG 兜底补写: ${qlId}（guard 缺失/brownfield 会话）`)
+        } catch (e) {
+          console.error(`\n❌ QUICKLOG 补分配失败: ${e.message}`)
+          steps[currentIdx].status = 'pending'
+          steps[currentIdx].completedAt = null
+          if (outputText) steps[currentIdx].output = null
+          process.exit(1)
+        }
+      }
+      if (!findQuicklogEntry(specBase, gitUser, qlId)) {
+        console.error(`\n❌ quick 阶段完成校验失败：QUICKLOG 条目 ${qlId} 不存在。`)
+        console.error(`   会话期间记录被删除或从未写入。请检查 .sillyspec/quicklog/ 后重跑 --done。`)
+        steps[currentIdx].status = 'pending'
+        steps[currentIdx].completedAt = null
+        if (outputText) steps[currentIdx].output = null
+        process.exit(1)
       }
+      // 翻状态进行中→已完成 + 追加结果 + 勾选关联 tasks.md
+      try {
+        await completeQuicklogEntry(specBase, gitUser, qlId, {
+          resultText: outputText ? outputText.slice(0, 500) : '',
+          linkedChanges,
+        })
+        console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)
+      } catch (e) {
+        console.warn(`⚠️ QUICKLOG 完成态写入失败: ${e.message}`)
+      }
+
+      // 清理 session 目录（rmSync/unlinkSync 容忍不存在）。
+      try {
+        const { unlinkSync } = await import('fs')
+        if (changeName) {
+          const sessionDir = join(runtimeBase, 'quick-sessions', changeName)
+          rmSync(sessionDir, { recursive: true, force: true })
+        }
+        if (existsSync(legacyGuardFile)) unlinkSync(legacyGuardFile)
+      } catch {}
     }
 
     stageData.status = 'completed'

package/src/stages/quick.js

@@ -28,38 +28,15 @@ export const definition = {
 9. 根据任务描述初步判断可能涉及的模块
 10. 读取匹配到的 \`{SPEC_ROOT}/docs/<project>/modules/<module>.md\`
 
-### 创建任务记录（⛔ 此步骤不能跳过，没有 quicklog 记录 = 未完成）
-理解完任务后，**必须**立即创建记录文件，再输出任何其他内容：
+### QUICKLOG 记录（CLI 已接管，无需你手动创建）
+本 quick 会话的 ql-ID 由 CLI 在启动时分配，已注入为 \`<quicklog-id>\`。CLI 同时已自动：
+- 在 \`{SPEC_ROOT}/quicklog/QUICKLOG-<git-user>.md\` 写入「进行中」条目（含关联变更与预估文件）
+- 对每个关联变更 \`<c>\`：在 \`{SPEC_ROOT}/changes/<c>/tasks.md\` 追加未勾选 task \`- [ ] <quicklog-id> <任务描述>\`
 
-**A. 始终创建 QUICKLOG（无论是否关联变更）**
-1. 使用预注入的 git 用户名：\`<git-user>\`
-2. 创建/追加 \`{SPEC_ROOT}/quicklog/QUICKLOG-\`<git-user>\`.md\`，写入：
-   \`\`\`
-   ## ql-<YYYYMMDD>-<NNN>-<XXXX> | <now-datetime> | <一句话任务描述>
-   状态：进行中
-   关联变更：<linked-changes>
-   文件：<预估要改的文件>
-   \`\`\`
-   - ID 格式：\`ql-YYYYMMDD-NNN-XXXX\`
-   - \`XXXX\` 是 4 位随机十六进制字符（如 a3f2、b7c1、00ef），**不是描述词缩写**
-   - 追加前扫描文件中已有的 \`ql-<当天日期>-\` 前缀的最大序号，+1 作为新序号
-   - 每天从 001 开始，跨日重新计数
-   - 此 ID 可被 design.md / plan.md / archive / module 变更索引引用
-
-**B. 若关联变更（\`<linked-changes>\` 不为「（无）」）**
-3. 解析 \`<linked-changes>\`（逗号分隔的变更名列表，可能有多个 = 一次 quick 同时归属多个变更）
-4. 对**每个**变更 \`<c>\`：在 \`{SPEC_ROOT}/changes/<c>/tasks.md\` 追加一条未勾选 task：
-   \`- [ ] <ql-ID> <一句话任务描述>\`（复用步骤 A 生成的同一个 ql-ID）
-   - 若 \`changes/<c>/\` 目录或 tasks.md 不存在，先 \`mkdir -p {SPEC_ROOT}/changes/<c>\` 再创建 tasks.md
-   - 同一个 ql-ID 出现在 QUICKLOG 和所有关联变更的 tasks.md 中，便于交叉引用
-   - \`<linked-changes>\` 为「（无）」时跳过本步，仅保留 QUICKLOG
-
-这样 Gate 检测到 \`{SPEC_ROOT}/\` 下有变更，就不会拦截后续的代码修改。
+**你不要创建或修改任何 QUICKLOG / tasks.md 记录**——完成本任务时 CLI 会自动将条目翻为「已完成」并勾选 task（含轮转）。\`<quicklog-id>\` 可用于 design.md / plan.md / archive / 模块变更索引引用。
 
 ### 输出
-quicklog 已创建（必须放在输出的第一行确认）+ 任务理解 + 上下文摘要
-
-⚠️ **先创建 quicklog，再输出任务理解。** 如果 quicklog 未创建，CLI post-check 会报 warning。`,
+任务理解 + 上下文摘要`,
       outputHint: '任务理解',
       optional: false
     },
@@ -97,23 +74,20 @@ quicklog 已创建（必须放在输出的第一行确认）+ 任务理解 + 上
 2. 使用 \`git add -- <file...>\` 暂存本次 quick 实际修改的文件（不要 commit，由用户通过统一提交工具处理）
    - 禁止使用 \`git add -A\`
    - 不要暂存 quick 开始前就已存在的无关改动
-3. 更新 Step 1 创建的记录：
-   - QUICKLOG：找到对应 ql-ID 的条目，将「状态：进行中」改为「状态：已完成」，补充实际改动文件和结果摘要（**始终做**，无论是否关联变更）
-   - 关联变更：对 Step 1 在每个 \`changes/<c>/tasks.md\` 写入的 ql-ID task，将其 checkbox 由 \`- [ ]\` 勾选为 \`- [x]\`；若 Step 1 未写入（用户事后才决定关联），则按 Step 1 的格式补写并直接勾选
-4. QUICKLOG 轮转：超过 500 行则重命名为 \`QUICKLOG-<USER>-YYYY-MM-DD.md\`（日期取最后一条记录的日期）。新文件从空开始，ql-ID 需扫描同目录所有 QUICKLOG 文件中当天最大序号 +1
-5. 如果发现项目特有的坑，追加到 \`{SPEC_ROOT}/knowledge/uncategorized.md\`
-6. 任务比预期复杂 → 建议用完整流程
+3. QUICKLOG / tasks.md 记录由 CLI 在本 step 完成时自动收尾（翻「已完成」+ 勾选 task + 轮转），你无需手动更新
+4. 如果发现项目特有的坑，追加到 \`{SPEC_ROOT}/knowledge/uncategorized.md\`
+5. 任务比预期复杂 → 建议用完整流程
 
 ### 模块文档同步
-7. 读取 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
-8. 对比本次修改的文件（\`git diff --name-only HEAD\`）与模块映射
-9. 如果命中模块 → 直接同步模块文档：
+6. 读取 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+7. 对比本次修改的文件（\`git diff --name-only HEAD\`）与模块映射
+8. 如果命中模块 → 直接同步模块文档：
    - 读取对应的 \`{SPEC_ROOT}/docs/<project>/modules/<module>.md\`（如不存在则新建）
-   - 根据本次改动内容更新模块文档（正文描述当前状态，底部变更索引追加本次 ql-ID）
-   - 变更索引格式：\`- ql-YYYYMMDD-NNN-XXXX | <一句话描述>\`
+   - 根据本次改动内容更新模块文档（正文描述当前状态，底部变更索引追加本步骤预注入的 ql-ID）
+   - 变更索引格式：\`- <quicklog-id> | <一句话描述>\`
    - 写入模块文档
    - 使用 \`git add -- <module-doc>\` 暂存更新的模块文件
-10. 未命中任何模块 → 跳过，不做额外操作
+9. 未命中任何模块 → 跳过，不做额外操作
 
 ### 输出
 暂存确认 + 记录路径 + 模块文档同步结果（如有）`,