sillyspec 3.26.13 → 3.26.15

package/src/init.js

@@ -308,7 +308,7 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null, options
   mkdirSync(knowledgeDir, { recursive: true });
   const indexPath = join(knowledgeDir, 'INDEX.md');
   if (!existsSync(indexPath)) {
-    writeFileSync(indexPath, `# Knowledge Index\n\n> 子代理任务开始前查询此文件，按关键词匹配，只读命中的知识文件。\n> execute/quick 执行中发现的坑自动追加到 uncategorized.md，经用户确认后归类到对应文件。\n\n<!-- 格式：关键词1|关键词2|关键词3 → 文件路径 -->\n<!-- 示例：mybatis-plus|分页|Page → pagination.md -->\n<!-- 示例：跨域|CORS|preflight → cors.md -->\n`);
+    writeFileSync(indexPath, `# Knowledge Index\n\n> 子代理任务开始前查询此文件，按关键词匹配，只读命中的知识文件。\n> 只有遇到真正的项目特有坑（跨变更可复用、未来 agent 可能再次踩到）时才追加到 uncategorized.md；不要为了完成任务硬凑条目。经用户确认后归类到对应文件并更新本索引。\n\n<!-- 格式：关键词1|关键词2|关键词3 → 文件路径 -->\n<!-- 示例：mybatis-plus|分页|Page → pagination.md -->\n<!-- 示例：跨域|CORS|preflight → cors.md -->\n`);
   }
   const uncatPath = join(knowledgeDir, 'uncategorized.md');
   if (!existsSync(uncatPath)) {

package/src/local-register.js

@@ -0,0 +1,98 @@
+/**
+ * local-register.js — `sillyspec local register-repo <key> <path>` 的 repos: 段外科手术式写入。
+ *
+ * 背景（2026-08-21 agent-手工产出审计项④）：跨仓 change 的 repo key 必须在 local.yaml
+ * `repos:` 段注册（MultiRepoContext 约束② fail-closed），此前靠 agent 手编 YAML——正是
+ * agent 满目录找/在根目录乱建 local.yaml 的上游。本模块只动 `repos:` 段：已有该 key 就地
+ * 改值，没有就插入段内；其余内容（注释/凭据段/手调配置）逐行原样保留，绝不整文件重序列化。
+ *
+ * 写入口径与 parseRepoRegistry（plan-postcheck.js，读侧）成对：
+ *   repos:
+ *     sillyspec: C:/Users/you/IdeaProjects/sillyspec
+ *     # main 不用注册（隐式 = cwd）
+ *
+ * 文件不存在时新建只含 repos: 段的 minimal local.yaml（真实 local.yaml 其余段由
+ * `sillyspec local detect` / `platform connect` 各自补齐）。落盘走 writeAtomicSync
+ * （tmp+rename，防多会话并发写半截，与 local detect 写入口径一致）。
+ */
+import { existsSync, readFileSync, mkdirSync } from 'fs'
+import { dirname } from 'path'
+import { writeAtomicSync } from './fs-atomic.js'
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * 把 `<key>: <path>` 注册进 local.yaml 的 repos: 段（幂等，已有该 key 则改值）。
+ *
+ * @param {string} yamlPath - local.yaml 绝对路径（不存在则新建）
+ * @param {string} key - repo key（限 [A-Za-z0-9_.\-]+，'main' 隐式禁止注册）
+ * @param {string} repoPath - 跨仓仓根绝对路径（写入时统一正斜杠，与示例格式一致）
+ * @returns {{ fileCreated: boolean, sectionCreated: boolean, replaced: boolean }}
+ * @throws {Error} key 非法 / key='main' / repoPath 空 / 读写失败
+ */
+export function registerRepoInLocalYaml(yamlPath, key, repoPath) {
+  if (!yamlPath) throw new Error('registerRepoInLocalYaml: yamlPath 不能为空')
+  if (!key || !/^[A-Za-z0-9_.\-]+$/.test(key)) {
+    throw new Error(`repo key 非法: "${key}"（限字母数字 . _ -，与 parseRepoRegistry 读侧口径一致）`)
+  }
+  if (key === 'main') {
+    throw new Error("repo key 'main' 不用注册（隐式 = 主仓 cwd），跨仓仓才需要 register-repo")
+  }
+  if (!repoPath) throw new Error('registerRepoInLocalYaml: repoPath 不能为空')
+
+  const existed = existsSync(yamlPath)
+  // CRLF 归一后按 LF 写回（同 task 卡锚点写入的 CRLF 坑；local.yaml 各 CLI 写入口径均 LF）
+  const raw = existed ? readFileSync(yamlPath, 'utf8').replace(/\r\n?/g, '\n') : ''
+  const posixPath = String(repoPath).replace(/\\/g, '/')
+  const entryLine = `  ${key}: ${posixPath}`
+
+  const write = (text) => {
+    mkdirSync(dirname(yamlPath), { recursive: true })
+    writeAtomicSync(yamlPath, text)
+  }
+
+  const lines = raw.split('\n')
+  // repos: 段起点（顶层 key 行，与 parseRepoRegistry 同口径）
+  let reposIdx = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (/^repos:\s*(?:#.*)?$/.test(lines[i])) { reposIdx = i; break }
+  }
+
+  if (reposIdx === -1) {
+    // 无 repos: 段 → 文件尾追加（保留既有内容与注释；空文件/新文件直接起段）
+    const sep = raw.trim() === '' ? '' : (raw.endsWith('\n') ? '' : '\n') + '\n'
+    write(raw + sep + `repos:\n${entryLine}\n`)
+    return { fileCreated: !existed, sectionCreated: true, replaced: false }
+  }
+
+  // 段范围：reposIdx+1 起到下一个顶层 key（行首非空白非注释）为止（与 parseRepoRegistry 同口径）
+  let end = lines.length
+  for (let i = reposIdx + 1; i < lines.length; i++) {
+    const l = lines[i]
+    if (l.length > 0 && !/^[\s#]/.test(l) && l.trim() !== '') { end = i; break }
+  }
+
+  // 已有该 key → 就地改值（幂等）
+  const keyRe = new RegExp(`^\\s+${escapeRe(key)}:\\s`)
+  for (let i = reposIdx + 1; i < end; i++) {
+    if (keyRe.test(lines[i])) {
+      if (lines[i] === entryLine) {
+        return { fileCreated: false, sectionCreated: false, replaced: false } // 值未变，幂等跳过
+      }
+      lines[i] = entryLine
+      write(lines.join('\n'))
+      return { fileCreated: false, sectionCreated: false, replaced: true }
+    }
+  }
+
+  // 无该 key → 插到段内最后一个非空行（条目或段内注释）之后
+  let insertAt = reposIdx + 1
+  for (let i = reposIdx + 1; i < end; i++) {
+    if (lines[i].trim() !== '') insertAt = i + 1
+  }
+  lines.splice(insertAt, 0, entryLine)
+  write(lines.join('\n'))
+  return { fileCreated: false, sectionCreated: false, replaced: false }
+}

package/src/module-impact.js

@@ -0,0 +1,146 @@
+/**
+ * module-impact.js — `sillyspec module-impact` 的归类骨架生成
+ * （2026-08-21 agent-手工产出审计第三批 D3）。
+ *
+ * archive 阶段的 module-impact.md 要求「模块影响矩阵」+「未匹配文件」两章节、≥20 行，
+ * agent 此前从零手写整份矩阵。文件 × 模块的归属是纯机械分类（module-map paths 前缀匹配，
+ * 与 scan diff 归属同源），影响类型判定（逻辑/数据结构/接口/调用关系/配置/新增）是语义——
+ * 骨架预填「模块|文件|状态」三列，影响类型列留 <!--TODO--> 由 agent 逐行填。
+ *
+ * diff 源：resolveVerifyChangedFiles（worktree-aware，与 task-review 同源）；
+ * module-map：.sillyspec/docs/<p>/modules/_module-map.yaml 的 modules.<id>.paths
+ * （目录条目以 / 结尾按前缀匹配，与模块上下文索引读侧口径一致）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { resolveVerifyChangedFiles } from './verify-postcheck.js'
+import { resolveSpecDir } from './run/shared.js'
+
+/**
+ * 轻量解析 _module-map.yaml：modules.<id>.paths 列表（手写解析同 parseRepoRegistry 风格，
+ * 只取 paths 平面信息，status/doc 等忽略）。
+ * @returns {Map<string, string[]>} moduleId → paths（posix）
+ */
+export function parseModuleMapPaths(yamlText) {
+  const map = new Map()
+  if (!yamlText) return map
+  let currentModule = null
+  let inPaths = false
+  for (const line of yamlText.split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue
+    if (!/^\s/.test(line)) {
+      inPaths = line.startsWith('modules:')
+      currentModule = null
+      continue
+    }
+    const modMatch = line.match(/^  ([A-Za-z0-9_.\-]+):\s*$/)
+    if (modMatch) {
+      currentModule = modMatch[1]
+      inPaths = false
+      continue
+    }
+    if (currentModule && /^    paths:\s*$/.test(line)) {
+      inPaths = true
+      if (!map.has(currentModule)) map.set(currentModule, [])
+      continue
+    }
+    if (inPaths && currentModule) {
+      const item = line.match(/^      - (.+)$/)
+      if (item) map.get(currentModule).push(item[1].trim().replace(/\\/g, '/'))
+    }
+  }
+  return map
+}
+
+function classifyFile(posixPath, modulePaths) {
+  for (const [moduleId, paths] of modulePaths) {
+    for (const p of paths) {
+      // 目录条目以 / 结尾 → 前缀匹配；文件条目 → 精确或子路径（与模块上下文索引读侧口径一致）
+      if (p.endsWith('/')) {
+        if (posixPath.startsWith(p)) return moduleId
+      } else if (posixPath === p || posixPath.startsWith(p + '/')) {
+        return moduleId
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * 生成 module-impact.md 骨架。
+ * @param {{ cwd: string, changeName: string, specDir?: string|null }} opts
+ * @returns {{ markdown: string, matchedCount: number, unmatchedCount: number }|null}
+ *   无 module-map / 无 diff → null（无可归类输入，agent 全手写）
+ */
+export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+
+  // 找 _module-map.yaml（docs/<p>/modules/；多项目取首个含 modules 索引的）
+  let moduleMapPath = null
+  try {
+    for (const p of readdirSync(join(specBase, 'docs'), { withFileTypes: true })) {
+      if (!p.isDirectory()) continue
+      const candidate = join(specBase, 'docs', p.name, 'modules', '_module-map.yaml')
+      if (existsSync(candidate)) {
+        moduleMapPath = candidate
+        break
+      }
+    }
+  } catch { /* 无 docs/ */ }
+  if (!moduleMapPath) return null
+
+  const modulePaths = parseModuleMapPaths(readFileSync(moduleMapPath, 'utf8'))
+  if (modulePaths.size === 0) return null
+
+  const diffFiles = resolveVerifyChangedFiles(cwd, changeName) || []
+  const sourceFiles = diffFiles.map(f => f.split('\\').join('/')).filter(f => !f.startsWith('.sillyspec/'))
+  if (sourceFiles.length === 0) return null
+
+  const byModule = new Map()
+  const unmatched = []
+  for (const f of sourceFiles) {
+    const mod = classifyFile(f, modulePaths)
+    if (mod) {
+      if (!byModule.has(mod)) byModule.set(mod, [])
+      byModule.get(mod).push(f)
+    } else {
+      unmatched.push(f)
+    }
+  }
+
+  const L = [
+    '# 模块影响分析（骨架由 `sillyspec module-impact --change <变更名>` 生成）',
+    '',
+    '> 文件×模块归属由 CLI 按 _module-map.yaml paths 前缀匹配预填；',
+    '> **影响类型**（逻辑变更/数据结构变更/接口变更/调用关系变更/配置变更/新增）与 review 标记是语义判断，',
+    '> 逐行把 <!--TODO--> 替换为真实结论——以 git diff 为准（真实 > 声明）。',
+    '',
+    '## 模块影响矩阵',
+    '',
+    '| 模块 | 变更文件 | 影响类型 | 需 review |',
+    '|---|---|---|---|',
+  ]
+  const rows = [...byModule.entries()].sort((a, b) => a[0].localeCompare(b[0]))
+  for (const [moduleId, files] of rows) {
+    for (const f of files) {
+      L.push(`| ${moduleId} | \`${f}\` | <!--TODO--> | <!--TODO--> |`)
+    }
+  }
+  L.push('')
+  L.push('## 未匹配文件')
+  L.push('')
+  if (unmatched.length === 0) {
+    L.push('无（全部变更文件已归属到模块）。')
+  } else {
+    L.push('以下变更文件未命中 _module-map.yaml 任何模块 paths——确认是模块索引过期（该跑 `sillyspec modules rebuild`）还是真的游离文件：')
+    L.push('')
+    for (const f of unmatched) L.push(`- \`${f}\` <!--TODO: 归属判定-->`)
+  }
+  L.push('')
+  L.push('## 影响类型说明')
+  L.push('')
+  L.push('逻辑变更 / 数据结构变更 / 接口变更 / 调用关系变更 / 配置变更 / 新增；不确定的影响标 needs review。')
+  L.push('')
+
+  return { markdown: L.join('\n'), matchedCount: sourceFiles.length - unmatched.length, unmatchedCount: unmatched.length }
+}

package/src/progress/change-registry.js

@@ -276,8 +276,15 @@ export class ChangeRegistry {
   /**
    * 从活跃列表移除变更（归档时调用，不物理删除）
    * SQL: UPDATE changes SET status = 'archived'
+   *
+   * 归档终态一致化（坑 manual-archive-desync-status-only，2026-08-21 实证）：手动搬目录绕过
+   * `run archive --done --confirm` 后，自愈/幽灵清理路径只改 status 一个字段，留下「已归档 +
+   * current_stage 停在 execute + 归档 0/5 步」的自相矛盾终态，推送平台后渲染成「进度丢失」。
+   * opts.archiveStepNames（调用方取自 stageRegistry 单一真相）给定时同事务收尾：
+   * current_stage='archive' + stages.archive=completed + 其步骤行全 completed
+   * （缺行按定义补种——平台按步骤数展示完成度，零行会显示 0/5）。
    */
-  unregisterChange(cwd, changeName) {
+  unregisterChange(cwd, changeName, opts = {}) {
     if (!changeName) {
       console.warn('⚠️  unregisterChange: changeName 为空，跳过');
       return;
@@ -286,9 +293,41 @@ export class ChangeRegistry {
     db.transaction(() => {
       const sqlDb = db.getDb();
       const now = new Date().toISOString();
-      sqlDb.prepare(
-        `UPDATE changes SET status = 'archived', last_active = ? WHERE name = ?`
-      ).run(now, changeName);
+      let sql = `UPDATE changes SET status = 'archived', last_active = ?`;
+      const params = [now];
+      if (Array.isArray(opts.archiveStepNames)) sql += `, current_stage = 'archive'`;
+      sql += ` WHERE name = ?`;
+      params.push(changeName);
+      sqlDb.prepare(sql).run(...params);
+      if (Array.isArray(opts.archiveStepNames)) {
+        const row = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
+        if (row) {
+          sqlDb.prepare(
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at)
+             VALUES (?, 'archive', 'completed', ?, ?)
+             ON CONFLICT(change_id, stage) DO UPDATE SET status = 'completed', completed_at = excluded.completed_at`
+          ).run(row.id, now, now);
+          const stageRow = sqlDb.prepare(
+            'SELECT id FROM stages WHERE change_id = ? AND stage = ?'
+          ).get(row.id, 'archive');
+          if (stageRow) {
+            // 现有步骤行（含 pending/waiting）全收尾；定义里有而行里没有的（阶段从未初始化）按定义补种
+            sqlDb.prepare(
+              `UPDATE steps SET status = 'completed', completed_at = ? WHERE stage_id = ?`
+            ).run(now, stageRow.id);
+            const existing = new Set(
+              sqlDb.prepare('SELECT name FROM steps WHERE stage_id = ?').all(stageRow.id).map(r => r.name)
+            );
+            let order = existing.size;
+            const ins = sqlDb.prepare(
+              `INSERT INTO steps (stage_id, name, status, completed_at, ordering) VALUES (?, ?, 'completed', ?, ?)`
+            );
+            for (const name of opts.archiveStepNames) {
+              if (!existing.has(name)) { ins.run(stageRow.id, name, now, order++) }
+            }
+          }
+        }
+      }
       // 本地脏度（D-013 / task-04）：归档也是本地状态推进
       this.pm._touchLocalModified(cwd, changeName, now);
     });

package/src/progress/stage-machine.js

@@ -282,13 +282,18 @@ export class StageMachine {
    * @returns {{ text: string, command?: string }|null}
    */
   _getNextSuggestion(data) {
+    // 建议命令携带 --change（坑 suggestion-command-missing-change，2026-08-21 实证）：
+    // 多活跃变更仓 pm.read(cwd, null) 无法自动定位变更 → 照抄建议命令（不带 --change）执行
+    // 报「未找到进度数据」，阶段完结后的 --wait 确认门也登记不上。progress 带 currentChange
+    // 时附加；无（测试 fixture / 旧数据）保持裸命令（存量断言零回归）。
+    const cc = data.currentChange ? ` --change ${data.currentChange}` : '';
     // 找到第一个 revising 阶段
     const revisingStage = STAGE_ORDER.find(s => data.stages[s]?.status === 'revising');
     if (revisingStage) {
       const sd = data.stages[revisingStage];
       return {
         text: `${STAGE_LABELS[revisingStage] || revisingStage} 正在修订中（revision ${sd.revision || 1}），请继续完成修订。`,
-        command: `sillyspec run ${revisingStage}`,
+        command: `sillyspec run ${revisingStage}${cc}`,
       };
     }
 
@@ -298,7 +303,7 @@ export class StageMachine {
       const sd = data.stages[staleStage];
       return {
         text: `${STAGE_LABELS[staleStage] || staleStage} 已失效（${sd.staleReason || '上游修订'}），需要从第一步重建。`,
-        command: `sillyspec run ${staleStage} --reopen --from-step 1`,
+        command: `sillyspec run ${staleStage} --reopen --from-step 1${cc}`,
       };
     }
 
@@ -318,14 +323,14 @@ export class StageMachine {
           const ws = sd.steps[waitIdx];
           return {
             text: `${STAGE_LABELS[s] || s} 进行中，Step ${waitIdx + 1}「${ws.name}」等待用户输入${ws.waitReason ? `（${ws.waitReason}）` : ''}，用 --answer 恢复。`,
-            command: `sillyspec run ${s} --continue --answer "用户回答"`,
+            command: `sillyspec run ${s} --continue --answer "用户回答"${cc}`,
           };
         }
         const hasPending = sd.steps.some(st => ['pending', 'waiting', 'failed'].includes(st.status));
         if (hasPending) {
           return {
             text: `${STAGE_LABELS[s] || s} 进行中，继续执行下一步。`,
-            command: `sillyspec run ${s}`,
+            command: `sillyspec run ${s}${cc}`,
           };
         }
       }
@@ -349,7 +354,7 @@ export class StageMachine {
       if (upstreamOk) {
         return {
           text: `可以开始 ${STAGE_LABELS[s] || s}。`,
-          command: `sillyspec run ${s}`,
+          command: `sillyspec run ${s}${cc}`,
         };
       }
     }

package/src/progress.js

@@ -19,6 +19,7 @@ import { ConsistencyDoctor } from './progress/consistency-doctor.js';
 import { ChangeRegistry } from './progress/change-registry.js';
 import { StepStore } from './progress/step-store.js';
 import { StageMachine } from './progress/stage-machine.js';
+import { stageRegistry } from './stages/index.js';
 import { STAGE_ORDER, MAIN_FLOW_ORDER, VALID_STAGES, STAGE_LABELS, SPEC_DIR_NAME, CURRENT_VERSION, emptyStage } from './progress/shared.js';
 // resolveSpecDir 单一真相源在 src/run/shared.js（含 home 拒绝守卫，坑 cwd-correction-home-collision
 // 根治：home 下 .sillyspec 恒不命中，防 smoke/临时目录污染自我延续）。此处 re-export 保持
@@ -812,7 +813,18 @@ export class ProgressManager {
 
   renameChange(cwd, oldName, newName) { return this._changeRegistry.renameChange(cwd, oldName, newName); }
 
-  unregisterChange(cwd, changeName) { return this._changeRegistry.unregisterChange(cwd, changeName); }
+  // opts.archiveStepNames 给定时做归档终态一致化收尾（见 change-registry.unregisterChange 注释，
+  // 坑 manual-archive-desync-status-only）；archiveStepNamesForArchive() 取 stageRegistry 单一真相
+  //（stages/* 不反向依赖 progress.js，静态 import 无环）。
+  unregisterChange(cwd, changeName, opts) { return this._changeRegistry.unregisterChange(cwd, changeName, opts); }
+
+  archiveStepNamesForArchive() {
+    if (!this._archiveStepNamesCache) {
+      const defs = stageRegistry?.archive?.steps
+      this._archiveStepNamesCache = Array.isArray(defs) ? defs.map(s => s.name) : []
+    }
+    return this._archiveStepNamesCache
+  }
 
   updateChangeMeta(cwd, changeName, meta) { return this._changeRegistry.updateChangeMeta(cwd, changeName, meta); }
 
@@ -1188,8 +1200,11 @@ export class ProgressManager {
     if (projectRow === undefined) return null;
     const projectName = projectRow.name;
 
-    // 2. 活跃变更（取第一个，或空）
-    const changeRows = sqlDb.prepare("SELECT id, name, current_stage, last_active FROM changes WHERE status = 'active' ORDER BY name").all();
+    // 2. 活跃变更（取 last_active 最新的一个）
+    // ql-20260821-003：多活跃仓（变更隔离是常态，单仓可同时存在 N 个 active）下
+    // 原 ORDER BY name 恒取字典序最前（通常是最老的变更），「当前变更/最后活动」
+    // 停留在历史数据。dump 语义是「当前工作流状态」→ 取最近活跃的那个。
+    const changeRows = sqlDb.prepare("SELECT id, name, current_stage, last_active FROM changes WHERE status = 'active' ORDER BY last_active DESC").all();
     if (changeRows.length === 0) {
       // 无活跃变更 → 返回仅含 project 的骨架
       return {

package/src/quicklog.js

@@ -14,7 +14,7 @@ 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,
+  readFileSync, writeFileSync, writeSync, readdirSync, renameSync, appendFileSync, rmSync,
 } from 'fs'
 import { randomBytes } from 'crypto'
 
@@ -722,3 +722,108 @@ export function findQuicklogEntry(specBase, gitUser, qlId) {
   }
   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 }
+}