sillyspec 3.28.10 → 3.28.11

package/src/index.js

@@ -76,6 +76,9 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec wt-commit [--change <名>] -m <信息> [--pathspec-from-file <f>] -- <path...>
                                       worktree 内 per-task 串行化提交（文件锁排队 + 强制显式 pathspec，
                                       防 add -A 卷入并行兄弟 WIP；worktree 内可省 --change，从 cwd 推断）
+  sillyspec quicklog commit [--change <quick会话ID>] -m <信息> [--ql <ql-id>]... [-- <额外pathspec...>]
+                                      一键收编本会话 QUICKLOG 条目（切片提交：HEAD 基线+本会话条目块，
+                                      patches sidecar 一并带上；并行会话条目恢复为工作区未提交态，不夹带）
   sillyspec worktree <cmd>     git worktree 隔离管理（execute 阶段相关）
     create <change> [--base <branch>]   创建隔离 worktree
     apply <change> [--check-only]       校验并应用变更到主工作区
@@ -167,6 +170,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec run plan --reopen --from-step 2          # 修订 plan，从第 2 步重做
   sillyspec run quick --non-interactive --done --output "CI 内的快修"  # 脚本/CI
   sillyspec progress show
+  sillyspec progress show --all         # 多变更汇总时无信号变更全量单行列出（默认折叠超 8 个）
   sillyspec progress show --json        # 全局总览 envelope（面板/脚本消费）
   sillyspec worktree apply 2026-07-03-add-login
 `);
@@ -372,7 +376,7 @@ async function main() {
             process.exitCode = exitCode;
             break;
           }
-          pm.show(progDir, progChangeName);
+          pm.show(progDir, progChangeName, { all: filteredArgs.includes('--all') });
           break;
         }
         case 'check': {
@@ -606,6 +610,84 @@ async function main() {
       //     [--changed-files a,b]（归属切片为空或纯验证任务时显式给出；""=空覆盖）
       //     [--base <rev> --head <rev>]（无 worktree meta 时显式锡点）[--force]
       const rwSub = filteredArgs[1];
+      // ── review status（C1 轻量硬机制，坑 review-liveness-opaque，2026-09-15 wp EHS 实证：
+      // 独立审查 94 分钟无收敛、用户三催——宿主/agent 无只读探针可查「审查到哪了、审完没有、
+      // 审完之后文档又改过几版」。agent-tool 通道的子代理进程归宿主管（CLI 无 kill 面），但
+      // 「状态可见」这一半可以闭环：各 stage review 的 verdict/通道/刷新序数/代落盘·降级标记/
+      // docHash 现势一行可见，供催问时一查即答、也供派发前查前序审查复用（C2 互补）。──
+      if (rwSub === 'status') {
+        const rsVal = (flag) => {
+          const i = filteredArgs.indexOf(flag);
+          return i >= 0 && filteredArgs[i + 1] && !String(filteredArgs[i + 1]).startsWith("--") ? filteredArgs[i + 1] : null;
+        };
+        const rsChange = rsVal('--change');
+        if (!rsChange) {
+          console.error('用法: sillyspec review status --change <名> [--json]\n  只读查询各阶段 stage review 状态：verdict/执行通道/刷新序数/代落盘·降级标记/docHash 现势（主文档改版未刷新时提示）');
+          process.exit(2);
+        }
+        assertSafeChangeName(rsChange, '--change 变更名');
+        const { getLatestStageReviewRunId, computeDocHash, isDegradedSelfReview, hasDelegatedWriteDisclosure, classifyReviewerChannel } = await import('./stage-review.js');
+        const { resolveRuntimeRoot } = await import('./run/shared.js');
+        const rsPlatformOpts = {};
+        const rsResolved = resolvePlatformOpts(dir, specDir);
+        if (rsResolved) {
+          rsPlatformOpts.specRoot = rsResolved.specRoot;
+          if (rsResolved.runtimeRoot) rsPlatformOpts.runtimeRoot = rsResolved.runtimeRoot;
+        }
+        const rsSpecBase = rsPlatformOpts.specRoot || join(dir, '.sillyspec');
+        const rsRuntimeRoot = resolveRuntimeRoot(rsPlatformOpts, rsSpecBase);
+        const rows = [];
+        for (const st of ['brainstorm', 'plan', 'execute']) {
+          let runId = null;
+          try { runId = getLatestStageReviewRunId(rsRuntimeRoot, st, rsChange) } catch {}
+          if (!runId) { rows.push({ stage: st, status: 'none' }); continue }
+          const rjPath = join(rsRuntimeRoot, 'stage-reviews', `${st}-${runId}`, 'review.json');
+          let rev = null;
+          try { rev = JSON.parse(readFileSync(rjPath, 'utf8')) } catch {
+            rows.push({ stage: st, status: 'unreadable', runId, reviewPath: rjPath }); continue
+          }
+          const notes = typeof rev.reviewerNotes === 'string' ? rev.reviewerNotes : '';
+          const refreshCount = (notes.match(/docHash auto-refreshed at /g) || []).length;
+          // docHash 现势：主文档在 [specBase, changeDir, cwd] 基准解析后重算对比
+          let docState = 'unknown';
+          const primaryRel = Array.isArray(rev.reviewedFiles) ? rev.reviewedFiles[0] : null;
+          if (primaryRel) {
+            for (const base of [rsSpecBase, join(rsSpecBase, 'changes', rsChange), dir]) {
+              const abs = join(base, primaryRel);
+              if (existsSync(abs)) {
+                docState = computeDocHash(abs) === rev.docHash ? 'match' : 'stale(改版未刷新——gate 将自动重算放行，verdict 续用需人工确认)';
+                break
+              }
+            }
+            if (docState === 'unknown') docState = '主文档缺失';
+          }
+          rows.push({
+            stage: st, status: 'present', runId, reviewPath: rjPath,
+            specVerdict: rev.specVerdict, qualityVerdict: rev.qualityVerdict,
+            channel: classifyReviewerChannel(rev),
+            degradedSelf: isDegradedSelfReview(rev), delegatedWrite: hasDelegatedWriteDisclosure(rev),
+            refreshCount, docState,
+          });
+        }
+        if (json) {
+          process.stdout.write(JSON.stringify({ ok: true, command: 'review status', change: rsChange, stages: rows }) + '\n');
+        } else {
+          console.log(`📋 stage review 状态 [${rsChange}]：`);
+          for (const r of rows) {
+            if (r.status === 'none') { console.log(`  ⬜ ${r.stage}: 无 review 记录`); continue }
+            if (r.status === 'unreadable') { console.log(`  ⚠️ ${r.stage}: review.json 不可读（${r.reviewPath}）`); continue }
+            const flags = [
+              r.channel !== 'agent-tool' && r.channel !== 'platform' ? `通道=${r.channel}` : null,
+              r.degradedSelf ? '⚠️降级自审' : null,
+              r.delegatedWrite ? '⚠️代落盘' : null,
+              r.refreshCount > 0 ? `已刷新×${r.refreshCount}${r.refreshCount >= 2 ? '（反复改版，人工确认结论续用）' : ''}` : null,
+              r.docState !== 'match' && r.docState !== 'unknown' ? `docHash=${r.docState}` : null,
+            ].filter(Boolean).join('，');
+            console.log(`  ${r.specVerdict === 'pass' && r.qualityVerdict === 'pass' ? '✅' : '❌'} ${r.stage}: spec=${r.specVerdict} quality=${r.qualityVerdict}（${r.channel}${flags ? '；' + flags : ''}）`);
+          }
+        }
+        break;
+      }
       if (rwSub !== 'write') {
         console.error('用法: sillyspec review write --change <名> --task task-NN --spec <pass|fail|cannot_verify> --quality <verdict>\n  [--notes "评审备注"] [--evidence "cannot_verify 证据说明"] [--changed-files a,b] [--base <rev> --head <rev>] [--force] [--json]\n  单 task review.json 命令式写入：verdict/notes 由你给，executeRunId/base/head/changedFiles/diffPaths 由 CLI 从 git + task 卡代算；已存在默认拒覆盖（--force 越过）');
         process.exit(2);
@@ -1979,6 +2061,8 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
             console.log(`   marker → ${result.markerPath}`);
             if (result.mode === 'refreshed') {
               console.log(`   docHash 已按当前 ${result.mainDoc} 重算（verdict 结论是否仍适用需人工确认）`);
+            } else if (result.mode === 'noop-unchanged') {
+              console.log(`   docHash 已与当前 ${result.mainDoc} 一致，跳过重写（幂等 no-op，不动文件）`);
             } else {
               console.log(`   下一步：独立审查子代理对照 ${result.mainDoc} 填 verdict/checklist 后重跑 --done`);
             }
@@ -2697,6 +2781,50 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       }
       break;
     }
+    case 'quicklog': {
+      // known-issues ④ v1（2026-09-16）：QUICKLOG 多会话条目交织——本会话提交 git add 整文件
+      // 会夹带并行会话未完成条目，只能手工四步舞（备份→剥离→commit→恢复）。本命令一键机制化：
+      // 切片（HEAD 基线+本会话条目块）→ 显式 pathspec 提交（QUICKLOG 文件+patches sidecar+额外
+      // pathspec）→ 恢复工作区（并行条目留未提交态）。参数面照抄 wt-commit 先例（--change/-m/--
+      // pathspec）+ 可重复 --ql（guard 缺失/损坏时的显式逃生门；含已取消条目）。
+      if (filteredArgs[1] !== 'commit') {
+        console.error(`❌ 未知 quicklog 子命令: ${filteredArgs[1] || '(空)'}——当前支持: sillyspec quicklog commit [--change <quick会话ID>] -m <信息> [--ql <ql-id>]... [-- <额外pathspec...>]`);
+        process.exit(1);
+      }
+      const qlRest = filteredArgs.slice(2);
+      const qlDd = qlRest.indexOf('--');
+      const qlFlags = qlDd === -1 ? qlRest : qlRest.slice(0, qlDd);
+      const qlExtra = qlDd === -1 ? [] : qlRest.slice(qlDd + 1);
+      let qlChange = null;
+      let qlMessage = null;
+      const qlIds = [];
+      for (let i = 0; i < qlFlags.length; i++) {
+        if (qlFlags[i] === '--change' && qlFlags[i + 1]) qlChange = qlFlags[++i];
+        else if ((qlFlags[i] === '-m' || qlFlags[i] === '--message') && qlFlags[i + 1]) qlMessage = qlFlags[++i];
+        else if (qlFlags[i] === '--ql' && qlFlags[i + 1]) qlIds.push(qlFlags[++i]);
+      }
+      try {
+        const { resolvePlatformSpecDir, resolvePlatformOpts } = await import('./progress.js');
+        const qlSpecBase = resolvePlatformSpecDir(dir, specDir);
+        const { resolveQuickSessionsDir } = await import('./run/shared.js');
+        const qlSessionsDir = resolveQuickSessionsDir(resolvePlatformOpts(dir, specDir), qlSpecBase);
+        let qlUser = 'unknown';
+        try { qlUser = (await import('./git-helper.js')).git(dir, ['config', 'user.name']) || 'unknown'; } catch {}
+        const { runQuicklogCommit } = await import('./quicklog.js');
+        const r = await runQuicklogCommit({
+          specBase: qlSpecBase, cwd: dir, gitUser: qlUser, qlIds,
+          changeName: qlChange, sessionsDir: qlSessionsDir,
+          message: qlMessage, extraPathspecs: qlExtra,
+        });
+        if (json) console.log(JSON.stringify({ command: 'quicklog commit', ...r }, null, 2));
+        else if (r.skipped) console.log(`⏭️  quicklog commit 无新内容跳过（HEAD 不动）：${r.shortHead}（条目均已收编：${(r.skippedQlIds || []).join(', ') || '（无）'}）`);
+        else console.log(`✅ quicklog commit 完成：${r.shortHead}（${r.files.length} 文件；收编 ${(r.committedQlIds || []).join(', ')}）\n   并行会话条目已恢复为工作区未提交态；备份：${(r.backupPaths || []).join(' , ')}`);
+      } catch (e) {
+        console.error(`❌ quicklog commit 失败：${e.message}`);
+        process.exit(1);
+      }
+      break;
+    }
     case 'worktree': {
       const { WorktreeManager } = await import('./worktree.js');
       const { ProgressManager, resolveSessionIdentity } = await import('./progress.js');

package/src/machine-interface.js

@@ -168,6 +168,32 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
       warnings: r.warnings || [],
     });
 
+    // ── a2. design 文件清单行级核验（brainstorm；坑 design-file-ref-late-feedback，2026-09-15
+    //    wp EHS 会话实证：41 条 design_file_ref_invalid 只在 --done 末步爆出，gate 预检全绿——
+    //    前移进 gate 让写作期预检即可见，免「末步拦→改文档→重跑 --done」整轮往返。与 complete.js
+    //    --done 硬门同源实现（design-facts.js validateDesignFileList），gate 只读不写）──
+    if (stage === 'brainstorm') {
+      try {
+        const { validateDesignFileList } = await import('./design-facts.js');
+        const dfl = validateDesignFileList({ changeDir: join(specRoot, 'changes', changeName), cwd });
+        checks.push({
+          id: 'design-file-list',
+          ok: (dfl.errors || []).length === 0,
+          // errors 元素是 {path, message} 对象（与 complete.js --done 打印侧同源），gate check 面拍平为 message 字符串
+          errors: (dfl.errors || []).map(e => e && e.message ? e.message : String(e)),
+          warnings: dfl.warnings || [],
+        });
+      } catch (e) {
+        // fail-open 与 complete.js 同口径：核验自身异常不误拦，warning 留痕
+        checks.push({
+          id: 'design-file-list',
+          ok: true,
+          errors: [],
+          warnings: [`design 清单核验自身异常，跳过（${e && e.message ? e.message : e}）`],
+        });
+      }
+    }
+
     // ── b. transition：状态转换合法性（参与综合 ok，与 completeStep 硬阻断一致）──
     // 与 run.js runStage 同源：传 fromStageData 触发 failed_post_check 门控。
     // transition 必须参与 ok：否则 gate 返回 ok=true、exit 0，Agent 据此 --done 却被

package/src/probe7-anchor-check.js

@@ -4,7 +4,18 @@
  * 坑 probe7-covered-anchor-missing（2026-09-15 复盘实证：探针7 矩阵第一轮 7 行 covered 判定的
  * 证据列缺 file:line 锚点被审查打回——预填说明写着「证据列给首命中 file:line 锚点」但模板要求
  * 没细读就交，人工往返一轮）。本模块把该口径机器化：verify --done 时点解析正文探针7 段，
- * 判定列=covered 的行必须含 `path:line` 形态锚点，缺则 advisory 提示回补。
+ * 判定列=covered 的行必须含 file:line / `.test.` 测试文件名 / 反引号包裹路径或测试名三形态
+ * 之一，缺则 advisory 提示回补。
+ *
+ * 口径对齐（2026-09-16-friction5-hardening FR-05 / D-005@v1，用户 2026-09-16 驾驭小结⑤）：
+ * 锚点认 file:line 或 `.test.` 文件名两形态（对齐 stage-contract 硬门三形态中的两形态）——
+ * 行号随提交漂移场景 `.test.` 文件名锚过硬门仍被 advisory 提示回补是无效摩擦。file:line
+ * 侧本判定（/:\d+\b/）宽于 stage-contract 硬门形态集，advisory 宽于硬门是设计容差。
+ *
+ * 口径再对齐（2026-09-17-feedback-hardening FR-02 / D-005@v2，supersedes D-005@v1 的
+ * 「裸反引号不收」，用户 2026-09-17 驾驭小结②）：反引号包裹的路径/测试名与硬门
+ * matrixEvidenceHasAnchor 同权收认——硬门已保证锚点存在，advisory 多要行号在行号漂移
+ * 场景零正确性收益纯摩擦。
  *
  * 定位与边界：
  * - **advisory 不阻断**：covered 行缺锚点只 warn（证据可以是合法的人工核验形态，但 covered=
@@ -20,6 +31,10 @@
 // file:line 锚点：冒号后跟数字（`test/x.test.mjs:42`、`src/a.py:12-18` 均命中）
 const ANCHOR_RE = /:\d+\b/
 
+// 反引号包裹的路径/测试名（`test/x.mjs`、`src/plain.js` 等——D-005@v2 第三形态，
+// 与 stage-contract 硬门 matrixEvidenceHasAnchor 的 /`[^`]+`/ 同权）
+const BACKTICK_RE = /`[^`]+`/
+
 // 判定枚举纯值（骨架四枚举；容忍反引号包裹——门禁层 extractAcceptanceMatrixSlots 另有纯值校验）
 function normalizeVerdict(cell) {
   return String(cell || '').trim().replace(/^`|`$/g, '').toLowerCase()
@@ -57,7 +72,10 @@ export function checkProbe7AnchorCoverage(reportText) {
     if (verdict !== 'covered') continue
     out.coveredRows++
     const evidence = cells[5] || ''
-    if (!ANCHOR_RE.test(evidence)) {
+    // 三形态锚点（FR-05 / D-005@v2）：file:line（ANCHOR_RE，本体不动）、`.test.` 测试文件名、
+    // 反引号包裹路径/测试名（BACKTICK_RE）——三者对齐 stage-contract 硬门形态，消灭行号漂移
+    // 场景的无效回补提示
+    if (!ANCHOR_RE.test(evidence) && !/\.test\./.test(evidence) && !BACKTICK_RE.test(evidence)) {
       out.missingAnchors.push({
         task: task || '(未知 task)',
         acceptance: (cells[1] || '').slice(0, 80),

package/src/progress/stage-machine.js

@@ -185,7 +185,7 @@ export class StageMachine {
     console.log(`✅ 阶段 ${stage} 已标记为完成（不自动推进，下一步由你决定）`);
   }
 
-  show(cwd, changeName = null) {
+  show(cwd, changeName = null, opts = {}) {
     // 如果指定了变更名，只显示该变更
     if (changeName) {
       return this._showChange(cwd, changeName);
@@ -218,20 +218,36 @@ export class StageMachine {
     const changesRoot = join(this.pm._getSpecDir(cwd), 'changes');
     // P2-2-①：未决同步冲突标红（overview 同源 _listPendingConflicts；该变更命中 → 🔴 行）
     const pendingConflicts = this._listPendingConflicts(this.pm._getSpecDir(cwd));
+    // 折叠显示（2026-09-17 用户反馈⑥-③，ql-20260917-005）：29 个滞留变更的全量逐条输出
+    // （每条 3-5 行 + 空行）把真正需要看的信号淹掉。口径：**有信号的变更**（未决冲突/滞留/
+    // 疑似完成/目录缺失/无法读取）保持原有详情渲染——它们就是该看的东西；**无信号变更**压成
+    // 单行，且超过 CLEAN_SHOW_CAP 个时折叠为计数行（--all 展开全量单行；单变更详情恒走
+    // --change <名>）。--json envelope（机器面）不受影响。
+    const CLEAN_SHOW_CAP = 8;
+    const withSignals = [];
+    const clean = [];
     for (const cn of changes) {
       const data = this.pm.read(cwd, cn);
       const dirMissing = _isGhostChange(changesRoot, cn);
+      const cnConflicts = pendingConflicts.filter(c => c.change === cn);
+      const stall = data ? this._stallSignal(cwd, data, cn) : null;
+      if (!data || dirMissing || cnConflicts.length > 0 || stall) {
+        withSignals.push({ cn, data, dirMissing, cnConflicts, stall });
+      } else {
+        clean.push({ cn, data });
+      }
+    }
+
+    for (const { cn, data, dirMissing, cnConflicts, stall } of withSignals) {
       if (!data) {
         console.log(`  📂 ${cn} — (无法读取)${dirMissing ? ' ⚠️ 目录缺失（残留记录，sillyspec doctor --cleanup-ghosts --confirm 可归档清理）' : ''}`);
         continue;
       }
-      const currentStage = data.currentStage || '(无)';
-      const stageLabel = STAGE_LABELS[data.currentStage] || currentStage;
+      const stageLabel = STAGE_LABELS[data.currentStage] || data.currentStage || '(无)';
       const lastActive = data.lastActive ? this._timeAgo(data.lastActive) : '未知';
 
       console.log(`  📂 ${cn}${dirMissing ? ' ⚠️ 目录缺失（残留记录，sillyspec doctor --cleanup-ghosts --confirm 可归档清理）' : ''}`);
       // 变更级未决冲突标红（冲突可见性，2026-09-02 P2-2-①）：不再靠 agent 自己撞上才发现
-      const cnConflicts = pendingConflicts.filter(c => c.change === cn);
       if (cnConflicts.length > 0) {
         for (const cf of cnConflicts) {
           console.log(`     🔴 未决同步冲突（${cf.type === 'progress' ? '进度' : 'spec 树'}${cf.created_at ? `，${cf.created_at}` : ''}）——请 sillyspec platform resolve 处理后再推进`);
@@ -239,7 +255,6 @@ export class StageMachine {
       }
       console.log(`     当前阶段: ${stageLabel}  最近活跃: ${lastActive}`);
       // 滞留/疑似完成信号（2026-08-30 用户反馈②）：多变更汇总逐行透出，无需逐个 --change 看详情
-      const stall = this._stallSignal(cwd, data, cn);
       if (stall) {
         console.log(`     ⏳ ${stall.text}`);
         console.log(stall.kind === 'likely-complete'
@@ -249,6 +264,20 @@ export class StageMachine {
       console.log('');
     }
 
+    // 无信号变更：单行压缩（名 + 阶段 + 最近活跃），超帽折叠（--all 展开）
+    clean.sort((a, b) => String(b.data?.lastActive || '').localeCompare(String(a.data?.lastActive || '')));
+    const shown = opts.all ? clean : clean.slice(0, CLEAN_SHOW_CAP);
+    for (const { cn, data } of shown) {
+      const stageLabel = STAGE_LABELS[data.currentStage] || data.currentStage || '(无)';
+      const lastActive = data.lastActive ? this._timeAgo(data.lastActive) : '未知';
+      console.log(`  📂 ${cn} — ${stageLabel} · 最近活跃 ${lastActive}`);
+    }
+    if (!opts.all && clean.length > shown.length) {
+      console.log(`  … 另有 ${clean.length - shown.length} 个无信号活跃变更已折叠（progress show --change <名> 看单变更详情；全量单行列出加 --all）`);
+    } else if (clean.length > 0) {
+      console.log('');
+    }
+
     // P2-2-① 补丁（2026-09-02 晚）：全局未决冲突汇总段——逐变更行只显示「对上活跃变更」的冲突，
     // 挂在 ghost/非活跃变更上的冲突会漏（huber 面板联调实证 11 条只显示 0）。此处按
     // pending_conflicts 全量兜底显示，与 --json envelope 顶层字段同口径。

package/src/progress.js

@@ -1163,7 +1163,7 @@ export class ProgressManager {
 
   completeStage(cwd, stage, changeName = null, opts = {}) { return this._stageMachine.completeStage(cwd, stage, changeName, opts); }
 
-  show(cwd, changeName = null) { return this._stageMachine.show(cwd, changeName); }
+  show(cwd, changeName = null, opts = {}) { return this._stageMachine.show(cwd, changeName, opts); }
 
   // 只读全局总览（show 多变更汇总的机器版，2026-09-02 单一状态源）：纯数据，machine-interface 包装
   overview(cwd) { return this._stageMachine.overview(cwd); }

package/src/quicklog.js

@@ -10,13 +10,14 @@
  * 本模块把分配与写入下沉到 CLI 进程内，O_EXCL lockfile 串行化，彻底消除上述问题。
  * 无新 npm 依赖（仅 fs/path/crypto）——匹配项目零 FS 工具依赖的风格。
  */
-import { join, dirname, basename } from 'path'
+import { join, dirname, basename, resolve, relative, isAbsolute } 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'
+import { safeGit } from './git-helper.js'
 
 const sleep = (ms) => new Promise(r => setTimeout(r, ms))
 
@@ -1168,3 +1169,232 @@ export async function cancelQuickSession({ specBase, gitUser, qlId, sessionId =
 
   return { ok: true, quicklogFile, removedTaskRows }
 }
+
+// ── quicklog commit（known-issues ④ v1：本会话条目切片提交，2026-09-16）──
+//
+// 坑 QUICKLOG 多会话条目交织：QUICKLOG 是多会话共享追加的单文件，某会话 `git add` 整文件
+// 会夹带并行会话未完成条目（违反显式 pathspec 隔离纪律，AGENTS.md 第 18 条），只能
+// 「备份 → 剥离并行条目 → commit pathspec → 恢复」四步舞（2026-09-15/16 单会话实证 6 次）。
+// 本命令把四步舞机制化：
+//   切片（工作区 = HEAD 基线 + 本会话条目块）→ git add/commit 显式 pathspec（含 patches
+//   sidecar 与额外 pathspec）→ finally 恢复工作区全量（并行条目留「未提交」预期态）。
+// 任一步失败 fail-fast 打印人工兜底；恢复在 finally，commit 失败也不留半态。
+// 「完整文件化」（entries sidecar 权威 + 聚合渲染）不在 v1 范围，见 known-issues 条目。
+
+// git 子操作退避重试：与 wt-commit.js gitWithLockRetry 同款（本文件锁只约束 quicklog 写方，
+// 锁队列外裸跑 git 的并行进程仍可能短暂持 index.lock/HEAD 锁，等待重试消化）。
+async function quicklogGitRetry(cwd, args, label, { retries = 6, waitMs = 1000 } = {}) {
+  for (let i = 0; ; i++) {
+    const { value, error } = safeGit(cwd, args, { timeout: 30000 })
+    if (!error) return value
+    const msg = String((error && error.message) || error)
+    if (/index\.lock|HEAD\.lock|cannot lock ref/i.test(msg) && i < retries) {
+      await sleep(waitMs)
+      continue
+    }
+    throw new Error(`${label} 失败：${msg.split('\n')[0].trim()}`)
+  }
+}
+
+// 行级条目头匹配（容错口径与 countQuicklogEntries 一致：## 后空白可省、ID 与 | 间空白可变）
+function findQuicklogEntryLineIdx(lines, qlId) {
+  const re = new RegExp(`^##[ \\t]*${escapeRe(qlId)}[ \\t]*\\|`)
+  return lines.findIndex(l => re.test(l))
+}
+
+/**
+ * 切片：工作区全量 → 「基线 + 指定条目块」。
+ * 块界 = `## ql-<id>` 头到下一个 `## ` 头/文件尾（extractRawBlock 同口径）；条目间补单空行
+ * 分隔（对齐 allocateQuicklogEntry 条目模板形态）。EOL 随工作区文件——HEAD blob 归一到
+ * 工作区 EOL 再拼（.gitattributes eol=lf + autocrlf=true 环境下 blob 是 LF、工作区 CRLF；
+ * git add 时按配置归一回去，不产生整文件行尾假差异）。条目头已在基线（先前提交过）→
+ * 跳过不重复（重跑幂等）。返回 null = 无任何目标条目；blocks 为空 = 全部已在基线
+ * （调用方不落盘不动文件，避免基线归一化重写制造假提交）。
+ */
+function sliceQuicklogFileContent(fullContent, baselineContent, qlIds) {
+  const eol = fullContent.includes('\r\n') ? '\r\n' : '\n'
+  const norm = (s) => String(s || '').replace(/\r\n/g, '\n')
+  const lines = norm(fullContent).split('\n')
+  const baseLines = norm(baselineContent).split('\n')
+  while (baseLines.length && baseLines[baseLines.length - 1].trim() === '') baseLines.pop()
+  const blocks = []
+  const blockIds = []
+  const alreadyIncluded = []
+  for (const qlId of qlIds) {
+    const startIdx = findQuicklogEntryLineIdx(lines, qlId)
+    if (startIdx === -1) continue
+    if (findQuicklogEntryLineIdx(baseLines, qlId) !== -1) { alreadyIncluded.push(qlId); continue }
+    let endIdx = lines.length
+    for (let i = startIdx + 1; i < lines.length; i++) {
+      if (/^##[ \t]*\S/.test(lines[i])) { endIdx = i; break }
+    }
+    const block = lines.slice(startIdx, endIdx)
+    while (block.length && block[block.length - 1].trim() === '') block.pop()
+    blocks.push(block)
+    blockIds.push(qlId)
+  }
+  if (blocks.length === 0 && alreadyIncluded.length === 0) return null
+  const outLines = [...baseLines]
+  for (const block of blocks) {
+    if (outLines.length > 0) outLines.push('') // 条目间空行分隔
+    outLines.push(...block)
+  }
+  let sliced = outLines.join('\n') + '\n'
+  if (eol === '\r\n') sliced = sliced.replace(/\n/g, '\r\n')
+  return { content: sliced, blockIds, alreadyIncluded }
+}
+
+const QUICKLOG_COMMIT_MANUAL_FALLBACK = [
+  '人工兜底（四步舞）：',
+  '  ① 备份 QUICKLOG 文件：cp <文件> /tmp/quicklog-backup.md',
+  '  ② 从工作区文件剥离并行会话条目（只留本会话条目，条目块 = "## ql-…" 行到下一个 "## " 头）',
+  '  ③ git add -- <QUICKLOG文件> .sillyspec/quicklog/patches/<ql-id>.* && git commit -m "..."',
+  '  ④ 从备份恢复工作区全量（并行条目回到未提交态）',
+].join('\n')
+
+/**
+ * 一键收编本会话 QUICKLOG 条目（`sillyspec quicklog commit`，known-issues ④ v1）。
+ *
+ * 持用户 QUICKLOG 锁（与 allocate/complete/cancel 同锁）跨「定位 → 切片 → 提交 → 恢复」
+ * 全程——锁内重读文件，并发追加的并行条目不丢（恢复用的就是锁内读到的最新全量）。
+ *
+ * @param {object} opts
+ * @param {string} opts.specBase .sillyspec 根目录
+ * @param {string} [opts.cwd] 调用方 cwd（git rev-parse --show-toplevel 的起点）
+ * @param {string} opts.gitUser git user.name（定位本用户 QUICKLOG 文件与锁）
+ * @param {string[]} [opts.qlIds] 显式 ql-ID（--ql，可含已取消条目——历史一并收编）
+ * @param {string|null} [opts.changeName] quick 会话 ID（缺 --ql 时读其 guard.json 的 quicklogId）
+ * @param {string|null} [opts.sessionsDir] quick-sessions 目录（平台模式异位时由 dispatch 传入）
+ * @param {string} opts.message 提交信息
+ * @param {string[]} [opts.extraPathspecs] 额外 pathspec（-- 后透传，随本次提交带上）
+ * @returns {Promise<{ok:boolean,skipped:boolean,head:string,shortHead:string,files:string[],
+ *   quicklogFiles:string[],committedQlIds:string[],skippedQlIds:string[],backupPaths:string[]}>}
+ */
+export async function runQuicklogCommit({ specBase, cwd = process.cwd(), gitUser, qlIds = [], changeName = null, sessionsDir = null, message = '', extraPathspecs = [] }) {
+  if (!message || !message.trim()) throw new Error('缺少 -m/--message <提交信息>（建议 "chore: 收编本会话 QUICKLOG 条目——<一句话>"）')
+  const ids = [...new Set((Array.isArray(qlIds) ? qlIds : []).filter(id => typeof id === 'string' && id.trim()).map(id => id.trim()))]
+
+  // ql-ID 解析优先级：--ql 显式 > 会话 guard.json（写侧字段 quicklogId，兼容旧 .qlId）
+  if (ids.length === 0 && changeName) {
+    const guardPath = join(sessionsDir || join(specBase, '.runtime', 'quick-sessions'), changeName, 'guard.json')
+    try {
+      if (existsSync(guardPath)) {
+        const g = JSON.parse(readFileSync(guardPath, 'utf8'))
+        const q = g.quicklogId || g.qlId
+        if (typeof q === 'string' && q.trim()) ids.push(q.trim())
+      }
+    } catch { /* guard 损坏 → 按缺失走下方 fail-fast */ }
+  }
+  if (ids.length === 0) {
+    throw new Error(`无法定位 ql-ID：--change 会话的 guard.json 缺失/损坏且未传 --ql——显式传 --ql <ql-xxx>（可重复传多个；含已取消条目，cancelled 也是历史一并收编；ID 即 QUICKLOG 条目头 "## ql-…" 的 ID）`)
+  }
+
+  const quicklogDir = join(specBase, 'quicklog')
+  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
+  const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
+  const repoRootRaw = safeGit(cwd, ['rev-parse', '--show-toplevel'], { timeout: 10000 }).value
+  if (!repoRootRaw) throw new Error(`git 仓库定位失败（cwd=${cwd} 的 git rev-parse --show-toplevel 无输出）`)
+  const repoRoot = resolve(repoRootRaw)
+  const toRel = (abs) => relative(repoRoot, abs).replace(/\\/g, '/')
+
+  const result = await withFileLock(lockPath, async () => {
+    // 锁内重扫（并发追加不丢）：主文件优先，恒扫全部 QUICKLOG 文件（含轮转归档——
+    // 2026-09-16 实证 ql-013 落轮转新文件、ql-014 又落回旧文件，新旧都可能有本会话条目）
+    const allFiles = listQuicklogFiles(quicklogDir)
+    const mainName = `QUICKLOG-${user}.md`
+    const ordered = existsSync(join(quicklogDir, mainName))
+      ? [mainName, ...allFiles.filter(f => f !== mainName)] : allFiles
+    const plans = []
+    const found = new Set()
+    for (const f of ordered) {
+      const p = join(quicklogDir, f)
+      let content = ''
+      try { content = readFileSync(p, 'utf8') } catch { continue }
+      const contentLines = content.split(/\r?\n/)
+      const hit = ids.filter(id => findQuicklogEntryLineIdx(contentLines, id) !== -1)
+      for (const id of hit) found.add(id)
+      if (hit.length > 0) plans.push({ file: p, rel: toRel(p), content, hitIds: hit })
+    }
+    // 工作区未命中者查 HEAD 基线：已在 = 幂等跳过；两边都无 = fail-fast（--ql 笔误防护）
+    const alreadyCommitted = []
+    for (const id of ids.filter(i => !found.has(i))) {
+      let inHead = false
+      for (const f of ordered) {
+        const blob = safeGit(repoRoot, ['show', `HEAD:${toRel(join(quicklogDir, f))}`], { trim: false, timeout: 10000 }).value
+        if (blob && findQuicklogEntryLineIdx(blob.replace(/\r\n/g, '\n').split('\n'), id) !== -1) { inHead = true; break }
+      }
+      if (inHead) alreadyCommitted.push(id)
+      else throw new Error(`条目 ${id} 在所有 QUICKLOG-*.md（含轮转归档）与 HEAD 中均未找到——核对 --ql 的 ql-ID。\n${QUICKLOG_COMMIT_MANUAL_FALLBACK}`)
+    }
+
+    // 切片 + 备份（.runtime 不入库，恢复失败时的最后兜底）。无新块的文件不动不落盘——
+    // 已收编条目重跑形态下按基线归一化重写会制造只差尾部空行的假提交。
+    const now = new Date()
+    const stamp = `${todayStamp(now)}-${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}`
+    mkdirSync(join(specBase, '.runtime'), { recursive: true })
+    const backups = []
+    const originals = []
+    const slicePlans = []
+    for (const plan of plans) {
+      const baseline = safeGit(repoRoot, ['show', `HEAD:${plan.rel}`], { trim: false, timeout: 10000 }).value || ''
+      const sliced = sliceQuicklogFileContent(plan.content, baseline, plan.hitIds)
+      if (!sliced) continue // 不可能（plan.hitIds 非空才进 plans），防御
+      for (const id of sliced.alreadyIncluded) alreadyCommitted.push(id)
+      if (sliced.blockIds.length === 0) continue // 全部已在基线：文件不动、不进提交
+      const backupPath = join(specBase, '.runtime', `quicklog-slice-${stamp}-${basename(plan.file)}`)
+      writeFileSync(backupPath, plan.content)
+      backups.push(backupPath)
+      originals.push({ file: plan.file, content: plan.content })
+      await writeAtomic(plan.file, sliced.content)
+      slicePlans.push(plan)
+    }
+
+    // pathspec 组装：QUICKLOG 文件 + patches sidecar（--done 冻结件，存在才加）+ 额外透传
+    const addPaths = slicePlans.map(pl => pl.rel)
+    for (const id of ids) {
+      for (const ext of ['.json', '.patch']) {
+        const sp = join(quicklogDir, 'patches', id + ext)
+        if (existsSync(sp)) addPaths.push(toRel(sp))
+      }
+    }
+    for (const extra of (Array.isArray(extraPathspecs) ? extraPathspecs : []).filter(Boolean)) {
+      addPaths.push(toRel(isAbsolute(extra) ? extra : resolve(cwd, extra)))
+    }
+    if (addPaths.length === 0) {
+      // 条目均已收编且无 sidecar/额外 pathspec → 无事可做（幂等重跑）
+      return { skipped: true, head: safeGit(repoRoot, ['rev-parse', 'HEAD'], { timeout: 10000 }).value || '', addPaths: [], backups, alreadyCommitted, quicklogFiles: slicePlans.map(pl => basename(pl.file)) }
+    }
+
+    try {
+      await quicklogGitRetry(repoRoot, ['add', '--', ...addPaths], 'git add')
+      // pathspec 范围内无 staged 变更 = 条目均已收编（幂等重跑），HEAD 不动不算失败
+      const staged = safeGit(repoRoot, ['diff', '--cached', '--name-only', '--', ...addPaths], { timeout: 10000 }).value || ''
+      if (!staged.trim()) {
+        return { skipped: true, head: safeGit(repoRoot, ['rev-parse', 'HEAD'], { timeout: 10000 }).value || '', addPaths, backups, alreadyCommitted, quicklogFiles: slicePlans.map(pl => basename(pl.file)) }
+      }
+      await quicklogGitRetry(repoRoot, ['commit', '-m', message, '--', ...addPaths], 'git commit')
+      const head = safeGit(repoRoot, ['rev-parse', 'HEAD'], { timeout: 10000 }).value || ''
+      return { skipped: false, head, addPaths, backups, alreadyCommitted, quicklogFiles: slicePlans.map(pl => basename(pl.file)) }
+    } finally {
+      // 恢复：切片前工作区全量写回（并行会话条目回到「未提交」预期态；原子写防轮询读半截）
+      for (const o of originals) await writeAtomic(o.file, o.content)
+    }
+  }, {
+    staleMs: 120000, // 临界区含 git add/commit（AV 扫描的 Windows 上秒级起步），30s 默认会被误偷锁
+    timeoutMs: 120000,
+    content: JSON.stringify({ pid: process.pid, purpose: 'quicklog-commit' }),
+  })
+
+  const already = [...new Set(result.alreadyCommitted)]
+  return {
+    ok: true,
+    skipped: !!result.skipped,
+    head: result.head,
+    shortHead: (result.head || '').slice(0, 8),
+    files: result.addPaths,
+    quicklogFiles: result.quicklogFiles,
+    committedQlIds: ids.filter(id => !already.includes(id)),
+    skippedQlIds: already,
+    backupPaths: result.backups,
+  }
+}