@xulthekl/team-flow 0.22.4

package/scripts/check-version-consistency.mjs

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+// check-version-consistency.mjs — CI guard: fail if any file has a version
+// that doesn't match package.json. Prevents doc/code drift after tf version.
+//
+// Usage:
+//   node scripts/check-version-consistency.mjs          # check only (exit 1 on mismatch)
+//   node scripts/check-version-consistency.mjs --fix    # auto-fix skill counts & npx refs
+//
+// Exit 0: all versions consistent (or fixed successfully)
+// Exit 1: mismatches found (lists every file and its version)
+
+import { readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+const AUTO_FIX = process.argv.includes('--fix');
+
+// Canonical version from package.json
+const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+const CANONICAL = pkg.version;
+if (!CANONICAL || !/^\d+\.\d+\.\d+$/.test(CANONICAL)) {
+  console.error('❌ package.json version is missing or invalid');
+  process.exit(1);
+}
+
+const errors = [];
+const fixes = [];
+
+// ── JSON manifests ──
+const JSON_CHECKS = [
+  { file: 'plugin.json', path: ['version'] },
+  { file: '.claude-plugin/plugin.json', path: ['version'] },
+  { file: '.claude-plugin/marketplace.json', path: ['plugins', '0', 'version'] },
+  { file: '.cursor-plugin/plugin.json', path: ['version'] },
+  { file: '.cursor-plugin/marketplace.json', path: ['metadata', 'version'] },
+  { file: '.codex-plugin/plugin.json', path: ['version'] },
+  { file: 'gemini-extension.json', path: ['version'] },
+  { file: '.github/plugin/marketplace.json', path: ['metadata', 'version'] },
+  { file: '.github/plugin/marketplace.json', path: ['plugins', '0', 'version'] },
+];
+
+for (const check of JSON_CHECKS) {
+  const fp = join(ROOT, check.file);
+  if (!existsSync(fp)) {
+    errors.push({ file: check.file, found: 'FILE_NOT_FOUND', expected: CANONICAL });
+    continue;
+  }
+  try {
+    const obj = JSON.parse(readFileSync(fp, 'utf-8'));
+    let val = obj;
+    for (const p of check.path) val = val?.[p];
+    if (val !== CANONICAL) {
+      errors.push({ file: `${check.file} [${check.path.join('.')}]`, found: val, expected: CANONICAL });
+    }
+  } catch (e) {
+    errors.push({ file: check.file, found: `PARSE_ERROR: ${e.message}`, expected: CANONICAL });
+  }
+}
+
+// ── Text files (extraction-pattern check) ──
+// Each entry has a regex that extracts ONLY the declared version (capture group 1),
+// not historical references like "v0.6.0 起支持".
+// Note: CLAUDE.md is intentionally gitignored (project-local AI instructions).
+const TEXT_CHECKS = [
+  { file: 'README.md',              extract: /当前版本：`v(\d+\.\d+\.\d+)`/ },
+  { file: 'INSTALL.md',             extract: /当前发布版本：\*\*v(\d+\.\d+\.\d+)\*\*/ },
+  { file: 'docs/README_en.md',      extract: /Current: `v(\d+\.\d+\.\d+)`/ },
+  { file: 'hooks/session-start',    extract: /# v(\d+\.\d+\.\d+): conditional injection/ },
+  { file: 'llms.txt',               extract: /Current version: v(\d+\.\d+\.\d+)\./ },
+  { file: '.claude/always/phase-guard.md', extract: /# team-flow v(\d+\.\d+\.\d+) \|/ },
+  { file: 'GEMINI.md',              extract: /# team-flow v(\d+\.\d+\.\d+) \|/ },
+];
+
+for (const check of TEXT_CHECKS) {
+  const fp = join(ROOT, check.file);
+  if (!existsSync(fp)) {
+    errors.push({ file: check.file, found: 'FILE_NOT_FOUND', expected: CANONICAL });
+    continue;
+  }
+  const content = readFileSync(fp, 'utf-8');
+  const match = content.match(check.extract);
+  if (!match) {
+    errors.push({ file: check.file, found: 'PATTERN_NOT_MATCHED', expected: CANONICAL });
+  } else if (match[1] !== CANONICAL) {
+    errors.push({ file: check.file, found: match[1], expected: CANONICAL });
+  }
+}
+
+const RUNTIME_FILES = [
+  'workflow-start', 'need-explorer', 'spec-writer', 'contract-builder',
+  'build-executor', 'code-reviewer', 'bug-investigator', 'release-archivist', 'spec-merger',
+].map(skill => `skills/${skill}/SKILL.md`).concat([
+  'skills/build-executor/implementer-prompt.md',
+  'skills/build-executor/task-reviewer-prompt.md',
+  'skills/code-reviewer/code-reviewer-prompt.md',
+]);
+for (const file of RUNTIME_FILES) {
+  const fp = join(ROOT, file);
+  if (!existsSync(fp)) {
+    errors.push({ file, found: 'FILE_NOT_FOUND', expected: CANONICAL });
+    continue;
+  }
+  const versions = [...readFileSync(fp, 'utf8').matchAll(/npx --yes --package @xulthekl\/team-flow@(\d+\.\d+\.\d+) tf/g)]
+    .map(match => match[1]);
+  if (versions.length === 0) {
+    errors.push({ file, found: 'RUNTIME_PREFIX_NOT_FOUND', expected: CANONICAL });
+  } else if (versions.some(version => version !== CANONICAL)) {
+    errors.push({ file, found: [...new Set(versions)].join(', '), expected: CANONICAL });
+  }
+}
+
+// ── Skill count consistency ──
+// Count actual skill directories under skills/ and compare against the count
+// documented in manifests and docs. Prevents skill-count drift after add/remove.
+const skillsDir = join(ROOT, 'skills');
+const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
+  .filter(entry => entry.isDirectory());
+const ACTUAL_SKILL_COUNT = skillDirs.length;
+
+// JSON manifests: extract the "N skills" number from the description field.
+const SKILL_COUNT_JSON_CHECKS = [
+  { file: 'plugin.json', path: ['description'], extract: /(\d+) skills/ },
+  { file: '.claude-plugin/plugin.json', path: ['description'], extract: /(\d+) skills/ },
+];
+
+for (const check of SKILL_COUNT_JSON_CHECKS) {
+  const fp = join(ROOT, check.file);
+  if (!existsSync(fp)) {
+    errors.push({ file: check.file, found: 'FILE_NOT_FOUND', expected: ACTUAL_SKILL_COUNT });
+    continue;
+  }
+  try {
+    const obj = JSON.parse(readFileSync(fp, 'utf-8'));
+    let val = obj;
+    for (const p of check.path) val = val?.[p];
+    const match = typeof val === 'string' ? val.match(check.extract) : null;
+    if (!match) {
+      errors.push({ file: `${check.file} [${check.path.join('.')}]`, found: 'PATTERN_NOT_MATCHED', expected: ACTUAL_SKILL_COUNT });
+    } else if (Number(match[1]) !== ACTUAL_SKILL_COUNT) {
+      if (AUTO_FIX) {
+        // Auto-fix: update skill count in JSON
+        const newVal = val.replace(check.extract, `${ACTUAL_SKILL_COUNT} skills`);
+        obj[check.path[0]] = newVal;
+        writeFileSync(fp, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+        fixes.push(`${check.file}: ${match[1]} → ${ACTUAL_SKILL_COUNT}`);
+      } else {
+        errors.push({ file: `${check.file} [${check.path.join('.')}]`, found: match[1], expected: ACTUAL_SKILL_COUNT });
+      }
+    }
+  } catch (e) {
+    errors.push({ file: check.file, found: `PARSE_ERROR: ${e.message}`, expected: ACTUAL_SKILL_COUNT });
+  }
+}
+
+// Text files: extract the documented skill count.
+const SKILL_COUNT_TEXT_CHECKS = [
+  { file: 'README.md', extract: /(\d+) skills/, replace: (content, count) => content.replace(/(\d+) skills/, `${count} skills`) },
+  { file: 'AGENTS.md', extract: /Skills 索引（(\d+) 个）/, replace: (content, count) => content.replace(/Skills 索引（(\d+) 个）/, `Skills 索引（${count} 个）`) },
+];
+
+for (const check of SKILL_COUNT_TEXT_CHECKS) {
+  const fp = join(ROOT, check.file);
+  if (!existsSync(fp)) {
+    errors.push({ file: check.file, found: 'FILE_NOT_FOUND', expected: ACTUAL_SKILL_COUNT });
+    continue;
+  }
+  const content = readFileSync(fp, 'utf-8');
+  const match = content.match(check.extract);
+  if (!match) {
+    errors.push({ file: check.file, found: 'PATTERN_NOT_MATCHED', expected: ACTUAL_SKILL_COUNT });
+  } else if (Number(match[1]) !== ACTUAL_SKILL_COUNT) {
+    if (AUTO_FIX) {
+      // Auto-fix: update skill count in text
+      const newContent = check.replace(content, ACTUAL_SKILL_COUNT);
+      writeFileSync(fp, newContent, 'utf-8');
+      fixes.push(`${check.file}: ${match[1]} → ${ACTUAL_SKILL_COUNT}`);
+    } else {
+      errors.push({ file: check.file, found: match[1], expected: ACTUAL_SKILL_COUNT });
+    }
+  }
+}
+
+// ── npx version reference consistency ──
+// Scan every skills/*/SKILL.md for `team-flow@X.Y.Z` references and ensure
+// each one matches the canonical version. Catches stale npx pins in any skill —
+// broader than RUNTIME_FILES above, which only covers the known runtime set.
+const SKILL_MD_FILES = skillDirs
+  .map(entry => `skills/${entry.name}/SKILL.md`)
+  .filter(file => existsSync(join(ROOT, file)));
+
+// Also scan references/ subdirectories for stale npx refs
+const REFERENCES_FILES = [];
+function scanDir(dir, prefix = '') {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      scanDir(fullPath, relPath);
+    } else if (entry.name.endsWith('.md')) {
+      REFERENCES_FILES.push(relPath);
+    }
+  }
+}
+const refsDir = join(ROOT, 'skills');
+for (const skillEntry of skillDirs) {
+  const refsPath = join(refsDir, skillEntry.name, 'references');
+  if (existsSync(refsPath)) {
+    scanDir(refsPath, `skills/${skillEntry.name}/references`);
+  }
+}
+
+const ALL_SCANNABLE_FILES = [...SKILL_MD_FILES, ...REFERENCES_FILES];
+
+for (const file of ALL_SCANNABLE_FILES) {
+  const fp = join(ROOT, file);
+  if (!existsSync(fp)) continue;
+
+  const content = readFileSync(fp, 'utf-8');
+  const versions = [...content.matchAll(/team-flow@(\d+\.\d+\.\d+)/g)]
+    .map(match => match[1]);
+  const stale = [...new Set(versions)].filter(version => version !== CANONICAL);
+
+  if (stale.length > 0) {
+    if (AUTO_FIX) {
+      // Auto-fix: update all stale npx references
+      let newContent = content;
+      for (const oldVer of stale) {
+        newContent = newContent.replaceAll(`team-flow@${oldVer}`, `team-flow@${CANONICAL}`);
+      }
+      writeFileSync(fp, newContent, 'utf-8');
+      fixes.push(`${file}: ${stale.join(', ')} → ${CANONICAL}`);
+    } else {
+      errors.push({ file, found: stale.join(', '), expected: CANONICAL });
+    }
+  }
+}
+
+// ── Detect new skills not in any manifest ──
+const MANIFEST_SKILLS = new Set();
+// Extract from plugin.json description
+const pluginDesc = pkg.description || '';
+const skillListMatch = pluginDesc.match(/(\d+) skills/);
+// We'll check AGENTS.md for skill list (table format: | skill-name | ... |)
+const agentsMd = readFileSync(join(ROOT, 'AGENTS.md'), 'utf-8');
+const skillIndexMatch = agentsMd.match(/## Skills 索引[\s\S]*?(?=##|$)/);
+if (skillIndexMatch) {
+  // Match table rows: | skill-name | ... |
+  const skillNames = [...skillIndexMatch[0].matchAll(/^\|\s*([a-z][a-z0-9-]*)\s*\|/gm)]
+    .map(m => m[1])
+    .filter(name => name !== 'Skill'); // Skip header row
+  skillNames.forEach(name => MANIFEST_SKILLS.add(name));
+}
+
+const newSkills = skillDirs
+  .map(entry => entry.name)
+  .filter(name => !MANIFEST_SKILLS.has(name));
+
+if (newSkills.length > 0) {
+  console.warn(`⚠️  New skills detected not in AGENTS.md index: ${newSkills.join(', ')}`);
+  console.warn(`   Consider adding them to AGENTS.md Skills 索引`);
+}
+
+// ── Post-fix verification (only in --fix mode) ──
+// If we made any fixes, re-verify that all fixed files are now consistent.
+// This catches cases where auto-fix introduced new issues (e.g., wrong count).
+if (AUTO_FIX && fixes.length > 0) {
+  console.log('🔍 Verifying fixes...');
+
+  // Re-check skill counts
+  for (const check of SKILL_COUNT_JSON_CHECKS) {
+    const fp = join(ROOT, check.file);
+    if (!existsSync(fp)) continue;
+    try {
+      const obj = JSON.parse(readFileSync(fp, 'utf-8'));
+      let val = obj;
+      for (const p of check.path) val = val?.[p];
+      const match = typeof val === 'string' ? val.match(check.extract) : null;
+      if (match && Number(match[1]) !== ACTUAL_SKILL_COUNT) {
+        errors.push({
+          file: `${check.file} [${check.path.join('.')}]`,
+          found: match[1],
+          expected: ACTUAL_SKILL_COUNT,
+          note: 'Post-fix verification failed'
+        });
+      }
+    } catch (e) { /* ignore parse errors in verification */ }
+  }
+
+  for (const check of SKILL_COUNT_TEXT_CHECKS) {
+    const fp = join(ROOT, check.file);
+    if (!existsSync(fp)) continue;
+    const content = readFileSync(fp, 'utf-8');
+    const match = content.match(check.extract);
+    if (match && Number(match[1]) !== ACTUAL_SKILL_COUNT) {
+      errors.push({
+        file: check.file,
+        found: match[1],
+        expected: ACTUAL_SKILL_COUNT,
+        note: 'Post-fix verification failed'
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error('❌ Post-fix verification found remaining issues:');
+    for (const e of errors) {
+      console.error(`  ${e.file}: expected ${e.expected}, found ${e.found}`);
+    }
+    console.error('\nAuto-fix may have introduced errors. Please fix manually.');
+    process.exit(1);
+  }
+
+  console.log('✅ All fixes verified\n');
+}
+
+// ── Report ──
+if (fixes.length > 0) {
+  console.log(`🔧 Auto-fixed ${fixes.length} issue(s):`);
+  for (const fix of fixes) {
+    console.log(`   ${fix}`);
+  }
+  console.log('');
+}
+
+if (errors.length === 0) {
+  const msg = fixes.length > 0
+    ? `✅ Version consistency check passed after auto-fix — all files at ${CANONICAL}`
+    : `✅ Version consistency check passed — all files at ${CANONICAL}`;
+  console.log(msg);
+  process.exit(0);
+}
+
+console.log(`❌ Version consistency check FAILED — canonical version is ${CANONICAL}\n`);
+console.log('Mismatches found:');
+for (const e of errors) {
+  console.log(`  ${e.file}`);
+  console.log(`    expected: ${e.expected}`);
+  console.log(`    found:    ${e.found}`);
+}
+console.log(`\nRun: npm run check-versions -- --fix`);
+console.log(`Then manually verify and commit.`);
+process.exit(1);

package/scripts/ensure-branch.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// scripts/ensure-branch.mjs — enforce git isolation before editing main/master
+// Used by build-executor as a mandatory preflight. Exits non-zero when it
+// cannot create an isolated context and no --force approval was given, so the
+// agent MUST stop and ask the user instead of silently editing main/master.
+//
+// Usage: node ensure-branch.mjs <change-dir> [change-name] [--force]
+//
+// Security: every git invocation uses execFileSync with a LITERAL command
+// ('git') and a LITERAL argument array (no shell, no variable args array) —
+// the same form proven safe by install-cursor.mjs / install.mjs. There is no
+// string-form shell command, no variable command, and no dynamic args array.
+import { execFileSync } from 'node:child_process';
+
+const changeDir = process.argv[2];
+const changeName = process.argv[3];
+const force = process.argv.includes('--force');
+
+if (!changeDir) {
+  console.error('Usage: node ensure-branch.mjs <change-dir> [change-name] [--force]');
+  process.exit(2);
+}
+
+const PROTECTED = ['main', 'master'];
+const GIT_OPTS = { encoding: 'utf-8', cwd: changeDir, stdio: ['ignore', 'pipe', 'pipe'] };
+
+// Determine current branch (literal arg array).
+let branch = '';
+try {
+  branch = (execFileSync('git', ['branch', '--show-current'], GIT_OPTS) || '').trim();
+} catch {
+  console.error('ensure-branch: could not determine current git branch. Is <change-dir> inside a git repository?');
+  process.exit(1);
+}
+
+if (!PROTECTED.includes(branch)) {
+  console.log(`ensure-branch: already isolated on branch '${branch}'. Proceed with implementation edits.`);
+  process.exit(0);
+}
+
+console.error(`ensure-branch: on protected branch '${branch}'. Creating an isolated implementation context...`);
+
+const repoName = changeDir.split('/').filter(Boolean).pop() || 'repo';
+const name = changeName || repoName;
+const worktreePath = `../${repoName}-${name}`;
+
+// Preferred: git worktree (literal arg array).
+try {
+  execFileSync('git', ['worktree', 'add', worktreePath, '-b', name], { ...GIT_OPTS, stdio: 'inherit' });
+  console.log(`ensure-branch: created git worktree at ${worktreePath} on branch '${name}'. Make all implementation edits there.`);
+  process.exit(0);
+} catch (e) {
+  console.error(`ensure-branch: worktree creation failed: ${(e.stderr || e.stdout || e.message || 'unknown').toString().trim()}`);
+}
+
+// Fallback: local branch (literal arg array).
+try {
+  execFileSync('git', ['switch', '-c', name], { ...GIT_OPTS, stdio: 'inherit' });
+  console.log(`ensure-branch: created branch '${name}' via git switch -c. Make implementation edits there.`);
+  process.exit(0);
+} catch (e) {
+  console.error(`ensure-branch: branch creation failed: ${(e.stderr || e.stdout || e.message || 'unknown').toString().trim()}`);
+}
+
+// Both failed → require explicit approval to edit in place.
+if (force) {
+  console.error('ensure-branch: WARNING — editing protected branch in place with --force. This modifies main/master directly.');
+  process.exit(0);
+}
+console.error('ensure-branch: could not create an isolated context and no --force given. STOP and ask the user for explicit approval before editing main/master.');
+process.exit(1);

package/scripts/get-config

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Read a config field from team-flow.config.json
+# Usage: get-config <field-path>
+# Example: get-config execution.inlineThreshold → outputs "3"
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+field_path="${1:-}"
+
+if [ -z "$field_path" ]; then
+  echo "Usage: get-config <field-path>" >&2
+  echo "Example: get-config execution.inlineThreshold" >&2
+  exit 2
+fi
+
+# Use node to load config and extract field
+node --input-type=module -e "
+import { loadConfig } from '${SCRIPT_DIR}/lib/config-loader.mjs';
+const config = loadConfig(process.cwd());
+const parts = '${field_path}'.split('.');
+let val = config;
+for (const p of parts) {
+  if (val === undefined || val === null) { val = undefined; break; }
+  val = val[p];
+}
+if (val !== undefined) {
+  process.stdout.write(typeof val === 'object' ? JSON.stringify(val) : String(val));
+} else {
+  process.exit(1);
+}
+" 2>/dev/null || exit 1

package/scripts/guard/checks/artifacts-exist.mjs

@@ -0,0 +1,36 @@
+// scripts/guard/checks/artifacts-exist.mjs — check that required planning artifacts are present and non-empty
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from '../../lib/config-loader.mjs';
+import { validateSpecPathLayout } from '../../lib/spec-paths.mjs';
+
+/**
+ * Check that required planning artifacts exist and are non-empty,
+ * and that the specs/ directory has at least one spec file.
+ * Honors artifacts.skip from team-flow.config.json.
+ */
+export function checkArtifactsExist(changeDir) {
+  const failures = [];
+  const config = loadConfig(changeDir);
+  const skipList = config.artifacts?.skip || [];
+
+  const required = ['proposal.md', 'design.md', 'tasks.md'].filter(
+    f => !skipList.includes(f.replace('.md', ''))
+  );
+
+  for (const file of required) {
+    const filePath = path.join(changeDir, file);
+    if (!fs.existsSync(filePath)) {
+      failures.push(`${file}: missing`);
+    } else if (fs.readFileSync(filePath, 'utf-8').trim().length === 0) {
+      failures.push(`${file}: empty`);
+    }
+  }
+
+  if (!skipList.includes('specs')) {
+    const specLayout = validateSpecPathLayout(changeDir, { requireSpecs: true });
+    failures.push(...specLayout.failures);
+  }
+
+  return { pass: failures.length === 0, failures };
+}

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

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { computeContractHash } from '../../lib/hash.mjs';
+
+export function checkContractCurrent(changeDir) {
+  const contractPath = path.join(changeDir, 'execution-contract.md');
+  if (!fs.existsSync(contractPath)) {
+    return { pass: false, failures: ['execution-contract.md: missing'] };
+  }
+
+  const content = fs.readFileSync(contractPath, 'utf-8').trim();
+  if (content.length === 0) {
+    return { pass: false, failures: ['execution-contract.md: empty'] };
+  }
+
+  const state = readState(changeDir);
+  const current = computeContractHash(changeDir);
+  if (!state.contract_hash || state.contract_hash === 'null') {
+    return {
+      pass: false,
+      failures: ['execution-contract.md is not recorded in state. Run tf state init <change-dir> after contract generation.'],
+    };
+  }
+  if (state.contract_hash !== current) {
+    return {
+      pass: false,
+      failures: ['execution-contract.md is stale: contract hash mismatch. Re-run contract-builder or tf state rebuild.'],
+    };
+  }
+
+  return { pass: true, failures: [] };
+}

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

@@ -0,0 +1,17 @@
+// scripts/guard/checks/contract-fresh.mjs — check contract staleness via hash comparison
+import { isContractFresh } from '../../lib/hash.mjs';
+
+/**
+ * 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) {
+    return { pass: true, failures: [] };
+  }
+  return {
+    pass: false,
+    failures: ['execution-contract.md is stale: artifacts hash mismatch. Re-run contract-builder to regenerate.'],
+  };
+}

package/scripts/guard/checks/dp-gate-passed.mjs

@@ -0,0 +1,35 @@
+// scripts/guard/checks/dp-gate-passed.mjs — check that required decision points are recorded before allowing a transition
+import { readState } from '../../lib/state-loader.mjs';
+
+/**
+ * Mapping of transitions that require specific DPs to be recorded.
+ * Each entry lists the DP fields that must have a non-null value.
+ */
+const REQUIRED_DPS = {
+  // DP-4: Execution mode must be selected before entering executing
+  'approved-for-build→executing': ['dp_4_result'],
+  // DP-3: Contract must be approved before executing (hard gate)
+  'bridging→approved-for-build': ['dp_3_result'],
+};
+
+export function check(changeDir, fromState, toState) {
+  const key = `${fromState}→${toState}`;
+  const required = REQUIRED_DPS[key];
+
+  if (!required) {
+    return { pass: true, failures: [] };
+  }
+
+  const state = readState(changeDir);
+  const failures = [];
+
+  for (const dpField of required) {
+    const value = state[dpField];
+    if (value === null || value === undefined || value === '') {
+      const dpNum = dpField.match(/dp_(\d+)_/)?.[1] || '?';
+      failures.push(`DP-${dpNum} (${dpField}) is not recorded — this decision point must be confirmed before ${fromState} → ${toState}`);
+    }
+  }
+
+  return { pass: failures.length === 0, failures };
+}

package/scripts/guard/checks/dp3-approved.mjs

@@ -0,0 +1,22 @@
+import { readState } from '../../lib/state-loader.mjs';
+
+export function checkDp3Approved(changeDir) {
+  const state = readState(changeDir);
+  const decision = typeof state.dp_3_result === 'string' ? state.dp_3_result.trim() : '';
+
+  if (!decision) {
+    return {
+      pass: false,
+      failures: ['DP-3 (dp_3_result) is not recorded — minimal contract approval is required before hotfix build'],
+    };
+  }
+
+  if (!/^approved\b/i.test(decision)) {
+    return {
+      pass: false,
+      failures: [`DP-3 (dp_3_result) must start with "approved"; got: ${decision}`],
+    };
+  }
+
+  return { pass: true, failures: [] };
+}

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

@@ -0,0 +1,40 @@
+import { readPlan, validatePlan } from '../../lib/execution-plan.mjs';
+import { readState } from '../../lib/state-loader.mjs';
+
+/**
+ * Verifies that DP-4 refers to the current, persisted execution plan.
+ *
+ * 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) {
+  const plan = readPlan(changeDir);
+  if (!plan) {
+    return {
+      pass: false,
+      failures: ['execution plan is missing. Record a current plan with "tf execution plan" before entering executing.'],
+    };
+  }
+
+  const validation = validatePlan(changeDir, plan);
+  if (!validation.valid) {
+    return { pass: false, failures: validation.failures };
+  }
+
+  const state = readState(changeDir);
+  const expectedRevision = `plan revision ${plan.revision}`;
+  const decision = typeof state.dp_4_result === 'string' ? state.dp_4_result : '';
+  const revisionReference = new RegExp(`\\bplan revision\\s+${escapeRegExp(String(plan.revision))}\\b`, 'i');
+  if (!revisionReference.test(decision)) {
+    return {
+      pass: false,
+      failures: [`DP-4 must precisely reference current ${expectedRevision}; recorded value is '${decision || 'null'}'. Re-record the execution plan.`],
+    };
+  }
+
+  return { pass: true, failures: [] };
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -0,0 +1,36 @@
+import { readCurrentReview, readPlan, validatePlan } from '../../lib/execution-plan.mjs';
+
+/**
+ * Verifies that every wave in the current execution plan has a passing review
+ * receipt. A failed or malformed receipt is a blocking result, never a signal
+ * that a later wave may proceed to closing.
+ */
+export function checkExecutionReviewsPassed(changeDir) {
+  const plan = readPlan(changeDir);
+  if (!plan) {
+    // This dimension only evaluates receipts. Full/hotfix transitions pair it
+    // with execution-plan-ready, which rejects a missing plan; tweak omits
+    // this dimension entirely. Keep the missing-plan result owned by that
+    // dedicated dimension rather than duplicating it here.
+    return { pass: true, failures: [] };
+  }
+
+  const validation = validatePlan(changeDir, plan);
+  if (!validation.valid) {
+    return { pass: false, failures: validation.failures };
+  }
+
+  const failures = [];
+  for (const wave of plan.waves) {
+    const receipt = readCurrentReview(changeDir, wave.id, plan);
+    if (!receipt) {
+      failures.push(`review receipt missing for planned wave '${wave.id}'. Record a passing review before closing.`);
+      continue;
+    }
+    if (receipt?.status !== 'pass') {
+      failures.push(`review receipt for planned wave '${wave.id}' has status '${receipt?.status ?? 'missing'}'; expected 'pass'.`);
+    }
+  }
+
+  return { pass: failures.length === 0, failures };
+}