@xulthekl/team-flow 0.64.0 → 0.67.0

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

@@ -0,0 +1,41 @@
+// scripts/guard/checks/prd-clarity-state.mjs — 变更级 PRD 清晰度维度（agent-governance P1-1）
+//
+// 与产品级 `prd-clarity.mjs`（checker 本体，跑在 S2 冻结前）的分工：
+//   - 产品级门：对 requirement/vN/prd.md 做机械判定（弱词/段/§8.4 漂移）；
+//   - 本 runner（变更级）：**只读 change state 的记录**（prd_clarity_result），不重跑判定——
+//     clarity 跨层管道 = 产品级 `tf prd check-clarity` 落 `.team-flow/prd-clarity.json`
+//     → `tf state init` 拷入 change state → 本维度在接活前转换消费。
+//
+// 三态语义（缺失态中性，memo §2.4 / plan §6）：
+//   - `fail`  → **FAIL**（阻断转换 = 强制 HITL）：带病 PRD 不得接活；
+//   - `pass`  → PASS；
+//   - 未记录（null；存量 change、绕过产品级的 direct change、hotfix 语义）→ **中性 PASS**，
+//     冷启动零行为变化——缺数据不得判低（全量 HITL）也不得伪造高。
+//
+// 防绕过（[[gate-hint-is-a-bypass]]）：prd_clarity_result **不在** `tf state set` 白名单
+// （SETTABLE_FIELDS 有意不含）——唯一写入路径 = init 从产品级落盘文件拷贝。
+// 手改 state 的逃生通道由 hook 拦截（非 build 态禁写 .team-flow.yaml）。
+import { readState } from '../../lib/state-loader.mjs';
+
+export function checkPrdClarityState(changeDir) {
+  const state = readState(changeDir);
+  const result = state.prd_clarity_result;
+
+  if (result === 'fail') {
+    return {
+      pass: false,
+      failures: [
+        'product-level PRD clarity gate recorded FAIL (state.prd_clarity_result=fail) — '
+        + '回 S2 重跑 `tf prd check-clarity` 并修 PRD 至 PASS，或重建 change（init 会重新拷贝记录）。',
+      ],
+    };
+  }
+  if (result === 'pass') {
+    return { pass: true, failures: [], reason: 'prd_clarity_result=pass' };
+  }
+  return {
+    pass: true,
+    failures: [],
+    reason: 'no clarity record (neutral — 产品级门未覆盖本 change：存量/direct/hotfix)',
+  };
+}

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`,
   };
 }