sillyspec 3.29.0 → 3.29.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.29.0",
+  "version": "3.29.2",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/agent-session-log.js

@@ -497,12 +497,66 @@ function detectOpencode(ctx) {
  *     防「Cursor IDE 在别的项目聊天 / 其他项目 opencode 会话活跃」被误报进当前登记。
  * 新增 CLI = 加一个探测器对象 + protocol 文档补布局与格式说明。
  */
+/**
+ * cursor-agent（CLI 子代理，非 Cursor IDE）：transcript = <home>/.cursor/projects/
+ * <encoded-workspace-path>/agent-transcripts/<uuid>/<uuid>.jsonl（{role,message} 行 +
+ * turn_ended 事件）。workspace 目录名是 cwd 的连字符编码（C:/Users/qinyi → C-Users-qinyi，
+ * 路径内合法连字符保留原样——编码不可逆，匹配方向为 cwd→编码名正向比对）→ **precise** 探测：
+ * 逐 cwdCandidate 编码后与目录名精确相等才登记（数字目录名无从解码，跳过不误报）。
+ * 归属规则与 zcode/claude-code 同款（本会话 cwd 即 workspace 根）；token 不落盘属数据源
+ * 缺失（usage 未知，平台侧 FR-03 口径不伪造）。
+ * 坑 cursor-agent-transcript-report-pipeline（2026-09-19 平台侧就绪声明）：daemon 解析器
+ * 注册键 `cursor-agent-transcript-jsonl` 必须与此处 format 串逐字一致。
+ */
+function detectCursorAgentTranscripts(ctx) {
+  const { cwdCandidates, homeDir, now, windowMs } = ctx;
+  const projectsRoot = join(homeDir, '.cursor', 'projects');
+  let projectDirs;
+  try {
+    projectDirs = readdirSync(projectsRoot, { withFileTypes: true }).filter(d => d.isDirectory());
+  } catch { return []; }
+  // cwd → 编码名（正向，避免解码歧义）：盘符冒号与路径分隔符全部 → '-'
+  const encodeCwd = (p) => toPosix(String(p)).replace(/^([a-zA-Z]):/, '$1').replace(/[/:]/g, '-');
+  const wanted = new Set(cwdCandidates.filter(Boolean).map(encodeCwd));
+  if (wanted.size === 0) return [];
+  const entries = [];
+  for (const proj of projectDirs) {
+    if (!wanted.has(proj.name)) continue;
+    const tsRoot = join(projectsRoot, proj.name, 'agent-transcripts');
+    let sessionDirs;
+    try {
+      sessionDirs = readdirSync(tsRoot, { withFileTypes: true }).filter(d => d.isDirectory());
+    } catch { continue; }
+    for (const sess of sessionDirs) {
+      let files;
+      try {
+        files = readdirSync(join(tsRoot, sess.name)).filter(f => f.endsWith('.jsonl'));
+      } catch { continue; }
+      for (const f of files) {
+        const full = join(tsRoot, sess.name, f);
+        const st = statSafe(full);
+        if (!st || now - st.mtimeMs > windowMs) continue;
+        entries.push({
+          harness: 'cursor-agent', format: 'cursor-agent-transcript-jsonl',
+          detected_via: 'cursor-agent-transcript-scan',
+          log_path: toPosix(full), agent_cwd: toPosix(cwdCandidates[0] || ''),
+          session_id: sess.name, originator: null,
+          mtime_ms: st.mtimeMs,
+        });
+      }
+    }
+  }
+  entries.sort((a, b) => b.mtime_ms - a.mtime_ms);
+  return entries.slice(0, 3);
+}
+
 const HARNESS_DETECTORS = [
   { name: 'claude-code', tier: 'precise', detect: detectClaudeCode },
   { name: 'codex', tier: 'precise', detect: detectCodex },
   { name: 'zcode', tier: 'precise', detect: detectZcode },
   { name: 'pi', tier: 'precise', detect: detectPi },
   { name: 'deepseek-dsh', tier: 'precise', detect: detectDsh },
+  { name: 'cursor-agent', tier: 'precise', detect: detectCursorAgentTranscripts },
   { name: 'cursor', tier: 'loose', detect: detectCursor },
   { name: 'opencode', tier: 'loose', detect: detectOpencode },
 ];

package/src/config-schema.js

@@ -156,7 +156,7 @@ export const LOCAL_YAML_SCHEMA = {
     {
       id: 'gate_snapshot',
       title: '门禁隔离快照 copy 面',
-      note: '门禁快照（gate-snapshot）= HEAD worktree + 会话文件 overlay + 环境目录 junction——gitignored 生成物（api-types/generated 类）不进 HEAD 也不在会话集，快照内 lint/test 环境性假败（2026-09-16 驾驭小结④，friction5-hardening R4 / D-002@v1）。按本清单在快照构建期从主仓 junction 链接补齐（失败回退复制）；快照内 overlay 已覆盖的同名路径跳过（本变更最新态优先）。⚠️ junction 是活链接：快照内再跑生成命令会写穿到主仓该目录。',
+      note: '门禁快照（gate-snapshot）= HEAD worktree + 会话文件 overlay + 环境目录 junction——gitignored 生成物（类型生成/代码生成产物类）不进 HEAD 也不在会话集，快照内 lint/test 环境性假败（2026-09-16 驾驭小结④，friction5-hardening R4 / D-002@v1）。按本清单在快照构建期从主仓 junction 链接补齐（失败回退复制）；快照内 overlay 已覆盖的同名路径跳过（本变更最新态优先）。⚠️ junction 是活链接：快照内再跑生成命令会写穿到主仓该目录。',
       keys: [
         { path: 'gate_snapshot.copy', type: 'array', optional: true, status: 'live', readers: ['createGateSnapshot (src/run/gate-snapshot.js)'], desc: '门禁隔离快照的生成物/额外路径 copy 面（元素 string，相对仓根）：HEAD 快照缺 gitignored 生成物导致 lint/test 环境性假败；声明后快照构建期从主仓 junction 链接（失败回退复制）。⚠️ junction 是活链接，快照内再跑生成命令会写穿到主仓该目录。未配置/空清单 = 全段空转零行为变化。', example: 'gate_snapshot:\n  copy:\n    - src/generated' },
         { path: 'gate_snapshot.commands', type: 'array', optional: true, status: 'live', readers: ['parseGateSnapshotCommands + runGateSnapshotCommands (src/run/gate-snapshot.js — createGateSnapshot 环境预检后 copy 面前)'], desc: '门禁隔离快照的命令面（元素 string）：快照构建期在环境目录链接后、copy 面前于快照根逐条执行（cwd=快照根、300s/条超时帽、非零退出/超时只 warn 继续——fail-open 不作废快照），产出「本仓应然态」生成物，收口主仓生成物缺失/过期（fresh clone 未跑 postinstall / build-id 类产物）时快照内全量 lint/test 必挂的坑（D-002@v2，2026-09-17-feedback-hardening FR-01）。⚠️ 环境目录（node_modules/venv）是活链接，命令写它们会穿透主仓——只放生成物命令（npm run gen:build-id 类），不放 install/build 全家桶。未配置 = 全段空转零行为。', example: 'npm run gen:build-id' },

package/src/fr-index.js

@@ -54,32 +54,79 @@ export function parseChangeRequirements(changeDir) {
   const frs = [];
   const malformed = [];
   const lines = content.replace(/\r\n/g, '\n').split('\n');
+  // L2（2026-09-20-fr-index-l2）：决策覆盖矩阵解析——requirements.md 尾表行
+  // `| D-xxx@vN | FR-01, FR-02 |` 提取 D→FR-NN 映射（local 号），归档时随条目落「依据决策：」行。
+  // 格式漂移/缺矩阵 → decisions 恒 []（省略行降级，不阻断归档）。
+  const decisionMap = new Map();
+  for (const line of lines) {
+    const m = line.match(/^\|\s*(D-\d+@v\d+)\s*\|([^|]+)\|/);
+    if (!m) continue;
+    for (const tok of m[2].split(/[,，、]/)) {
+      const fr = tok.trim().match(/^(FR-\d+)$/);
+      if (!fr) continue;
+      if (!decisionMap.has(fr[1])) decisionMap.set(fr[1], []);
+      decisionMap.get(fr[1]).push(m[1]);
+    }
+  }
   let cur = null;
+  // L2 厚版（D-003@v2）：GWT 行捕获——Given/When/Then 归最近场景名下（无名归默认场景）。
+  // scenarioBodies: [{name, given, when, then}]；scenarios（名字数组）保留 L1 契约不动。
   for (const line of lines) {
     const h = line.match(/^###\s+(FR-\d+)\s*[:：]\s*(.*)$/);
     if (h) {
       if (cur) frs.push(cur);
-      cur = { local: h[1], title: (h[2] || '').trim(), supersedes: [], scenarios: [] };
+      cur = { local: h[1], title: (h[2] || '').trim(), supersedes: [], scenarios: [], decisions: decisionMap.get(h[1]) || [], __bodies: [{ name: null, given: '', when: '', then: '' }] };
       continue;
     }
     if (!cur) continue;
     const s = line.match(/^\s*承接\s*[:：]\s*(.+)$/);
     if (s) {
       for (const tok of s[1].split(/[,，、]/)) {
-        const id = tok.trim();
-        if (!id) continue;
-        if (FR_GLOBAL_ID_RE.test(id)) cur.supersedes.push(id);
-        else malformed.push(`${cur.local} 的承接行含非全局 id 形态「${id}」（应为 FR-<域>-NNN）`);
+        const t = tok.trim();
+        if (!t) continue;
+        // 退役理由语法（追平刀②，对标 OpenSpec REMOVED 语义）：`FR-域-NNN（退役理由：一句话）`
+        //——理由随承接令牌走，翻链时写进被取代条目。理由内禁逗号（token 切分边界）。
+        const rm = t.match(/^(FR-[A-Za-z0-9-]+)[（(]\s*退役理由[：:]\s*([^）)]+)[）)]$/);
+        if (rm) {
+          if (FR_GLOBAL_ID_RE.test(rm[1])) {
+            cur.supersedes.push(rm[1]);
+            if (!cur.supersedeReasons) cur.supersedeReasons = {};
+            cur.supersedeReasons[rm[1]] = rm[2].trim();
+          } else {
+            malformed.push(`${cur.local} 的承接行退役理由令牌含非全局 id 形态「${rm[1]}」（应为 FR-<域>-NNN）`);
+          }
+          continue;
+        }
+        if (FR_GLOBAL_ID_RE.test(t)) cur.supersedes.push(t);
+        else malformed.push(`${cur.local} 的承接行含非全局 id 形态「${t}」（应为 FR-<域>-NNN）`);
       }
       continue;
     }
     const sc = line.match(/^\s*(?:#{2,4}\s*场景\s*[:：]\s*(.+)|\*\*场景\s*[:：]\s*([^*]+)\*\*)\s*$/);
     if (sc) {
-      const name = ((sc[1] || sc[2] || '')).trim();
-      cur.scenarios.push(name || `场景${cur.scenarios.length + 1}`);
+      const name = ((sc[1] || sc[2] || '')).trim() || `场景${cur.scenarios.length + 1}`;
+      cur.scenarios.push(name);
+      cur.__bodies.push({ name, given: '', when: '', then: '' });
+      continue;
+    }
+    const gwt = line.match(/^\s*(Given|When|Then)\s+(.+)$/i);
+    if (gwt) {
+      const body = cur.__bodies[cur.__bodies.length - 1];
+      const key = gwt[1].toLowerCase();
+      body[key] = (body[key] ? body[key] + ' ' : '') + gwt[2].trim();
+      // 无名默认场景已收 GWT → 命名并同步进 scenarios 名字数组（L1 摘要契约兼容）
+      if (body.name === null && cur.scenarios.length === 0 && (body.given || body.when || body.then)) {
+        cur.scenarios.push('默认场景');
+        body.name = '默认场景';
+      }
     }
   }
   if (cur) frs.push(cur);
+  // 剥离内部键，暴露 scenarioBodies（有 GWT 内容的体块才进）
+  for (const fr of frs) {
+    fr.scenarioBodies = (fr.__bodies || []).filter((b) => b.name !== null || b.given || b.when || b.then).map((b) => ({ name: b.name, given: b.given, when: b.when, then: b.then }));
+    delete fr.__bodies;
+  }
   return { missing: false, frs, malformed };
 }
 
@@ -129,6 +176,7 @@ function loadDomainSections(knowledgeRoot, domain) {
         '',
         '> fr-index 从归档变更 requirements.md 幂等提炼（「最近确认」= 归档时 HEAD）。条目字段行为机械解析契约，勿手改。',
         '> superseded 条目保留供取代链回溯；brainstorm 注入默认只给 active。',
+        `> 模块卡：modules/${domain}.md（域=模块 id 同构；行为条目↔模块契约互跳）`,
         '',
       ],
       sections: [],
@@ -153,6 +201,26 @@ function renderFrLines(entry, headHash) {
   if (entry.supersededBy) lines.push(`superseded_by：${entry.supersededBy}`);
   if (entry.supersededOf) lines.push(`取代链：${entry.supersededOf} ← 本条目（${entry.change} 承接）`);
   lines.push(`摘要：${(entry.scenarios || []).slice(0, 5).join('；') || '（无场景名）'}`);
+  // L2：依据决策行（决策覆盖矩阵提取；空省略——旧条目无此行照常解析）。
+  if (Array.isArray(entry.decisions) && entry.decisions.length > 0) {
+    lines.push(`依据决策：${entry.decisions.join('、')}`);
+  }
+  // L2 厚版（D-003@v2）：场景正文块——每场景一行（各段截 80 字，≤5 场景）。
+  // 空体块省略整块；回填幂等锚=「场景正文：」行在场即跳过。
+  const bodies = (entry.scenarioBodies || []).filter((b) => b.given || b.when || b.then).slice(0, 5);
+  if (bodies.length > 0) {
+    lines.push('场景正文：');
+    const cut = (s) => String(s || '').slice(0, 80);
+    for (const b of bodies) {
+      const parts = [`Given ${cut(b.given)}`, `When ${cut(b.when)}`, `Then ${cut(b.then)}`].filter((p) => !p.endsWith(' '));
+      lines.push(`- 场景：${b.name || '默认场景'} — ${parts.join('；')}`);
+    }
+  }
+  // 全文锚（追平刀①）：正文是截断摘要，全文活在来源归档——引用行不复制正文零体积税，
+  // 锚=归档 requirements.md 内的 FR 局部号标题（### FR-NN:），docs-check 层1 可校验存在性。
+  if (entry.local) {
+    lines.push(`全文：.sillyspec/changes/archive/${entry.change}/requirements.md#${entry.local}`);
+  }
   lines.push(`最近确认：${headHash || ''}`);
   return lines;
 }
@@ -241,7 +309,7 @@ export function indexRequirements({ changeDir, knowledgeRoot, headHash = '' }) {
       id,
       title: fr.title,
       change: changeName,
-      lines: renderFrLines({ id, title: fr.title, change: changeName, scenarios: fr.scenarios }, headHash),
+      lines: renderFrLines({ id, title: fr.title, change: changeName, scenarios: fr.scenarios, decisions: fr.decisions, scenarioBodies: fr.scenarioBodies, local: fr.local }, headHash),
     });
     dirtyDomains.add(primaryDomain);
     written.push({ file: `${FR_DIR}/${primaryDomain}.md`, id, action: 'added' });
@@ -254,9 +322,15 @@ export function indexRequirements({ changeDir, knowledgeRoot, headHash = '' }) {
         // 就地补丁：状态翻 superseded + 插 superseded_by + 追取代链注记 + 刷新最近确认（摘要/标题保留）
         target.lines = target.lines
           .map((l) => (l.startsWith('状态：') ? `状态：superseded` : l.startsWith('最近确认：') ? `最近确认：${headHash || ''}` : l))
-          .filter((l) => !l.startsWith('superseded_by：') && !l.startsWith('取代链：'));
+          .filter((l) => !l.startsWith('superseded_by：') && !l.startsWith('取代链：') && !l.startsWith('退役理由：'));
         const stateIdx = target.lines.findIndex((l) => l.startsWith('状态：'));
-        target.lines.splice(stateIdx + 1, 0, `superseded_by：${id}`, `取代链：${refId} ← ${id}（${changeName} 承接）`);
+        // 退役理由（追平刀②）：承接令牌带（退役理由：…）时写进被取代条目——对标 OpenSpec REMOVED
+        // 的 Migration 语义；无理由则省略行（不伪造）。
+        const reason = fr.supersedeReasons && fr.supersedeReasons[refId];
+        target.lines.splice(stateIdx + 1, 0,
+          `superseded_by：${id}`,
+          `取代链：${refId} ← ${id}（${changeName} 承接）`,
+          ...(reason ? [`退役理由：${reason}`] : []));
         dirtyDomains.add(st2Domain);
         superseded.push({ from: refId, to: id, change: changeName });
       }
@@ -322,6 +396,138 @@ export function scanFrIndex(knowledgeRoot) {
   return out;
 }
 
+/**
+ * L2 厚版（D-003@v2 / FR-04）：存量回填——active 条目缺「场景正文：」块 → 从其来源
+ * 变更的归档 requirements.md 按标题匹配补齐（fallback 按序）。幂等：已有正文块的条目
+ * 跳过；来源归档缺失/标题不匹配 → 警告不阻断。回填只动正文块，其余行（摘要/依据决策/
+ * 状态链/最近确认）原样保留。
+ * @param {object} opts
+ * @param {string} opts.knowledgeRoot - knowledge/ 目录
+ * @param {string} opts.archiveRoot - changes/archive/ 目录
+ * @returns {{backfilled: Array<{file,id,title}>, skipped: number, warnings: string[]}}
+ */
+export function backfillScenarioBodies({ knowledgeRoot, archiveRoot }) {
+  const backfilled = [];
+  const warnings = [];
+  let skipped = 0;
+  // 归档 requirements 缓存：changeName → parse 结果（多条目共享一次读盘）
+  const parsedCache = new Map();
+  const parseArchive = (changeName) => {
+    if (parsedCache.has(changeName)) return parsedCache.get(changeName);
+    const dir = join(archiveRoot, changeName);
+    let result = null;
+    try { result = parseChangeRequirements(dir); } catch { result = { missing: true, frs: [] }; }
+    if (!result || result.missing) {
+      warnings.push(`来源归档缺 requirements.md：${changeName}（该条目正文不回填）`);
+    }
+    parsedCache.set(changeName, result);
+    return result;
+  };
+  let files;
+  try { files = readdirSync(frDirPath(knowledgeRoot)).filter((f) => f.endsWith('.md')); }
+  catch { return { backfilled: [], skipped: 0, warnings: ['knowledge/fr 目录不可读'] }; }
+  for (const f of files) {
+    const p = join(frDirPath(knowledgeRoot), f);
+    let content;
+    try { content = readFileSync(p, 'utf8'); } catch (e) { warnings.push(`读 ${f} 失败（${e && e.code ? e.code : 'error'}）跳过`); continue; }
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    // 按条目分段：## 开头为新段；段内判定「场景正文：」在场性
+    const out = [];
+    let sectionLines = [];
+    let sectionMeta = null; // {title, change, hasBody, backfilled}
+    const flushSection = () => {
+      if (sectionMeta === null) return;
+      // 全文锚回填（追平刀①）：独立于正文块——已有正文（或 superseded）的条目缺锚同样补
+      //（正文块早退分支之前的必经路径；锚插入位=场景正文/摘要行后）。
+      let anchoredThisSection = false;
+      if (sectionMeta.change && !sectionLines.some((l) => l.startsWith('全文：'))) {
+        const parsedA = parseArchive(sectionMeta.change);
+        if (parsedA && !parsedA.missing) {
+          let srcA = parsedA.frs.find((fr) => (fr.title || '').trim() === sectionMeta.title);
+          if (!srcA) srcA = parsedA.frs[sectionMeta.ordInChange - 1] || null;
+          if (srcA) {
+            const isSceneLine = (l) => l.startsWith('场景正文：') || l.startsWith('- 场景：');
+            const aIdx = sectionLines.findLastIndex ? sectionLines.findLastIndex(isSceneLine) : -1;
+            const fallbackIdx = sectionLines.findLastIndex ? sectionLines.findLastIndex((l) => l.startsWith('摘要：')) : -1;
+            sectionLines.splice(Math.max(aIdx, fallbackIdx) + 1, 0, `全文：.sillyspec/changes/archive/${sectionMeta.change}/requirements.md#${srcA.local}`);
+            backfilled.push({ file: `fr/${f}`, id: sectionMeta.id, title: sectionMeta.title, what: '全文锚' });
+            anchoredThisSection = true;
+          }
+        }
+      }
+      if (sectionMeta.hasBody || !sectionMeta.change) {
+        if (!sectionMeta.hasBody) skipped++;
+        out.push(...sectionLines);
+        return;
+      }
+      const parsed = parseArchive(sectionMeta.change);
+      if (!parsed || parsed.missing) { skipped++; out.push(...sectionLines); return; }
+      // 标题匹配（剥 FR-x-NNN 前缀后的标题全等；fallback 按序：本域文件中该来源变更的第 n 条）
+      const bareTitle = sectionMeta.title;
+      let src = parsed.frs.find((fr) => (fr.title || '').trim() === bareTitle);
+      if (!src) {
+        const sameChange = parsed.frs;
+        src = sameChange[sectionMeta.ordInChange - 1] || null;
+        if (src) warnings.push(`${f} 的「${sectionMeta.title}」按序匹配回填（标题不精确匹配——建议核对）`);
+      }
+      const bodies = src && Array.isArray(src.scenarioBodies) ? src.scenarioBodies.filter((b) => b.given || b.when || b.then).slice(0, 5) : [];
+      if (!src || bodies.length === 0) {
+        if (!anchoredThisSection) {
+          warnings.push(`${f} 的「${sectionMeta.title}」来源无场景正文可回填（跳过）`);
+          skipped++;
+        }
+        out.push(...sectionLines);
+        return;
+      }
+      // 就地插入：状态行后（依据决策行若有则其后）
+      const insertAfter = Math.max(
+        sectionLines.findLastIndex ? sectionLines.findLastIndex((l) => l.startsWith('依据决策：')) : -1,
+        sectionLines.findLastIndex ? sectionLines.findLastIndex((l) => l.startsWith('摘要：')) : -1,
+      );
+      const block = ['场景正文：'];
+      const cut = (s) => String(s || '').slice(0, 80);
+      for (const b of bodies) {
+        const parts = [`Given ${cut(b.given)}`, `When ${cut(b.when)}`, `Then ${cut(b.then)}`].filter((x) => !x.endsWith(' '));
+        block.push(`- 场景：${b.name || '默认场景'} — ${parts.join('；')}`);
+      }
+      sectionLines.splice(insertAfter + 1, 0, ...block);
+      backfilled.push({ file: `fr/${f}`, id: sectionMeta.id, title: sectionMeta.title });
+      out.push(...sectionLines);
+    };
+    let ordCounter = new Map(); // changeName → 该来源在当前文件已见条目数
+    for (const line of lines) {
+      const hm = line.match(/^##\s+(FR-[A-Za-z0-9-]+)\s+(.*)$/);
+      if (hm) {
+        flushSection();
+        sectionLines = [line];
+        const changeLine = null; // 变更行在下文读取；先记标题
+        sectionMeta = { title: hm[2].trim(), change: null, hasBody: false, id: hm[1], ordInChange: 0 };
+        continue;
+      }
+      sectionLines.push(line);
+      if (sectionMeta) {
+        if (line.startsWith('变更：')) {
+          sectionMeta.change = line.replace(/^变更：\s*/, '').trim();
+          const n = (ordCounter.get(sectionMeta.change) || 0) + 1;
+          ordCounter.set(sectionMeta.change, n);
+          sectionMeta.ordInChange = n;
+        }
+        if (line.startsWith('状态：superseded')) sectionMeta.hasBody = true; // superseded 条目不回填（历史回溯面）
+        if (line.startsWith('场景正文：')) sectionMeta.hasBody = true;
+      }
+    }
+    flushSection();
+    if (backfilled.length > 0 || content !== out.join('\n')) {
+      // 仅当本文件确有回填才写盘（无回填保持字节不变）
+      const orig = content.replace(/\r\n/g, '\n');
+      if (out.join('\n') !== orig) {
+        try { writeFileSync(p, out.join('\n')); } catch (e) { warnings.push(`写 ${f} 失败（${e && e.message ? e.message : e}）`); }
+      }
+    }
+  }
+  return { backfilled, skipped, warnings };
+}
+
 /**
  * 注入源：触达域的 active 条目（superseded 默认藏——D-004）。
  * @returns {Array<{domain,id,title,change,scenarios:string[]}>}
@@ -333,8 +539,10 @@ export function readActiveFrDigest(knowledgeRoot, domains) {
     for (const s of st.sections) {
       if (s.lines.some((l) => l.startsWith('superseded_by：'))) continue;
       const scenarioLine = s.lines.find((l) => l.startsWith('摘要：'));
+      const decisionLine = s.lines.find((l) => l.startsWith('依据决策：'));
+      const decisions = decisionLine ? decisionLine.replace(/^依据决策：s*/, '').split('、').map((x) => x.trim()).filter(Boolean) : [];
       const scenarios = scenarioLine ? scenarioLine.replace(/^摘要：\s*/, '').split('；').map((x) => x.trim()).filter(Boolean) : [];
-      out.push({ domain, id: s.number, title: s.title || '', change: s.change || '', scenarios });
+      out.push({ domain, id: s.number, title: s.title || '', change: s.change || '', scenarios, decisions });
     }
   }
   return out;

package/src/handoff.js

@@ -0,0 +1,113 @@
+/**
+ * handoff.js —— 阶段跑者瘦会话交接块生成器（P1-5 v1，2026-09-20 对撞实验驱动）
+ *
+ * 为什么需要：单会话跑全流程时主上下文 ~300K 底座 × 每 CLI 往返重发一次——对撞实验
+ * 实测 sillyspec 侧主会话 203 请求烧 63M（肥上下文编排税是最大浪费源）。而 CLI prompt
+ * 本就自足（进度快照/模块命中/知识注入全由进度库与 prompt 渲染提供，新会话零背景可
+ * 续跑）——「每阶段一个瘦会话」是零机制改动的省法，缺的只是把交接信息打成一块可粘贴。
+ *
+ * 定位：纯只读（ProgressManager 读路径 + 环境探测），不写盘不动状态。输出三件：
+ *   ① 新会话启动块（保持 SILLYSPEC_SESSION_ID 不变——变更所有权按此判定）；
+ *   ② 下一阶段建议（当前阶段完成 → MAIN_FLOW_ORDER 后继；进行中 → 同阶段续跑）；
+ *   ③ 当前状态摘要（阶段进度 + 停留步骤）。
+ */
+import { ProgressManager, resolveSpecDir } from './progress.js';
+import { MAIN_FLOW_ORDER, STAGE_LABELS } from './progress/shared.js';
+
+/**
+ * 解析下一阶段建议。
+ * @param {string} currentStage - DB 当前阶段
+ * @param {boolean} stageCompleted - 当前阶段是否已完成（进度库 stageData.status === 'completed'）
+ * @returns {{ next: string, mode: 'advance' | 'resume', reason: string }}
+ */
+export function nextStageSuggestion(currentStage, stageCompleted) {
+  if (!currentStage) return { next: 'brainstorm', mode: 'resume', reason: '无进度记录，从头脑风暴起步' };
+  if (!stageCompleted) {
+    return { next: currentStage, mode: 'resume', reason: `${STAGE_LABELS[currentStage] || currentStage} 进行中——新会话续跑本阶段（步骤态由进度库恢复）` };
+  }
+  const idx = MAIN_FLOW_ORDER.indexOf(currentStage);
+  if (idx >= 0 && idx < MAIN_FLOW_ORDER.length - 1) {
+    const next = MAIN_FLOW_ORDER[idx + 1];
+    return { next, mode: 'advance', reason: `${STAGE_LABELS[currentStage] || currentStage} 已完成——新会话开跑下一阶段 ${STAGE_LABELS[next] || next}` };
+  }
+  if (currentStage === 'archive') {
+    return { next: '', mode: 'done', reason: '流程已归档终态——无下一阶段（可 sillyspec progress show 复核或开新变更）' };
+  }
+  // 辅助阶段（quick/scan/explore/status/doctor）完成：建议回主流程或开新
+  return { next: 'brainstorm', mode: 'resume', reason: `辅助阶段 ${STAGE_LABELS[currentStage] || currentStage} 完成——主流程变更请带 --change 续跑，或开新变更` };
+}
+
+/**
+ * 生成交接块（human 模式行数组 / --json 由调用方取结构）。
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {string} [opts.specBase] - 平台模式 specRoot；缺省 resolveSpecDir
+ * @param {string} [opts.changeName] - 变更名；缺省取唯一活跃主流程变更
+ * @returns {Promise<{ok:true, change, currentStage, stageCompleted, suggestion, sessionId, lines:string[]}|{ok:false, error:string}>}
+ */
+export async function buildHandoff({ cwd, specBase, changeName } = {}) {
+  const specRoot = specBase || resolveSpecDir(cwd);
+  const pm = new ProgressManager({ specDir: specRoot });
+
+  let target = changeName;
+  let picked = false;
+  if (!target) {
+    // 唯一活跃主流程变更自动选中（listChanges=目录+DB 联合口径，read 取 currentStage）
+    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 (mains.length === 1) {
+      target = mains[0].name;
+      picked = true;
+    } 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 面向主流程阶段交接' };
+    }
+  }
+
+  const progress = pm.read(cwd, target);
+  if (!progress) return { ok: false, error: `变更不存在: ${target}` };
+
+  const currentStage = progress.currentStage || '';
+  const stageData = (progress.stages && progress.stages[currentStage]) || null;
+  const stageCompleted = !!(stageData && stageData.status === 'completed');
+  const suggestion = nextStageSuggestion(currentStage, stageCompleted);
+  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;
+
+  const lines = [];
+  lines.push('🔗 交接块（瘦会话模式——下一阶段/续跑在新会话执行，主会话收尾省上下文）');
+  lines.push('');
+  lines.push('# ── 在新会话粘贴以下内容 ──');
+  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) {
+    lines.push(`sillyspec run ${suggestion.next} --change ${target}`);
+  } else {
+    lines.push('# （流程终态，无续跑命令）');
+  }
+  lines.push('# ── 交接块结束 ──');
+  lines.push('');
+  lines.push(`📋 ${target}：当前 ${STAGE_LABELS[currentStage] || currentStage}${steps.length > 0 ? `（步骤 ${doneSteps}/${steps.length}）` : ''}${stageCompleted ? ' ✅ 已完成' : ''}`);
+  lines.push(`➡️ ${suggestion.reason}`);
+  lines.push('💡 为什么可行：CLI prompt 自足——进度快照/模块命中/知识注入由进度库与渲染提供，新会话零背景可续跑。');
+  lines.push('⚠️ SILLYSPEC_SESSION_ID 必须保持不变（变更所有权/接管判定按此标识）；缺省降级机器级标识只拦他机。');
+
+  return {
+    ok: true,
+    change: target,
+    autoPicked: picked,
+    currentStage,
+    stageCompleted,
+    suggestion,
+    sessionId,
+    lines,
+  };
+}

package/src/index.js

@@ -3402,6 +3402,58 @@ SillySpec worktree — git worktree 隔离管理
       await cmdAgentLog(filteredArgs.slice(1), { json, cwd: dir, specDir });
       break;
     }
+    case 'handoff': {
+      // 阶段跑者瘦会话交接块（P1-5 v1，2026-09-20 对撞实验驱动）：打印下一阶段新会话
+      // 启动块（保持 SILLYSPEC_SESSION_ID）+ 状态摘要。纯只读。CLI prompt 自足——
+      // 新会话零背景可续跑，主会话按阶段收尾省肥上下文重发税。
+      const hoChangeIdx = filteredArgs.indexOf('--change');
+      const hoChange = hoChangeIdx >= 0 ? filteredArgs[hoChangeIdx + 1] : undefined;
+      const { buildHandoff } = await import('./handoff.js');
+      const specRootHo = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const ho = await buildHandoff({ cwd: dir, specBase: specRootHo, changeName: hoChange });
+      if (!ho.ok) {
+        console.error(`❌ ${ho.error}`);
+        process.exit(2);
+      }
+      if (json) {
+        console.log(JSON.stringify({
+          schema_version: 1,
+          change: ho.change,
+          auto_picked: ho.autoPicked,
+          current_stage: ho.currentStage,
+          stage_completed: ho.stageCompleted,
+          next_stage: ho.suggestion.next,
+          mode: ho.suggestion.mode,
+          session_id: ho.sessionId,
+        }, null, 2));
+      } else {
+        for (const l of ho.lines) console.log(l);
+      }
+      break;
+    }
+    case 'fr-backfill': {
+      // L2 厚版（2026-09-20-fr-index-l2 / D-003@v2 / FR-04）：存量 FR 条目场景正文回填——
+      // active 条目缺「场景正文：」块 → 从来源变更归档 requirements.md 按标题匹配补齐
+      //（幂等；superseded 不回填；来源缺失警告不阻断）。一次性/手动命令，归档管线不挂载。
+      const specRootFb = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const { backfillScenarioBodies } = await import('./fr-index.js');
+      const r = backfillScenarioBodies({
+        knowledgeRoot: join(specRootFb, 'knowledge'),
+        archiveRoot: join(specRootFb, 'changes', 'archive'),
+      });
+      if (json) {
+        console.log(JSON.stringify({ schema_version: 1, backfilled: r.backfilled, skipped: r.skipped, warnings: r.warnings }, null, 2));
+      } else {
+        if (r.backfilled.length === 0) {
+          console.log(`✅ 无待回填条目（已有正文或无来源可回填 ${r.skipped} 条跳过）`);
+        } else {
+          console.log(`📦 回填 ${r.backfilled.length} 条：`);
+          for (const b of r.backfilled) console.log(`   - ${b.id} ${b.title}（${b.file}）`);
+        }
+        for (const w of r.warnings) console.warn(`   ⚠️ ${w}`);
+      }
+      break;
+    }
     case 'dispatch': {
       // SillyHub 派发抽象层的 agent 调用桥（design.md §Phase2 / D-007@v1）：
       // 仅做能力探测（probe）与派发策略生成（hint），**不执行任何 tool 调用**——