@xulthekl/team-flow 0.65.0 → 0.68.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/checks/security-baseline-light.mjs

@@ -0,0 +1,9 @@
+// scripts/guard/checks/security-baseline-light.mjs — 安全基线闸门（轻档：quick/lightweight）
+// 设计：docs/plan/security-baseline-integration-design.md v1.3 §L2
+// 与重档共享全部判定（存量分档 / 推导落盘 / skip 短路 / infra 交接），
+// **省略逐条 verdict 核验**（direct 档无审查 receipt，verification 无生产者——诚实降级 §八.5）。
+import { evaluateSecurityBaseline } from './security-baseline.mjs';
+
+export function checkSecurityBaselineLight(changeDir) {
+  return evaluateSecurityBaseline(changeDir, 'light');
+}

package/scripts/guard/checks/security-baseline.mjs

@@ -0,0 +1,141 @@
+// scripts/guard/checks/security-baseline.mjs — 安全基线闸门（重档：full/hotfix/planned）
+// 设计：docs/plan/security-baseline-integration-design.md v1.3 §L2
+// 输入只读结构化制品，不解析 markdown 审查报告：
+//   ① .security-scope.json（现场推导落盘，security-scope.mjs 唯一实现）
+//   ② .security-verification.json（L3 code-reviewer 产出）
+//   ③ state 键（security_baseline_skipped / _skip_reason / security_scope_hash + schema_version）
+// 判定序（v1.3 重排）：存量分档 → 现场推导 → 无类别 PASS → skip 短路 →
+// 重/轻档分流（完备性对账 + verdict 映射）→ infra 交接检查。
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { deriveSecurityScope, loadSecurityBaseline, readScopeFile } from '../../lib/security-scope.mjs';
+
+const VERIFICATION_FILE = '.security-verification.json';
+const HANDOFF_REL = join('security', 'handoff.md');
+
+function readVerification(changeDir) {
+  const p = join(changeDir, VERIFICATION_FILE);
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { return 'malformed'; }
+}
+
+// verdict → 门禁映射（设计 §L3，写死）：
+//   must+satisfied / should+satisfied → PASS
+//   not-applicable → 须过 reason 判据（≥10 字符或含控制点序号），否则视同 uncovered
+//   uncovered / 缺席 → must=FAIL，should=WARN（不阻断）
+function evaluateVerdicts(baseline, scope, verification) {
+  const failures = [];
+  const warnings = [];
+  const byId = new Map((verification.items || []).map(i => [Number(i.id), i]));
+  const reasonOk = (v, id) => {
+    const r = (v.reason || '').trim();
+    return r.length >= 10 || r.includes(String(id));
+  };
+
+  for (const id of scope.code_item_ids) {
+    const item = baseline.items.find(b => b.id === id);
+    const v = byId.get(id);
+    const must = item?.severity === 'must';
+    if (!v) {
+      // 完备性对账：适用项缺席 = uncovered（防空/残缺 items 空过，设计 §L3）
+      (must ? failures : warnings).push(`#${id} ${item?.title ?? ''} 缺席于 verification（=uncovered）`);
+      continue;
+    }
+    if (v.verdict === 'satisfied') continue;
+    if (v.verdict === 'not-applicable') {
+      if (!reasonOk(v, id)) {
+        failures.push(`#${id} not-applicable 的 reason 不合格（需 ≥10 字符或含序号）`);
+      }
+      continue;
+    }
+    // uncovered 或未知 verdict（未知按 uncovered，fail-closed）
+    if (must) failures.push(`#${id} ${item?.title ?? ''} uncovered（must）`);
+    else warnings.push(`#${id} ${item?.title ?? ''} uncovered（should，WARN 不阻断）`);
+  }
+  return { failures, warnings };
+}
+
+/**
+ * 核心求值。mode = 'full'（查 verification）| 'light'（跳过逐条核验）
+ */
+export function evaluateSecurityBaseline(changeDir, mode) {
+  const state = readState(changeDir);
+
+  // 步 1：存量分档（单一判据 = 无 schema_version → WARN 软着陆，设计 §二.3）
+  if (state.schema_version == null) {
+    return { pass: true, failures: [], reason: 'legacy soft-land: no schema_version (存量 change，安全基线不阻断)' };
+  }
+
+  // 步 2：现场推导（写盘留痕；推导失败 fail-closed）
+  let scope;
+  try {
+    scope = deriveSecurityScope(changeDir, { source: 'guard' });
+  } catch (e) {
+    return { pass: false, failures: [`security scope derive crashed: ${e.message}`] };
+  }
+  if (scope.error) {
+    return {
+      pass: false,
+      failures: [`scope derive degraded (error=${scope.error}) — 无法推导适用范围，fail-closed；检查 git 基线（tf state init 打戳 base_sha）后重试 tf security scope`],
+    };
+  }
+
+  // 步 3：无适用触发类别 → PASS（已落盘留痕，可区分"无触发"与"门禁未生效"）
+  if (scope.triggered_categories.length === 0) {
+    return { pass: true, failures: [], reason: `no applicable trigger categories (${scope.files_scanned} surface files scanned); scope written for audit` };
+  }
+
+  // 步 4：skip 短路（最先于实质检查；hash 不匹配 = 范围已变 → skip 失效继续）
+  const skipped = state.security_baseline_skipped === true || state.security_baseline_skipped === 'true';
+  if (skipped) {
+    const reason = (state.security_baseline_skip_reason || '').trim();
+    if (!reason || reason === 'null') {
+      return { pass: false, failures: ['security_baseline_skipped=true but no skip reason — set security_baseline_skip_reason via tf state set'] };
+    }
+    if (state.security_scope_hash && state.security_scope_hash === scope.scope_hash) {
+      return { pass: true, failures: [], reason: `skipped: ${reason}` };
+    }
+    // hash 缺失/不匹配 → skip 失效（fail-closed 方向），继续实质检查
+  }
+
+  // 步 5：档位分流
+  if (mode === 'full') {
+    const ver = readVerification(changeDir);
+    if (!ver) {
+      return {
+        pass: false,
+        failures: [`.security-verification.json missing — 派发 code-reviewer（末 wave / planned 最终审查）产核验 JSON；无适用 code 项时亦须落盘（空 items + 全 N/A 说明）`],
+      };
+    }
+    if (ver === 'malformed') {
+      return { pass: false, failures: ['.security-verification.json malformed (JSON parse failed)'] };
+    }
+    const baseline = loadSecurityBaseline();
+    const { failures, warnings } = evaluateVerdicts(baseline, scope, ver);
+    if (failures.length) {
+      return { pass: false, failures, ...(warnings.length ? { warnings } : {}) };
+    }
+    if (warnings.length) {
+      return { pass: true, failures: [], reason: `pass with WARN: ${warnings.join('; ')}` };
+    }
+  }
+  // light 档（quick/lightweight）：不查 verification（direct 档无审查 receipt，设计 §八.5）
+
+  // 步 6：infra/config/process 交接检查（检查对象 = handoff.md，台账不进 guard）
+  if (scope.infra_item_ids.length > 0) {
+    const handoffPath = join(changeDir, HANDOFF_REL);
+    if (!existsSync(handoffPath) || !readFileSync(handoffPath, 'utf-8').trim()) {
+      return {
+        pass: false,
+        failures: [`infra-scope items ${scope.infra_item_ids.join('/')} apply but security/handoff.md missing or empty — write the handoff BEFORE tf state transition closing (设计 §L5 时序)`],
+      };
+    }
+  }
+
+  return { pass: true, failures: [] };
+}
+
+export function checkSecurityBaseline(changeDir) {
+  return evaluateSecurityBaseline(changeDir, 'full');
+}

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';
@@ -33,6 +36,9 @@ import { checkCompoundWritebackLight } from './checks/compound-writeback-light.m
 import { checkTestMergedLight } from './checks/test-merged-light.mjs';
 import { checkCrossChangeConsistencyLight } from './checks/cross-change-consistency-light.mjs';
 import { checkExecutionReviewsPassedLight } from './checks/execution-reviews-passed-light.mjs';
+// security-baseline-integration-design v1.3：安全基线双维度（executing→closing）
+import { checkSecurityBaseline } from './checks/security-baseline.mjs';
+import { checkSecurityBaselineLight } from './checks/security-baseline-light.mjs';
 
 // Transition matrix: <from>:<to> → required check dimensions
 const TRANSITION_CHECKS = {
@@ -57,10 +63,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 豁免（紧急/微调不挂）。
   //
@@ -77,7 +85,12 @@ const TRANSITION_CHECKS = {
   // artifacts_hash）→ **伪绿静默通过**。本维度直接比对 state.artifacts_hash 与制品实算值，
   // refresh-hash 无法清屏（它只改 plan JSON，不碰 state）——故为 refresh-hash 之外的独立锚。
   // hotfix/tweak 不挂：二者跳过 spec-writer、无 planning 四件，冻结机制本身 N/A（设计 §3.9）。
-  'executing:closing':              ['contract-fresh', 'tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete', 'arch-snapshot', 'delegation-status', 'arch-merged'],
+  // v1.3（security-baseline-integration-design）：security-baseline 新增——
+  // 44 项企业安全基线的机械闸门（现场推导 scope + verification 完备性 + infra 交接）。
+  // full（legacy variant）走本基表；hotfix 走 WORKFLOW 表、planned 走 PLANNED 表、
+  // quick/lightweight 走 QUICK 表挂 -light 变体、tweak 天然不挂（豁免）。
+  // 存量 change（无 schema_version）WARN 软着陆，冷启动零行为变化。
+  'executing:closing':              ['contract-fresh', 'tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete', 'arch-snapshot', 'delegation-status', 'arch-merged', 'security-baseline'],
 
   // Debugging side-path
   'executing:debugging':            [],
@@ -111,7 +124,9 @@ const WORKFLOW_TRANSITION_CHECKS = {
     'bridging:approved-for-build': ['contract-current', 'dp3-approved'],
     'approved-for-build:executing': ['contract-current', 'dp3-approved', 'execution-plan-ready'],
     // hotfix exemption: no test-matrix-complete (v0.12 §45.3)
-    'executing:closing': ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured'],
+    // v1.3：security-baseline 重档——hotfix 走逐 wave 审查（execution-reviews-passed 已挂），
+    // code-reviewer 派发即 verification 生产者，重档不死锁（P1.5 R3-C1 裁定回滚）。
+    'executing:closing': ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'security-baseline'],
   },
   tweak: {
     'exploring:approved-for-build': [],
@@ -134,16 +149,17 @@ 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'],
-    'executing:closing': ['direct-short-path', 'direct-test-result', 'test-matrix-complete'],
+    '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'],
+    // v1.3：security-baseline-light——direct 档无审查 receipt，省逐条 verdict（设计 §八.5）
+    'executing:closing': ['direct-short-path', 'direct-test-result', 'test-matrix-complete', 'security-baseline-light'],
     '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'],
-    'executing:closing': ['direct-short-path', 'direct-test-result', 'lightweight-completion-evidence', 'test-matrix-complete'],
+    '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', 'security-baseline-light'],
     'executing:debugging': [],
     'debugging:executing': ['direct-test-result'],
   },
@@ -155,12 +171,14 @@ 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',
     'cross-change-consistency-light', 'delegation-status', 'specs-merged', 'tasks-complete',
+    // v1.3：security-baseline 重档（planned 有最终审查，verification 有生产者）
+    'security-baseline',
   ],
   'executing:debugging': [],
   'debugging:executing': ['execution-plan-ready', 'tests-passing'],
@@ -293,6 +311,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：接活前双维度。缺失态中性——冷启动零行为变化。
+    '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),
@@ -309,6 +330,10 @@ async function main() {
     'test-merged-light': (dir) => checkTestMergedLight(dir),
     'cross-change-consistency-light': (dir) => checkCrossChangeConsistencyLight(dir),
     'execution-reviews-passed-light': (dir) => checkExecutionReviewsPassedLight(dir),
+    // security-baseline-integration-design v1.3（35 维）：安全基线双维度。
+    // 重档（full/hotfix/planned）查 verification 完备性；轻档（quick/lightweight）省逐条核验。
+    'security-baseline': (dir) => checkSecurityBaseline(dir),
+    'security-baseline-light': (dir) => checkSecurityBaselineLight(dir),
   };
 
   const checks = [];

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());