@xulthekl/team-flow 0.65.0 → 0.67.0

package/scripts/guard/checks/prd-clarity.mjs

@@ -0,0 +1,176 @@
+// scripts/guard/checks/prd-clarity.mjs — 产品级 PRD 清晰度机械门（agent-governance P0-1）
+//
+// 背景（2026-09-25）：LT 拍板 Q5 推翻 DEC-8 中的弱词机械门决策（DEC-8a）——
+// 「接活前 fail-closed」必须有机械层；LLM reviewer（prd-completeness-reviewer）保留，
+// 与本 checker 并存：checker 管机械可判定项，reviewer 管语义完整性。
+//
+// 检查对象：**产品级 PRD**（requirement/vN/prd.md）。不查变更级 change spec
+// （归 spec-writer/评审既有职责）；tasks_skipped 类 change 不经产品级冻结路径，天然不适用。
+//
+// 接入 = 三处（SKILL 调用纪律级，非 hook 强制——如实声明）：
+//   1. `tf prd check-clarity <dir|file>`（cmd-prd.mjs，末行 STATUS: PASS | FAIL）
+//   2. standalone：`references/prototype-loop.md` §3.5.5 前置段（ce-brainstorm SKILL QA-4 引用之）
+//   3. orchestrated：`s2-prd-prototype-loop.md` 步骤 3.4（3.5 完整性评审之前）
+//
+// 判定语义 fail-closed：必需段缺失 / 判据无法执行 → FAIL，不得落 N/A 放行。
+// 首版**不建豁免通道**（不过就改 PRD 或调 checker，走正常代码变更流程）。
+// 产品级无 state 文件（.team-flow.yaml 属 change 级），故不使用 gates-probed 式
+// skip-with-reason 豁免模式——那是首版不建豁免的根本原因，不得照抄。
+//
+// 规则源（单真相源裁定，memo v0.5 §4.1 / 反方 I7；**回写已闭合 2026-09-25**）：
+//   权威正文 = skills/ce-brainstorm/references/prd-84-authoring-spec.md §4「精确性」，
+//   DEC-8a 复议时已扩为 8 类全集（第 6–8 类：否定句/连接歧义/被动语态），
+//   镜像弱词表（工作区 prd-business-readable-design）不再独立维护。
+
+import fs from 'node:fs';
+
+/**
+ * ISO/IEC/IEEE 29148 弱词 8 类规则表（数据可调——误报校准的唯一落点）。
+ * 词表来源：prd-84 §4（权威，8 类全集，DEC-8a 复议后收口于此）。
+ * 校准纪律：调词表 = 改本文件规则数据并同步权威正文，不得在调用侧打补丁。
+ * 格式：{ category, words: string[], note? }；words 为子串匹配（中文无词边界）。
+ *
+ * **2026-09-25 校准排除决策（刻意不收，权威正文 §4 已留痕）**：
+ *   - `处理`（§4 类 3 示例词）：子串会命中模板段名「系统功能处理说明书」→ 冻结死循环；
+ *   - 单字 `等`（§4 类 4 示例）：子串命中「等待/等于/以及」等一切含字场景 → 噪声失控；
+ *     词表只收「等等」。两者判读由 LLM reviewer 精确性检查覆盖（并存层职责）。
+ */
+export const WEAK_RULES = [
+  { category: '比较级与最高级', words: ['更好', '较好', '更快', '更佳', '更稳定', '最快', '最高级', '较快'] },
+  { category: '主观评价词', words: ['友好', '易用', '良好', '美观', '简洁', '直观'] },
+  { category: '歧义词', words: ['尽量', '总是', '最优', '最小化', '最大化', '适当', '必要时'] },
+  { category: '开放式表述', words: ['至少', '不限于', '尽可能', '视情况', '等等'] },
+  { category: '漏洞词', words: ['可能', '如适用', '一般', '通常', '支持'] },
+  { category: '否定句', words: ['不支持'], note: '改为「当 X 时，系统执行 Y」' },
+  { category: '连接歧义', words: ['和/或'], note: '拆分条目或用决策表' },
+  { category: '被动语态', words: ['应被'], note: '明确动作主体' },
+];
+
+/** 段缺失判据（fail-closed 最小必需集）：命中任一 pattern 即认为段存在。 */
+export const REQUIRED_SECTIONS = [
+  // version-1.2：只认 1.2 修订行 / 1.1 版本信息子段（h2「版本修订记录」兜底过松——
+  // 子段全删时 h2 仍在，首版实测会漏判，故收紧到子段级）。
+  { id: 'version-1.2', desc: '### 1.1 版本信息 / 1.2 修订记录', pattern: /^#{2,4}\s*.*(?:1\.[12]\s*(?:版本信息|修订)|版本信息\s*$)/m },
+  { id: 'func-list', desc: '功能清单章节（## 七 / 功能清单）', pattern: /^#{2,3}\s*.*(?:七、|功能清单|系统功能)/m },
+  { id: 'sec-8.4', desc: '### 8.4 功能模块详细说明', pattern: /^#{2,4}\s*.*8\.4/m },
+];
+
+/**
+ * §8.4 左列语义漂移判据（判据源 = prd-completeness-reviewer.md D6/G7 第 1 条）：
+ * 左列须为画面/入口锚点；技术维度名 = 违规。
+ * 机械实现的边界：**整格匹配**（防「单据类型」这类业务词误杀），另加强技术词子串。
+ */
+const DRIFT_EXACT = /^(维度|字段|类型|属性|参数|枚举|单位|数据项)(列表|清单|定义)?$/;
+const DRIFT_SUBSTRING = /(字段名|维度名|数据类型|技术维度|参数名|表字段)/;
+
+/** 去除围栏代码块与行内 code（弱词扫描的误报源），保留原文行结构用于定位。 */
+export function stripCode(text) {
+  const lines = text.split(/\r?\n/);
+  let inFence = false;
+  return lines.map((line) => {
+    if (/^\s*```/.test(line)) { inFence = !inFence; return ''; }
+    if (inFence) return '';
+    return line.replace(/`[^`]*`/g, '');
+  }).join('\n');
+}
+
+/** 提取标题段正文（到下一个同级或更高级标题）。返回 null 表示段不存在。 */
+export function extractSection(text, headingRe) {
+  const lines = text.split(/\r?\n/);
+  let start = -1;
+  let level = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = lines[i].match(/^(#{1,6})\s/);
+    if (m && headingRe.test(lines[i])) { start = i; level = m[1].length; break; }
+  }
+  if (start === -1) return null;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const m = lines[i].match(/^(#{1,6})\s/);
+    if (m && m[1].length <= level) break;
+    body.push(lines[i]);
+  }
+  return body.join('\n');
+}
+
+/** 收集段内所有 markdown 表格的首列数据单元格（跳过表头与分隔行）。 */
+export function firstColumnCells(sectionBody) {
+  const cells = [];
+  const lines = sectionBody.split(/\r?\n/);
+  let inTable = false;
+  let headerSeen = false;
+  for (const line of lines) {
+    if (!line.trim().startsWith('|')) { inTable = false; headerSeen = false; continue; }
+    const cols = line.split('|').map((c) => c.trim());
+    // cols[0] === ''（前导竖线），数据首列在 index 1
+    if (!inTable) { inTable = true; headerSeen = false; continue; } // 表头行
+    if (!headerSeen) { headerSeen = true; continue; }              // 分隔行（|---|---|）
+    const first = cols[1] || '';
+    if (first) cells.push(first);
+  }
+  return cells;
+}
+
+/**
+ * 核心判定。
+ * @param {string} prdPath prd.md 文件绝对/相对路径
+ * @returns {{pass: boolean, failures: string[], stats: object}}
+ * 失败条目格式：`[类别] 行 N: <片段>` / `[section] ...` / `[drift] ...`
+ */
+export function checkPrdClarity(prdPath) {
+  const failures = [];
+  const stats = { weakHits: 0, driftCells: 0, sectionsMissing: [] };
+
+  if (!prdPath || !fs.existsSync(prdPath)) {
+    return {
+      pass: false,
+      failures: [`[section] PRD file not found: ${prdPath ?? '(unset)'} — locate requirement/vN/prd.md first`],
+      stats,
+    };
+  }
+  const raw = fs.readFileSync(prdPath, 'utf-8');
+  if (!raw.trim()) {
+    return { pass: false, failures: ['[section] PRD file is empty — write the PRD before running clarity check'], stats };
+  }
+
+  // 1) 必需段存在性（fail-closed：缺失 = FAIL，不得 N/A 放行）。
+  for (const sec of REQUIRED_SECTIONS) {
+    if (!sec.pattern.test(raw)) {
+      stats.sectionsMissing.push(sec.id);
+      failures.push(`[section] required section missing: ${sec.desc} — template skeleton incomplete`);
+    }
+  }
+
+  // 2) 弱词 8 类扫描（排除代码块/行内 code；表格内容照扫——PRD 表格是业务正文）。
+  const clean = stripCode(raw);
+  const cleanLines = clean.split(/\r?\n/);
+  for (let i = 0; i < cleanLines.length; i += 1) {
+    const line = cleanLines[i];
+    if (!line.trim()) continue;
+    for (const rule of WEAK_RULES) {
+      for (const word of rule.words) {
+        const idx = line.indexOf(word);
+        if (idx >= 0) {
+          stats.weakHits += 1;
+          const snippet = line.slice(Math.max(0, idx - 12), idx + word.length + 12).trim();
+          failures.push(`[weak:${rule.category}] 行 ${i + 1}: …${snippet}… （${rule.note ?? '改为精确表述'}）`);
+        }
+      }
+    }
+  }
+
+  // 3) §8.4 左列语义漂移（G7 第 1 条机械化）。
+  const sec84 = extractSection(clean, /8\.4/);
+  if (sec84 === null) {
+    // 必需段已在其处 FAIL（REQUIRED_SECTIONS sec-8.4），此处不重复计。
+  } else {
+    for (const cell of firstColumnCells(sec84)) {
+      if (DRIFT_EXACT.test(cell) || DRIFT_SUBSTRING.test(cell)) {
+        stats.driftCells += 1;
+        failures.push(`[drift] §8.4 左列技术维度名: "${cell}" — 左列须为画面/入口锚点（G7-1）`);
+      }
+    }
+  }
+
+  return { pass: failures.length === 0, failures, stats };
+}

package/scripts/guard/guard.mjs

@@ -17,6 +17,9 @@ import { checkCompoundCaptured } from './checks/compound-captured.mjs';
 import { checkTestMatrixComplete } from './checks/test-matrix-complete.mjs';
 import { checkTestMatrixReady } from './checks/test-matrix-ready.mjs';
 import { checkGatesProbed } from './checks/gates-probed.mjs';
+// agent-governance P1-1：接活前双维度（履历 experimental + clarity 跨层管道）
+import { checkPrdClarityState } from './checks/prd-clarity-state.mjs';
+import { checkHistoryRisk } from './checks/history-risk.mjs';
 import { checkArchReadiness } from './checks/arch-readiness.mjs';
 import { checkArchSnapshot } from './checks/arch-snapshot.mjs';
 import { checkArchMerged } from './checks/arch-merged.mjs';
@@ -57,10 +60,12 @@ const TRANSITION_CHECKS = {
   // 「闸门已实测可跑」文字自证物化为机械证据。检查五件：evidence 存在 / 首行 RED 基线 /
   // CONTRACT_HASH 值新鲜 / 契约 Gate Registry 的 id 逐 id 覆盖 / **段缺失即 FAIL（fail-closed）**。
   // hotfix 走 WORKFLOW_TRANSITION_CHECKS 自有覆盖（下方），tweak 由 skip 回退阀放行。
-  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed', 'dp3-approved', 'gates-probed'],
+  // agent-governance P1-1：prd-clarity + history-risk 挂接活门（full 档）——
+  // 「接活前验规格 + 履历」；两维缺失态均中性（无记录/INDEX 空 = 放行），存量零变化。
+  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed', 'dp3-approved', 'gates-probed', 'prd-clarity', 'history-risk'],
   // v0.13 §49：test-matrix-ready 门禁前移——full 模式进入 executing 前强制测试准备度
   //（矩阵存在非空 OR 显式 skip 附理由；legacy 豁免）。hotfix/tweak 沿用 §45.3 豁免，不挂。
-  'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready', 'test-matrix-ready'],
+  'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready', 'test-matrix-ready', 'prd-clarity', 'history-risk'],
   // v0.35.0 (v0.14 §59.4): arch-snapshot 新增——"先快照后回写"的强制化（legacy 豁免）。
   // 仅在 full workflow 挂；hotfix/tweak 沿用 §59.4 豁免（紧急/微调不挂）。
   //
@@ -134,15 +139,15 @@ const TRANSITION_WORKFLOW_REQUIREMENTS = {
 // 必须显式列出关键跳——未列出的 key 会回落 full 基表（contract-fresh 等对轻路径恒 FAIL）。
 const QUICK_TRANSITION_CHECKS = {
   quick: {
-    'exploring:approved-for-build': ['direct-short-path'],
-    'approved-for-build:executing': ['direct-short-path', 'test-matrix-ready'],
+    'exploring:approved-for-build': ['direct-short-path', 'prd-clarity', 'history-risk'],
+    'approved-for-build:executing': ['direct-short-path', 'test-matrix-ready', 'prd-clarity', 'history-risk'],
     'executing:closing': ['direct-short-path', 'direct-test-result', 'test-matrix-complete'],
     'executing:debugging': [],
     'debugging:executing': ['direct-test-result'],
   },
   lightweight: {
-    'exploring:approved-for-build': ['direct-short-path'],
-    'approved-for-build:executing': ['direct-short-path', 'test-matrix-ready'],
+    'exploring:approved-for-build': ['direct-short-path', 'prd-clarity', 'history-risk'],
+    'approved-for-build:executing': ['direct-short-path', 'test-matrix-ready', 'prd-clarity', 'history-risk'],
     'executing:closing': ['direct-short-path', 'direct-test-result', 'lightweight-completion-evidence', 'test-matrix-complete'],
     'executing:debugging': [],
     'debugging:executing': ['direct-test-result'],
@@ -155,8 +160,8 @@ const PLANNED_TRANSITION_CHECKS = {
   // 注：不挂 schema-valid——该 checker 强制 canonical specs/<capability>/spec.md，
   // 与 planned「specs 按需」冲突（P1 实测修正，同步方案 §4.5）；反空壳由 artifacts-planned
   // （proposal≥10 行 + checkbox）+ 最终审查内容契约承担。
-  'exploring:approved-for-build': ['artifacts-planned'],
-  'approved-for-build:executing': ['execution-plan-ready', 'test-matrix-ready'],
+  'exploring:approved-for-build': ['artifacts-planned', 'prd-clarity', 'history-risk'],
+  'approved-for-build:executing': ['execution-plan-ready', 'test-matrix-ready', 'prd-clarity', 'history-risk'],
   'executing:closing': [
     'execution-plan-ready', 'execution-reviews-passed-light', 'test-matrix-complete',
     'tests-passing', 'arch-merged-light', 'compound-writeback-light', 'test-merged-light',
@@ -293,6 +298,9 @@ async function main() {
     'test-matrix-complete': (dir) => checkTestMatrixComplete(dir, CTX),
     'test-matrix-ready': (dir) => checkTestMatrixReady(dir, CTX),
     'gates-probed': (dir) => checkGatesProbed(dir),
+    // agent-governance P1-1（33 维）：接活前双维度。缺失态中性——冷启动零行为变化。
+    'prd-clarity': (dir) => checkPrdClarityState(dir),
+    'history-risk': (dir) => checkHistoryRisk(dir),
     'arch-readiness': (dir) => checkArchReadiness(dir),
     'arch-snapshot': (dir) => checkArchSnapshot(dir),
     'arch-merged': (dir) => checkArchMerged(dir),

package/scripts/infer-workflow.mjs

@@ -55,6 +55,11 @@ function hasKeyword(text, patterns) {
 
 function inferMode(changeDir) {
   const state = readState(changeDir);
+  // agent-governance P1-1 双信号（轻量分值化）：
+  //   clarity = 产品级 prd-clarity 跨层记录（pass|fail|null=null 中性——见 prd-clarity-state.mjs）；
+  //   risk    = 0.64 双通道信号的分档聚合（low|medium|high|null——显式档位/无产物时 null）。
+  // 消费方 = workflow-start 路由推荐（建议级；阻断由 guard 维度承担，这里只影响推荐倾向）。
+  const clarity = state.prd_clarity_result ?? null;
 
   // Explicit override: honor any non-auto, non-null workflow value
   // v0.64.0（§3.2 F1）：VALID_WORKFLOWS 扩为五值，quick/lightweight 亦为合法显式档位。
@@ -66,6 +71,8 @@ function inferMode(changeDir) {
         // 双通道（§3.2）：显式 workflow 已定时不再建议前门（显式 > 推断）
         suggested_path: null,
         explicit: true,
+        clarity,
+        risk: null, // 显式档位不推断风险分档
         reason: `workflow explicitly set to '${state.workflow}' in .team-flow.yaml; skipping auto-detection`,
       };
     }
@@ -101,6 +108,9 @@ function inferMode(changeDir) {
   const archPathSignal = hasSchemaChange || hasArchAggregate;
   // 跨模块 / 高不确定性 → full（D1：full 只留重场景）
   const fullSignal = hasCrossModule || (taskCount > 4 && fileCount > 6);
+  // P1-1 risk 分档：四个布尔信号计数（0=low / 1=medium / ≥2=high）
+  const riskSignals = [hasSchemaChange, hasArchAggregate, hasCrossModule, fullSignal].filter(Boolean).length;
+  const risk = riskSignals >= 2 ? 'high' : riskSignals === 1 ? 'medium' : 'low';
 
   const allExts = files.map(f => {
     const parts = f.split('.');
@@ -115,6 +125,8 @@ function inferMode(changeDir) {
       mode: 'full',
       suggested_path: null,
       explicit: false,
+      clarity,
+      risk,
       reason: 'no planning artifacts detected → full (safe default)',
     };
   }
@@ -125,6 +137,8 @@ function inferMode(changeDir) {
       mode: 'hotfix',
       suggested_path: 'direct',
       explicit: false,
+      clarity,
+      risk,
       reason: `≤2 tasks, ≤2 files, no schema/API/new-module keywords → hotfix (trivial → suggest path direct; hotfix retained when reusing an existing contract)`,
     };
   }
@@ -135,6 +149,8 @@ function inferMode(changeDir) {
       mode: 'tweak',
       suggested_path: 'direct',
       explicit: false,
+      clarity,
+      risk,
       reason: `≤4 tasks, only config/doc files, no schema/API/new-module keywords → tweak (trivial → suggest path direct)`,
     };
   }
@@ -145,6 +161,8 @@ function inferMode(changeDir) {
       mode: 'full',
       suggested_path: 'planned',
       explicit: false,
+      clarity,
+      risk,
       reason: `${taskCount} tasks, ${fileCount} files${hasSchemaChange ? ', schema/API change detected' : ''}${hasArchAggregate ? ', arch/aggregate keywords detected' : ''} → suggest path planned (light architecture); front door: workflow start --path planned (new change) or tf state upgrade <dir> planned (existing change)`,
     };
   }
@@ -154,6 +172,8 @@ function inferMode(changeDir) {
     mode: 'full',
     suggested_path: null,
     explicit: false,
+    clarity,
+    risk,
     reason: `${taskCount} tasks, ${fileCount} files${codeFileCount > 0 ? ` (${codeFileCount} code files)` : ''}${hasSchemaChange ? ', schema/API change detected' : ''}${hasNewModule ? ', new module detected' : ''}${hasCrossModule ? ', cross-module detected' : ''} → full`,
   };
 }

package/scripts/lib/cmd-doctor.mjs

@@ -382,9 +382,9 @@ function checkSolutions(root) {
     for (const line of readFileSync(indexPath, 'utf-8').split('\n')) {
       if (!line.startsWith('|') || line.startsWith('| date') || line.startsWith('|--')) continue;
       const cells = parseTableRow(line);
-      // v0.57.0 P4：`source` 列新增后列数为 7（存量 INDEX）或 8（本版重建）；
+      // v0.57.0 P4：`source` 列新增后列数为 7（存量）/ 8；P2-2 `flags` 列后 9（本版重建）；
       // 另校验 `file` 列形状——列数在界内仍可能因未转义的 `|` 而错位。
-      if (cells.length < 7 || cells.length > 8) continue;
+      if (cells.length < 7 || cells.length > 9) continue;
       if (!/^[a-z][a-z-]*\/.+\.md$/.test(cells[6])) continue;
       indexRows.set(cells[6], { date: cells[0], phase: cells[1], domain: cells[2], type: cells[3], severity: cells[4] });
     }

package/scripts/lib/cmd-prd.mjs

@@ -14,7 +14,9 @@
 // 供主会话 Phase 0.0 的阻塞提问（G1）取判据——**判据不在 skill 散文里另写一套**。
 
 import fs from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import { loadConfig, resolveConfigWritePath } from './config-loader.mjs';
 import {
@@ -23,6 +25,7 @@ import {
   compareAgainstAck,
   shortHash,
 } from './template-hash.mjs';
+import { checkPrdClarity } from '../guard/checks/prd-clarity.mjs';
 
 const VALID_MODES = ['adopt_latest', 'keep_legacy'];
 
@@ -48,6 +51,7 @@ export async function run(args) {
   const sub = positionals[0];
   if (sub === 'ack') return ack(positionals.slice(1), values);
   if (sub === 'check') return check(values);
+  if (sub === 'check-clarity') return checkClarity(positionals.slice(1));
   usage();
 }
 
@@ -58,11 +62,90 @@ function usage() {
       '  tf prd ack set --mode adopt_latest --in-use-hash … [--plugin-hash …] [--spec-hash …]\n' +
       '  tf prd ack show                            # 查看当前 ack\n' +
       '  tf prd ack clear                           # 清除 ack（下次将重新提问）\n' +
-      '  tf prd check [--template-path <p>] [--plugin-root <p>]   # 比对 hash 与 ack，输出 STATUS'
+      '  tf prd check [--template-path <p>] [--plugin-root <p>]   # 比对 hash 与 ack，输出 STATUS\n' +
+      '  tf prd check-clarity <dir|prd.md>                        # 清晰度机械门（弱词/段/§8.4 漂移），末行 STATUS: PASS | FAIL，FAIL exit 1'
   );
   process.exit(2);
 }
 
+/**
+ * `tf prd check-clarity`：产品级 PRD 清晰度机械门（agent-governance P0-1，DEC-8a）。
+ *
+ * 入参 = 目录（自动定位 requirement/vN/prd.md，多个 vN 取最大）或 prd.md 文件路径。
+ * 输出末行固定 `STATUS: PASS | FAIL`；**FAIL 时 exit 1**（fail-closed——本命令是门，
+ * 不同于 `tf prd check` 的判据工具语义；SKILL 冻结步骤 MUST 读 STATUS 且不得忽略非零退出码）。
+ * 判定细节见 scripts/guard/checks/prd-clarity.mjs 头注（规则源 / 豁免边界 / 校准纪律）。
+ */
+function checkClarity(positionalArgs) {
+  const target = positionalArgs[0];
+  if (!target) usage();
+
+  let prdPath = target;
+  if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
+    prdPath = resolvePrdInDir(target);
+    if (!prdPath) {
+      console.error(`no requirement/vN/prd.md found under: ${target}`);
+      console.log('STATUS: FAIL');
+      process.exit(1);
+    }
+  }
+  if (!fs.existsSync(prdPath)) {
+    console.error(`PRD file not found: ${prdPath}`);
+    console.log('STATUS: FAIL');
+    process.exit(1);
+  }
+
+  const { pass, failures, stats } = checkPrdClarity(prdPath);
+  console.log('prd         :', prdPath);
+  console.log('weak_hits   :', stats.weakHits, '| drift_cells:', stats.driftCells,
+    '| missing_sections:', stats.sectionsMissing.length ? stats.sectionsMissing.join(',') : '(none)');
+  for (const f of failures) console.log(f);
+  console.log(`STATUS: ${pass ? 'PASS' : 'FAIL'}`);
+  recordClarityResult(pass, prdPath); // P1-1 跨层管道：落产品级记录供 tf state init 拷贝
+  if (!pass) process.exit(1);
+}
+
+/**
+ * P1-1 clarity 跨层管道的写侧：落 `<cwd>/.team-flow/prd-clarity.json`。
+ * 消费链 = `tf state init` 拷入 change state（prd_clarity_result/prd_clarity_hash）
+ * → guard 维度 `prd-clarity`（checks/prd-clarity-state.mjs）在接活前转换消费。
+ * PASS/FAIL 都落盘（fail 记录让绕过 S2 的 direct change 也在变更级被拦——双保险）。
+ */
+function recordClarityResult(pass, prdPath) {
+  try {
+    const dir = path.join(process.cwd(), '.team-flow');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const content = fs.readFileSync(prdPath, 'utf-8');
+    const sha = createHash('sha256').update(content).digest('hex');
+    fs.writeFileSync(path.join(dir, 'prd-clarity.json'), `${JSON.stringify({
+      status: pass ? 'pass' : 'fail',
+      prd: prdPath,
+      prd_hash: `sha256:${sha}`,
+      checked_at: new Date().toISOString(),
+    }, null, 2)}\n`);
+  } catch {
+    // 落盘失败不吞主判定——STATUS 已输出；管道缺失 = 变更级维度走中性，fail-closed 不受影响
+  }
+}
+
+/**
+ * 目录内定位 prd.md：<dir>/prd.md、requirement/ 下最大 vN、或老布局 prd/ 下最大 vN
+ * （存量项目用 `prd/vN/prd.md`——2026-09-25 存量校准时实测补上，防新门卡死老布局）。
+ */
+function resolvePrdInDir(dir) {
+  const direct = path.join(dir, 'prd.md');
+  if (fs.existsSync(direct)) return direct;
+  for (const base of ['requirement', 'prd']) {
+    const reqDir = path.join(dir, base);
+    if (!fs.existsSync(reqDir)) continue;
+    const versions = fs.readdirSync(reqDir)
+      .filter((n) => fs.existsSync(path.join(reqDir, n, 'prd.md')))
+      .sort((a, b) => parseInt(a.replace(/\D/g, ''), 10) - parseInt(b.replace(/\D/g, ''), 10)); // 数值序：v10 > v9（字典序会取错）
+    if (versions.length > 0) return path.join(reqDir, versions[versions.length - 1], 'prd.md');
+  }
+  return null;
+}
+
 /** 读原始配置文件（未与 DEFAULTS 合并），用于区分「用户显式配置」与「默认值」。 */
 function readRawConfig() {
   const p = resolveConfigWritePath(process.cwd());

package/scripts/lib/cmd-solutions.mjs

@@ -21,6 +21,8 @@ export async function run(args) {
       severity: { type: 'string' },
       summary: { type: 'string' },
       source: { type: 'string' },
+      // agent-governance P2-1：纠错条目的来源事件锚（HOLD 的 msg_id / 决策日志行）
+      'source-event': { type: 'string' },
       // v0.57.0 §4.1：inject 的展示条数控制与 backfill 的预演
       limit: { type: 'string' },
       all: { type: 'boolean' },
@@ -52,6 +54,7 @@ export async function run(args) {
       severity: values.severity,
       summary: values.summary,
       source: values.source,
+      source_event: values['source-event'],
       dir: values.dir,
     });
     return;

package/scripts/lib/cmd-state.mjs

@@ -1,7 +1,7 @@
 // scripts/lib/cmd-state.mjs — tf state subcommand handler
 import { parseArgs } from 'node:util';
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // VALID_STATES 统一从 state-loader.mjs 引入(状态机合法值唯一真相源),不再本地硬编码。
@@ -11,6 +11,26 @@ import { computeArtifactsHash, computeContractHash, computeTestMatrixHash } from
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * P1-1：自 changeDir 向上（限 6 层）找 `<root>/.team-flow/prd-clarity.json` 并解析。
+ * 找不到 / 解析失败 → null（= 中性，init 不打字段）。
+ */
+function findProductClarityRecord(changeDir) {
+  let dir = path.resolve(changeDir);
+  for (let i = 0; i < 6; i += 1) {
+    const rec = path.join(dir, '.team-flow', 'prd-clarity.json');
+    if (existsSync(rec)) {
+      const parsed = JSON.parse(readFileSync(rec, 'utf-8'));
+      if (parsed && (parsed.status === 'pass' || parsed.status === 'fail')) return parsed;
+      return null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
 // v0.13 §50（BUG-A 政策修正）：test_result 移出可手工设置字段——测试证据必须经
 // tf test record 程序化记录，手工自述值不再被 tests-passing 门禁接受。
 // v0.13 §48.2：test_matrix_skip_reason 可设置（显式 skip 的理由留痕）。
@@ -121,6 +141,16 @@ export async function run(args) {
       const state = readState(changeDir);
       if (!stateFileExisted) {
         state.schema_version = 1;
+        // P1-1 clarity 跨层管道：拷贝产品级记录（唯一写入路径——state 字段不在
+        // SETTABLE_FIELDS，防自助放行）。find 向上找 <root>/.team-flow/prd-clarity.json。
+        // 记录 fail 也拷：绕过 S2 冻结的 direct change 在变更级被 guard 拦下（双保险）。
+        try {
+          const rec = findProductClarityRecord(changeDir);
+          if (rec) {
+            state.prd_clarity_result = rec.status === 'fail' ? 'fail' : 'pass';
+            state.prd_clarity_hash = rec.prd_hash ?? null;
+          }
+        } catch { /* 无记录 = 中性，不阻断 init */ }
         // v0.64.0 P0（§4 扫描基线）：init 打戳 base_sha（架构 surface 扫描的 git 基线）。
         // 非 git 环境 / 尚无提交 → 保持 null，扫描时按 §4 退化参照（origin → FAIL）。
         try {

package/scripts/lib/solutions-capture.mjs

@@ -42,6 +42,10 @@ export function run(args = {}) {
   const severity = args.severity || 'medium';
   const summary = args.summary || '(no summary)';
   const source = args.source || '';
+  // agent-governance P2-1：来源事件锚——correction 条目的毕业条件消费它
+  //（P2-2「锚未标撤销」判定；无锚条目按未毕业处理）。HOLD 场景 = escalation msg_id
+  // 或决策日志行；非空才写入 frontmatter。
+  const sourceEvent = args.source_event || '';
   const dir = args.dir || 'docs/solutions';
 
   // 注：process.exit 后补 return——真实 CLI 下 exit 即终止；测试环境 mock exit 时
@@ -79,6 +83,7 @@ type: ${type}
 severity: ${severity}
 date: ${date}
 source: ${source}
+${sourceEvent ? `source_event: ${sourceEvent}` : ''}
 title: ${title}
 ---
 

package/scripts/lib/solutions-index-gen.mjs

@@ -41,6 +41,34 @@ import { parseFrontmatter, listSolutionEntries } from './solutions-entry.mjs';
 /** INDEX 保留的最大**条目数**（非行数——文件还含 4 行头部） */
 export const MAX_INDEX_ENTRIES = 150;
 
+/**
+ * agent-governance P2-2（earned automation 见习）：毕业阈值。
+ * `flags` 列派生规则（**纯派生、随重建重算**——INDEX 是投影）：
+ * - 条目有 `source_event` 锚（P2-1 起的 correction 条目）：confirmations ≥ 本阈值 → `auto-ok`，
+ *   否则 → `probation`（见习：不进自动注入上下文）。
+ *   「锚被标撤销」的毕业否决暂无实现（撤销动作未建，如实声明——source_event 锚已就位，
+ *   撤销标记是其消费侧的未来项）。
+ * - 无锚存量条目 → `auto-ok`（**grandfather**：它们已在注入通道，见习化 = 行为回退，不采纳；
+ *   与 schema_version 存量豁免同构）。
+ * - 红区硬排除不在此处：红区判定是**消费侧**职责（inject 按 summary/domain 关键词排除），
+ *   flags 表示毕业状态、不表示区域。
+ */
+export const GRADUATED_MIN_CONFIRMATIONS = 3;
+
+/** 解析 frontmatter confirmations 计数（宽松：仅计数，promote 的严格解析不在此复用）。 */
+function countConfirmations(fm) {
+  const raw = fm?.confirmations;
+  if (raw == null || raw === '') return 0;
+  return String(raw).replace(/[[\]]/g, '').split(',').map((s) => s.trim()).filter(Boolean).length;
+}
+
+/** 派生 flags（见上注释的规则表）。 */
+export function deriveFlags(fm) {
+  const hasAnchor = Boolean(fm?.source_event && String(fm.source_event).trim());
+  if (!hasAnchor) return 'auto-ok';
+  return countConfirmations(fm) >= GRADUATED_MIN_CONFIRMATIONS ? 'auto-ok' : 'probation';
+}
+
 /**
  * 解析条目文件的 frontmatter（扁平键值）——**收敛到共享层**（v0.57.0 P4 二轮）。
  *
@@ -111,6 +139,8 @@ export function refreshIndex(dir, { phases = SOLUTION_PHASES, maxEntries = MAX_I
         file: `${phase}/${file}`,
         // v0.57.0 P4：source 进 INDEX 供 inject 做同源聚类（此前只存在于条目文件，消费方读不到）
         source: fm.source || '',
+        // P2-2：见习/毕业派生状态（规则见 GRADUATED_MIN_CONFIRMATIONS 注释）
+        flags: deriveFlags(fm),
       });
     }
   }
@@ -133,10 +163,10 @@ export function refreshIndex(dir, { phases = SOLUTION_PHASES, maxEntries = MAX_I
   // "只读 INDEX、不读条目文件"，故聚类键必须进索引。消费方对 7/8 列都容错（见 solutions-inject）。
   let index = '# Solutions Index\n';
   index += `<!-- 每条一行，排序 severity 降序 → date 降序 → file 兜底，≤${maxEntries} 条上限；summary/source 内的 | 转义为 \\| -->\n`;
-  index += '| date | phase | domain | type | severity | summary | file | source |\n';
-  index += '|------|-------|--------|------|----------|---------|------|--------|\n';
+  index += '| date | phase | domain | type | severity | summary | file | source | flags |\n';
+  index += '|------|-------|--------|------|----------|---------|------|--------|-------|\n';
   for (const e of kept) {
-    index += `| ${escapeCell(e.date)} | ${escapeCell(e.phase)} | ${escapeCell(e.domain)} | ${escapeCell(e.type)} | ${escapeCell(e.severity)} | ${escapeCell(e.summary)} | ${escapeCell(e.file)} | ${escapeCell(e.source)} |\n`;
+    index += `| ${escapeCell(e.date)} | ${escapeCell(e.phase)} | ${escapeCell(e.domain)} | ${escapeCell(e.type)} | ${escapeCell(e.severity)} | ${escapeCell(e.summary)} | ${escapeCell(e.file)} | ${escapeCell(e.source)} | ${escapeCell(e.flags)} |\n`;
   }
 
   writeFileSync(join(dir, 'INDEX.md'), index, 'utf-8');