@xulthekl/team-flow 0.62.0 → 0.64.0

package/scripts/guard/checks/contract-fresh.mjs

@@ -1,17 +1,61 @@
 // scripts/guard/checks/contract-fresh.mjs — check contract staleness via hash comparison
+//
+// v0.63.0（workflow-feedback 20260923-013114 S3）：本维度新增挂载到 executing:closing。
+// 动机：S3「DP-3 后 planning 制品冻结」的反查锚——原本 closing 侧反查依赖
+// execution-plan-ready（validatePlan 比对 plan 内嵌的 artifacts_hash/contract_hash），
+// 而该比对可被 `tf execution refresh-hash` 一键刷平（它只改 plan JSON）→ 把 gate-affecting
+// 变更伪记为陈述性勘误后，closing 全维 PASS、wave receipt 亦不失效（wave_fingerprint
+// 不含 artifacts_hash）→ **伪绿静默通过**。本维度直接比对 state.artifacts_hash 与制品实算值，
+// refresh-hash 无法清屏（它不碰 state），故为独立锚。
+//
+// 注意（卡死面）：本维度**无 legacy 豁免**（与既有挂载点一致）——存量 change 在 closing
+// 若状态文件缺 artifacts_hash 会被拦。故失败信息必须给出可执行出路（tf state rebuild），
+// 不得让门禁成为无出口的闭门（参照 arch_merge_skipped 的设计原则）。
+import fs from 'node:fs';
+import path from 'node:path';
 import { isContractFresh } from '../../lib/hash.mjs';
+import { readState } from '../../lib/state-loader.mjs';
+
+// v0.63.0（P4 评审 L3）：裸 rebuild 会重算并覆盖 state.artifacts_hash——若发生在 DP-3 冻结之后，
+// 它就成了与 refresh-hash 并列的「清屏」通道，且不留任何 errata 痕迹。故提示按时间点分流：
+// 冻结前的改动可裸 rebuild；冻结后的改动必须走勘误登记/例外 2，不得用 rebuild 把差异抹平。
+const REBUILD_HINT =
+  'If the planning change predates DP-3 approval, re-capture the hash: `tf state rebuild <dir>`. '
+  + 'If it happened AFTER DP-3, the artifacts are FROZEN: record it in the contract `## Errata Register` '
+  + 'under the applicable exception (doc-only corrections), or take the gate-affecting path rebuild->revise '
+  + '(exception 2). Do NOT rebuild past a frozen change — that erases the diff without any errata trace.';
 
 /**
  * Compare stored artifacts_hash in .team-flow.yaml against current artifact hashes.
  * Returns { pass, failures[] }.
  */
 export function checkContractFresh(changeDir) {
-  const fresh = isContractFresh(changeDir);
-  if (fresh) {
+  if (isContractFresh(changeDir)) {
     return { pass: true, failures: [] };
   }
+
+  // 区分两类失败，给出各自的出路（否则关闭期死锁无指示）。
+  let stored = null;
+  try {
+    const state = readState(changeDir);
+    stored = state?.artifacts_hash ?? null;
+  } catch {
+    stored = null;
+  }
+  if (!stored || stored === 'null') {
+    return {
+      pass: false,
+      failures: [
+        'execution-contract.md freshness cannot be judged: the state file carries no artifacts_hash '
+        + '(hand-written or truncated .team-flow.yaml). Re-capture it: `tf state rebuild <dir>`.',
+      ],
+    };
+  }
+
   return {
     pass: false,
-    failures: ['execution-contract.md is stale: artifacts hash mismatch. Re-run contract-builder to regenerate.'],
+    failures: [
+      `execution-contract.md is stale: artifacts hash mismatch. ${REBUILD_HINT}`,
+    ],
   };
-}
+}

package/scripts/guard/checks/cross-change-consistency-light.mjs

@@ -0,0 +1,75 @@
+// scripts/guard/checks/cross-change-consistency-light.mjs — 跨 change 冲突确定性初筛（§3.3）
+// v0.64.0（A-14/S-07 重定义）：guard runner 是 10s 内确定性 Node 函数，**不能调 LLM agent**。
+// 本 runner 做机械初筛：其他在途 change（state ∈ executing/debugging/approved-for-build）
+// 的 minimal api.md 端点路径 / architecture.md 聚合行 与本 change 的最小源求交——
+// 交集非空 = 共享 surface 冲突。语义级冲突由 release-archivist 关门序列派发
+// cross-change-consistency-checker agent 兜底（分工见 §3.3）。
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { findProjectRoot } from '../../lib/surface-scan.mjs';
+
+const IN_FLIGHT = new Set(['approved-for-build', 'executing', 'debugging']);
+
+function extractApiPaths(file) {
+  if (!existsSync(file)) return new Set();
+  const text = readFileSync(file, 'utf-8');
+  // 端点表单元格里的路径 token（/api/xxx、/v1/xxx、{id} 形态）
+  const out = new Set();
+  for (const m of text.matchAll(/(\/[A-Za-z0-9_\-{}./]+)/g)) {
+    const p = m[1];
+    if (p.length > 1 && !p.endsWith('.md')) out.add(p.replace(/\/+$/, ''));
+  }
+  return out;
+}
+
+function extractAggregateNames(file) {
+  if (!existsSync(file)) return new Set();
+  const text = readFileSync(file, 'utf-8');
+  const out = new Set();
+  for (const m of text.matchAll(/聚合[：:\s*`]+[`*]*([A-Za-z][A-Za-z0-9_\-]*)/g)) out.add(m[1]);
+  return out;
+}
+
+export function checkCrossChangeConsistencyLight(changeDir) {
+  const state = readState(changeDir);
+  const projectRoot = findProjectRoot(changeDir);
+  const changesDir = join(projectRoot, 'changes');
+  if (!existsSync(changesDir)) return { pass: true, failures: [], reason: 'no changes/ dir' };
+
+  const selfName = state.change_name || basename(changeDir);
+  const selfApi = extractApiPaths(join(changeDir, 'architecture', 'api.md'));
+  const selfAgg = extractAggregateNames(join(changeDir, 'architecture', 'architecture.md'));
+
+  const conflicts = [];
+  for (const entry of readdirSync(changesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === selfName) continue;
+    const otherDir = join(changesDir, entry.name);
+    const otherStatePath = join(otherDir, '.team-flow.yaml');
+    if (!existsSync(otherStatePath)) continue;
+    const other = readState(otherDir);
+    if (!IN_FLIGHT.has(other.state)) continue;
+
+    const otherApi = extractApiPaths(join(otherDir, 'architecture', 'api.md'));
+    const otherAgg = extractAggregateNames(join(otherDir, 'architecture', 'architecture.md'));
+
+    const apiOverlap = [...selfApi].filter(p => otherApi.has(p));
+    const aggOverlap = [...selfAgg].filter(a => otherAgg.has(a));
+    if (apiOverlap.length || aggOverlap.length) {
+      conflicts.push(
+        `${entry.name}: api=[${apiOverlap.slice(0, 5).join(', ')}] aggregates=[${aggOverlap.slice(0, 5).join(', ')}]`
+      );
+    }
+  }
+
+  if (conflicts.length) {
+    return {
+      pass: false,
+      failures: [
+        `shared surface conflicts with in-flight change(s):\n    ${conflicts.join('\n    ')} `
+        + '— resolve ownership or stagger closing; semantic-level review via cross-change-consistency-checker agent',
+      ],
+    };
+  }
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/direct-short-path.mjs

@@ -0,0 +1,52 @@
+// scripts/guard/checks/direct-short-path.mjs — direct/lightweight 短路径 + 架构 surface 扫描
+// v0.64.0（实施计划 §4，G1 加固）：
+// - 挂 quick/lightweight 的 exploring→approved-for-build / approved-for-build→executing / closing
+// - G4 前提保障：无架构 surface（API/DB/聚合）→ 过（真琐碎零负担）
+// - 命中架构 surface → FAIL 并给升级指引（禁止静默过）；扫描失败/清单缺失一律 fail-closed
+import { readState } from '../../lib/state-loader.mjs';
+import { scanArchitectureSurface } from '../../lib/surface-scan.mjs';
+
+const UPGRADE_HINT =
+  'architecture surface (API/DB/aggregate) touched — upgrade to planned: '
+  + 'tf state upgrade <change-dir> planned (keeps code/test evidence, rolls back to approved-for-build, '
+  + 're-runs planned gates + light writeback sequence; downgrades rejected)';
+
+export function checkDirectShortPath(changeDir) {
+  const state = readState(changeDir);
+  const scan = scanArchitectureSurface(changeDir, state);
+
+  if (scan.error === 'no-baseline') {
+    return {
+      pass: false,
+      failures: [
+        'no scan baseline: base_sha missing and no origin/<default> to derive merge-base — '
+        + 'run inside a git repo with at least one commit (tf state init stamps base_sha), fail-closed',
+      ],
+    };
+  }
+  if (scan.error === 'diff-failed') {
+    return {
+      pass: false,
+      failures: [`git diff against base failed (base=${scan.base ?? 'unknown'}) — cannot verify architecture surface, fail-closed`],
+    };
+  }
+  if (scan.error === 'aggregate-list-missing') {
+    return {
+      pass: false,
+      failures: [
+        'aggregate list missing: create .team-flow/aggregate-dirs.txt (one dir prefix per line; '
+        + 'empty file = explicitly no aggregates) or run workflow-bootstrap — fail-closed, aggregate surface is blind otherwise',
+      ],
+    };
+  }
+
+  if (scan.architectureSurface.length > 0) {
+    return {
+      pass: false,
+      failures: [
+        `${UPGRADE_HINT}\n    touched: ${scan.architectureSurface.slice(0, 10).join(', ')}`,
+      ],
+    };
+  }
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/direct-test-result.mjs

@@ -0,0 +1,30 @@
+// scripts/guard/checks/direct-test-result.mjs — direct/lightweight 验证证据（§4.5 注记③）
+// v0.64.0：guard 只读 tf test record 程序化证据，绝不在 guard 进程内现场跑测试
+// （cmd-state spawnSync 10s 总超时会杀掉 guard，A-19）。证据机制与 tests-passing 同源。
+import fs from 'node:fs';
+import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { parseStructuredTestResult } from './tests-passing.mjs';
+
+const RECORD_HINT = 'run your verification command, then record it: tf test record <change-dir> --from <runner-output>';
+
+export function checkDirectTestResult(changeDir) {
+  const state = readState(changeDir);
+  const parsed = parseStructuredTestResult(state.test_result);
+  if (!parsed || parsed.verdict !== 'pass') {
+    return { pass: false, failures: [`no passing programmatic test evidence recorded — ${RECORD_HINT}`] };
+  }
+  if (parsed.total == null || parsed.total <= 0) {
+    return { pass: false, failures: [`recorded evidence has total=0 (empty-run rejected) — ${RECORD_HINT}`] };
+  }
+  if (!state.test_evidence_path) {
+    return { pass: false, failures: [`test_evidence_path missing — ${RECORD_HINT}`] };
+  }
+  const evidenceAbs = path.isAbsolute(state.test_evidence_path)
+    ? state.test_evidence_path
+    : path.join(changeDir, state.test_evidence_path);
+  if (!fs.existsSync(evidenceAbs)) {
+    return { pass: false, failures: [`evidence file not found: ${state.test_evidence_path} — ${RECORD_HINT}`] };
+  }
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/execution-plan-ready.mjs

@@ -7,7 +7,7 @@ import { readState } from '../../lib/state-loader.mjs';
  * A non-empty DP-4 field is not sufficient: it must name the current plan
  * revision, whose hashes, workflow, mode, and state summary remain current.
  */
-export function checkExecutionPlanReady(changeDir) {
+export function checkExecutionPlanReady(changeDir, ctx = {}) {
   const plan = readPlan(changeDir);
   if (!plan) {
     return {
@@ -21,6 +21,12 @@ export function checkExecutionPlanReady(changeDir) {
     return { pass: false, failures: validation.failures };
   }
 
+  // v0.64.0（§4.5 注记⑤，R2 兼容性修复）：planned 无 DP-4——豁免 DP-4 revision 精确引用，
+  // 判据 = plan 存在 + validatePlan 通过（内嵌 hash 与制品一致）。
+  if (ctx.variant === 'planned') {
+    return { pass: true, failures: [], reason: 'planned variant: DP-4 reference waived; plan file + hash validation suffice' };
+  }
+
   const state = readState(changeDir);
   const expectedRevision = `plan revision ${plan.revision}`;
   const decision = typeof state.dp_4_result === 'string' ? state.dp_4_result : '';

package/scripts/guard/checks/execution-reviews-passed-light.mjs

@@ -0,0 +1,28 @@
+// scripts/guard/checks/execution-reviews-passed-light.mjs — planned 一次最终审查（§4.5）
+// v0.64.0（A-05①）：planned 无波次无逐波 receipt——判据 = 关门前存在非空（≥5 非空行）
+// 最终审查记录 final-review.md；内容最低契约（B-01）防空文件桩。
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MIN_LINES = 5;
+
+export function checkExecutionReviewsPassedLight(changeDir) {
+  const p = join(changeDir, 'final-review.md');
+  if (!existsSync(p)) {
+    return {
+      pass: false,
+      failures: [
+        'final-review.md missing — planned path requires ONE final review before closing '
+        + '(record verdict, scope, and findings; ≥5 lines)',
+      ],
+    };
+  }
+  const lines = readFileSync(p, 'utf-8').split('\n').filter(l => l.trim()).length;
+  if (lines < MIN_LINES) {
+    return {
+      pass: false,
+      failures: [`final-review.md too thin (${lines} non-empty lines, need ≥${MIN_LINES}) — record verdict + scope + findings`],
+    };
+  }
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/gates-probed.mjs

@@ -0,0 +1,175 @@
+// scripts/guard/checks/gates-probed.mjs — bridging dry-run evidence gate
+//
+// v0.63.0（workflow-feedback 20260923-013114 S2）：
+// full workflow 的 bridging→approved-for-build 新增本维度——契约产出的 G 类闸门
+// 必须已在**主工作区当前态**跑过 dry-run（预期 FAIL = RED 基线），原始输出留档。
+// 动机：`design.md` R-7「闸门命令已实测可跑」长期只是**文字自证**；实测中 G1 格式约束、
+// grep shim、dist 误入扫描、desc 文案 vs G2 互斥均在施工中才暴露。
+//
+// **存在性强制（Critical 处置，不得退回内容型豁免）**：
+// 契约缺 `## Gate Registry` 段 / 表解析失败 → **FAIL**，不得落入 N/A 放行。
+// 依据：v0.13 RC-1 已删除「以 contract 内容为键」的豁免——test-gate-exemptions.mjs
+// :7-10 明文记载「无法区分真存量与漏生成，导致零测试通过全部门禁」；既有先例
+// `contractDeclaresTestMatrix` 走的是段存在性硬要求。本 check 复刻该先例。
+//
+// 与 test-matrix-ready（:49 入口门禁）同构：legacy 豁免 + 显式 skip 附理由。
+import fs from 'node:fs';
+import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { computeContractHash } from '../../lib/hash.mjs';
+import { isLegacyChange } from './test-gate-exemptions.mjs';
+
+export const EVIDENCE_REL = path.join('.superpowers', 'test-evidence', 'bridging-gates-red.txt');
+const REGISTRY_HEADING = '## Gate Registry';
+const RED_BASELINE_LINE = 'EXPECTED: FAIL (RED baseline)';
+const SKIP_REASON_HINT =
+  'gates_probed_skipped=true requires gates_probed_skip_reason — record it: '
+  + "tf state set <dir> gates_probed_skip_reason '<why this change has no gate dry-run>'";
+
+/** 提取 '## Gate Registry' 段正文（到下一个同级标题或文件尾）。 */
+export function extractRegistrySection(contractText) {
+  const lines = contractText.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === REGISTRY_HEADING);
+  if (start === -1) return null;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^##\s/.test(lines[i])) break;
+    body.push(lines[i]);
+  }
+  return body.join('\n');
+}
+
+/**
+ * 解析 Gate Registry 表格的 id 列。
+ * 表头固定 `| id | phase | command | expected |`；id 形如 G-1。
+ * @returns {string[]} id 列表（去重，出现顺序）
+ */
+export function parseGateIds(sectionBody) {
+  const ids = [];
+  for (const line of sectionBody.split(/\r?\n/)) {
+    if (!line.trim().startsWith('|')) continue;
+    const cells = line.split('|').map((c) => c.trim());
+    // cells[0] === ''（前导竖线），故首列在 index 1
+    const first = cells[1] || '';
+    if (!first || /^-+$/.test(first) || first.toLowerCase() === 'id') continue;
+    if (!ids.includes(first)) ids.push(first);
+  }
+  return ids;
+}
+
+/** 段内显式声明零闸门 + 理由（形如 `N/A: <理由>`）。 */
+export function declaredNotApplicable(sectionBody) {
+  const m = sectionBody.match(/(?:^|\n)\s*(?:N\/A|NA)\s*[:：]\s*(.+)/i);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Returns { pass, failures[], reason? }.
+ */
+export function checkGatesProbed(changeDir) {
+  const state = readState(changeDir);
+
+  // Exemption 1：legacy change（v0.32.0 之前初始化，无 schema_version 打戳）。
+  if (isLegacyChange(state)) {
+    return { pass: true, failures: [], reason: 'legacy change — initialized before v0.32.0' };
+  }
+
+  // Exemption 2：显式 skip（必须附理由）。
+  if (state.gates_probed_skipped === 'true') {
+    const reason = state.gates_probed_skip_reason;
+    if (typeof reason !== 'string' || reason.trim().length === 0) {
+      return { pass: false, failures: [SKIP_REASON_HINT] };
+    }
+    return { pass: true, failures: [], reason: `explicitly skipped: ${reason}` };
+  }
+
+  // 段存在性硬要求（fail-closed）：缺段 / 解析失败一律 FAIL，不得落 N/A。
+  const contractPath = path.join(changeDir, 'execution-contract.md');
+  if (!fs.existsSync(contractPath)) {
+    return { pass: false, failures: ['execution-contract.md is missing — run contract-builder first'] };
+  }
+  const contractText = fs.readFileSync(contractPath, 'utf-8');
+  const section = extractRegistrySection(contractText);
+  if (section === null) {
+    return {
+      pass: false,
+      failures: [
+        `contract does not declare ${REGISTRY_HEADING} — return to bridging so contract-builder generates it.`,
+        'A missing section is NOT a "no gates" declaration: absence of the registry cannot be distinguished '
+        + 'from an omitted registry (v0.13 RC-1 content-key exemption was removed for exactly this reason).',
+        'If this change genuinely has no gates, write the section with an explicit "N/A: <reason>" line.',
+      ],
+    };
+  }
+  const gateIds = parseGateIds(section);
+
+  // N/A：段存在 + 显式声明零闸门 + 理由（state 键为备用通道）。
+  if (gateIds.length === 0) {
+    const naReason = declaredNotApplicable(section);
+    if (naReason) {
+      return { pass: true, failures: [], reason: `not applicable — ${naReason}` };
+    }
+    if (state.gates_probed_na === 'true') {
+      return { pass: true, failures: [], reason: 'not applicable — gates_probed_na set in state' };
+    }
+    return {
+      pass: false,
+      failures: [
+        `${REGISTRY_HEADING} present but declares no gate id and no "N/A: <reason>" line.`,
+        'Either list the gates (| id | phase | command | expected |) or state "N/A: <reason>".',
+      ],
+    };
+  }
+
+  // 正常路径：evidence 文件 + 首行 RED 基线 + hash 值新鲜 + id 全覆盖。
+  const evidencePath = path.join(changeDir, EVIDENCE_REL);
+  if (!fs.existsSync(evidencePath)) {
+    return {
+      pass: false,
+      failures: [
+        `${EVIDENCE_REL} is missing — run the bridging gate dry-run (expect FAIL = RED baseline) `
+        + 'and persist the raw output there.',
+        'Required first line: ' + RED_BASELINE_LINE,
+      ],
+    };
+  }
+  const evidence = fs.readFileSync(evidencePath, 'utf-8');
+  const failures = [];
+  const evidenceLines = evidence.split(/\r?\n/);
+  const firstNonEmpty = evidenceLines.find((l) => l.trim().length > 0) || '';
+  if (firstNonEmpty.trim() !== RED_BASELINE_LINE) {
+    failures.push(
+      `evidence first line must be exactly "${RED_BASELINE_LINE}", got: "${firstNonEmpty.trim().slice(0, 80)}". `
+      + 'A gate that already PASSES means the baseline was not RED — record the expected-FAIL run instead.',
+    );
+  }
+
+  // 新鲜度 = hash 值比对（非 mtime）：
+  // refresh-hash / state rebuild 均不重写契约文件，故 mtime 判据只会在「契约字节等价重生成」
+  // 或 git 恢复场景下误报；hash 值比对天然免疫。
+  const contractHash = computeContractHash(changeDir);
+  const hashMatch = evidence.match(/CONTRACT_HASH:\s*(sha256:[0-9a-f]{64})/);
+  if (!hashMatch) {
+    failures.push(
+      'evidence must carry a "CONTRACT_HASH: sha256:<64 hex>" line so freshness is judged by content, not mtime.',
+    );
+  } else if (contractHash && hashMatch[1] !== contractHash) {
+    failures.push(
+      `evidence is stale: CONTRACT_HASH ${hashMatch[1].slice(0, 20)}… does not match current contract `
+      + `${String(contractHash).slice(0, 20)}… — re-run the dry-run against the current contract.`,
+    );
+  }
+
+  const missingIds = gateIds.filter((id) => {
+    const esc = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return !new RegExp(`(^|[^\\w-])${esc}([^\\w-]|$)`).test(evidence);
+  });
+  if (missingIds.length > 0) {
+    failures.push(
+      `evidence does not cover declared gate id(s): ${missingIds.join(', ')} — every id in ${REGISTRY_HEADING} needs a dry-run record.`,
+    );
+  }
+
+  if (failures.length > 0) return { pass: false, failures };
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/lightweight-completion-evidence.mjs

@@ -0,0 +1,27 @@
+// scripts/guard/checks/lightweight-completion-evidence.mjs — lightweight 档完成证据（§4.5）
+// v0.64.0：类 direct-test-result——证据文件须存在且非空（独立于 test_result 解析，
+// 兜住「test_result 被清但文件还在」与「文件被删但记录还在」两种漂移）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+
+export function checkLightweightCompletionEvidence(changeDir) {
+  const state = readState(changeDir);
+  if (!state.test_evidence_path) {
+    return {
+      pass: false,
+      failures: ['completion evidence missing: test_evidence_path is null — record verification via tf test record before closing'],
+    };
+  }
+  const abs = path.isAbsolute(state.test_evidence_path)
+    ? state.test_evidence_path
+    : path.join(changeDir, state.test_evidence_path);
+  if (!fs.existsSync(abs)) {
+    return { pass: false, failures: [`completion evidence file not found: ${state.test_evidence_path}`] };
+  }
+  const content = fs.readFileSync(abs, 'utf-8').trim();
+  if (!content) {
+    return { pass: false, failures: [`completion evidence file is empty: ${state.test_evidence_path}`] };
+  }
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/specs-merged.mjs

@@ -34,11 +34,35 @@ function hasDeltaSpecs(changeDir) {
  * Passes when either spec_merged is recorded, or there are no delta specs to merge.
  * Blocks `executing → closing` when delta specs exist but spec-merger hasn't run.
  */
-export function checkSpecsMerged(changeDir) {
+export function checkSpecsMerged(changeDir, ctx = {}) {
   const state = readState(changeDir);
   if (state.spec_merged === true || state.spec_merged === 'true') {
     return { pass: true, failures: [] };
   }
+  // v0.64.0（§4.5 注记⑦，B-02）：planned 轻语义——无 specs/ 目录即过；
+  // 有 specs/ 但无 delta 头 = 手写完整形态 specs 永不合并 → FAIL（补 delta 头或移除）。
+  if (ctx.variant === 'planned') {
+    const specsDir = join(changeDir, 'specs');
+    if (!existsSync(specsDir)) {
+      return { pass: true, failures: [], reason: 'planned: no specs/ dir — merge N/A' };
+    }
+    if (!hasDeltaSpecs(changeDir)) {
+      return {
+        pass: false,
+        failures: [
+          'specs/ exists but no ## ADDED/MODIFIED/REMOVED/RENAMED Requirements delta headers — '
+          + 'full-form specs would never merge; add delta headers (then spec-merger) or remove specs/',
+        ],
+      };
+    }
+    // 有 delta 头但未合并 → 落到下方统一失败
+    return {
+      pass: false,
+      failures: [
+        'Delta specs exist in specs/ but spec-merger has not run (spec_merged not recorded). Run spec-merger to merge ADDED/MODIFIED/REMOVED/RENAMED requirements before closing.',
+      ],
+    };
+  }
   if (!hasDeltaSpecs(changeDir)) {
     return { pass: true, failures: [] };
   }

package/scripts/guard/checks/test-matrix-complete.mjs

@@ -19,7 +19,7 @@ import {
 /**
  * Returns { pass, failures[], reason? }.
  */
-export function checkTestMatrixComplete(changeDir) {
+export function checkTestMatrixComplete(changeDir, ctx = {}) {
   const state = readState(changeDir);
 
   // Step 1 — legacy：v0.32.0 之前初始化的 change（无 schema_version 打戳）保留旧行为。
@@ -40,6 +40,32 @@ export function checkTestMatrixComplete(changeDir) {
     return { pass: true, failures: [], reason: `explicitly skipped: ${state.test_matrix_skip_reason}` };
   }
 
+  // v0.64.0（§4.5 注记②，D4 无契约轻量判据）：direct/planned/quick/lightweight
+  // 无契约 → 跳过 Step 3 契约声明检查；矩阵存在非空 +（若已记录）hash 一致即可。
+  const isLight = ctx.variant === 'direct' || ctx.variant === 'planned'
+    || ctx.workflow === 'quick' || ctx.workflow === 'lightweight';
+  if (isLight) {
+    const matrix = readTestMatrixFile(changeDir);
+    if (!matrix.exists || matrix.empty) {
+      return {
+        pass: false,
+        failures: [
+          !matrix.exists
+            ? 'test-matrix.md missing — light path requires the matrix file itself (no contract)'
+            : 'test-matrix.md is empty — must contain at least a Summary section and Cases table',
+          'or skip explicitly: tf state set <dir> test_matrix_skipped true + test_matrix_skip_reason "<reason>"',
+        ],
+      };
+    }
+    if (state.test_matrix_hash) {
+      const computedLight = computeTestMatrixHash(changeDir);
+      if (computedLight !== state.test_matrix_hash) {
+        return { pass: false, failures: ['test-matrix.md changed since recorded hash — run tf state rebuild'] };
+      }
+    }
+    return { pass: true, failures: [] };
+  }
+
   // Step 3 — 非存量 change 的契约必须声明矩阵（v0.13：内容型豁免删除）。
   const contract = contractDeclaresTestMatrix(changeDir);
   if (!contract.exists) {

package/scripts/guard/checks/test-matrix-ready.mjs

@@ -17,7 +17,7 @@ import {
 /**
  * Returns { pass, failures[], reason? }.
  */
-export function checkTestMatrixReady(changeDir) {
+export function checkTestMatrixReady(changeDir, ctx = {}) {
   const state = readState(changeDir);
 
   // Exemption 1：legacy change（v0.32.0 之前初始化，无 schema_version 打戳）。
@@ -25,6 +25,33 @@ export function checkTestMatrixReady(changeDir) {
     return { pass: true, failures: [], reason: 'legacy change — initialized before v0.32.0' };
   }
 
+  // v0.64.0（§4.5 注记②，D4 无契约轻量判据）：direct/planned/quick/lightweight
+  // 无 execution-contract——判据降为「test-matrix.md 存在非空 OR 显式 skip 附理由」，
+  // 不要求契约声明段。skip 仍须附理由（拒 state set 自清为常规通过路径）。
+  const isLight = ctx.variant === 'direct' || ctx.variant === 'planned'
+    || ctx.workflow === 'quick' || ctx.workflow === 'lightweight';
+  if (isLight) {
+    if (state.test_matrix_skipped === 'true') {
+      if (skipMissingReason(state)) {
+        return { pass: false, failures: [SKIP_REASON_HINT] };
+      }
+      return { pass: true, failures: [], reason: `explicitly skipped: ${state.test_matrix_skip_reason}` };
+    }
+    const matrix = readTestMatrixFile(changeDir);
+    if (matrix.exists && !matrix.empty) {
+      return { pass: true, failures: [] };
+    }
+    return {
+      pass: false,
+      failures: [
+        matrix.exists
+          ? 'test-matrix.md is empty — add a Summary + Cases table (light path has no contract section)'
+          : 'test-matrix.md missing — create it (light path: matrix file alone is sufficient, no contract needed)',
+        'or skip explicitly: tf state set <dir> test_matrix_skipped true + test_matrix_skip_reason "<reason>"',
+      ],
+    };
+  }
+
   // Exemption 2：显式 skip（必须附理由）。
   if (state.test_matrix_skipped === 'true') {
     // v2.1 §6.3 skip 禁令：glaf4-delegation 模式禁止 skip（唯一例外 TEST_BOOTSTRAP）

package/scripts/guard/checks/test-merged-light.mjs

@@ -0,0 +1,36 @@
+// scripts/guard/checks/test-merged-light.mjs — 测试台账轻回写（§4，横展发现的同型全局态）
+// v0.64.0：无测试触碰 → 过；有 → docs/test-ledger/** 须含归因 change:<name>
+//（写入走 tf test-merge --light，同 sink 同 rewriteIndex 单写入口）。
+import { readState } from '../../lib/state-loader.mjs';
+import { scanArchitectureSurface } from '../../lib/surface-scan.mjs';
+import { filesContainDir } from './_fs-utils.mjs';
+import { join } from 'node:path';
+
+export function checkTestMergedLight(changeDir) {
+  const state = readState(changeDir);
+  const changeName = state.change_name || changeDir.split('/').filter(Boolean).pop();
+  const scan = scanArchitectureSurface(changeDir, state);
+
+  if (scan.error === 'no-baseline' || scan.error === 'diff-failed') {
+    return { pass: false, failures: [`surface scan failed (${scan.error}) — cannot determine touched tests, fail-closed`] };
+  }
+  if (scan.error === 'aggregate-list-missing') {
+    // 测试判定不依赖聚合清单——降级为仅用文件清单分类（清单缺失不阻塞本维度）
+    // 但 scanArchitectureSurface 在清单缺失时不返回 files……此时保守 FAIL：
+    return { pass: false, failures: ['aggregate list missing (.team-flow/aggregate-dirs.txt) — shared scan precondition unmet, fail-closed'] };
+  }
+
+  if (scan.testFiles.length === 0) {
+    return { pass: true, failures: [], reason: 'no test files touched — test ledger writeback N/A' };
+  }
+
+  const ledger = join(scan.projectRoot, 'docs', 'test-ledger');
+  const anchor = `change:${changeName}`;
+  if (filesContainDir(ledger, anchor) || filesContainDir(ledger, changeName)) {
+    return { pass: true, failures: [] };
+  }
+  return {
+    pass: false,
+    failures: [`tests touched but docs/test-ledger/** has no '${anchor}' entry — run: tf test-merge --light <change-dir>`],
+  };
+}