sillyspec 3.29.4 → 3.31.0

package/src/greenfield-bootstrap.js

@@ -0,0 +1,98 @@
+/**
+ * greenfield-bootstrap.js — 绿地仓模块图草案起草（2026-09-25-greenfield-bootstrap）
+ *
+ * R17 实证：无模块图的新仓，FR 域路由全落伪域/unmapped（臂2 auto-claude、臂3 unmapped），
+ * 知识复利从第一条断流。本模块在 flow start 检测到模块图缺席且 --input 有路径语料时，
+ * 机器起草初始 _module-map.yaml：
+ *   - 模块 id = 路径目录段里首个非泛化段（cli/server/api…），paths = 该文件所在目录（/ 结尾）
+ *   - generator: flow-bootstrap-draft + status: draft 自明身份——与 scan 产的正式图区分；
+ *     模块图契约本就是机器（scan）产物，「手动维护」指 paths 后续增量，缺席首建不冲突
+ *     （方案评审裁定三条件：草案头带警告 + draft 标识 + 不含 blast 段——判级对缺席安全降级 S1）
+ *   - 不覆盖已有文件；全库任一 _module-map.yaml 在场（多项目仓）即不写（幂等）
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { writeAtomicSync } from './fs-atomic.js'
+
+const GENERIC_SEGMENTS = new Set(['src', 'lib', 'test', 'tests', 'spec', 'docs', 'doc', 'app', 'packages', 'scripts', 'config', 'public', 'internal', 'node_modules'])
+
+/** 路径组 → { moduleId → Set<dirPath> }（目录以 / 结尾；根文件无模块归属丢弃）。 */
+function groupByModule(paths) {
+  const mods = new Map()
+  for (const raw of paths) {
+    const p = String(raw || '').replace(/\\/g, '/')
+    const segs = p.split('/').filter(Boolean)
+    if (segs.length < 2) continue // 根文件：无目录段
+    const dirSegs = segs.slice(0, -1)
+    const rawMod = dirSegs.find((s) => !GENERIC_SEGMENTS.has(s.toLowerCase()))
+    if (!rawMod) continue // 全泛化段（src/x.js）：无可命名模块——留给 unmapped 兜底
+    // id 消毒（评审 P2 清偿）：FR 域正则 [a-z0-9-]——大写/点/下划线段会铸出不可回读域；
+    // 消毒后空（纯符号段如 .github → github，纯点段丢弃）则该路径不建模块
+    const modId = rawMod.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/^[-.]+|[-.]+$/g, '')
+    if (!modId || /^-+$/.test(modId)) continue
+    const dir = dirSegs.join('/') + '/'
+    if (!mods.has(modId)) mods.set(modId, new Set())
+    mods.get(modId).add(dir)
+  }
+  return mods
+}
+
+/** 项目目录名：package.json name 优先（sanitize 成文件名安全段），fallback 'app'。 */
+function projectName(cwd) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'))
+    const n = String(pkg && pkg.name || '').split('/').pop().replace(/[^\w.-]/g, '-').replace(/^[-.]+|[-.]+$/g, '')
+    if (n) return n
+  } catch { /* 非 node 项目或缺件 */ }
+  return 'app'
+}
+
+/**
+ * 起草初始 _module-map.yaml。
+ * @param {{ cwd: string, specBase: string, paths: string[] }} opts
+ * @returns {{ written: boolean, path?: string, modules: number, moduleIds: string[], reason?: string }}
+ */
+export function draftModuleMap({ cwd, specBase, paths }) {
+  const docsDir = join(specBase, 'docs')
+  // 幂等闸门：任一项目已有模块图（含草案）即不写——多项目仓防重复建
+  try {
+    if (existsSync(docsDir)) {
+      for (const e of readdirSync(docsDir, { withFileTypes: true })) {
+        if (e.isDirectory() && existsSync(join(docsDir, e.name, 'modules', '_module-map.yaml'))) {
+          return { written: false, modules: 0, moduleIds: [], reason: `已有模块图（${e.name}）` }
+        }
+      }
+    }
+  } catch { /* 扫描异常按缺席处理 */ }
+  const mods = groupByModule(paths)
+  if (mods.size === 0) return { written: false, modules: 0, moduleIds: [], reason: '路径语料无可命名模块（全泛化段/根文件）' }
+  const proj = projectName(cwd)
+  const mapDir = join(docsDir, proj, 'modules')
+  mkdirSync(mapDir, { recursive: true })
+  const mapPath = join(mapDir, '_module-map.yaml')
+  if (existsSync(mapPath)) return { written: false, modules: 0, moduleIds: [], reason: '目标文件已存在（不覆盖）' }
+  const lines = [
+    'schema_version: 2',
+    'generated_at: ' + new Date().toISOString(),
+    'generator: flow-bootstrap-draft',
+    'status: draft',
+    '',
+    '# ⚠️ 绿地草案——flow start 按 --input 路径语料机器聚合，未经 scan 校准。',
+    '# 校准路径：sillyspec run scan（或 modules 重建）后转正；转正前域路由按本草案分流（不再落 unmapped）。',
+    '# ⚠️ 勿跑 modules rebuild --force——会清空手动维护的 paths（与正式图同警告）。',
+    '',
+    'modules:',
+  ]
+  const ids = [...mods.keys()].sort()
+  for (const id of ids) {
+    lines.push(`  ${id}:`)
+    lines.push('    status: draft')
+    lines.push('    paths:')
+    for (const p of [...mods.get(id)].sort()) lines.push(`      - ${p}`)
+    lines.push('')
+  }
+  writeAtomicSync(mapPath, lines.join('\n'))
+  return { written: true, path: mapPath.replace(/\\/g, '/'), modules: ids.length, moduleIds: ids }
+}
+
+export default { draftModuleMap }

package/src/handoff.js

@@ -6,13 +6,66 @@
  * 本就自足（进度快照/模块命中/知识注入全由进度库与 prompt 渲染提供，新会话零背景可
  * 续跑）——「每阶段一个瘦会话」是零机制改动的省法，缺的只是把交接信息打成一块可粘贴。
  *
- * 定位：纯只读（ProgressManager 读路径 + 环境探测），不写盘不动状态。输出三件：
+ * 定位：纯只读（ProgressManager 读路径 + 变更目录文本 + 环境探测），不写盘不动状态。输出：
  *   ① 新会话启动块（保持 SILLYSPEC_SESSION_ID 不变——变更所有权按此判定）；
  *   ② 下一阶段建议（当前阶段完成 → MAIN_FLOW_ORDER 后继；进行中 → 同阶段续跑）；
- *   ③ 当前状态摘要（阶段进度 + 停留步骤）。
+ *   ③ 当前状态摘要（阶段进度 + 停留步骤）；
+ *   ④ 上下文三段（B4a 加厚，2026-09-21-r5 优化 C-2）：未决阻断（waiting/blocked/failed 步骤）/
+ *      任务面（tasks.md checkbox 计数+待办清单）/ 决策 ID 清单（decisions.md D-xxx@vN，翻案先回源）——
+ *      整块 80 行帽（HANDOFF_LINE_CAP），超限从上下文段尾截，粘贴块与警示行永不动。
  */
 import { ProgressManager, resolveSpecDir } from './progress.js';
 import { MAIN_FLOW_ORDER, STAGE_LABELS } from './progress/shared.js';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** 交接块总行数帽（优化方案 C-2 B4a：把「任务太大爆窗」从硬墙变操作规程——块本身不许变大到失控） */
+const HANDOFF_LINE_CAP = 80;
+
+function readChangeFile(specRoot, change, name) {
+  try { return readFileSync(join(specRoot, 'changes', change, name), 'utf8'); } catch { return null; }
+}
+
+/**
+ * 任务面摘要：tasks.md checkbox 行计数（done/total + 待办 ID 清单）。
+ * @param {string|null} tasksMdText
+ * @returns {string|null} 无 checkbox 行（非 execute 期/未落盘）返回 null
+ */
+export function summarizeTaskFace(tasksMdText) {
+  if (!tasksMdText) return null;
+  const boxes = [...tasksMdText.matchAll(/^-\s?\[([ xX])\]\s*(task-\d+)/gm)];
+  if (!boxes.length) return null;
+  const pending = boxes.filter((m) => m[1].toLowerCase() !== 'x').map((m) => m[2]);
+  let line = `📦 任务面：${boxes.length - pending.length}/${boxes.length} 完成`;
+  if (pending.length) {
+    line += `（待办：${pending.slice(0, 8).join('、')}${pending.length > 8 ? ` 等 ${pending.length} 项` : ''}）`;
+  }
+  return line;
+}
+
+/**
+ * 决策清单摘要：decisions.md 的 `## D-xxx@vN` 标题行 ID（跨会话恢复时按 ID 回源翻否决理由）。
+ * @param {string|null} decisionsMdText
+ * @returns {string|null}
+ */
+export function summarizeDecisions(decisionsMdText) {
+  if (!decisionsMdText) return null;
+  const ids = [...decisionsMdText.matchAll(/^##\s+(D-[\w-]+@v\d+)/gm)].map((m) => m[1]);
+  if (!ids.length) return null;
+  return `🧠 决策：${ids.slice(0, 10).join('、')}${ids.length > 10 ? ` 等 ${ids.length} 条` : ''}（翻案/复潮先读 decisions.md 对应条目）`;
+}
+
+/**
+ * 未决阻断摘要：进度库步骤态 waiting/blocked/failed（--wait 决策点与门禁拦截点）。
+ * @param {object|null} stageData
+ * @returns {string|null}
+ */
+export function summarizeBlockers(stageData) {
+  const steps = Array.isArray(stageData && stageData.steps) ? stageData.steps : [];
+  const stuck = steps.filter((s) => s && (s.status === 'waiting' || s.status === 'blocked' || s.status === 'failed'));
+  if (!stuck.length) return null;
+  return `⛔ 未决：${stuck.slice(0, 3).map((s) => `「${String(s.name || s.stepName || s.title || `Step ${s.index ?? '?'}`).slice(0, 20)}」${s.status}`).join('；')}${stuck.length > 3 ? ` 等 ${stuck.length} 步` : ''}`;
+}
 
 /**
  * 解析下一阶段建议。
@@ -52,12 +105,14 @@ export async function buildHandoff({ cwd, specBase, changeName } = {}) {
   let target = changeName;
   let picked = false;
   if (!target) {
-    // 唯一活跃主流程变更自动选中（listChanges=目录+DB 联合口径，read 取 currentStage）
+    // 唯一活跃主流程变更自动选中（listChanges=目录+DB 联合口径，read 取 currentStage）；
+    // 轻量变更（flow-state.yaml 在场）同样入候选——thin 变更也需要跨会话交接（评审 P3 清偿）
+    const isThinChange = (cn) => existsSync(join(specRoot, 'changes', cn, 'flow-state.yaml'));
     const names = pm.listChanges(cwd) || [];
     const mains = [];
     for (const cn of names) {
       const p = pm.read(cwd, cn);
-      if (p && MAIN_FLOW_ORDER.includes(p.currentStage || '')) mains.push({ name: cn, stage: p.currentStage });
+      if (p && (MAIN_FLOW_ORDER.includes(p.currentStage || '') || isThinChange(cn))) mains.push({ name: cn, stage: p.currentStage });
     }
     if (mains.length === 1) {
       target = mains[0].name;
@@ -65,7 +120,7 @@ export async function buildHandoff({ cwd, specBase, changeName } = {}) {
     } else if (mains.length > 1) {
       return { ok: false, error: `多活跃主流程变更（${mains.length} 个：${mains.map((m) => m.name).join('、')}）——请带 --change <名> 指定` };
     } else {
-      return { ok: false, error: '无活跃主流程变更（quick/scan 会话或全部归档）——handoff 面向主流程阶段交接' };
+      return { ok: false, error: '无活跃主流程/轻量变更（quick/scan 会话或全部归档）——handoff 面向主流程与轻量变更交接' };
     }
   }
 
@@ -75,12 +130,25 @@ export async function buildHandoff({ cwd, specBase, changeName } = {}) {
   const currentStage = progress.currentStage || '';
   const stageData = (progress.stages && progress.stages[currentStage]) || null;
   const stageCompleted = !!(stageData && stageData.status === 'completed');
-  const suggestion = nextStageSuggestion(currentStage, stageCompleted);
+  let suggestion = nextStageSuggestion(currentStage, stageCompleted);
+  // 轻量变更（thin/flow）感知（2026-09-25-quick-channel-retire 评审 P1）：flow-state.yaml 在场 =
+  // 轻量变更，续跑/收口走 flow 协议——run <stage> 对 thin 变更会被混跑守卫拒（升厚须用户同意
+  // 带 --upgrade-thick），交接命令改写为 flow 入口
+  const isThin = existsSync(join(specRoot, 'changes', target, 'flow-state.yaml'));
+  if (isThin) {
+    suggestion = { next: 'flow', mode: 'resume', reason: '轻量变更（thin）——新会话重跑 flow start 看恢复简报，干完跑 flow done 收口；run <stage> 会被混跑守卫拒（升厚须用户同意带 --upgrade-thick）' };
+  }
   const sessionId = process.env.SILLYSPEC_SESSION_ID || null;
 
   const steps = Array.isArray(stageData && stageData.steps) ? stageData.steps : [];
   const doneSteps = steps.filter((s) => s && s.status === 'completed').length;
 
+  // ── 上下文三段（B4a 加厚：任务面 / 未决 / 决策——进度库+变更目录机械抽取，仍纯只读）──
+  const faceLine = summarizeTaskFace(readChangeFile(specRoot, target, 'tasks.md'));
+  const decisionLine = summarizeDecisions(readChangeFile(specRoot, target, 'decisions.md'));
+  const blockerLine = summarizeBlockers(stageData);
+  const contextLines = [blockerLine, faceLine, decisionLine].filter(Boolean);
+
   const lines = [];
   lines.push('🔗 交接块（瘦会话模式——下一阶段/续跑在新会话执行，主会话收尾省上下文）');
   lines.push('');
@@ -88,7 +156,9 @@ export async function buildHandoff({ cwd, specBase, changeName } = {}) {
   if (sessionId) lines.push(`export SILLYSPEC_SESSION_ID=${sessionId}`);
   else lines.push('export SILLYSPEC_SESSION_ID=<本变更的会话标识——旧会话 echo $SILLYSPEC_SESSION_ID 取>');
   lines.push(`cd ${cwd}`);
-  if (suggestion.next) {
+  if (suggestion.next === 'flow') {
+    lines.push(`sillyspec flow start --change ${target}`);
+  } else if (suggestion.next) {
     lines.push(`sillyspec run ${suggestion.next} --change ${target}`);
   } else {
     lines.push('# （流程终态，无续跑命令）');
@@ -96,10 +166,52 @@ export async function buildHandoff({ cwd, specBase, changeName } = {}) {
   lines.push('# ── 交接块结束 ──');
   lines.push('');
   lines.push(`📋 ${target}：当前 ${STAGE_LABELS[currentStage] || currentStage}${steps.length > 0 ? `（步骤 ${doneSteps}/${steps.length}）` : ''}${stageCompleted ? ' ✅ 已完成' : ''}`);
+  const contextStart = lines.length;
+  for (const c of contextLines) lines.push(c);
+  // 80 行帽：粘贴块（头）与警示行（尾）不动，超限从上下文段尾截（决策→任务面→未决，重要性递增反向丢）
+  let truncated = false;
+  while (lines.length + 3 > HANDOFF_LINE_CAP && lines.length > contextStart) {
+    lines.splice(lines.length - 1, 1);
+    truncated = true;
+  }
+  if (truncated) lines.push('…（上下文超 80 行帽截尾——任务面/决策明细回源 tasks.md 与 decisions.md）');
+  // 机器预览态段（2026-09-23-watcher-preview-progress task-03 / FR-05）：watcher 投影的
+  // 进行态参考——新会话据此快速恢复现场（证据引用可回源事件流）。无预览行时零输出（不添行）。
+  try {
+    const { readPreviewProgress } = await import('./progress.js');
+    const pv = readPreviewProgress(specRoot, target);
+    if (pv.exists && pv.stages.length > 0) {
+      lines.push('');
+      lines.push(`👀 机器预览态（watcher 推断 ${pv.stages.length} 行——非流程真相，权威以 progress show 为准）：`);
+      for (const r of pv.stages) {
+        const files = r.evidence && Array.isArray(r.evidence.files) ? r.evidence.files.join('/') : '';
+        lines.push(`   [预览] ${r.stage} → ${r.status}${files ? `（依据：${files}）` : ''} 最后活动 ${r.startedAt || '?'}`);
+      }
+    }
+  } catch { /* 预览段 best-effort，不影响交接块本体 */ }
+
   lines.push(`➡️ ${suggestion.reason}`);
   lines.push('💡 为什么可行：CLI prompt 自足——进度快照/模块命中/知识注入由进度库与渲染提供，新会话零背景可续跑。');
   lines.push('⚠️ SILLYSPEC_SESSION_ID 必须保持不变（变更所有权/接管判定按此标识）；缺省降级机器级标识只拦他机。');
 
+  // handoffAt 切割凭证（R16-b 实证修正 2026-09-25）：stage.wall=hard 的墙按「前驱收口后
+  // 是否执行过 handoff」判定硬续（SESSION_ID 是所有权标识非会话标识，handoff 要求新会话
+  // 保持不变——SESSION_ID 相同不能当硬续证据）。本命令执行即切割：best-effort 给
+  // stage-session ledger 盖 handoffAt 章，墙据此放行新会话的 execute/verify 首入。
+  try {
+    const ledgerPath = join(specRoot, '.runtime', `stage-session-ledger-${target}.json`);
+    let ledger = null;
+    try { ledger = JSON.parse(readFileSync(ledgerPath, 'utf8')); } catch { /* 无账本（阶段未收口）→ 无墙可放行，零动作 */ }
+    if (ledger && typeof ledger === 'object') {
+      ledger.handoffAt = new Date().toISOString();
+      try {
+        const { writeFileSync, mkdirSync } = await import('node:fs');
+        mkdirSync(join(specRoot, '.runtime'), { recursive: true });
+        writeFileSync(ledgerPath, JSON.stringify(ledger, null, 1) + '\n', 'utf8');
+      } catch { /* 盖章失败不影响交接块本体 */ }
+    }
+  } catch { /* handoffAt 盖章 best-effort */ }
+
   return {
     ok: true,
     change: target,
@@ -108,6 +220,7 @@ export async function buildHandoff({ cwd, specBase, changeName } = {}) {
     stageCompleted,
     suggestion,
     sessionId,
+    truncated,
     lines,
   };
 }

package/src/hunk-attribution.js

@@ -0,0 +1,191 @@
+/**
+ * hunk-attribution —— 提交面行级归属门（2026-09-27-hunk-attribution-gate）。
+ *
+ * 背景事故（本仓 4f859053 实证）：两个会话并发编辑同一文件，文件级 pathspec 提交把并行
+ * 会话 25 行在途代码夹带进冻结面——规则 11 的文件级对账防「别的文件」，防不住「同一文件
+ * 里别人的行」。用户裁决：不默认挂工作树（合并税过重，wt-parallel-commit-race 等坑史为
+ * 证），改为把对账升到 hunk 级归属门。
+ *
+ * 三类信号（诚实口径：机器无法判定「哪行是谁的」，门的目标是把静默混合变成显式中断）：
+ *   ① 未归因文件：提交面文件不在本变更声明面（design 清单 ∪ requirements 测试绑定，
+ *      复用 parseFileChangeList / extractRequirementBindings / testAnchorFile 同源解析）；
+ *   ② 跨变更竞争：其他活跃变更的声明面与提交面相交——同文件无法按行归属，显式列出
+ *      竞争文件、对方变更名与 hunk 数，收口前人工核对；
+ *   ③ 在途残留：提交面文件当前工作树仍有未提交 diff——活跃并发 WIP 信号。
+ *
+ * 分级：local.yaml hunk_gate（warn 默认 / error / off）。error 档由接线方（flow.js probes
+ * 子步）阻断收口；本模块只产结果不执法。fail-soft：非 git 环境与异常降级跳过。
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** local.yaml 读 hunk_gate（warn|error|off，默认 warn；CRLF 容错）。 */
+export function readHunkGate(specBase) {
+  try {
+    const raw = readFileSync(join(specBase, 'local.yaml'), 'utf8')
+    const m = raw.match(/^\s*hunk_gate\s*:\s*['\"]?(warn|error|off)['\"]?\s*$/m)
+    return m ? m[1] : 'warn'
+  } catch {
+    return 'warn'
+  }
+}
+
+function normalizePath(p) {
+  return String(p).replace(/^NEW:\s*/, '').replace(/\\/g, '/').trim()
+}
+
+/**
+ * 本变更声明面（design 清单 ∪ requirements 测试绑定路径）。解析器与 flow done 既有
+ * 「提交面夹带嫌疑 advisory」同源（不二算口径一致）。
+ * @returns {{ declared: Set<string>, parseFailed: boolean }}
+ */
+export async function collectDeclaredFace(changeDir, change) {
+  const declared = new Set()
+  let parseFailed = false
+  try {
+    const { parseFileChangeList } = await import('./change-list.js')
+    for (const p of parseFileChangeList(join(changeDir, 'design.md'))) declared.add(normalizePath(p))
+  } catch { parseFailed = true }
+  try {
+    const { extractRequirementBindings } = await import('./flow-draft.js')
+    const { testAnchorFile } = await import('./test-bindings.js')
+    for (const row of extractRequirementBindings({ changeDir, change })) {
+      for (const t of row.tests || []) declared.add(normalizePath(testAnchorFile(t)))
+    }
+  } catch { parseFailed = true }
+  return { declared, parseFailed }
+}
+
+/** 其他活跃变更的声明面（排除 archive 与本变更；design 缺失的变更跳过）。 */
+async function collectForeignDeclarations(specBase, changeName) {
+  const map = new Map() // file -> Set<changeName>
+  const changesRoot = join(specBase, 'changes')
+  let dirs
+  try { dirs = readdirSync(changesRoot, { withFileTypes: true }) } catch { return map }
+  const { parseFileChangeList } = await import('./change-list.js')
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue
+    if (d.name === 'archive' || d.name === changeName) continue
+    const designPath = join(changesRoot, d.name, 'design.md')
+    if (!existsSync(designPath)) continue
+    try {
+      for (const p of parseFileChangeList(designPath)) {
+        const f = normalizePath(p)
+        if (!map.has(f)) map.set(f, new Set())
+        map.get(f).add(d.name)
+      }
+    } catch { /* 单变更解析失败跳过（fail-soft） */ }
+  }
+  return map
+}
+
+/** 数某文件 baseline..HEAD 的 hunk 数（二进制/重命名无 @@ 头计 0——按文件级处理）。 */
+function countHunks(gitFn, cwd, baselineCommit, file) {
+  try {
+    const out = gitFn(cwd, ['diff', `${baselineCommit}..HEAD`, '--', file])
+    const text = String(out || '')
+    let n = 0
+    for (const line of text.split('\n')) if (line.startsWith('@@')) n++
+    return n
+  } catch {
+    return -1
+  }
+}
+
+/** 当前工作树未提交修改文件集（M 状态；新增未跟踪不算——residue 只关心已提交文件的并发改动）。 */
+function collectWorkingTreeModified(gitFn, cwd) {
+  try {
+    const out = gitFn(cwd, ['status', '--porcelain'])
+    const set = new Set()
+    for (const line of String(out || '').split('\n')) {
+      const status = line.slice(0, 2)
+      const path = normalizePath(line.slice(3).split(' -> ').pop())
+      // porcelain XY 双列：X=暂存位 Y=工作树位（" M a.js" 是未暂存修改）——任一列 M/A 都算在途
+      if ((status[0] === 'M' || status[0] === 'A' || status[1] === 'M' || status[1] === 'A') && path) set.add(path)
+    }
+    return set
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 行级归属门主体。committedFiles 为 baseline..HEAD 提交面文件清单（相对路径正斜杠）。
+ * @returns {{ ok: boolean, degraded: boolean, gate: string, unattributed: Array,
+ *   contended: Array, residue: Array, notes: string[] }}
+ */
+export async function runHunkAttributionGate({ cwd, specBase, changeName, baselineCommit, committedFiles, gitFn, gate = 'warn' }) {
+  const result = { ok: true, degraded: false, gate, faceCount: 0, unattributed: [], contended: [], residue: [], notes: [] }
+  if (gate === 'off') {
+    result.notes.push('hunk_gate=off——归属门关闭')
+    return result
+  }
+  if (!baselineCommit || !Array.isArray(committedFiles) || committedFiles.length === 0) {
+    result.notes.push('提交面为空或基线缺失——归属门跳过')
+    return result
+  }
+  const changeDir = join(specBase, 'changes', changeName)
+  const { declared } = await collectDeclaredFace(changeDir, changeName)
+
+  const deliverables = committedFiles
+    .map(normalizePath)
+    .filter((f) => !f.startsWith('.sillyspec/'))
+  result.faceCount = deliverables.length
+
+  // ① 未归因文件（声明面全空时降为提示，不指认夹带——advisory 同口径）
+  if (declared.size > 0) {
+    for (const f of deliverables) {
+      if (!declared.has(f)) {
+        result.unattributed.push({ file: f, hunks: countHunks(gitFn, cwd, baselineCommit, f) })
+      }
+    }
+  } else {
+    result.notes.push('本变更无文件声明面（design 无清单、requirements 无绑定）——未归因判定降为提示')
+  }
+
+  // ② 跨变更竞争（同文件无法按行归属——显式暴露）
+  const foreign = await collectForeignDeclarations(specBase, changeName)
+  for (const f of deliverables) {
+    const by = foreign.get(f)
+    if (by && by.size > 0) {
+      result.contended.push({ file: f, by: [...by], hunks: countHunks(gitFn, cwd, baselineCommit, f) })
+    }
+  }
+
+  // ③ 在途残留（提交面文件当前仍有未提交修改——活跃并发 WIP）
+  const modified = collectWorkingTreeModified(gitFn, cwd)
+  if (modified) {
+    for (const f of deliverables) {
+      if (modified.has(f)) result.residue.push({ file: f })
+    }
+  }
+
+  result.ok = result.unattributed.length === 0 && result.contended.length === 0
+  return result
+}
+
+/** 渲染（warn/error 由接线方选择输出流；本函数只产行）。 */
+export function renderHunkAttributionLines(r) {
+  const L = []
+  if (!r || r.gate === 'off' || r.degraded) {
+    L.push(`- 不适用（${r && r.gate === 'off' ? 'hunk_gate=off' : '降级跳过（非 git 环境或异常）'}）`)
+    for (const n of (r && r.notes) || []) L.push(`- ℹ️ ${n}`)
+    return L
+  }
+  const attributed = r.faceCount - r.unattributed.length
+  L.push(`- ℹ️ 提交面 ${r.faceCount} 个交付文件对账：声明面归因 ${attributed}、未归因 ${r.unattributed.length}、跨变更竞争 ${r.contended.length}、在途残留 ${r.residue.length}`)
+  for (const u of r.unattributed) {
+    L.push(`- ⚠️ 未归因：\`${u.file}\`（${u.hunks >= 0 ? `${u.hunks} hunk` : 'hunk 数不可得'}）不在 design 清单与 requirements 测试绑定——属并行会话在途交付则须显式 pathspec 隔离并协调归属；属本变更则补 design 自声明`)
+  }
+  for (const c of r.contended) {
+    L.push(`- ⚠️ 跨变更竞争：\`${c.file}\` 同时被活跃变更 ${c.by.join('、')} 声明（${c.hunks >= 0 ? `${c.hunks} hunk` : '?'}）——同文件无法按行归属，收口前逐 hunk 核对全部改动确属本变更，否则协调串行或拆分提交`)
+  }
+  for (const s of r.residue) {
+    L.push(`- ⚠️ 在途残留：\`${s.file}\` 已进提交面但当前工作树仍有未提交修改——活跃并发 WIP 信号，确认无 interleaved 提交风险`)
+  }
+  if (r.unattributed.length === 0 && r.contended.length === 0 && r.residue.length === 0) {
+    L.push('- ✅ 提交面全部文件归属清晰（声明面覆盖、无跨变更竞争、无在途残留）')
+  }
+  for (const n of r.notes || []) L.push(`- ℹ️ ${n}`)
+  return L
+}