sillyspec 3.28.4 → 3.28.5

package/src/mcp-server.js

@@ -0,0 +1,144 @@
+/**
+ * mcp-server.js（P2-g = MCP Phase 2，noai-ir-roadmap §5）：SillySpec 最小 stdio MCP server。
+ *
+ * 动机：agent 此前靠 shell 调 CLI + 解析人类可读文本，flag 幻觉与文本解析漂移是真实痛点
+ * （铁律里专门有一条「不确定命令时停下问用户」）。MCP tools 的 schema 化参数把 flag 面锁死；
+ * machine-interface 的 JSON envelope（gate/derive/progress）与 next 的 JSON 输出是现成地基。
+ *
+ * 形态：`sillyspec mcp` 启动（hosts 配 command=sillyspec args=[mcp]）。stdio 上跑 JSON-RPC 2.0
+ * 行协议（每行一个请求/响应）。**只读 tools**（Phase 2 边界：--done 等状态推进不暴露——
+ * Phase 3 另计；工具全部经子进程 `--json` 执行，stdout 纪律天然隔离，不 import 重模块）：
+ *   - sillyspec_next：状态探测与下一步建议（detectNextStep）
+ *   - sillyspec_gate：阶段完成门控聚合（machine-interface runGate envelope）
+ *   - sillyspec_derive：单项事实核验（runDerive envelope）
+ *   - sillyspec_progress：全局进度总览（progress show --json envelope）
+ */
+import { createInterface } from 'node:readline'
+import { spawn } from 'node:child_process'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const CLI_ENTRY = join(__dirname, 'index.js')
+const PROTOCOL_VERSION = '2025-06-18'
+const SERVER_INFO = { name: 'sillyspec', version: '3.28.4' }
+
+const TOOLS = [
+  {
+    name: 'sillyspec_next',
+    description: '项目状态探测：状态 + 下一步命令 + 依据 + 活跃变更列表（只读；无活跃进度时从产物反推）',
+    inputSchema: { type: 'object', properties: { spec_dir: { type: 'string', description: '规范目录（缺省 <cwd>/.sillyspec）' } } },
+  },
+  {
+    name: 'sillyspec_gate',
+    description: '阶段完成门控聚合：变更的 <stage> 阶段此刻能否标记完成（envelope：ok/errors/warnings/checks；exit 0/1/2）',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        stage: { type: 'string', enum: ['brainstorm', 'plan', 'execute', 'verify', 'archive'], description: '目标阶段' },
+        change: { type: 'string', description: '变更名（必填）' },
+        spec_dir: { type: 'string' },
+      },
+      required: ['stage', 'change'],
+    },
+  },
+  {
+    name: 'sillyspec_derive',
+    description: '单项事实核验（facet：execute-evidence / verify-test / task-reviews / artifacts）',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        facet: { type: 'string', enum: ['execute-evidence', 'verify-test', 'task-reviews', 'artifacts'] },
+        change: { type: 'string' },
+        spec_dir: { type: 'string' },
+      },
+      required: ['facet', 'change'],
+    },
+  },
+  {
+    name: 'sillyspec_progress',
+    description: '全局进度总览（活跃变更 × 阶段 × 步骤态，envelope JSON；只读）',
+    inputSchema: { type: 'object', properties: { spec_dir: { type: 'string' } } },
+  },
+]
+
+/** tools/call 路由：子进程 --json（stdout 纪律隔离；CLI 的 stderr 透传进 text 供诊断） */
+async function callTool(name, args) {
+  const argv = ['--meta'] // 占位防误配：--meta 是 run 的 flag，工具不走 run
+  argv.length = 0
+  const specDir = args && typeof args.spec_dir === 'string' && args.spec_dir ? ['--spec-dir', args.spec_dir] : []
+  switch (name) {
+    case 'sillyspec_next':
+      return await runCli(['next', '--json', ...specDir])
+    case 'sillyspec_gate':
+      return await runCli(['gate', String(args.stage), '--change', String(args.change), '--json', ...specDir])
+    case 'sillyspec_derive':
+      return await runCli(['derive', String(args.facet), '--change', String(args.change), '--json', ...specDir])
+    case 'sillyspec_progress':
+      return await runCli(['progress', 'show', '--json', ...specDir])
+    default:
+      return { text: `未知工具: ${name}`, isError: true }
+  }
+}
+
+function runCli(cliArgs) {
+  return new Promise((resolve) => {
+    const p = spawn(process.execPath, [CLI_ENTRY, ...cliArgs], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let out = ''
+    let err = ''
+    p.stdout.on('data', (d) => { out += String(d) })
+    p.stderr.on('data', (d) => { err += String(d) })
+    p.on('close', (code) => {
+      // envelope 原样透传（text = stdout JSON 全文；machine 侧自解）；stderr 仅失败时附诊断
+      const text = (out.trim() || err.trim().slice(-2000) || `（exit ${code}，无输出）`)
+      resolve({ text, isError: code !== null && code !== 0 && code !== 1, exitCode: code })
+    })
+    p.on('error', (e) => resolve({ text: `CLI 子进程失败: ${e.message}`, isError: true }))
+  })
+}
+
+/** 单请求分发。返回 result 对象（或抛 {code, message} 形态错误由上层包 error）。 */
+async function handleMessage(msg) {
+  const { id, method, params } = msg
+  switch (method) {
+    case 'initialize':
+      return { protocolVersion: (params && params.protocolVersion) || PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO }
+    case 'ping':
+      return {}
+    case 'tools/list':
+      return { tools: TOOLS }
+    case 'tools/call': {
+      const name = params && params.name
+      const args = (params && params.arguments) || {}
+      const r = await callTool(name, args)
+      return { content: [{ type: 'text', text: r.text }], ...(r.isError ? { isError: true } : {}) }
+    }
+    default:
+      throw { code: -32601, message: `Method not found: ${method}` }
+  }
+}
+
+/** stdio 行协议主循环（readline 逐行 JSON；通知无 id 不回包）。导出供测试与 `sillyspec mcp` 接线。 */
+export function startMcpServer({ input = process.stdin, output = process.stdout } = {}) {
+  const rl = createInterface({ input })
+  rl.on('line', async (line) => {
+    const trimmed = line.trim()
+    if (!trimmed) return
+    let msg
+    try { msg = JSON.parse(trimmed) } catch { return /* 非 JSON 行静默忽略（协议健壮性） */ }
+    if (msg === null || typeof msg !== 'object' || !msg.method) return
+    if (msg.id === undefined || msg.id === null) return // notification（如 notifications/initialized）
+    try {
+      const result = await handleMessage(msg)
+      output.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result }) + '\n')
+    } catch (e) {
+      const err = e && typeof e === 'object' && e.code !== undefined ? e : { code: -32603, message: (e && e.message) || String(e) }
+      output.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, error: err }) + '\n')
+    }
+  })
+  return new Promise((resolve) => rl.on('close', () => resolve()))
+}

package/src/module-impact.js

@@ -152,7 +152,14 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null,
 
   let sourceFileList
   if (sourceFiles) {
-    sourceFileList = sourceFiles.map(f => f.split('\\').join('/')).filter(f => !f.startsWith('.sillyspec/'))
+    // NEW: 前缀剥离（坑 module-impact-new-prefix-mismatch，2026-09-10 驾驭小结③，用户实锤）：
+    // design 清单待建文件带 NEW: 标记，pathMatches 比对侧早已剥（坑
+    // platform-sync-progress-rollback-and-db-corruption 坑3「仅在比对处剥」），本归类是同
+    // 语义比对（目标文件 × module-map paths）却漏剥——前缀不剥则 classifyFile 前缀匹配必
+    // 失配，NEW 文件全部落「未匹配文件」逼手动回填。剥后与裸路径去重（NEW: a.js 与 a.js 同文件）。
+    sourceFileList = [...new Set(sourceFiles
+      .map(f => String(f).replace(/^NEW:\s*/, '').split('\\').join('/').trim())
+      .filter(f => f && !f.startsWith('.sillyspec/')))]
   } else {
     // includeWorkingTree 同 verify module 子集（坑 module-subset-zero-hit-uncommitted）：
     // worktree 未提交改动也计入模块影响面（module-impact 按实际 diff 归属模块）

package/src/modules.js

@@ -87,18 +87,16 @@ export async function rebuildModuleMap(cwd, { force = false } = {}) {
     }
   }
 
-  // 解析现有 _module-map.yaml 保留已有字段（复用 parseModuleMapSimple：原内置解析只收模块名、
-  // 从不收集列表项 → existingPaths 恒空 → --force 重建后 core_files 全丢，scan-diff scope 退化
-  // 为全量、module-impact classifyFile 全 unmatched——注释声称的「从已有 map 保留」名存实亡）
+  // 解析现有 _module-map.yaml（复用 parseModuleMapSimple canonical 解析）。P2-c
+  //（noai-ir-roadmap §5 字段分离）：existing 条目**全字段**整体保留——merge 语义下
+  // rebuild 只做「补缺 + 增新卡」，--force 不再可能清空 tags/main_symbols/depends_on/
+  // used_by/status/needs_review 等人工维护字段（旧版只保 3 个列表字段，实例 map 文件头
+  // 常年挂着「勿跑 rebuild --force 会清空手动维护」的警告——该警告随本变更退役）。
   let existingModules = {};
   if (existingMap) {
     const parsed = parseModuleMapSimple(existingMap);
     for (const [id, fields] of Object.entries(parsed || {})) {
-      existingModules[id] = {
-        core_files: Array.isArray(fields.core_files) ? fields.core_files : [],
-        test_files: Array.isArray(fields.test_files) ? fields.test_files : [],
-        entrypoints: Array.isArray(fields.entrypoints) ? fields.entrypoints : [],
-      };
+      existingModules[id] = { ...(fields || {}) };
     }
   }
 
@@ -132,53 +130,67 @@ export async function rebuildModuleMap(cwd, { force = false } = {}) {
     ...cards.map(c => c.moduleId)
   ]);
 
+  // ── P2-c merge 语义发射：existing 全字段优先（人工维护不丢）→ 卡片补缺 → 骨架默认垫底 ──
+  const stripQuotes = (v) => String(v).replace(/^"|"$/g, '')
   for (const moduleId of allModuleIds) {
     const card = cards.find(c => c.moduleId === moduleId);
     const cardContent = card?.content || '';
 
     // 从模块卡片提取 context index 字段
     const role = extractSection(cardContent, '定位') || '';
-    const contract = extractSection(cardContent, '契约摘要') || '';
-    const logic = extractSection(cardContent, '关键逻辑') || '';
-    const notes = extractSection(cardContent, '注意事项') || '';
 
-    yaml += `  ${moduleId}:\n`;
-    yaml += `    status: active\n`;
-    if (card) yaml += `    doc: modules/${card.filename}\n`;
-    else yaml += `    doc: modules/${moduleId}.md\n`;
-    yaml += `    needs_review: false\n`;
-    yaml += `    review_reasons: []\n`;
-    // context index 字段（v2）
-    if (role) yaml += `    role: "${escapeYamlString(role)}"\n`;
-    // core_files / test_files / entrypoints 从已有 _module-map.yaml 全量保留（列表项级保真）
     const existing = existingModules[moduleId] || {};
-    for (const [field, items] of [['core_files', existing.core_files], ['test_files', existing.test_files], ['entrypoints', existing.entrypoints]]) {
-      if (Array.isArray(items) && items.length > 0) {
-        yaml += `    ${field}:\n`;
-        for (const p of items) yaml += `      - ${p}\n`;
-      }
+    const merged = {
+      // 骨架默认（垫底）
+      status: 'active',
+      doc: `modules/${(card && card.filename) || moduleId + '.md'}`,
+      needs_review: false,
+      review_reasons: [],
+      risk_level: 'low',
+      verify_commands: [],
+      related_docs: [],
+      // existing 全字段覆盖（人工维护优先）
+      ...existing,
+    }
+    // 卡片补缺：role 仅当 existing 没有时从卡片取；doc 在卡片在场时以卡片文件名为准
+    //（existing.doc 可能指向已改名的旧文件）；卡片不在场则保留 existing.doc
+    if (!merged.role && role) merged.role = role
+    if (card) merged.doc = `modules/${card.filename}`
+
+    yaml += `  ${moduleId}:\n`;
+    for (const k of ['status', 'doc', 'needs_review']) {
+      if (merged[k] !== undefined) yaml += `    ${k}: ${typeof merged[k] === 'boolean' ? merged[k] : merged[k]}\n`;
+    }
+    if (merged.role) yaml += `    role: "${escapeYamlString(stripQuotes(merged.role))}"\n`;
+    // 列表字段全量保真（existing 用什么字段名就保什么——paths/core_files 双形态兼容读者）
+    for (const k of ['paths', 'core_files', 'test_files', 'entrypoints', 'main_symbols', 'tags', 'aliases', 'depends_on', 'used_by', 'review_reasons', 'related_docs', 'verify_commands']) {
+      const items = merged[k];
+      if (items === undefined) continue;
+      if (Array.isArray(items) && items.length === 0) { yaml += `    ${k}: []\n`; continue }
+      if (!Array.isArray(items) || items.length === 0) continue;
+      yaml += `    ${k}:\n`;
+      for (const p of items) yaml += `      - ${p}\n`;
     }
-    if (card) yaml += `    verify_commands: []\n`;
-    yaml += `    risk_level: low\n`;
-    if (contract || logic) yaml += `    related_docs: []\n`;
+    if (merged.risk_level !== undefined) yaml += `    risk_level: ${merged.risk_level}\n`;
     yaml += `\n`;
   }
 
-  // 破坏性保护（multi-agent-platform 坑 modules-rebuild-destructive）：默认 dry-run 只预览不写，--force 才覆盖。
+  // 写入保护（multi-agent-platform 坑 modules-rebuild-destructive）：默认 dry-run 只预览不写。
+  // P2-c 后 --force 为 merge 语义（手动字段全量保留），但重写仍会刷新 generated_at/source_commit
+  // 与排版——dry-run 预览默认保留，确认写入用 --force。
   if (!force && existingMap) {
-    console.log('⚠️  rebuild 默认不写入（破坏性保护）：该命令会覆盖 _module-map.yaml，清空 tags/entrypoints/main_symbols/depends_on/used_by 等手动维护字段');
-    console.log('    本次为预览，未写入磁盘。确认覆盖请运行：sillyspec modules rebuild --force');
+    console.log('⚠️  rebuild 默认不写入（预览保护）。--force 为 merge 语义：existing 全字段保留（tags/main_symbols/depends_on/used_by/status/needs_review 等手动维护字段不丢），只补缺 + 增新卡');
+    console.log('    本次为预览，未写入磁盘。确认写入请运行：sillyspec modules rebuild --force');
     return { dryRun: true, path: mapPath }
   }
 
   writeFileSync(mapPath, yaml, 'utf8');
-  console.log(`✅ _module-map.yaml 已重建：${mapPath}`);
+  console.log(`✅ _module-map.yaml 已重建（merge 语义）：${mapPath}`);
   console.log(`   模块数量：${allModuleIds.size}`);
   for (const id of allModuleIds) {
     console.log(`   - ${id}`);
   }
-  console.log(`\n⚠️  注意：rebuild 只重建骨架。tags/entrypoints/main_symbols/depends_on/used_by 需要重新运行 scan 或手动补充。`);
-  console.log(`ℹ️  schema 已升级到 v2，支持 role/core_files/test_files/entrypoints/depends_on/risk_level/verify_commands 等字段。`);
+  console.log(`\nℹ️  手动维护字段（tags/entrypoints/main_symbols/depends_on/used_by/status/needs_review 等）已全量保留；rebuild 只补缺与增新卡。`);
   return { dryRun: false, path: mapPath, modules: allModuleIds.size }
 }
 

package/src/progress/change-registry.js

@@ -62,6 +62,24 @@ export class ChangeRegistry {
     } catch { return null; }
   }
 
+  /**
+   * 读某变更某阶段的 started_at（2026-09-10 用户反馈②：evidence mtime 窗口锚点从
+   * execute completed_at 放宽到 started_at——证据合法产自 execute 或 verify 两窗口，
+   * 锚「完成时刻」会把 execute 期间产的证据判旧，逼出「先提交则 diff 空、不提交则
+   * mtime 旧」的时序两难）。只读不抛：无行/列空/读失败返回 null（调用方退
+   * getStageCompletedAt → R-05 fallback，与 getStageCompletedAt 同族容错）。
+   */
+  getStageStartedAt(cwd, changeName, stage) {
+    try {
+      const db = this.pm._ensureDB(cwd);
+      const row = db.getDb().prepare(
+        `SELECT s.started_at FROM stages s JOIN changes c ON s.change_id = c.id
+         WHERE c.name = ? AND s.stage = ? ORDER BY s.started_at DESC LIMIT 1`
+      ).get(changeName, stage);
+      return row && row.started_at ? row.started_at : null;
+    } catch { return null; }
+  }
+
   getChangeStage(cwd, changeName) {
     const db = this.pm._ensureDB(cwd);
     const sqlDb = db.getDb();

package/src/progress.js

@@ -10,7 +10,7 @@
  * worktree-guard hook 直读 sillyspec.db，不再有 gate-status.json 缓存双源（task-10 废除）。
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync, realpathSync } from 'fs';
 import { join, basename, dirname, resolve, sep } from 'path';
 import { tmpdir } from 'os';
 import { writeAtomicSync } from './fs-atomic.js';
@@ -159,6 +159,14 @@ export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
       `   修复：sillyspec platform pointer --cleanup（删除 ${pointerPath}），或删除该 pointer 文件后回到项目目录重跑。`
     );
   }
+  // junction 规范化（2026-09-10 驾驭小结第五批①，用户实锤「design-init/endpoints 落盘路径
+  // 偶发锚到 daemon junction 副本」）：daemon 写入的 pointer specRoot 可能是通向真实 spec 根的
+  // junction/symlink 路径——经 junction 读写与真实路径同文件（无害）但路径呈现与比对漂移、
+  // junction 随 daemon 生命周期可能蒸发。realpath 坍缩为真实路径（失败回退原值，保守不干预）。
+  try {
+    const canonical = realpathSync(ptr.specRoot)
+    if (canonical && canonical !== ptr.specRoot) return canonical
+  } catch { /* realpath 失败（权限/竞态删除）→ 原值（上方已过存在性检查） */ }
   return ptr.specRoot;
 }
 
@@ -900,6 +908,10 @@ export class ProgressManager {
   // verifyStartAt 基准只读（2026-09-08-ir-verify-facts）：execute 行 completed_at；无行 null 走 R-05 fallback
   getStageCompletedAt(cwd, changeName, stage) { return this._changeRegistry.getStageCompletedAt(cwd, changeName, stage); }
 
+  // evidence mtime 窗口锚点（2026-09-10 用户反馈②）：execute 行 started_at——证据合法产自 execute
+  // 或 verify 两窗口，锚「完成时刻」会把 execute 期间产的证据判旧（时序两难）；无行 null 走 completed_at → R-05
+  getStageStartedAt(cwd, changeName, stage) { return this._changeRegistry.getStageStartedAt(cwd, changeName, stage); }
+
   registerChange(cwd, changeName) { return this._changeRegistry.registerChange(cwd, changeName); }
 
   updateChangeIsolation(cwd, changeName, isolation) { return this._changeRegistry.updateChangeIsolation(cwd, changeName, isolation); }

package/src/quicklog.js

@@ -155,6 +155,39 @@ function extractRawBlock(content, qlId) {
 
 // 落盘条目块 → 推送 payload（design §5.3：以落盘终态为准，不从入参拼）。
 // 宽松标签解析对齐平台：全半角冒号、多条状态行取最后、文件行单行/多行 bullet。
+/**
+ * QUICKLOG 结构化 sidecar（P1-4，noai-ir-roadmap §4）：completeQuicklogEntry 组装 payload 的
+ * 同时把终态结构落 .runtime/quicklog-sidecar/<qlId>.json——一次解析持久化，daemon/查询/重推
+ * 直读结构化数据不必再解析 md（md 只给人看）。fail-soft：sidecar 是加速层不是正确性依赖，
+ * 落盘失败零阻断（读取侧自动回退 md 解析路径）。
+ */
+const QUICKLOG_SIDECAR_SCHEMA_VERSION = 1
+
+export function quicklogSidecarPath(specBase, qlId) {
+  return join(specBase, '.runtime', 'quicklog-sidecar', `${qlId}.json`)
+}
+
+export function writeQuicklogSidecar(specBase, payload) {
+  if (!payload || !payload.ql_id) return false
+  try {
+    const p = quicklogSidecarPath(specBase, payload.ql_id)
+    mkdirSync(dirname(p), { recursive: true })
+    writeAtomic(p, JSON.stringify({ schemaVersion: QUICKLOG_SIDECAR_SCHEMA_VERSION, ...payload }, null, 2) + String.fromCharCode(10))
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function readQuicklogSidecar(specBase, qlId) {
+  try {
+    const rec = JSON.parse(readFileSync(quicklogSidecarPath(specBase, qlId), 'utf8'))
+    return rec && rec.schemaVersion === QUICKLOG_SIDECAR_SCHEMA_VERSION ? rec : null
+  } catch {
+    return null
+  }
+}
+
 function buildPushPayloadFromRaw(rawBlock, { ql_id, author_raw, status, linked_changes, fallback_title }) {
   const payload = {
     ql_id,
@@ -568,7 +601,7 @@ function splitSingleLineFields(body) {
   return scanFields(body, findBoundaryLabel) ?? scanFields(body, (b, l, f) => b.indexOf(l, f))
 }
 
-function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes = [], auditNotes = []) {
+function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes = [], auditNotes = [], softFiles = []) {
   const lines = content.split('\n')
   const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
   if (startIdx === -1) return null
@@ -591,9 +624,19 @@ function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes
     // 都空则不动（保持「（见实际改动）」）。bullet 用「数组元素内嵌 \n」写——lines.join('\n') 展平为
     // 多行，数组长度不变 → 与下方状态/结果 splice 的索引完全解耦（changedFiles 单行同理原地替换）。
     if (lines[i].startsWith('文件：')) {
+      // 软归属（2026-09-10 用户反馈）：softFiles = 审计判定的「窗口内未声明同模块测试文件」——
+      // 补入文件行 bullet 带括注标记，消每回手工核对；fileNotes 已显式括注的不重复加。
+      // fileNotes 空但有 softFiles 时同样升级 bullet（单行格式放不下括注标记）。
+      const notedPaths = new Set(fileNotes.map((n) => n.path))
+      const softBullets = []
+      for (const f of softFiles) {
+        if (!notedPaths.has(f)) softBullets.push(`- ${f}（软归属·同模块测试，未声明）`)
+      }
       if (fileNotes.length > 0) {
-        const bullets = fileNotes.map((n) => `- ${n.path}${n.note ? `（${n.note}）` : ''}`)
+        const bullets = [...fileNotes.map((n) => `- ${n.path}${n.note ? `（${n.note}）` : ''}`), ...softBullets]
         lines[i] = `文件：\n${bullets.join('\n')}`
+      } else if (softBullets.length > 0) {
+        lines[i] = `文件：\n${[...changedFiles.map((f) => `- ${f}`), ...softBullets].join('\n')}`
       } else if (changedFiles.length > 0) {
         lines[i] = `文件：${changedFiles.join(', ')}`
       }
@@ -775,7 +818,7 @@ export async function appendQuicklogEntryWithId(specBase, gitUser, qlId, { descr
 /**
  * 翻某 qlId 条目为「已完成」+ 追加结果 + 勾选关联 tasks.md。持锁。
  */
-export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultText = '', linkedChanges = [], changedFiles = [], auditNotes = [] } = {}) {
+export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultText = '', linkedChanges = [], changedFiles = [], auditNotes = [], softFiles = [] } = {}) {
   const quicklogDir = join(specBase, 'quicklog')
   // 与 allocateQuicklogEntry 同源消毒：锁文件路径含 user（防穿越写，两入口必须一致否则锁不上同一文件）
   const user = sanitizeQuicklogUser(gitUser) || 'unknown'
@@ -788,6 +831,11 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
   // 读后即清（per-process，防残留跨调用）。flipEntryInContent 优先用 fileNotes，空则回退 realFiles。
   const fileNotes = parseFileNotes(_pendingFileNotes)
   _pendingFileNotes = ''
+  // 软归属文件（complete-handlers 传入，已过 isQuickMetadata；反斜杠归一与 fileNotes 同口径）：
+  // 窗口内未声明同模块测试文件，flipEntryInContent 补入文件行 bullet 带「软归属」括注。
+  const soft = Array.isArray(softFiles)
+    ? softFiles.filter(Boolean).map((f) => String(f).replace(/\\/g, '/'))
+    : []
 
   await withFileLock(lockPath, async () => {
     // 条目可能在主文件或轮转归档中
@@ -798,7 +846,7 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
       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() !== '') : [])
+        Array.isArray(auditNotes) ? auditNotes.filter((n) => typeof n === 'string' && n.trim() !== '') : [], soft)
       if (updated !== null) {
         await writeAtomic(filePath, updated) // 命中处原子落盘（只改含目标条目的那一个文件）
         updatedContent = updated
@@ -812,12 +860,15 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
     // （design §5.3：翻完成时标题行被 extractTitleFromResult 刷新，推送须与落盘一致，
     // 不能用入参拼——标题/结果块/文件行都会在 flipEntryInContent 中重写）。
     const rawBlock = extractRawBlock(updatedContent, qlId)
-    await pushQuicklogEntryToPlatform(specBase, buildPushPayloadFromRaw(rawBlock, {
+    const finalPayload = buildPushPayloadFromRaw(rawBlock, {
       ql_id: qlId,
       author_raw: user,
       status: 'completed',
       linked_changes: linked,
-    })).catch(() => {})
+    })
+    // P1-4：终态结构 sidecar 持久化（同一解析器产出，md/sidecar 恒一致；fail-soft）
+    writeQuicklogSidecar(specBase, finalPayload)
+    await pushQuicklogEntryToPlatform(specBase, finalPayload).catch(() => {})
   })
 }
 
@@ -895,6 +946,9 @@ export async function cancelQuickSession({ specBase, gitUser, qlId, sessionId =
         // 会产出 \r\r\n 字节级污染（git diff 全文件红）；原子写防 agent/dashboard 轮询读半截
         const eol = content.includes('\r\n') ? '\r\n' : '\n'
         await writeAtomic(p, lines.join(eol))
+        // P1-4：sidecar 同步翻「已取消」（无 sidecar 的存量条目跳过——md 仍是真相源）
+        const _sc = readQuicklogSidecar(specBase, qlId)
+        if (_sc) writeQuicklogSidecar(specBase, { ..._sc, status: '已取消' })
       }
       break
     }