sillyspec 3.29.4 → 3.29.5

package/src/init.js

@@ -5,6 +5,7 @@ import { checkbox, confirm, input } from '@inquirer/prompts';
 import { ProgressManager } from './progress.js';
 import chalk from 'chalk';
 import { getVersion } from './version.js';
+import { injectCommandCards } from './command-cards.js';
 import { gitQuiet } from './git-helper.js';
 import { renderExample } from './config-schema.js';
 // 向后兼容：getVersion 已抽到轻量 version.js（避免 index.js 为 --version 静态加载 init.js 的 inquirer 税），
@@ -76,10 +77,11 @@ function copyDirSync(src, dst) {
 
 
 
-const VALID_TOOLS = ['claude', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
+const VALID_TOOLS = ['claude', 'zcode', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
 
 const TOOL_LABELS = {
   claude: 'Claude Code',
+  zcode: 'ZCode',
   cursor: 'Cursor',
   openclaw: 'OpenClaw',
   codex: 'OpenAI Codex (通过 AGENTS.md)',
@@ -288,14 +290,17 @@ function isTTY() {
 
 // ── 核心安装逻辑 ──
 
-function doInstall(projectDir, tools, subprojects = [], specDir = null, options = {}) {
+async function doInstall(projectDir, tools, subprojects = [], specDir = null, options = {}) {
   // specDir: 规范目录（默认 projectDir/.sillyspec）
   // projectDir: 源码项目根目录（用于工具检测、指令注入、.gitignore）
   // options.noSkills: 跳过 skills 复制段（--no-skills；指令注入不受影响）
   // options.platformMode: 平台模式（cmdInit 收到 platformOpts 非空）——项目内 .sillyspec/
   //   通常只有 local.yaml（平台 init lease 写、含用户手调 mcp 段），任何清理都会丢失，整体跳过
-  const { noSkills = false, platformMode = false } = options;
+  const { noSkills = false, platformMode = false, forceCards = false } = options;
   const spec = specDir || join(projectDir, '.sillyspec');
+  // 命令卡工具面（2026-09-21-flow-command-cards）：仅 zcode/claude 有落点（D-003）；
+  // noSkills/platformMode 与 skills 同门跳过（Grill P2-4）
+  const cardTools = noSkills || platformMode ? [] : tools.filter((t) => t === 'zcode' || t === 'claude');
 
   // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
   // ⚠️ 必须保护真实资产：若本地 .sillyspec 含 changes/（非空）、projects/（非空）
@@ -443,11 +448,23 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null, options
     }
   }
 
-  // 注入 AGENTS.md 完整指引（claude/codex 共用：版本感知幂等三态四分支 + 旧 ## SillySpec 段迁移）
-  if (tools.includes('claude') || tools.includes('codex')) {
+  // 注入 AGENTS.md 完整指引（claude/codex/zcode 共用：版本感知幂等三态四分支 + 旧 ## SillySpec 段迁移；
+  // zcode 2026-09-21-flow-command-cards FR-05 入面——AGENTS.md 是跨工具通用标准内容源）
+  if (tools.includes('claude') || tools.includes('codex') || tools.includes('zcode')) {
     injectAgentsInstructions(projectDir);
   }
 
+  // 流程命令卡注入（2026-09-21-flow-command-cards：zcode→.zcode/commands/sillyspec/、claude→.claude/commands/sillyspec/；
+  // 尾部锚行三态幂等。与 skills 复制同门：noSkills/platformMode 跳过（工具目录零污染语义，Grill P2-4）；
+  // 挂点在 noSkills return 之前——卡与 AGENTS.md 同批，早于 skills 复制不影响）
+  if (cardTools.length > 0) {
+    const cards = await injectCommandCards(projectDir, { tools: cardTools, force: forceCards, version: getVersion() });
+    for (const w of cards.warnings) console.warn(`    ⚠️ [命令卡] ${w}`);
+    if (cards.written.length + cards.updated.length > 0) {
+      console.log(chalk.green(`    ✓ 流程命令卡已${cards.written.length ? '生成' : '更新'} ${cards.written.length + cards.updated.length} 张 → ${cardTools.map((t) => (t === 'zcode' ? '.zcode' : '.claude') + '/commands/sillyspec/').join(' + ')}`));
+    }
+  }
+
   // 注入 CLAUDE.md 指针（claude 专属：@AGENTS.md 导入薄文件，须在 AGENTS.md 之后）
   if (tools.includes('claude')) {
     injectClaudePointer(projectDir);
@@ -546,7 +563,7 @@ function showSummary(version, tools, specDir) {
 // ── 主命令 ──
 
 export async function cmdInit(projectDir, options = {}) {
-  const { tool, tools: toolsOpt, interactive, specDir, noSkills = false, platformOpts = null } = options;
+  const { tool, tools: toolsOpt, interactive, specDir, noSkills = false, forceCards = false, platformOpts = null } = options;
   const version = getVersion();
   const resolvedSpecDir = specDir ? resolve(specDir) : null;
 
@@ -654,7 +671,7 @@ export async function cmdInit(projectDir, options = {}) {
     }
 
     console.log('');
-    await doInstall(projectDir, selectedTools, subprojects, resolvedSpecDir, { noSkills, platformMode: platformOpts != null });
+    await doInstall(projectDir, selectedTools, subprojects, resolvedSpecDir, { noSkills, forceCards, platformMode: platformOpts != null });
     writeInitPlatformPointer(projectDir, resolvedSpecDir, platformOpts);
     showSummary(version, selectedTools, resolvedSpecDir);
     return;
@@ -682,7 +699,7 @@ export async function cmdInit(projectDir, options = {}) {
     tools = detectTools(projectDir);
   }
 
-  await doInstall(projectDir, tools, [], resolvedSpecDir, { noSkills, platformMode: platformOpts != null });
+  await doInstall(projectDir, tools, [], resolvedSpecDir, { noSkills, forceCards, platformMode: platformOpts != null });
   writeInitPlatformPointer(projectDir, resolvedSpecDir, platformOpts);
 
   console.log('');

package/src/machine-interface.js

@@ -15,7 +15,7 @@
  * 仅依赖 Node 18+ 原生 API，零新增外部依赖。
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { ProgressManager, resolveSpecDir } from './progress.js';
 import { resolveRuntimeRoot } from './run/shared.js';
@@ -25,7 +25,6 @@ import { runVerifyTestCheck } from './verify-postcheck.js';
 import { checkCode } from './diagnostic-codes.js';
 
 // ============ 退出码常量（D-004@v1）============
-
 export const EXIT_OK = 0;          // 核验通过（可含 warnings）
 export const EXIT_BLOCKED = 1;     // 事实性阻断（JSON 含 errors）
 export const EXIT_UNKNOWN = 2;     // 无法核验（用法错/变更不存在/环境错/内部异常）
@@ -295,8 +294,9 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
         vtWarnings.push(`⚠️ verify-test SKIPPED — gate 未核验测试（${vt.reason || 'local.yaml 未配置 commands.test 或显式无测试'}）。本次 gate 结论不含测试客观核验，driver 不应据 exit 0 判定测试通过；integration-critical 变更应在 verify 阶段降级 FAIL`);
       }
       // known_failures 豁免披露：本次 PASS 含豁免，driver 应提示人工复核清单是否过宽
+      // （quick-E，2026-09-20 报告问题 E：提示原不带清单位置，复核要先翻一遍才找到——带路径）
       if (vt.exemptedCount > 0) {
-        vtWarnings.push(`⚠️ verify-test PASS 含 ${vt.exemptedCount} 个 known_failures 豁免（${vt.reason || ''}）；driver 应提示人工复核豁免清单是否过宽（避免误豁免本变更引入的真实失败）`);
+        vtWarnings.push(`⚠️ verify-test PASS 含 ${vt.exemptedCount} 个 known_failures 豁免（${vt.reason || ''}）；driver 应提示人工复核豁免清单是否过宽（避免误豁免本变更引入的真实失败）——清单位置：${join(specRoot, 'local.yaml')} 的 known_failures 键`);
       }
       // 全量 fallback 明示：跑了全量 commands.test 但非变更范围子集，失败可能含未变更
       // 模块的预存错误——driver 不应据 exit 0 判定本次变更范围已客观测试（见 3.24 verify 坑1）。
@@ -318,6 +318,64 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
           fallbackReason: vt.fallbackReason ?? null,
         },
       });
+
+      // ── d2. verify-lint（parity 补齐，2026-09-21 R4-S-F 实证）──
+      // gate verify 原先只查 test 不查 lint，而 verify --done 的 lint 隔离快照门会拦——
+      // gate PASS / --done FAIL 两套口径并存，误导 agent 诊断 16 分钟（对撞会话 db 实证）。
+      // 本检查与 --done 同引擎（runVerifyLintCheck + triageLintOwnership 归属降档）；口径差异
+      // 永久明示：gate 在工作树直跑 lint，--done 在隔离快照（HEAD+归属文件 overlay）跑——
+      // 不一致时以 --done 为准。lint 未配置/不可跑 → informational，不阻断只读查询。
+      try {
+        const { runVerifyLintCheck, triageLintOwnership, resolveVerifyChangedFiles } = await import('./verify-postcheck.js');
+        const lc = runVerifyLintCheck({ cwd, specBase: specRoot });
+        if (lc.status === 'skipped') {
+          checks.push({
+            id: 'verify-lint',
+            code: checkCode('verify-lint'),
+            ok: true,
+            informational: true,
+            warnings: [`verify-lint SKIPPED — ${lc.reason || 'local.yaml 未配置 commands.lint'}；本次 gate 结论不含 lint 客观核验`],
+            data: { status: lc.status },
+          });
+        } else {
+          const lcWarnings = [
+            '口径说明：gate verify 的 lint 在工作树直跑；verify --done 的 lint 在隔离快照（HEAD+归属文件 overlay）跑——两口径不一致时以 --done 为准。',
+          ];
+          let ownership = null;
+          let lintOk = lc.status !== 'failed';
+          if (lc.status === 'failed') {
+            const changed = resolveVerifyChangedFiles(cwd, changeName, null, { specBase: specRoot }) || [];
+            ownership = triageLintOwnership({ failureFiles: lc.failureFiles || [], changeFiles: changed });
+            if (ownership.verdict === 'pre-existing') {
+              lintOk = true; // 存量债不拦只读查询（与 --done 的 advisory 降档同口径）
+              lcWarnings.push('lint 失败文件与本变更零交集（HEAD 存量债）→ 本 check 降档放行；--done 同口径 advisory，建议顺手清偿解锁全仓 lint 门。');
+            }
+          }
+          checks.push({
+            id: 'verify-lint',
+            code: checkCode('verify-lint'),
+            ok: lintOk,
+            errors: !lintOk ? [`lint 失败（工作树口径）: ${lc.reason || ''}`] : [],
+            warnings: lcWarnings,
+            data: {
+              status: lc.status,
+              exitCode: lc.exitCode,
+              durationMs: lc.durationMs,
+              ownership: ownership ? ownership.verdict : null,
+              overlap: ownership ? ownership.overlap : [],
+            },
+          });
+        }
+      } catch (e) {
+        checks.push({
+          id: 'verify-lint',
+          code: checkCode('verify-lint'),
+          ok: true,
+          informational: true,
+          warnings: [`verify-lint 检查装配失败（fail-open）: ${e && e.message ? e.message : e}`],
+          data: { status: 'error' },
+        });
+      }
     }
 
     // ── 综合结论：所有非 informational check 均 ok ──
@@ -667,3 +725,30 @@ export function runStatusOverview({ cwd, specBase } = {}) {
     return { envelope, exitCode: EXIT_UNKNOWN };
   }
 }
+
+// ============ gate 失败明细稳定路径落盘（quick-D，2026-09-20 报告问题 D）============
+
+/**
+ * `sillyspec gate <stage> --change <name>` 的失败信封落盘（稳定路径，每次覆盖）。
+ * 背景：gate 失败明细只在 stdout——宿主把长命令转后台截断输出后 ❌ 段落实际取不回
+ * （2026-09-20 实证：agent 靠推断绕 3 轮）。runGate 本体保持只读契约（D-002@v1，不写
+ * sillyspec.db），落盘由本函数承担（CLI 层调用，fail-soft）——审计附件非状态。
+ * @param {{ specBase: string, stage: string, changeName: string, envelope: object }} opts
+ * @returns {string|null} 成功返回落盘路径；失败返回 null
+ */
+export function writeGateResultArtifact({ specBase, stage, changeName, envelope }) {
+  try {
+    const runsDir = join(specBase, '.runtime', 'verify-runs')
+    const resultPath = join(runsDir, `gate-${stage}-${changeName}.json`)
+    mkdirSync(runsDir, { recursive: true })
+    writeFileSync(resultPath, JSON.stringify({
+      written_at: new Date().toISOString(),
+      stage,
+      change: changeName,
+      envelope,
+    }, null, 2) + '\n')
+    return resultPath
+  } catch {
+    return null // fail-soft：落盘是审计附件，失败只缺附件不误门
+  }
+}

package/src/module-impact.js

@@ -48,7 +48,15 @@ export function parseModuleMapPaths(yamlText) {
     }
     if (inPaths && currentModule) {
       const item = line.match(/^      - (.+)$/)
-      if (item) map.get(currentModule).push(item[1].trim().replace(/\\/g, '/'))
+      if (item) {
+        // 引号剥离（坑 map-quoted-path-deadmatch，2026-09-21 R4-L 实证）：docs/<p>/modules/
+        // _module-map.yaml 存在带引号条目（"frontend/src/app/page.tsx"）——只 trim 不剥引号时
+        // classifyFile 的 === / startsWith 恒失配，引号条目全是死路径（frontend map 790 条
+        // 几乎全带引号＝整图失效）。仅首尾成对引号才剥（路径内部引号不动）。
+        const raw = item[1].trim()
+        const unquoted = raw.replace(/^(['"])([\s\S]*)\1$/, '$2')
+        map.get(currentModule).push(unquoted.replace(/\\/g, '/'))
+      }
     }
   }
   return map
@@ -89,18 +97,33 @@ export function syncModuleDocSidecars({ cwd, changeName, note, specDir = null })
   // 复用 generateModuleImpactSkeleton 的 map 发现 + 归类（diff 来源）
   const skel = generateModuleImpactSkeleton({ cwd, changeName, specDir })
   if (!skel) return { synced: [], unmatched: [], skipped: [], reason: '无 module-map 或无 diff 可归类' }
-  const modulesDir = findModulesDir(specBase)
-  if (!modulesDir) return { synced: [], unmatched: [], skipped: [], reason: 'modules 目录不存在' }
-  // 从骨架 markdown 反解归类结果（命中模块集合 + 未匹配清单）
-  const hitModules = [...skel.markdown.matchAll(/^\| (\S+) \| `([^`]+)`/gm)].map(m => m[1])
-  const unmatched = [...skel.markdown.matchAll(/^- `([^`]+)` /gm)].map(m => m[1])
+  // 结构化归类直用（classified 含 project 归属；multimap-first-found-mismatch 同坑修复面）——
+  // 不再反解 markdown（正则脆且丢 project 维度）。classified 缺席时兜底反解 + 首个 modules 目录。
+  let mods = []
+  if (Array.isArray(skel.classified) && skel.classified.length >= 0) {
+    const seen = new Set()
+    for (const r of skel.classified) {
+      const key = r.project + '/' + r.module
+      if (seen.has(key)) continue
+      seen.add(key)
+      mods.push({ project: r.project, module: r.module, modulesDir: join(specBase, 'docs', r.project, 'modules') })
+    }
+  } else {
+    const modulesDir = findModulesDir(specBase)
+    if (!modulesDir) return { synced: [], unmatched: [], skipped: [], reason: 'modules 目录不存在' }
+    mods = [...new Set([...skel.markdown.matchAll(/^\| (\S+) \| `([^`]+)`/gm)].map(m => m[1]))]
+      .map(mod => ({ project: null, module: mod, modulesDir }))
+  }
+  const unmatched = Array.isArray(skel.unmatchedFiles)
+    ? skel.unmatchedFiles
+    : [...skel.markdown.matchAll(/^- `([^`]+)` /gm)].map(m => m[1])
   const synced = []
   const skipped = []
-  for (const mod of [...new Set(hitModules)]) {
+  for (const { project: proj, module: mod, modulesDir } of mods) {
     const sidecarPath = join(modulesDir, `${mod}.changelog.md`)
     let sidecar = ''
     try { sidecar = readFileSync(sidecarPath, 'utf8') } catch { sidecar = '' }
-    if (sidecar.includes(`- ${changeName} |`)) { skipped.push(mod); continue }
+    if (sidecar.includes(`- ${changeName} |`)) { skipped.push(proj ? `${proj}/${mod}` : mod); continue }
     const NL = String.fromCharCode(10)
     const line = `- ${changeName} | ${note || '(见该变更 quicklog/归档)'}`
     const base = sidecar
@@ -114,7 +137,7 @@ export function syncModuleDocSidecars({ cwd, changeName, note, specDir = null })
       const stamped = card.replace(/^updated_at:.*$/m, `updated_at: ${new Date().toISOString().slice(0, 19) + '+08:00'}`)
       if (stamped !== card) writeFileSync(cardPath, stamped)
     } catch { /* 卡不存在——sidecar 照写，卡内容留给 agent */ }
-    synced.push(mod)
+    synced.push(proj ? `${proj}/${mod}` : mod)
   }
   return { synced, unmatched, skipped }
 }
@@ -133,22 +156,22 @@ function findModulesDir(specBase) {
 export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null, sourceFiles = null, origin = null }) {
   const specBase = resolveSpecDir(cwd, { specDir })
 
-  // 找 _module-map.yaml（docs/<p>/modules/；多项目取首个含 modules 索引的）
-  let moduleMapPath = null
+  // 多项目 map 联合归类（坑 multimap-first-found-mismatch，2026-09-21 R4-L 实证）：docs/ 下
+  // 各项目可各带 _module-map.yaml（对撞仓 5 个），原「取首个命中」让 daemon/frontend 文件对
+  // 按目录序排前的 backend map 全失配——24 文件全未匹配、sidecar 也写错项目目录。联合口径：
+  // 逐项目 classify、目录序首个命中 wins（单项目时联合退化为一图，行为不变）。
+  const moduleMaps = []
   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
+        const pm = parseModuleMapPaths(readFileSync(candidate, 'utf8'))
+        if (pm.size > 0) moduleMaps.push({ project: p.name, modulePaths: pm })
       }
     }
   } catch { /* 无 docs/ */ }
-  if (!moduleMapPath) return null
-
-  const modulePaths = parseModuleMapPaths(readFileSync(moduleMapPath, 'utf8'))
-  if (modulePaths.size === 0) return null
+  if (moduleMaps.length === 0) return null
 
   let sourceFileList
   if (sourceFiles) {
@@ -169,12 +192,18 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null,
   if (sourceFileList.length === 0) return null
 
   const byModule = new Map()
+  const classified = [] // {project, module, file}——syncModuleDocSidecars 按 project 落 sidecar 用
   const unmatched = []
   for (const f of sourceFileList) {
-    const mod = classifyFile(f, modulePaths)
-    if (mod) {
-      if (!byModule.has(mod)) byModule.set(mod, [])
-      byModule.get(mod).push(f)
+    let hit = null
+    for (const m of moduleMaps) {
+      const mod = classifyFile(f, m.modulePaths)
+      if (mod) { hit = { project: m.project, moduleId: mod }; break }
+    }
+    if (hit) {
+      if (!byModule.has(hit.moduleId)) byModule.set(hit.moduleId, [])
+      byModule.get(hit.moduleId).push(f)
+      classified.push({ project: hit.project, module: hit.moduleId, file: f })
     } else {
       unmatched.push(f)
     }
@@ -234,5 +263,5 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null,
   L.push('规则：execute/verify 完成文档同步后把对应行回填 done；确定不同步的行改 skipped 并在操作列写明原因。')
   L.push('')
 
-  return { markdown: L.join('\n'), matchedCount: sourceFileList.length - unmatched.length, unmatchedCount: unmatched.length }
+  return { markdown: L.join('\n'), matchedCount: sourceFileList.length - unmatched.length, unmatchedCount: unmatched.length, classified, unmatchedFiles: unmatched }
 }

package/src/run/command.js

@@ -511,6 +511,10 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         console.error(`❌ 检测到祖先链有 ${ancestorSpecs.length} 个 .sillyspec 实例(monorepo 多实例)，当前使用: ${specBase}`)
         console.error(`   当前 cwd 不在 git 顶层仓库根下，静默绑定到子项目实例会导致进度/QUICKLOG 分裂。`)
         console.error(`   修复：cd 回项目根目录，或用 --spec-dir <根>/.sillyspec 显式指定。`)
+        // 一键指定整行（R4-S-Q 实证：嵌套 worktree 场景下 agent 多次试错才拼对放行组合）——
+        // 意图实例即当前最近命中（specBase），直接给出可贴完整命令行。
+        console.error(`   一键指定（当前最近实例，整行照贴）：`)
+        console.error(`   sillyspec ${process.argv.slice(2).join(' ')} --spec-dir "${specBase}"`)
         process.exit(2)
       }
       // 在 git 根下但有多实例(子项目也有 .sillyspec)→ 仅警告(正确实例已命中)

package/src/run/complete-handlers.js

@@ -1265,6 +1265,25 @@ export async function handleWorkflowPostCheck({ stageName, steps, currentIdx, cw
   }
   return null
 }
+/**
+ * guard.linkedChanges/linkedChangesAuto 并入 --done 显式声明（R4-S-Q 缺陷 B 纯函数核）：
+ * 持久化值 ∪ 显式值（去重保序，persisted 在前）；显式 ['none'] 语义为清空 manual 面（auto 不动）；
+ * 无变化返回原对象引用（调用点以此判「是否需要回写」）。guard 非对象原样返回。
+ */
+export function mergeGuardLinkedChanges(guard, explicitLinked, explicitAuto) {
+  if (!guard || typeof guard !== 'object') return guard
+  const cur = Array.isArray(guard.linkedChanges) ? guard.linkedChanges : []
+  const curAuto = Array.isArray(guard.linkedChangesAuto) ? guard.linkedChangesAuto : []
+  const ex = (Array.isArray(explicitLinked) ? explicitLinked : []).filter(Boolean)
+  const exAuto = (Array.isArray(explicitAuto) ? explicitAuto : []).filter(Boolean)
+  const next = ex.length === 1 && ex[0] === 'none' ? [] : [...new Set([...cur, ...ex])]
+  const nextAuto = exAuto.length === 0 ? curAuto : [...new Set([...curAuto, ...exAuto])]
+  const unchanged = next.length === cur.length && next.every((v, i) => v === cur[i])
+    && nextAuto.length === curAuto.length && nextAuto.every((v, i) => v === curAuto[i])
+  if (unchanged) return guard
+  return { ...guard, linkedChanges: next, linkedChangesAuto: nextAuto }
+}
+
 /**
  * quick 阶段完成收尾（W6 Step6b 从 completeStep 内联块抽出）：
  * 强校验 QUICKLOG 条目 + 审计（auditQuickCompletion）+ 结果摘要结构校验 + 翻状态/勾 tasks.md
@@ -1274,7 +1293,7 @@ export async function handleWorkflowPostCheck({ stageName, steps, currentIdx, cw
  * isForceBaseline/isAllowNew/platformOpts。辅助函数直接 import（safeGit/auditQuickCompletion ← shared，
  * printQuickAuditReview ← quick-audit，4 个 quicklog fns ← quicklog，unlinkSync/rmSync ← fs 静态）。
  */
-export async function handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag = null, platformOpts, pm, quickFiles = [] }) {
+export async function handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag = null, platformOpts, pm, quickFiles = [], linkedChanges = [], linkedChangesAuto = [] }) {
   // quick 收尾：强校验 QUICKLOG 条目 + 翻状态 + 勾 tasks.md（CLI 接管）
   if (stageName === 'quick') {
     // §4.6 从 session guard.json 读 guard（不依赖 progress.quickGuard）。
@@ -1293,6 +1312,22 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
     } catch {}
 
+    // R4-S-Q 缺陷 B：--done 时显式 --linked-changes 并入 guard（启动持久化值 ∪ 本次显式值，
+    // 'none' 清空）再回写 sessionGuardFile。下游关账 closeQuickLinkedChanges / 资产尾蒸馏 /
+    // quicklog「关联变更」渲染全读 guard——不并入则 --done 时声明的关联被静默丢弃（R4-S-Q
+    // 实测：--linked-changes 两次都在命令行上，资产尾零触发 + 条目渲染「（无）」）。
+    // guard 缺失（brownfield）不造对象——保持 D-3 无 guard 降级语义不变。
+    try {
+      if (guard && (linkedChanges.length > 0 || linkedChangesAuto.length > 0)) {
+        const merged = mergeGuardLinkedChanges(guard, linkedChanges, linkedChangesAuto)
+        if (merged !== guard) {
+          guard = merged
+          writeAtomicSync(sessionGuardFile, JSON.stringify(guard, null, 2))
+          console.log(`🔗 --done 显式关联变更已并入 guard: ${(guard.linkedChanges ?? []).join(', ') || '（none 清空）'}`)
+        }
+      }
+    } catch { /* 并入/回写失败不拦完成，guard 内存原值兜底 */ }
+
     // 强校验 / 收尾：本会话必须有一条真实 QUICKLOG 条目（治「报 SAFE 但漏写」bug）。
     // guard 缺失（brownfield：新代码前启动的会话）不阻断——兜底补写一条记录，保住「完成必有记录」不变量。
     const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'

package/src/run/complete.js

@@ -120,7 +120,7 @@ export function synthesizeStepOutput({ stageName, stepName, cwd }) {
 }
 
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
-  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, isNoDocs = false, isSkipApply = false, sessionFlag = null, quickFiles = [] } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, isNoDocs = false, isSkipApply = false, sessionFlag = null, quickFiles = [], linkedChanges = [], linkedChangesAuto = [] } = options
   // specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)——
   // 与 prompt.js resolvePromptSpecBase 同序：--done 收尾的 user-inputs.md/超长 artifact 落盘
   // 必须与 prompt 渲染同一根，否则写进 worktree 副本目录、随 cleanup 整目录删除。
@@ -619,8 +619,11 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     }
     // quick 收尾（W6 Step6b 抽至 complete-handlers.js handleQuickStageCompletion）；
     // isNoDocs（task-02）--no-docs 豁免随链透传进 auditQuickCompletion options；
-    // sessionFlag（task-03）--session 随链透传进 quick 轻量归档链所有权校验
-    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag, platformOpts, pm, quickFiles })
+    // sessionFlag（task-03）--session 随链透传进 quick 轻量归档链所有权校验；
+    // linkedChanges/linkedChangesAuto（R4-S-Q 缺陷 B）：--done 时显式 --linked-changes 随链透传——
+    // 完成侧 guard 从落盘文件读，不接 opts 会静默丢弃 --done 时声明的关联（蒸馏尾/quicklog
+    // 关联变更行/closeQuickLinkedChanges 三处消费同断）
+    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag, platformOpts, pm, quickFiles, linkedChanges, linkedChangesAuto })
 
     // ── reopen --done 回填（坑 brainstorm-reopen-step-state-desync）──
     // nextPendingIdx === -1 且无 waiting，说明要进阶段完成分支。此时若存在 stale 步骤

package/src/run/gate-snapshot.js

@@ -389,15 +389,21 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     // 两份都变于祖先且互不相等（真双写分叉）→ 显式警告 + 取 cwd（主仓直写=本会话最新编辑位约定）。
     // 行尾归一（坑 autocrlf-byte-misjudge）：本机 autocrlf=true 时快照 checkout 是 CRLF、
     // 工作区文件常是 LF——字节直比会误判「两边都改」。比较一律 CRLF→LF 归一后做。
+    // 对称 trim（坑 gate-snapshot-ancestor-trim，2026-09-20 taskcard-yaml-hardgate verify 实证）：
+    // git() 助手对全部输出 .trim()（rev-parse 场景需要），git show 的祖先内容因此被剥掉尾换行——
+    // 与磁盘读取（仅 CRLF 归一）不对称，已存在文件恒 anc!==cwd 误判「双写分叉」取主仓旧版，
+    // worktree 交付的修改进不了 verify 门快照→门假红（新文件因主仓不存在幸免）。比较三侧
+    // 统一 normalizeEol+trim 同口径——首尾空白差异不参与分叉判定（语义修改不会只差首尾空白）。
     const normalizeEol = (buf) => String(buf).replace(/\r\n/g, '\n')
+    const cmpText = (t) => normalizeEol(t).trim()
     const headFileContent = (rel) => {
       if (mergeBase) {
         try {
           const anc = git(cwd, ['show', `${mergeBase}:${rel}`])
-          if (typeof anc === 'string') return normalizeEol(anc)
+          if (typeof anc === 'string') return cmpText(anc)
         } catch { /* 祖先无此文件（新增文件）→ 落到快照 HEAD 口径 */ }
       }
-      try { return normalizeEol(readFileSync(join(snapshotRoot, rel))) } catch { return null }
+      try { return cmpText(readFileSync(join(snapshotRoot, rel))) } catch { return null }
     }
     for (const f of files) {
       const isSillyspecRuntime = typeof f === 'string' && (f.startsWith('.sillyspec/.runtime/') || f.startsWith('.sillyspec/quicklog/') || f === '.sillyspec/local.yaml' || f === '.sillyspec/.sillyspec-platform.json')
@@ -407,8 +413,8 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
         const wtPath = join(sourceRoot, f), cwdPath = join(cwd, f)
         if (existsSync(wtPath) && existsSync(cwdPath)) {
           let wtText = null, cwdText = null
-          try { wtText = normalizeEol(readFileSync(wtPath)) } catch { /* 读失败不介入 */ }
-          try { cwdText = normalizeEol(readFileSync(cwdPath)) } catch { /* 读失败不介入 */ }
+          try { wtText = cmpText(readFileSync(wtPath)) } catch { /* 读失败不介入 */ }
+          try { cwdText = cmpText(readFileSync(cwdPath)) } catch { /* 读失败不介入 */ }
           if (wtText !== null && cwdText !== null && wtText !== cwdText) {
             const base = headFileContent(f)
             const wtDiff = base === null || wtText !== base