agentic-flow-kit 1.7.0 → 1.7.15

package/templates/_agents/scripts/check-loop.test.mjs

@@ -13,7 +13,7 @@ import { fileURLToPath } from 'node:url';
 import { computeFingerprint } from './confirm-doc.mjs';
 import { POLICIES, loadKitPolicy } from './policy.mjs';
 import { entryConfirmed, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
-import { parseAddedDatesLog, addedDatesWithCache } from './check-loop.mjs';
+import { parseAddedDatesLog, addedDatesWithCache, scenarioIdsOf, extractThenByScenario, sectionHasBody, sedimentLandingIsShell } from './check-loop.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CHECK_LOOP = path.join(SCRIPT_DIR, 'check-loop.mjs');
@@ -3023,5 +3023,315 @@ w(T, 'workflow/intents/2026-09-12-deep.md', INTENT('deep', '状态: draft\n级
   fs.rmSync(cacheP, { force: true });
 }
 
+// ---- 场景 23：场景覆盖子判据（2026-10-10 scenario-coverage，灰度 warning）----
+// scenarioIdsOf 纯函数 + 端到端（spec 有「验收场景」节 → done intent 须逐场景引用；缺 = warning 不阻断）
+{
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'scen-ids-'));
+  fs.writeFileSync(path.join(d, 's1.md'),
+    '---\n状态: draft\n---\n# SPEC\n## 功能行为\n### S0 不该被提取（节外）\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- WHEN y\n- THEN z\n### S2 退款\n- GIVEN a\n## 数据流\n### S3 也不提取（节外）\n');
+  const ids = scenarioIdsOf(path.join(d, 's1.md'));
+  check('场景 24a scenarioIdsOf：只提「验收场景」节内 ID，按序去重', ids.join(',') === 'S1,S2', JSON.stringify(ids));
+  fs.writeFileSync(path.join(d, 's2.md'), '---\n状态: draft\n---\n# SPEC\n## 功能行为\n无场景节\n');
+  check('场景 24b scenarioIdsOf：无「验收场景」节 → 空数组', scenarioIdsOf(path.join(d, 's2.md')).length === 0);
+  check('场景 24c scenarioIdsOf：文件不可读 → 空数组（fail-open）', scenarioIdsOf(path.join(d, 'nope.md')).length === 0);
+  fs.rmSync(d, { recursive: true, force: true });
+}
+{
+  // 端到端：spec 两场景 + intent 全引用 → exit 0 且无「场景未覆盖」warning
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-sc.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — sc\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- WHEN y\n- THEN z\n### S2 退款\n- GIVEN a\n');
+  w(T, 'workflow/intents/2026-09-12-sc.md', INTENT('sc', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1 折扣生效（证据:冒烟 checkout.json）\n- [x] 场景：S2 退款到账（证据:refund.test.js）\n'));
+  w(T, 'workflow/plans/2026-09-12-sc.md', PLAN('sc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 24d spec 有场景且 intent 全引用 → exit 0 无告警', r.status === 0 && !outOf(r).includes('场景未覆盖'), `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+{
+  // 端到端：缺 S2 引用 → warning（灰度，不阻断：exit 仍 0）
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-sc.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — sc\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n### S2 退款\n- GIVEN a\n');
+  w(T, 'workflow/intents/2026-09-12-sc.md', INTENT('sc', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1 折扣生效（证据:冒烟 checkout.json）\n'));
+  w(T, 'workflow/plans/2026-09-12-sc.md', PLAN('sc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 24e 缺场景引用 → warning 且不阻断（exit 0）',
+    r.status === 0 && outOf(r).includes('场景未覆盖') && outOf(r).includes('缺 S2'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 端到端：spec 无场景节 → 零变化（不出现「场景未覆盖」）
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-sc.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — sc\n## 功能行为\n普通 spec\n');
+  w(T, 'workflow/intents/2026-09-12-sc.md', INTENT('sc', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n'));
+  w(T, 'workflow/plans/2026-09-12-sc.md', PLAN('sc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 24f spec 无场景节 → 零变化（无场景告警，exit 0）', r.status === 0 && !outOf(r).includes('场景未覆盖'), `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+
+// ---- 场景 25：沉淀追踪子判据（2026-10-10 sediment-tracking，灰度 warning）----
+// sectionHasBody 纯函数 + 端到端（done intent 含影响面/触达红线 且 frontmatter 无「沉淀」→ WARN 未沉淀；
+// incident closed 且三件套齐全 → 同款；「沉淀: 无」豁免；路径断档 → WARN 沉淀断档）
+{
+  check('场景 25a sectionHasBody：标题后有实质行 → true',
+    sectionHasBody(['## 影响面', '- 页面 A', ''], '影响面') === true);
+  check('场景 25b sectionHasBody：光标题（模板未填）→ false',
+    sectionHasBody(['## 影响面', '<页面 / 接口 / 数据范围>', ''], '影响面') === false);
+  check('场景 25c sectionHasBody：无该节 → false',
+    sectionHasBody(['## 目标', '做 X'], '影响面') === false);
+  check('场景 25d sectionHasBody：前缀匹配 + 节外有同名行不算',
+    sectionHasBody(['## 目标', '提影响面', '## 影响面与边界', '- 内容'], '影响面') === true);
+}
+{
+  // intent 侧：done + 影响面有内容 + 无沉淀字段 → WARN 未沉淀（不阻断）
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A / 接口 B\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25e done intent 高价值无沉淀 → WARN 未沉淀且不阻断',
+    r.status === 0 && outOf(r).includes('未沉淀') && outOf(r).includes('2026-09-12-sed.md'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 「沉淀: 无」显式豁免 → 无未沉淀告警
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12\n沉淀: 无',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25f 「沉淀: 无」显式豁免 → 无未沉淀告警',
+    r.status === 0 && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 沉淀字段指向不存在的文件 → WARN 沉淀断档
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12\n沉淀: wiki/项目规范/不存在.md',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25g 沉淀字段指向缺失文件 → WARN 沉淀断档',
+    r.status === 0 && outOf(r).includes('沉淀断档') && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // intent 无影响面/触达红线 → 零变化（不出现未沉淀告警）
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25h intent 无高价值节 → 零变化', r.status === 0 && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+{
+  // incident 侧：closed 且三件套齐全 且无沉淀 → WARN 未沉淀
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25i closed incident 三件套齐全无沉淀 → WARN 未沉淀',
+    r.status === 0 && outOf(r).includes('未沉淀') && outOf(r).includes('2026-09-12-inc.md'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // incident 三件套不全 → 沉淀子判据不触发（不出未沉淀，只出三件套不全）
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n1. 结构性修复\n - 修复 commit:abc1234\n - 是否需要新 intent:\n - 否 → 理由:单点修复\n`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25j incident 三件套不全 → 只告三件套不全，不出未沉淀',
+    r.status === 0 && outOf(r).includes('三件套不全') && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+
+// ---- 场景 25 续：落点真实性（2026-10-11 landing-reality，P1-3，灰度 warning）----
+// sedimentLandingIsShell 纯函数 + 端到端（落点只有标题/占位 → WARN 落点空壳；带「来源:」frontmatter
+// 或 ≥3 行非占位正文 → 不出；不存在 → 仍 WARN 沉淀断档（回归）；指向目录（读取失败）→ 空壳并注明读取失败）
+{
+  check('场景 25k sedimentLandingIsShell：只有标题+占位（空壳）→ true',
+    sedimentLandingIsShell('---\n标题: 某主题\n---\n# 某主题\n<状态:待整理>\n') === true);
+  check('场景 25l sedimentLandingIsShell：frontmatter 有「来源:」→ false',
+    sedimentLandingIsShell('---\n来源: workflow/incidents/2026-09-12-inc.md\n---\n# 某主题\n') === false);
+  check('场景 25m sedimentLandingIsShell：非占位正文 ≥3 行 → false',
+    sedimentLandingIsShell('# 某主题\n- 要点一\n- 要点二\n- 要点三\n') === false);
+  check('场景 25n sedimentLandingIsShell：非占位正文仅 2 行 → true',
+    sedimentLandingIsShell('# 某主题\n- 要点一\n- 要点二\n') === true);
+  check('场景 25o sedimentLandingIsShell：读取失败（null）→ true',
+    sedimentLandingIsShell(null) === true);
+}
+{
+  // incident 侧：closed + 三件套齐全 + 沉淀指向只有标题/占位的文件 → WARN 落点空壳（不阻断）
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n沉淀: wiki/项目规范/shell.md\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  w(T, 'wiki/项目规范/shell.md', '---\n标题: 某主题沉淀\n---\n# 某主题沉淀\n<状态:待整理>\n');
+  const r = run(T);
+  check('场景 25p incident 沉淀落点为标题/占位空壳 → WARN 落点空壳',
+    r.status === 0 && outOf(r).includes('落点空壳') && outOf(r).includes('2026-09-12-inc.md')
+    && !outOf(r).includes('沉淀断档') && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // intent 侧对称：done + 影响面有内容 + 沉淀指向空壳文件 → WARN 落点空壳（不阻断）
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12\n沉淀: wiki/项目规范/shell.md',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  w(T, 'wiki/项目规范/shell.md', '# 某主题沉淀\n<待整理>\n');
+  const r = run(T);
+  check('场景 25q intent 沉淀落点为标题/占位空壳 → WARN 落点空壳',
+    r.status === 0 && outOf(r).includes('落点空壳') && outOf(r).includes('2026-09-12-sed.md')
+    && !outOf(r).includes('沉淀断档') && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 落点带「来源:」frontmatter → 非空壳（无落点空壳告警）
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12\n沉淀: wiki/项目规范/real.md',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  w(T, 'wiki/项目规范/real.md', '---\n来源: workflow/incidents/2026-09-12-inc.md\n---\n# 某主题沉淀\n');
+  const r = run(T);
+  check('场景 25r 沉淀落点带来源 frontmatter → 不出落点空壳',
+    r.status === 0 && !outOf(r).includes('落点空壳') && !outOf(r).includes('沉淀断档'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 落点有 ≥3 行非占位正文 → 非空壳（incident 侧非空壳路径）
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n沉淀: wiki/项目规范/real.md\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  w(T, 'wiki/项目规范/real.md', '---\n标题: 某主题沉淀\n---\n# 某主题沉淀\n- 要点一\n- 要点二\n- 要点三\n');
+  const r = run(T);
+  check('场景 25s 沉淀落点有 ≥3 行非占位正文 → 不出落点空壳',
+    r.status === 0 && !outOf(r).includes('落点空壳') && !outOf(r).includes('沉淀断档'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 回归：沉淀指向不存在的文件 → 仍是 WARN 沉淀断档（incident 侧；intent 侧由既有 25g 锚定）
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n沉淀: wiki/项目规范/不存在.md\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25t 沉淀指向缺失文件 → 仍 WARN 沉淀断档（不出落点空壳）',
+    r.status === 0 && outOf(r).includes('沉淀断档') && !outOf(r).includes('落点空壳'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 落点指向目录（readFileSync 抛异常）→ 按空壳出账并在文案注明读取失败
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n沉淀: wiki/项目规范\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  const r = run(T);
+  check('场景 25u 沉淀落点读取失败（目录）→ WARN 落点空壳并注明读取失败',
+    r.status === 0 && outOf(r).includes('落点空壳') && outOf(r).includes('读取失败'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+
+// ---- 场景 92：THEN 断言抽取（2026-10-11 then-assertion，P2-2，灰度 warning）----
+// extractThenByScenario 纯函数 + 端到端（声明场景缺 THEN 行 = 空壳场景 → WARN 场景无断言，聚合一条；
+// 验收场景节本身可选——节不存在零变化）
+{
+  const spec = [
+    '## 验收场景（可选）',
+    '<说明行，不属于任何场景块>',
+    '### S1 折扣',
+    '- GIVEN 购物车有商品 THEN 不误抽（行中段 THEN 字样不算断言）',
+    '- WHEN 结算',
+    '- THEN 折扣金额入账',
+    '  - THEN 重复结算幂等（缩进变体也认）',
+    '### S2 退款',
+    'THEN: 退款单生成（无连字符带冒号也认）',
+    'THEN 审计流水落库（无连字符空格也认）',
+  ].join('\n');
+  const m = extractThenByScenario(spec);
+  check('场景 92a extractThenByScenario：- THEN / 缩进 / THEN: / THEN 变体均抽取',
+    m.get('S1').length === 2 && m.get('S2').length === 2
+    && m.get('S1')[0] === '- THEN 折扣金额入账' && m.get('S2')[0] === 'THEN: 退款单生成（无连字符带冒号也认）',
+    JSON.stringify([...m]));
+  check('场景 92b extractThenByScenario：GIVEN 行中段 THEN 字样不误抽',
+    !m.get('S1').some((s) => s.includes('GIVEN')), JSON.stringify(m.get('S1')));
+  check('场景 92c extractThenByScenario：无验收场景节 → 空 Map（节外 THEN 不认）',
+    extractThenByScenario('# SPEC\n## 功能行为\n- THEN 节外不认\n').size === 0);
+  check('场景 92d extractThenByScenario：非字符串（读取失败）→ 空 Map（不可判定不误报）',
+    extractThenByScenario(null).size === 0);
+}
+{
+  // 端到端：全场景带 THEN → 无「场景无断言」
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-thn.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — thn\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- WHEN y\n- THEN z\n### S2 退款\n- GIVEN a\n- THEN b\n');
+  w(T, 'workflow/intents/2026-09-12-thn.md', INTENT('thn', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1 折扣生效（证据:checkout.json）\n- [x] 场景：S2 退款到账（证据:refund.test.js）\n'));
+  w(T, 'workflow/plans/2026-09-12-thn.md', PLAN('thn', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 92e 全场景带 THEN → 无场景无断言告警（exit 0）',
+    r.status === 0 && !outOf(r).includes('场景无断言'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 端到端：S2/S3 缺 THEN → 聚合一条 WARN，S1（有断言）不在列
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-thn.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — thn\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- THEN z\n### S2 退款\n- GIVEN a\n### S3 对账\n- WHEN c\n');
+  w(T, 'workflow/intents/2026-09-12-thn.md', INTENT('thn', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1（证据:a.log）\n- [x] 场景：S2（证据:b.log）\n- [x] 场景：S3（证据:c.log）\n'));
+  w(T, 'workflow/plans/2026-09-12-thn.md', PLAN('thn', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 92f 场景缺 THEN → 聚合 WARN 且只列缺断言的 ID（S2、S3）',
+    r.status === 0 && outOf(r).includes('场景无断言') && outOf(r).includes('缺 THEN 断言：S2、S3'),
+    `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 端到端：spec 无验收场景节 → THEN 对账不适用（零变化）
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-thn.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — thn\n## 功能行为\n普通 spec，无场景节\n');
+  w(T, 'workflow/intents/2026-09-12-thn.md', INTENT('thn', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n'));
+  w(T, 'workflow/plans/2026-09-12-thn.md', PLAN('thn', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 92g spec 无验收场景节 → 零场景告警（exit 0）',
+    r.status === 0 && !outOf(r).includes('场景无断言') && !outOf(r).includes('场景引用断链'),
+    `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+
+// ---- 场景 93：引用断链反向对账（2026-10-11 dangling-ref，P2-1，灰度 warning）----
+// 端到端（与「场景未覆盖」共用同一次解析）：验收标准引用 spec 未声明的场景 ID → WARN 场景引用断链
+{
+  // 引用 S1（已声明且覆盖）+ S9（未声明）→ 只出断链，不出未覆盖
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-dr.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — dr\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- THEN z\n');
+  w(T, 'workflow/intents/2026-09-12-dr.md', INTENT('dr', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1（证据:a.log）\n- [x] 场景：S9 幻影场景（证据:ghost.log）\n'));
+  w(T, 'workflow/plans/2026-09-12-dr.md', PLAN('dr', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 93a 引用 spec 未声明的 S9 → WARN 场景引用断链（不阻断）',
+    r.status === 0 && outOf(r).includes('场景引用断链') && outOf(r).includes('S9'),
+    `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+  check('场景 93b 已覆盖的 S1 不触发未覆盖（两方向互不误伤）',
+    !outOf(r).includes('场景未覆盖'), outOf(r).slice(0, 400));
+}
+{
+  // 引用与声明完全一致 → 无断链
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-dr.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — dr\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- THEN z\n### S2 退款\n- GIVEN a\n- THEN b\n');
+  w(T, 'workflow/intents/2026-09-12-dr.md', INTENT('dr', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1（证据:a.log）\n- [x] 场景：S2（证据:b.log）\n'));
+  w(T, 'workflow/plans/2026-09-12-dr.md', PLAN('dr', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 93c 引用与声明一致 → 无断链无未覆盖（exit 0）',
+    r.status === 0 && !outOf(r).includes('场景引用断链') && !outOf(r).includes('场景未覆盖'),
+    `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+{
+  // spec 无场景节但 intent 引用 S1 → 同样算断链（引用了不存在的场景）
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-dr.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — dr\n## 功能行为\n普通 spec，无场景节\n');
+  w(T, 'workflow/intents/2026-09-12-dr.md', INTENT('dr', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1（证据:a.log）\n'));
+  w(T, 'workflow/plans/2026-09-12-dr.md', PLAN('dr', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 93d spec 无场景节且引用 S1 → 断链 WARN（exit 0）',
+    r.status === 0 && outOf(r).includes('场景引用断链') && outOf(r).includes('S1'),
+    `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/confirm-doc.mjs

@@ -39,7 +39,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { createHash, randomBytes } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
-import { confirmGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
+import { confirmGateFor, clarifyGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
 import { loadKitPolicy, hasFreshVerifyLine, ledgerChainHash, scopeDigest } from './policy.mjs';
 
 // hasFreshVerify(root, doc)：读 <root>/.agents/verifications.jsonl 判 24h 窗口绿行（判定单源
@@ -358,6 +358,19 @@ if (isMain) {
         refused++;
         continue;
       }
+      // 待澄清项门（2026-10-12 needs-clarification）：起草期挂「待澄清」标记**不阻断**（零阻塞），
+      // 但 draft→approved 确认时若仍挂着未澄清项则拒绝——确认即「认可这份文档」，文档里还写着
+      // 「这里我不知道」，确认就没有意义。与上面的前置门分开出账：拒绝原因必须指向真正的原因
+      // （合并会让作者去查「前置」，而前置其实是好的）。
+      // ⚠️ 文案锚点硬约束：本段禁止并入上方 gate 分支的输出契约（既有 confirm-doc.test.mjs 断言
+      // 锚定「未过逐阶段前置门（stage-gates）」子串），故单列独立分支。
+      const cl = clarifyGateFor(abs);
+      if (!cl.ok) {
+        console.error(`❌ ${doc} 含未澄清项（needs-clarification）：${cl.reason}`);
+        console.error(`   ${cl.hint}（本份未落账、未写盘）`);
+        refused++;
+        continue;
+      }
     }
     // done 前置门（2026-09-30 confirm-gate-approved-history）：→done 须 git 历史已留 approved 态
     // （先 done 后提交 / 两跳同批提交 → 拒绝；防「确认态缺失」缺陷复发；判据单源见 stage-gates.doneGateFor）。

package/templates/_agents/scripts/confirm-doc.test.mjs

@@ -386,6 +386,65 @@ const readLedgerOf = (root) => {
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- S19b【待澄清门】spec 挂未澄清项 → 拒绝落账（2026-10-12 needs-clarification）----
+// 夹具沿 S23 的正路入口（台账行 + approved），确保**前置门已过**——否则拒绝原因会指向前置而非待澄清，
+// 用例就测不出新门。断言拒绝文案点名「needs-clarification」且**不含**前置门文案（两门分开出账）。
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-cl1-'));
+  for (const sub of ['intents', 'specs']) fs.mkdirSync(path.join(root, 'workflow', sub), { recursive: true });
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  const fp = 'c'.repeat(64);
+  fs.writeFileSync(path.join(root, 'workflow', 'intents', '2026-10-12-n.md'), `---\n状态: approved\n级别: L2\n日期: 2026-10-12\n确认指纹: ${fp.slice(0, 16)}\n---\n# I\n`);
+  fs.writeFileSync(path.join(root, '.agents', 'confirmations.jsonl'), JSON.stringify({ ts: '2026-10-12T02:00:00.000Z', doc: 'workflow/intents/2026-10-12-n.md', stage: 'approved', fingerprint: fp, prev: 'draft', source: 'chat-delegated', batch: 'n1', seq: 1, of: 1 }) + '\n');
+  const specP = path.join(root, 'workflow', 'specs', '2026-10-12-n.md');
+  fs.writeFileSync(specP, '---\n状态: draft\n级别: L2\n---\n# S\n\n## 功能行为\n- 待澄清：错误率的判据是 5xx 占比还是全量？\n');
+  const before = fs.readFileSync(specP, 'utf8');
+  const r = spawnSync(process.execPath, [CLI, 'workflow/specs/2026-10-12-n.md', '--delegated', '可以'], { cwd: root, encoding: 'utf8' });
+  const after = fs.readFileSync(specP, 'utf8');
+  const led = readLedgerOf(root);
+  check('S19b 待澄清门：挂未澄清项 → exit 2 + 点名行号与内容 + 未落盘 + 零新增台账',
+    r.status === 2 && /needs-clarification/.test(r.stderr) && /第8行/.test(r.stderr) && /5xx 占比还是全量/.test(r.stderr)
+      && after === before && led.length === 1,
+    JSON.stringify({ status: r.status, stderr: r.stderr, ledger: led.length }));
+  check('S19b 待澄清门：拒绝原因不误指向前置门（两门分开出账，否则作者查错地方）',
+    !/逐阶段前置门/.test(r.stderr), r.stderr);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S19c【待澄清门】解决后（行首改「已澄清」）→ 放行；纯删行亦可 ----
+{
+  const mkClarified = (body) => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-cl2-'));
+    for (const sub of ['intents', 'specs']) fs.mkdirSync(path.join(root, 'workflow', sub), { recursive: true });
+    fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+    const fp = 'd'.repeat(64);
+    fs.writeFileSync(path.join(root, 'workflow', 'intents', '2026-10-12-o.md'), `---\n状态: approved\n级别: L2\n日期: 2026-10-12\n确认指纹: ${fp.slice(0, 16)}\n---\n# I\n`);
+    fs.writeFileSync(path.join(root, '.agents', 'confirmations.jsonl'), JSON.stringify({ ts: '2026-10-12T02:00:00.000Z', doc: 'workflow/intents/2026-10-12-o.md', stage: 'approved', fingerprint: fp, prev: 'draft', source: 'chat-delegated', batch: 'o1', seq: 1, of: 1 }) + '\n');
+    fs.writeFileSync(path.join(root, 'workflow', 'specs', '2026-10-12-o.md'), body);
+    return root;
+  };
+  for (const [name, body] of [
+    ['改前缀为「已澄清」（保留行、留痕曾不清楚）', '---\n状态: draft\n级别: L2\n---\n# S\n\n- 已澄清：错误率判据 = 5xx 占比（与用户 10-12 对齐）\n'],
+    ['直接删行', '---\n状态: draft\n级别: L2\n---\n# S\n\n## 功能行为\n- 错误率判据 = 5xx 占比\n'],
+  ]) {
+    const root = mkClarified(body);
+    const r = spawnSync(process.execPath, [CLI, 'workflow/specs/2026-10-12-o.md', '--delegated', '可以'], { cwd: root, encoding: 'utf8' });
+    const after = fs.readFileSync(path.join(root, 'workflow', 'specs', '2026-10-12-o.md'), 'utf8');
+    check(`S19c 待澄清门：${name} → 放行落态`, r.status === 0 && after.includes('状态: approved'),
+      JSON.stringify({ status: r.status, stderr: r.stderr }));
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  // intents 不受本门约束（歧义标记的落点是 spec/plan 的设计判据；intent 是需求单，澄清天然发生在此处）
+  const root3 = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-cl3-'));
+  fs.mkdirSync(path.join(root3, 'workflow', 'intents'), { recursive: true });
+  fs.writeFileSync(path.join(root3, 'workflow', 'intents', '2026-10-12-p.md'), '---\n状态: draft\n级别: L1\n---\n# I\n\n- 待澄清：范围含不含移动端？\n');
+  const r3 = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-10-12-p.md', '--delegated', '可以'], { cwd: root3, encoding: 'utf8' });
+  check('S19c 待澄清门：intent 不受本门约束（澄清天然发生在需求单处）',
+    r3.status === 0 && fs.readFileSync(path.join(root3, 'workflow', 'intents', '2026-10-12-p.md'), 'utf8').includes('状态: approved'),
+    JSON.stringify({ status: r3.status, stderr: r3.stderr }));
+  fs.rmSync(root3, { recursive: true, force: true });
+}
+
 // ---- S20【逐阶段门】入口存在但未确认（draft）→ 拒绝 ----
 {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-sg2-'));