sillyspec 3.28.3 → 3.28.5

package/src/run/command.js

@@ -20,13 +20,13 @@
  *     './run/stage.js' → './shared.js' 等同级
  */
 import { basename, join, resolve, dirname } from 'node:path'
-import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync, unlinkSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, ancestorSpecDirs, resolveAncestorCeiling, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, resolveQuickSessionsDir, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, ancestorSpecDirs, resolveAncestorCeiling, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, resolveQuickSessionsDir, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, isTempResidueSpecRoot, PLATFORM_MANAGED_FILENAME, warnSelfRefPointerOnce } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
-import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
+import { completeStep, skipStep, waitStep, continueStep, synthesizeStepOutput } from './complete.js'
 import { runStage } from './stage.js'
 import { sanitizeDesc } from '../quicklog.js'
 import { ProgressManager } from '../progress.js'
@@ -100,11 +100,18 @@ export function looksLikeMsysMangledPath(v) {
 /**
  * MSYS 污染告警出口：命中嗅探时向 stderr 打 flag 名 + 值前缀 + 修复指引（不阻断）。
  */
-function warnMsysMangledFlag(flag, value) {
+function warnMsysMangledFlag(flag, value, { block = false } = {}) {
   if (!looksLikeMsysMangledPath(value)) return
-  console.error(`⚠️ ${flag} 的值疑似被 Git Bash(MSYS) 路径转换污染：「${value.slice(0, 60)}${value.length > 60 ? '…' : ''}」`)
-  console.error('   以 / 开头的文案在 Git Bash 下会被展开成 <Git 安装目录>/… 绝对路径后才传入 CLI。')
-  console.error('   非本意 → 去掉前导 / 或改写表述后重发本命令；确需原样 → 命令前加 MSYS_NO_PATHCONV=1。')
+  const head = `⚠️ ${flag} 的值疑似被 Git Bash(MSYS) 路径转换污染：「${value.slice(0, 60)}${value.length > 60 ? '…' : ''}」`
+  const fix = '   以 / 开头的文案在 Git Bash 下会被展开成 <Git 安装目录>/… 绝对路径后才传入 CLI。\n   非本意 → 去掉前导 / 或改写表述后重发本命令；确需原样 → 命令前加 MSYS_NO_PATHCONV=1。'
+  // 2026-09-09 ql-20260909-003（轮次经济学 §3.4）：--output/--input 携带落盘语义（标题/正文
+  // 会写进 QUICKLOG），warn 会被忽略继续落脏标题——升 exit 2 阻断；其余调用点维持 warn。
+  if (block) {
+    console.error(head + '\n' + fix + '\n   已阻断：修复后重发本命令（进度未推进，无重跑代价）。')
+    process.exit(2)
+  }
+  console.error(head)
+  console.error(fix)
 }
 
 /**
@@ -260,6 +267,13 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     process.exit(2) // 用法错 → exit 2
   }
 
+  // P1-3（noai-ir-roadmap §4）：--meta → 本次调用渲染 SS-META 机器块（prompt.js outputStep
+  // 读 SILLYSPEC_RUN_META）。CLI 是短进程：env 只在本进程生命周期内有效，不跨调用泄漏；
+  // auto 模式本就恒渲染（autoMeta 路径不变），--meta 对常规模式补齐同款出口。
+  if (flags.includes('--meta')) {
+    process.env.SILLYSPEC_RUN_META = '1'
+  }
+
   if (!stageRegistry[stageName] && stageName !== 'auto') {
     console.error(`❌ 未知阶段: ${stageName}`)
     console.error(`可选: ${Object.keys(stageRegistry).join(', ')}, auto`)
@@ -388,7 +402,9 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         // 忽略恢复（specRoot/runtimeRoot/workspaceId/scanRunId 全不回填，platformOpts 保持
         // 无平台参数状态），按本地模式运行——内置 sync 走本地链路，specRoot 保持本地取值链。
         if (isSelfReferentialSpecRoot(cwd, saved.specRoot)) {
-          console.warn(`⚠️ 检测到自指平台指针（repo-native junction 回环，specRoot 指回本地 .sillyspec），已忽略并按本地模式运行: ${platformOptsFile}`)
+          // 跨进程窗口降频（2026-09-10 驾驭小结第五批①）：daemon junction 形态下每命令命中的重复噪音
+          warnSelfRefPointerOnce(cwd, saved.specRoot,
+            `⚠️ 检测到自指平台指针（repo-native junction 回环，specRoot 指回本地 .sillyspec），已忽略并按本地模式运行: ${platformOptsFile}（10 分钟内不重复提示）`)
         } else {
           if (saved.specRoot) platformOpts.specRoot = saved.specRoot
           if (saved.runtimeRoot) platformOpts.runtimeRoot = saved.runtimeRoot
@@ -427,6 +443,15 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       // .sillyspec，无跨库状态分裂风险；非自指声明维持 fail-closed 原样（状态保护阻断）。
       if (isSelfReferentialSpecRoot(cwd, decl.specRoot)) {
         console.warn(`⚠️ 检测到陈旧的自指平台接管声明（repo-native junction 回环，原 specRoot 指回本地 .sillyspec），已降级并按本地模式运行；可 sillyspec platform disconnect 清理残留声明: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+      } else if (isTempResidueSpecRoot(cwd, decl.specRoot)) {
+        // temp 残留降级（2026-09-08 temp 投毒治理，与入口一 resolvePlatformSpecDir 同源
+        // 判定）：声明 specRoot 在系统 temp 且 cwd 不在 temp → 可证伪的测试/联调残留。
+        // 与自指降级不同点：直接自动清理声明（自指场景 specRoot 指回本地 .sillyspec 有
+        // 真实数据面，留待 disconnect 是保守正确；temp 场景声明描述的 specRoot 物理上
+        // 就是临时产物，清理无损失，且不清理则每次命令重复 warn）。不用 disconnect——
+        // 它会连带清 local.yaml platform 段，误伤真实平台连接。删除失败仍按本地继续。
+        console.warn(`⚠️ 检测到 temp 残留平台接管声明（specRoot 指向系统 temp 目录：${decl.specRoot}，测试/联调投毒特征），已自动清理并按本地模式运行: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+        try { unlinkSync(join(cwd, PLATFORM_MANAGED_FILENAME)) } catch { /* best effort */ }
       } else {
         console.error(`❌ 平台接管声明生效：本项目已由平台托管（原 specRoot: ${decl.specRoot || '(未记录)'}），但恢复指针缺失，拒绝静默回退本地模式。`)
         console.error(`   声明文件: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
@@ -537,7 +562,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   let outputText = null
   const outputValue = getFlagValue('--output')
   if (outputValue !== null) outputText = outputValue
-  warnMsysMangledFlag('--output', outputValue)
+  warnMsysMangledFlag('--output', outputValue, { block: true })
 
   // 解析 quick 末步四字段参数（2026-08-21 agent-手工产出审计第二批 F6）：--req/--cause/
   // --solution/--result 各传一项，CLI 合成单行四字段 outputText（quicklog 落盘侧
@@ -580,7 +605,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       break
     }
   }
-  warnMsysMangledFlag('--input', inputText)
+  warnMsysMangledFlag('--input', inputText, { block: true })
 
   // 解析 --linked-changes <a,b|none>（quick 专用：显式声明关联变更，CI/脚本友好）
   // 与 --change 解耦：--linked-changes 语义清晰（关联变更），不与「指定变更名」混淆。
@@ -804,6 +829,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     '--deep', '--quick', '--standard', // scan profile 三档显式选择（scan-profile.js 从 argv 读；互斥见下方 PROFILE_FLAGS 检测）
     '--adopt-branch', // execute 显式收编既有 sillyspec/<change> 分支为 worktree 工作分支（坑 worktree-user-branch-conflict）
     '--diff', '--base', '--full', '--report', // scan diff（D-001：command.js 只补 flag，裸 token 解析归 index.js 子命令拦截）
+    '--meta', // P1-3：渲染 SS-META 机器块（布尔 flag，不吃值）
     '-h',
   ])
   for (let i = 0; i < flags.length; i++) {
@@ -1250,7 +1276,12 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     if (!qlId) {
       const guardPath = join(specBase, '.runtime', 'quick-sessions', cancelSessionRaw, 'guard.json')
       try {
-        if (existsSync(guardPath)) qlId = JSON.parse(readFileSync(guardPath, 'utf8')).qlId
+        if (existsSync(guardPath)) {
+          // 字段名 bug 修复（2026-09-09 §7-5，会话实证：guard 在场仍报「缺失/损坏」）：
+          // guard 写侧字段是 quicklogId（run/stage.js quickGuard），旧读侧读 .qlId 恒 undefined
+          const g = JSON.parse(readFileSync(guardPath, 'utf8'))
+          qlId = g.quicklogId || g.qlId
+        }
       } catch { /* guard 损坏 → 下面按找不到报错 */ }
     }
     if (!qlId) {
@@ -1717,8 +1748,12 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
   }
 
   if (!outputText) {
-    console.error('auto --done requires --output')
-    process.exit(2) // 用法错 → exit 2
+    // P0-2（noai-ir-roadmap §3）：auto --done 的 --output 同样可省略——与 completeStep 同源
+    // 的事实性摘要合成（此前硬拒 exit 2 是用法守卫；SS-META 的 doneCommand 仍带 --output，
+    // 照抄路径零变化，省略路径不再罚一轮）。
+    const _autoStep = progress?.stages?.[currentStage]?.steps?.find((s) => s && ['pending', 'in-progress', 'blocked'].includes(s.status))
+    outputText = synthesizeStepOutput({ stageName: currentStage, stepName: _autoStep?.name || currentStage, cwd })
+    console.log(`🤖 auto --done 未带 --output——CLI 已按事实合成步骤摘要（语义说明下次带 --output 手写）。`)
   }
 
   const result = await completeStep(pm, progress, currentStage, cwd, outputText, inputText, { printNext: false, changeName, platformOpts })

package/src/run/complete-handlers.js

@@ -26,14 +26,15 @@ import { basename, join, resolve, relative, isAbsolute } from 'node:path'
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync } from 'node:fs'
 import { renameSyncRetry, writeAtomicSync } from '../fs-atomic.js'
 import { gitQuiet } from '../git-helper.js'
-import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, mergeQuickBoundaryFiles } from './shared.js'
+import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, isQuicklogFileLineNoise, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, mergeQuickBoundaryFiles } from './shared.js'
 import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnchor } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
 import { printQuickAuditReview, runQuickTestLintGate, printQuickTestLintGate } from './quick-audit.js'
-import { validateQuickResult, allocateQuicklogEntry, appendQuicklogEntryWithId, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
+import { validateQuickResult, allocateQuicklogEntry, appendQuicklogEntryWithId, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult, parseFileNotes, getQuickFileNotes } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
+import { collectNumstatByPath } from '../scope-audit.js'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -121,11 +122,115 @@ export function findAlreadyArchivedDir(archiveDir, changeName) {
   return null
 }
 
+/**
+ * reviewedFiles[0] → 归属变更名。契约为 `changes/<change>/<doc>`（stage-review.js
+ * getLatestStageReviewRunId）。取 `changes/` 后第一路径段精确相等——`includes('changes/'+name+'/')`
+ * 会让短名 login 命中 2026-08-01-login（坑 marker-suffix-overmatch 同类）。
+ * @returns {string|null}
+ */
+function ownerFromReviewedFiles(reviewedFiles) {
+  const r0 = Array.isArray(reviewedFiles) ? String(reviewedFiles[0] || '') : ''
+  const m = r0.replace(/\\/g, '/').match(/(?:^|\/)changes\/([^/]+)\//)
+  return m ? m[1] : null
+}
+
+/**
+ * 归档后按 change 精确回收 .runtime 取证（ql-20260908-005-7549）。
+ *
+ * 调用时点：handleArchiveConfirmStep 已把 reconcile/apply-pathspec 吃进 delta.md 之后
+ * （fail-soft 生成失败也不阻断——变更已终态，runtime 取证无读者）。自愈归档 / quick 轻量
+ * 归档 / change-delete 无 delta 同样可删。
+ *
+ * 归属 fail-closed（禁 mtime 猜、禁后缀匹配）：
+ *   apply-pathspec-<change>.txt 精确文件名
+ *   execute-runs/<runId>/ 仅当 `change` 戳全等（无戳旧 run 留下，不按覆盖度启发式删）
+ *   stage-reviews/<dir>/ 仅当 review.json reviewedFiles 首段 === changeName
+ *   verify-runs/<ts>/ 仅当目录内 JSON 的 change 字段集合 size=1 且等于本变更
+ * 本轮不扩 endpoint-baselines / contract-artifacts / last-delta.json。
+ *
+ * fail-open：卫生动作失败不抛，返回 { ok:true }。
+ *
+ * @param {string} runtimeRoot
+ * @param {string} changeName
+ * @returns {{ ok: true, removed: number }}
+ */
+export function pruneArchivedChangeRuntime(runtimeRoot, changeName) {
+  if (!runtimeRoot || !changeName || !existsSync(runtimeRoot)) return { ok: true, removed: 0 }
+  let removed = 0
+  const gone = (p, recursive = false) => {
+    try {
+      if (recursive) rmSync(p, { recursive: true, force: true })
+      else unlinkSync(p)
+      removed++
+    } catch { /* 单份失败不连坐，下次归档/删变更再收 */ }
+  }
+
+  try {
+    const pathspec = join(runtimeRoot, `apply-pathspec-${changeName}.txt`)
+    if (existsSync(pathspec)) gone(pathspec)
+  } catch {}
+
+  try {
+    const execDir = join(runtimeRoot, 'execute-runs')
+    if (existsSync(execDir)) {
+      for (const runId of readdirSync(execDir)) {
+        const stampFile = join(execDir, runId, 'change')
+        if (!existsSync(stampFile)) continue
+        let stamp = ''
+        try { stamp = readFileSync(stampFile, 'utf8').trim() } catch { continue }
+        if (stamp !== changeName) continue
+        gone(join(execDir, runId), true)
+      }
+    }
+  } catch {}
+
+  try {
+    const srDir = join(runtimeRoot, 'stage-reviews')
+    if (existsSync(srDir)) {
+      for (const entry of readdirSync(srDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue
+        const rjPath = join(srDir, entry.name, 'review.json')
+        if (!existsSync(rjPath)) continue
+        let owner = null
+        try {
+          const rj = JSON.parse(readFileSync(rjPath, 'utf8'))
+          owner = ownerFromReviewedFiles(rj.reviewedFiles)
+        } catch { continue }
+        if (owner !== changeName) continue
+        gone(join(srDir, entry.name), true)
+      }
+    }
+  } catch {}
+
+  try {
+    const vrDir = join(runtimeRoot, 'verify-runs')
+    if (existsSync(vrDir)) {
+      for (const entry of readdirSync(vrDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue
+        const dir = join(vrDir, entry.name)
+        let files = []
+        try { files = readdirSync(dir).filter(f => f.endsWith('.json')) } catch { continue }
+        const owners = new Set()
+        for (const f of files) {
+          try {
+            const data = JSON.parse(readFileSync(join(dir, f), 'utf8'))
+            if (data && typeof data.change === 'string' && data.change) owners.add(data.change)
+          } catch { /* 单文件坏 JSON 跳过，不据此猜归属 */ }
+        }
+        if (owners.size === 1 && owners.has(changeName)) gone(dir, true)
+      }
+    }
+  } catch {}
+
+  return { ok: true, removed }
+}
+
 /**
  * 归档时清理可能残留的 worktree（execute 自动清理未走到 / 有未 apply 变更被遗弃）。
  * 安全策略：有未 apply 变更时保留 worktree 并警告，避免误删用户未应用的代码。
  * 同时清理该变更的 execute / stage-review runId marker（只写不删的累积物，
- * 见 stage.js execute 启动固定 executeRunId / stage-review.js stageReviewMarkerPath）。
+ * 见 stage.js execute 启动固定 executeRunId / stage-review.js stageReviewMarkerPath）
+ * 以及归档后无读者的 runtime 取证（pruneArchivedChangeRuntime）。
  * 从 archiveChangeDirectory 抽出，供正常归档 + 自愈归档复用。
  */
 export async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts = {}) {
@@ -151,6 +256,12 @@ export async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, p
       if (markers.length > 0) {
         console.log(`🧹 归档清理 ${markers.length} 个 runId marker（execute/stage-review）`)
       }
+      // 取证回收必须在下方 worktree 块的 `if (!meta) return` 之前：无 meta 早退是常态
+      // （apply 已 cleanup），漏接就会让 execute-runs/verify-runs 继续按变更数累积。
+      const pruned = pruneArchivedChangeRuntime(runtimeRoot, archiveChangeName)
+      if (pruned.removed > 0) {
+        console.log(`🧹 归档回收 ${pruned.removed} 项 runtime 取证（execute-runs/stage-reviews/verify-runs/apply-pathspec，按 change 精确匹配）`)
+      }
     }
   } catch (e) {
     console.warn(`⚠️  归档 runId marker 清理失败（不阻断归档）: ${e.message}`)
@@ -900,6 +1011,21 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         console.log(`🛡️ quick 边界已追加: ${added.length} 个文件（累计 ${guard.allowedFiles.length} 个）: ${added.join(', ')}`)
       }
     }
+    // --file-notes 路径同源并入边界（2026-09-08 用户反馈①：step3 只带 --file-notes 未带
+    // --files 时，QUICKLOG 文件行写进了这些文件、审计却按「超出 allowedFiles + 未声明」
+    // 拦——两条声明通道口径打架）。--file-notes 是显式的改动文件声明（路径部分参与落盘
+    // 文件行），与 --files 同语义追加；括注只是展示不参与。读取用 getQuickFileNotes（与
+    // 下方 completeQuicklogEntry 消费同一 per-process 值，读不清）。
+    {
+      const fileNotePaths = parseFileNotes(getQuickFileNotes()).map(n => n.path).filter(Boolean)
+      if (guard && fileNotePaths.length > 0) {
+        const { added } = mergeQuickBoundaryFiles(guard, fileNotePaths, cwd)
+        if (added.length > 0) {
+          try { writeAtomicSync(sessionGuardFile, JSON.stringify(guard, null, 2)) } catch { /* 同上：内存合并值兜底 */ }
+          console.log(`🛡️ quick 边界已追加（--file-notes 声明与文件行同源）: ${added.length} 个文件（累计 ${guard.allowedFiles.length} 个）: ${added.join(', ')}`)
+        }
+      }
+    }
     // 审计：仅在有 guard 时跑（brownfield 无 guard 跳过，兼容 D-003 brownfield 行为）。
     // task-02：mergedGuard 提升到 if 外声明，供下方并发预检钩子复用与 auditQuickCompletion
     // 同源的 guard 字段（baselineFiles/linkedChanges）。brownfield 无 guard 时保持 null，
@@ -1068,14 +1194,24 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
     // 翻状态进行中→已完成 + 追加结果 + 勾选关联 tasks.md
     // resultText 不再截断：结构化结果块（需求/根因/方案/结果）完整落盘，多行写成字段化块。
     try {
-      // 回填实际改动文件：review.changedFiles 含 quick 自身元数据（quicklog/.runtime/modules 等），
-      // 用 isQuickMetadata 过滤掉，只留真实业务文件。brownfield 无 review → 空数组，文件行不动。
+      // 回填实际改动文件：review.changedFiles 含 quick 自身元数据（quicklog/.runtime 等），
+      // 过滤掉只留真实业务文件——但**模块卡 + changelog sidecar 保留**（isQuicklogFileLineNoise，
+      // 2026-09-08 用户反馈①：收尾必改项此前每回手工补录；审计豁免面与记录面分叉）。brownfield
+      // 无 review → 空数组，文件行不动。
       // 归属口径（2026-08-18 误归属修复）：声明会话优先 attributedFiles（窗口∩声明∪同文件并发命中），
       // 他者窗口文件不进文件行；未声明会话/旧 review 无 attributedFiles → 兜底 changedFiles 全量。
       const auditFiles = Array.isArray(review?.attributedFiles)
         ? review.attributedFiles
         : (Array.isArray(review?.changedFiles) ? review.changedFiles : [])
-      const realFiles = auditFiles.filter(f => !isQuickMetadata(f, linkedChanges))
+      const realFiles = auditFiles.filter(f => !isQuicklogFileLineNoise(f, linkedChanges))
+      // 软归属（2026-09-10 用户反馈：--file-notes 括注只落声明文件，同模块测试文件漏声明时文件行
+      // 不自动补齐，连续多批手工核对）：auditQuickCompletion 判定的「窗口内未声明同模块测试文件」
+      // → 补入文件行 bullet 带软归属括注；审计面单列 🔍 行（可追溯、错认可手工剔除），⚠️ 不进
+      // attributedFiles——硬归属口径「声明即归属」不变（2026-08-18 误归属修复）。
+      const softFiles = (Array.isArray(review?.softTestFiles) ? review.softTestFiles : [])
+        .map(f => String(f).replace(/\\/g, '/')).filter(f => !isQuickMetadata(f, linkedChanges))
+      // task-06（FR-04）：文件行/审计行并上 numstat 行数——attachQuickLineCounts 见文件尾（声明提升）
+      const { annotatedRealFiles, annotatedSoftFiles, fmtLineCounts } = attachQuickLineCounts({ cwd, realFiles, softFiles, review, auditFiles, qlId })
       // D-8 落盘（2026-08-18 修）：advisory 欠账信号从「纯打印」升级为「随条目落盘」——修复
       // 「欠账已记录（QUICKLOG reasons）」的不实承诺（交叉审查实证 reasons 纯 stdout，事后不可审计）。
       // 两周实测（2026-08-31 裁决，doc-consistency-debt §七）需要分母：信号触发次数必须可追溯。
@@ -1087,20 +1223,47 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       }
       if (review?.docsCheckHint && review.docsCheckHint.invalid > 0) {
         auditNotes.push(`📎 文档引用失效：${review.docsCheckHint.invalid}/${review.docsCheckHint.total} 处 file:line 失效（sillyspec docs check 可复现）`)
+        // 行号漂移自动重锚（2026-09-08 用户反馈②：活文档 file:line 硬编码随任何插入失效，
+        // 每回手跑 docs check --fix 是机械活）：autoReanchorDocRefs = --fix 主链路编程化封装
+        // （fixable 唯一/优选命中才改 + 定点替换 + 同口径回执），只作用于本次改动的文档。
+        // fail-open：重锚任何异常只退化为上方 advisory 文案，绝不阻断 --done。
+        try {
+          const deletedSet = new Set(review.deletedFiles || [])
+          const mdChanged = (review.changedFiles || [])
+            .filter(f => f.endsWith('.md') && !deletedSet.has(f) && !isQuickMetadata(f, linkedChanges))
+          if (mdChanged.length > 0) {
+            const { autoReanchorDocRefs, readDocsCheckConfig } = await import('../docs-check.js')
+            let fixCfg = {}
+            try { fixCfg = readDocsCheckConfig(cwd) || {} } catch { fixCfg = {} }
+            const r = autoReanchorDocRefs(cwd, mdChanged, fixCfg)
+            if (r.applied > 0) {
+              auditNotes.push(`🔧 行号漂移已自动重锚 ${r.applied} 处（同口径复跑：${r.invalidBefore} → ${r.invalidAfter}；剩余 ${r.remaining} 处需人工 sillyspec docs check）`)
+              console.log(`🔧 文档行号漂移自动重锚：${r.applied} 处已改写，剩余 ${r.remaining} 处需人工（sillyspec docs check 可复现）`)
+            }
+          }
+        } catch { /* 自动重锚失败退化为纯 advisory（上方 auditNote 已落盘） */ }
       }
       // 归属切分注（2026-08-18 误归属修复）：窗口内未声明脏文件不进「文件：」行，但必须落盘可追溯
       // （多 agent 并发仓他者窗口改动 / 本会话漏声明均可能），防真实改动被静默挤走。
+      // 软归属拆分（2026-09-10）：softFiles 中的同模块测试文件已补入文件行，不再占 ⚖️「未计入」
+      // 文案（否则审计行与文件行自相矛盾），单列 🔍 行交代软归属依据与剔除指引。
       if (Array.isArray(review?.undeclaredFiles) && review.undeclaredFiles.length > 0) {
-        const undeclared = review.undeclaredFiles.filter(f => !isQuickMetadata(f, linkedChanges))
+        const softSet = new Set(softFiles)
+        const undeclared = review.undeclaredFiles.filter(f => !isQuickMetadata(f, linkedChanges) && !softSet.has(String(f).replace(/\\/g, '/')))
         if (undeclared.length > 0) {
-          auditNotes.push(`⚖️ 归属切分：${undeclared.length} 个窗口内未声明脏文件未计入文件行（并行会话改动或本会话漏声明）：${undeclared.join(', ')}`)
+          auditNotes.push(`⚖️ 归属切分：${undeclared.length} 个窗口内未声明脏文件未计入文件行（并行会话改动或本会话漏声明）：${undeclared.map(f => `${f}${fmtLineCounts(f)}`).join(', ')}`)
+        }
+        if (softFiles.length > 0) {
+          auditNotes.push(`🔍 软归属：${softFiles.length} 个窗口内未声明同模块测试文件已补入文件行（若属并行会话改动请手工剔除）：${annotatedSoftFiles.join(', ')}`)
+          console.log(`🔍 软归属：${softFiles.length} 个窗口内未声明同模块测试文件已按软归属补入文件行（若属并行会话改动请手工剔除）：${annotatedSoftFiles.join(', ')}`)
         }
       }
       await completeQuicklogEntry(specBase, gitUser, qlId, {
         resultText: outputText || '',
         linkedChanges,
-        changedFiles: realFiles,
+        changedFiles: annotatedRealFiles,
         auditNotes,
+        softFiles,
       })
       console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)
       // 刷新 DB title：从 step3「需求：」提取（agent 可改 title 的途径），覆盖启动时的兜底快照。
@@ -1682,3 +1845,46 @@ export async function handleScanStageCompleted({ stageName, currentIdx, cwd, pro
   return null
 }
 
+// ── task-06（2026-09-10-change-scope-audit，FR-04）：quick 文件行/审计行 numstat 行数注入 ──
+// collectNumstatByPath 与 scope-audit 命令同源采集（D-003 单一真相；R-03 单次 git 调用非逐文件）。
+// 基点 'HEAD' = 未提交工作区窗口（D-004：quick 无 merge-base 锚，对未提交窗口采集语义自洽；
+// untracked 新文件 wc-l 记全 + 行、binary 显 BIN）。纯展示列（advisory，D-006）：采集失败/行数
+// 不可得 → 括注省略不出伪数据；不改 auditQuickCompletion 判定、runQuickTestLintGate 与任何门禁。
+// 放文件尾（函数声明提升）而不内联进 handleQuickStageCompletion：docs/platform-interface-map
+// 行号锚在上方（complete-handlers.js:1688 handleScanStageCompleted），内联大块会把 doc-ref 锚
+// 推出关键词窗口。
+//
+// 消费分工（调用方 quick 收尾）：
+//   - annotatedRealFiles → completeQuicklogEntry changedFiles（QUICKLOG「文件：」行/bullet 带括注；
+//     fileNotes 模式下 realFiles 本就不渲染，括注只出现在回退渲染面）
+//   - annotatedSoftFiles → 🔍 软归属审计行 + console；softFiles 传参保持**裸路径**——
+//     flipEntryInContent 用它与 fileNotes.path 精确等值去重（带括注会不等值 → 同文件双 bullet）
+//   - fmtLineCounts → ⚖️ 归属切分审计行逐文件括注（降级返回空串 → 原样不带）
+//   - 已提交降级（D-004）：窗口空（改动已 commit/会话未产生改动）且 QUICKLOG 条目已存在 →
+//     记录态提示读 QUICKLOG 条目文件行，不以空表冒充实时（与 scope-audit quick 模式 note 同口径）
+function attachQuickLineCounts({ cwd, realFiles, softFiles, review, auditFiles, qlId }) {
+  const posix = (f) => String(f).replace(/\\/g, '/')
+  const lineCountFiles = [...new Set([...(realFiles || []).map(posix), ...(softFiles || [])])]
+  let numstatByPath = new Map()
+  if (lineCountFiles.length > 0) {
+    try {
+      numstatByPath = collectNumstatByPath(cwd, lineCountFiles, { baseRef: 'HEAD' })
+    } catch { /* 采集异常 → 行数列整体降级省略（fail-soft） */ }
+  }
+  const fmtLineCounts = (f) => {
+    const st = numstatByPath.get(posix(f))
+    if (!st) return ''
+    if (st.kind === 'binary') return '（BIN）'
+    if (!Number.isFinite(st.additions) || !Number.isFinite(st.deletions)) return ''
+    return `（+${st.additions}/-${st.deletions}）`
+  }
+  const annotatedRealFiles = (realFiles || []).map(f => `${f}${fmtLineCounts(f)}`)
+  const annotatedSoftFiles = (softFiles || []).map(f => `${f}${fmtLineCounts(f)}`)
+  if (lineCountFiles.length > 0) {
+    console.log(`📊 变更行数（vs HEAD 未提交窗口）：${[...annotatedRealFiles, ...annotatedSoftFiles].join(', ')}`)
+  } else if (review && Array.isArray(auditFiles) && auditFiles.length === 0) {
+    console.log(`ℹ️ 本会话无未提交改动（窗口已提交或会话未产生改动）——实时行数不可采，文件行请读 QUICKLOG 条目 ${qlId}（记录态）`)
+  }
+  return { annotatedRealFiles, annotatedSoftFiles, fmtLineCounts }
+}
+