@xulthekl/team-flow 0.22.4

package/scripts/guard/checks/schema-valid.mjs

@@ -0,0 +1,63 @@
+// scripts/guard/checks/schema-valid.mjs — validate artifacts using the existing Validator engine
+import fs from 'node:fs';
+import path from 'node:path';
+import { validateSpecPathLayout, relativeSpecPath } from '../../lib/spec-paths.mjs';
+
+// Cached Validator instance, lazily loaded from dist/
+let _Validator = null;
+
+async function getValidator() {
+  if (_Validator) return _Validator;
+  try {
+    const distPath = new URL('../../../dist/index.js', import.meta.url).pathname;
+    const mod = await import(distPath);
+    _Validator = mod.Validator;
+    return _Validator;
+  } catch (err) {
+    throw new Error(`Failed to load Validator engine. Run 'npm run build' first. Original error: ${err.message}`);
+  }
+}
+
+/**
+ * Validate all artifacts in a change directory using the Validator engine.
+ * Returns { pass, failures[] } — pass is true only if all artifacts are valid.
+ */
+export async function checkSchemaValid(changeDir) {
+  const failures = [];
+  const warnings = [];
+  const Validator = await getValidator();
+  const validator = new Validator();
+
+  // Validate proposal.md
+  const proposalPath = path.join(changeDir, 'proposal.md');
+  if (fs.existsSync(proposalPath)) {
+    const content = fs.readFileSync(proposalPath, 'utf-8');
+    const changeName = path.basename(changeDir);
+    const report = validator.validateChangeContent(changeName, content);
+    for (const issue of report.issues) {
+      if (issue.level === 'ERROR') {
+        failures.push(`proposal.md: ${issue.message}`);
+      } else if (issue.level === 'WARNING') {
+        warnings.push(`proposal.md: ${issue.message}`);
+      }
+    }
+  }
+
+  const specLayout = validateSpecPathLayout(changeDir, { requireSpecs: true });
+  failures.push(...specLayout.failures);
+
+  for (const specFile of specLayout.specFiles) {
+    const content = fs.readFileSync(specFile, 'utf-8');
+    const report = validator.validateDeltaSpec(content);
+    const rel = relativeSpecPath(changeDir, specFile);
+    for (const issue of report.issues) {
+      if (issue.level === 'ERROR') {
+        failures.push(`${rel}: ${issue.message}`);
+      } else if (issue.level === 'WARNING') {
+        warnings.push(`${rel}: ${issue.message}`);
+      }
+    }
+  }
+
+  return { pass: failures.length === 0, failures, warnings };
+}

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

@@ -0,0 +1,51 @@
+// scripts/guard/checks/specs-merged.mjs — block closing while delta specs are unmerged
+import { readState } from '../../lib/state-loader.mjs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+// A delta spec block is introduced by any of these requirement headers.
+const DELTA_RE = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements/m;
+
+function collectSpecFiles(specsDir) {
+  const out = [];
+  const entries = readdirSync(specsDir, { recursive: true, withFileTypes: true });
+  for (const e of entries) {
+    if (e.isFile() && /\.(md|markdown)$/i.test(e.name)) {
+      // With recursive readdir, e.parentPath gives the directory.
+      const dir = typeof e.parentPath === 'string' ? e.parentPath : specsDir;
+      out.push(join(dir, e.name));
+    }
+  }
+  return out;
+}
+
+function hasDeltaSpecs(changeDir) {
+  const specsDir = join(changeDir, 'specs');
+  if (!existsSync(specsDir)) return false;
+  for (const file of collectSpecFiles(specsDir)) {
+    const content = readFileSync(file, 'utf-8');
+    if (DELTA_RE.test(content)) return true;
+  }
+  return false;
+}
+
+/**
+ * Returns { pass, failures[] }.
+ * 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) {
+  const state = readState(changeDir);
+  if (state.spec_merged === true || state.spec_merged === 'true') {
+    return { pass: true, failures: [] };
+  }
+  if (!hasDeltaSpecs(changeDir)) {
+    return { pass: true, failures: [] };
+  }
+  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.',
+    ],
+  };
+}

package/scripts/guard/checks/tasks-complete.mjs

@@ -0,0 +1,31 @@
+// scripts/guard/checks/tasks-complete.mjs — verify all tasks in tasks.md are checked off
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Check that tasks.md has no unchecked items and at least one completed item.
+ * Returns { pass, failures[] }.
+ */
+export function checkTasksComplete(changeDir) {
+  const tasksPath = path.join(changeDir, 'tasks.md');
+  if (!fs.existsSync(tasksPath)) {
+    return { pass: false, failures: ['tasks.md: missing'] };
+  }
+
+  const content = fs.readFileSync(tasksPath, 'utf-8');
+  const unchecked = content.match(/^[ \t]*- \[ \]/gm);
+
+  if (unchecked && unchecked.length > 0) {
+    return {
+      pass: false,
+      failures: [`tasks.md: ${unchecked.length} unchecked task(s) remaining`],
+    };
+  }
+
+  const hasAny = content.match(/^[ \t]*- \[[xX]\]/gm);
+  if (!hasAny) {
+    return { pass: false, failures: ['tasks.md: no completed tasks found'] };
+  }
+
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/tests-passing.mjs

@@ -0,0 +1,31 @@
+// scripts/guard/checks/tests-passing.mjs — verify verification outcome is recorded as pass
+import { readState } from '../../lib/state-loader.mjs';
+
+/**
+ * Check that .team-flow.yaml records a passing verification outcome.
+ *
+ * Historically only `test_result: pass` was accepted, but release-archivist
+ * records the verification result in `dp_6_result` (e.g. "pass: ..."). The
+ * closing transition was unreachable because nothing ever wrote `test_result`,
+ * so we accept either signal. See BUG-A (issue #28 root cause).
+ *
+ * Returns { pass, failures[] }.
+ */
+export function checkTestsPassing(changeDir) {
+  const state = readState(changeDir);
+  const markers = [state.test_result, state.dp_6_result];
+  const passed = markers.some((v) => {
+    if (typeof v !== 'string') return false;
+    const normalized = v.trim().replace(/^["']|["']$/g, '');
+    return normalized.toLowerCase().startsWith('pass');
+  });
+  if (passed) {
+    return { pass: true, failures: [] };
+  }
+  return {
+    pass: false,
+    failures: [
+      `verification outcome missing: test_result is '${state.test_result || 'null'}' and dp_6_result is '${state.dp_6_result || 'null'}' — expected a result starting with 'pass'. Run release-archivist verification (DP-6) first.`,
+    ],
+  };
+}

package/scripts/guard/design-token-guard.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+// design-token-guard.mjs — 设计系统完整性检查（v0.18.0）
+//
+// Validates that a design-system.md is structurally complete and that a
+// design-tokens.css provides the token coverage the prototype skill relies on
+// (A1 identity tokens, A2 derived state tokens, B-slot alias tokens).
+//
+// Usage: node scripts/guard/design-token-guard.mjs <design-system.md path> [design-tokens.css path]
+//   Exit 0: PASS — all required checks satisfied
+//   Exit 1: FAIL — one or more issues found (listed in the report)
+
+import { readFileSync, existsSync } from 'node:fs';
+
+// ── Check definitions ──
+
+// The 9 required ## sections in design-system.md.
+const REQUIRED_SECTIONS = [
+  'color', 'typography', 'spacing', 'layout', 'components',
+  'motion', 'voice', 'brand', 'anti-patterns',
+];
+
+// Optional ## sections — reported for visibility, never counted as failures.
+const OPTIONAL_SECTIONS = ['palette', 'aliases', 'extensions'];
+
+// The 5 palette directions checked when a palette section exists.
+const PALETTE_DIRECTIONS = ['neutral', 'primary', 'success', 'warning', 'danger'];
+
+// A1 identity tokens — 8 required in design-tokens.css.
+const A1_IDENTITY_TOKENS = [
+  '--bg', '--surface', '--fg', '--muted', '--border',
+  '--accent', '--font-display', '--font-body',
+];
+
+// A2 derived state tokens — must be defined via a color-mix() formula.
+const A2_DERIVED_TOKENS = ['--accent-hover', '--accent-active', '--focus-ring', '--elev-raised'];
+
+// B-slot alias tokens — each should resolve (via var()) to its base token.
+const B_SLOT_ALIASES = [
+  { token: '--fg-2', base: '--fg' },
+  { token: '--meta', base: '--muted' },
+  { token: '--border-soft', base: '--border' },
+  { token: '--surface-warm', base: '--surface' },
+];
+
+// ── Helpers ──
+
+// Read a file as UTF-8, or return null when it does not exist.
+function readFileOrNull(filePath) {
+  if (!filePath || !existsSync(filePath)) return null;
+  return readFileSync(filePath, 'utf-8');
+}
+
+// Collect the lower-cased text of every level-2 ("## ") markdown header.
+function extractH2Headers(markdown) {
+  return markdown
+    .split('\n')
+    .filter(line => /^##\s+/.test(line) && !/^###/.test(line))
+    .map(line => line.replace(/^##\s+/, '').trim().toLowerCase());
+}
+
+// True when any ## header mentions the given section name.
+function hasSection(headers, section) {
+  return headers.some(header => header.includes(section));
+}
+
+// Return the body of a section (text between its ## header and the next ##
+// header or EOF), lower-cased; null when the section is absent.
+function sectionBody(markdown, section) {
+  const lines = markdown.split('\n');
+  const startIdx = lines.findIndex(
+    line => /^##\s+/.test(line) && !/^###/.test(line) &&
+      line.replace(/^##\s+/, '').trim().toLowerCase().includes(section),
+  );
+  if (startIdx === -1) return null;
+  const body = [];
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i]) && !/^###/.test(lines[i])) break;
+    body.push(lines[i]);
+  }
+  return body.join('\n').toLowerCase();
+}
+
+// Escape a token name for safe use inside a RegExp (names contain "--").
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Return the declared value of a CSS custom property, or null when absent.
+function getTokenValue(css, name) {
+  const match = css.match(new RegExp(`${escapeRegExp(name)}\\s*:\\s*([^;]+);`));
+  return match ? match[1].trim() : null;
+}
+
+// Extract the var(--x) reference from a token value, if present.
+function extractVarTarget(value) {
+  const match = value.match(/var\(\s*(--[a-z0-9-]+)/i);
+  return match ? match[1] : null;
+}
+
+// ── Report accumulation ──
+
+const issues = [];
+function line(text = '') { console.log(text); }
+function pass(text) { line(`  ✅ ${text}`); }
+function fail(text) { issues.push(text); line(`  ❌ ${text}`); }
+
+// ── Argument parsing ──
+
+const mdPath = process.argv[2];
+const cssPath = process.argv[3];
+
+if (!mdPath) {
+  console.error('Usage: node scripts/guard/design-token-guard.mjs <design-system.md path> [design-tokens.css path]');
+  process.exit(1);
+}
+
+const markdown = readFileOrNull(mdPath);
+const css = cssPath ? readFileOrNull(cssPath) : null;
+
+line('Design Token Guard v0.18.0');
+line('==========================');
+line(`design-system.md: ${mdPath}`);
+line(`design-tokens.css: ${cssPath || 'not provided'}`);
+line();
+
+// ── File availability ──
+
+if (markdown === null) {
+  fail(`design-system.md not found: ${mdPath}`);
+}
+if (cssPath && css === null) {
+  fail(`design-tokens.css not found: ${cssPath}`);
+}
+
+// ── 9-Section Check ──
+
+line('## 9-Section Check');
+if (markdown === null) {
+  for (const section of REQUIRED_SECTIONS) fail(`${section} — MISSING (file not found)`);
+} else {
+  const headers = extractH2Headers(markdown);
+  for (const section of REQUIRED_SECTIONS) {
+    if (hasSection(headers, section)) pass(section);
+    else fail(`${section} — MISSING`);
+  }
+  // Optional sections: report presence only, never fail.
+  for (const section of OPTIONAL_SECTIONS) {
+    if (hasSection(headers, section)) line(`  ℹ️  ${section} (optional, present)`);
+  }
+}
+line();
+
+// ── Palette Check (5 directions) ──
+
+line('## Palette Check (5 directions)');
+if (markdown === null) {
+  line('  ⏭️  skipped — design-system.md not found');
+} else {
+  const palette = sectionBody(markdown, 'palette');
+  if (palette === null) {
+    line('  ⏭️  skipped — no palette section (optional)');
+  } else {
+    for (const direction of PALETTE_DIRECTIONS) {
+      if (palette.includes(direction)) pass(direction);
+      else fail(`${direction} — MISSING`);
+    }
+  }
+}
+line();
+
+// ── A1 Identity Tokens ──
+
+line('## A1 Identity Tokens (8 required)');
+if (css === null) {
+  line(`  ⏭️  skipped — design-tokens.css ${cssPath ? 'not found' : 'not provided'}`);
+} else {
+  for (const token of A1_IDENTITY_TOKENS) {
+    if (getTokenValue(css, token) !== null) pass(token);
+    else fail(`${token} — MISSING`);
+  }
+}
+line();
+
+// ── A2 Derived Tokens ──
+
+line('## A2 Derived Tokens');
+if (css === null) {
+  line(`  ⏭️  skipped — design-tokens.css ${cssPath ? 'not found' : 'not provided'}`);
+} else {
+  for (const token of A2_DERIVED_TOKENS) {
+    const value = getTokenValue(css, token);
+    if (value === null) {
+      fail(`${token} — MISSING`);
+    } else if (/color-mix\(/i.test(value)) {
+      pass(`${token} (color-mix found)`);
+    } else {
+      fail(`${token} — no color-mix formula`);
+    }
+  }
+}
+line();
+
+// ── B-Slot Aliases ──
+
+line('## B-Slot Aliases');
+if (css === null) {
+  line(`  ⏭️  skipped — design-tokens.css ${cssPath ? 'not found' : 'not provided'}`);
+} else {
+  for (const { token, base } of B_SLOT_ALIASES) {
+    const value = getTokenValue(css, token);
+    if (value === null) {
+      fail(`${token} — MISSING`);
+      continue;
+    }
+    const target = extractVarTarget(value);
+    if (target === base) {
+      pass(`${token} → var(${target})`);
+    } else if (target) {
+      // Alias exists but points somewhere other than the expected base token.
+      fail(`${token} → var(${target}) (expected var(${base}))`);
+    } else {
+      // Defined as a literal value rather than an alias to the base token.
+      pass(`${token} = ${value}`);
+    }
+  }
+}
+line();
+
+// ── Verdict ──
+
+if (issues.length === 0) {
+  line('Verdict: PASS');
+  process.exit(0);
+}
+
+line(`Verdict: FAIL (${issues.length} issue${issues.length === 1 ? '' : 's'})`);
+process.exit(1);

package/scripts/guard/guard.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// scripts/guard/guard.mjs — dimension-based phase transition guard
+// Usage: node guard.mjs check <change-dir> <from-state> <to-state> [--json]
+import { parseArgs } from 'node:util';
+import { checkArtifactsExist } from './checks/artifacts-exist.mjs';
+import { checkTasksComplete } from './checks/tasks-complete.mjs';
+import { checkTestsPassing } from './checks/tests-passing.mjs';
+import { checkContractFresh } from './checks/contract-fresh.mjs';
+import { check as checkDpGate } from './checks/dp-gate-passed.mjs';
+import { checkSpecsMerged } from './checks/specs-merged.mjs';
+import { checkContractCurrent } from './checks/contract-current.mjs';
+import { checkDp3Approved } from './checks/dp3-approved.mjs';
+import { checkExecutionPlanReady } from './checks/execution-plan-ready.mjs';
+import { checkExecutionReviewsPassed } from './checks/execution-reviews-passed.mjs';
+
+// Transition matrix: <from>:<to> → required check dimensions
+const TRANSITION_CHECKS = {
+  // Forward transitions
+  'exploring:specifying':           ['artifacts-exist'],
+  'specifying:bridging':            ['artifacts-exist', 'schema-valid'],
+  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed'],
+  'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready'],
+  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed'],
+
+  // Debugging side-path
+  'executing:debugging':            [],
+  'debugging:executing':            ['contract-fresh', 'execution-plan-ready'],
+
+  // Fast-path transitions are workflow-gated; full workflow must reject them explicitly.
+  'exploring:bridging':             [],
+  'exploring:approved-for-build':   [],
+
+  // Rewind transitions (scope change, contract drift, verification failure)
+  'specifying:exploring':           [],
+  'bridging:specifying':            [],
+  'approved-for-build:specifying':  [],
+  'approved-for-build:bridging':    [],
+  'executing:specifying':           [],
+  'executing:bridging':             [],
+  'closing:specifying':             [],
+
+  // Abandon transitions (terminal)
+  'exploring:abandoned':            [],
+  'specifying:abandoned':           [],
+  'bridging:abandoned':             [],
+  'approved-for-build:abandoned':   [],
+  'executing:abandoned':            [],
+  'debugging:abandoned':            [],
+};
+
+const WORKFLOW_TRANSITION_CHECKS = {
+  hotfix: {
+    'exploring:bridging': [],
+    'bridging:approved-for-build': ['contract-current', 'dp3-approved'],
+    'approved-for-build:executing': ['contract-current', 'dp3-approved', 'execution-plan-ready'],
+  },
+  tweak: {
+    'exploring:approved-for-build': [],
+    // Tweak remains a low-risk fast path: it is intentionally exempt from
+    // execution-plan and per-wave review receipt requirements.
+    'approved-for-build:executing': ['artifacts-exist', 'contract-fresh', 'dp-gate-passed'],
+    'executing:closing': ['tasks-complete', 'tests-passing', 'specs-merged'],
+    'debugging:executing': ['contract-fresh'],
+  },
+};
+
+const TRANSITION_WORKFLOW_REQUIREMENTS = {
+  'exploring:bridging': ['hotfix'],
+  'exploring:approved-for-build': ['tweak'],
+};
+
+function checkWorkflowAllowed(key, workflow) {
+  const allowed = TRANSITION_WORKFLOW_REQUIREMENTS[key];
+  if (!allowed || allowed.includes(workflow)) return { pass: true, checks: [] };
+  return {
+    pass: false,
+    checks: [{
+      dimension: 'workflow-mode',
+      pass: false,
+      failures: [`${key.replace(':', ' -> ')} is a fast-path transition allowed only for workflow ${allowed.join(' or ')}; current workflow is ${workflow}`],
+    }],
+  };
+}
+
+function resolveDimensions(key, workflow) {
+  return WORKFLOW_TRANSITION_CHECKS[workflow]?.[key] ?? TRANSITION_CHECKS[key];
+}
+
+async function main() {
+  const { positionals, values } = parseArgs({
+    options: {
+      json: { type: 'boolean', default: false },
+      workflow: { type: 'string', default: 'full' },
+    },
+    allowPositionals: true,
+  });
+
+  const subcommand = positionals[0];
+  if (subcommand !== 'check') {
+    console.error('Usage: guard.mjs check <change-dir> <from-state> <to-state> [--json] [--workflow <mode>]');
+    process.exit(2);
+  }
+
+  const changeDir = positionals[1];
+  const fromState = positionals[2];
+  const toState = positionals[3];
+  const useJson = values.json;
+  const workflow = values.workflow;
+
+  const VALID_WORKFLOWS = ['full', 'hotfix', 'tweak'];
+  if (!VALID_WORKFLOWS.includes(workflow)) {
+    console.error(`Invalid workflow: ${workflow}. Must be one of: ${VALID_WORKFLOWS.join(', ')}`);
+    process.exit(2);
+  }
+
+  if (!changeDir || !fromState || !toState) {
+    console.error('Usage: guard.mjs check <change-dir> <from-state> <to-state> [--json]');
+    process.exit(2);
+  }
+
+  const key = `${fromState}:${toState}`;
+  const dimensions = resolveDimensions(key, workflow);
+
+  if (!dimensions) {
+    const valid = Object.keys(TRANSITION_CHECKS).join(', ');
+    const msg = `Unknown transition: ${fromState} -> ${toState}. Valid transitions: ${valid}`;
+    if (useJson) console.log(JSON.stringify({ pass: false, checks: [], error: msg }));
+    else console.error(msg);
+    process.exit(1);
+  }
+
+  const workflowCheck = checkWorkflowAllowed(key, workflow);
+  if (!workflowCheck.pass) {
+    if (useJson) {
+      console.log(JSON.stringify({ pass: false, checks: workflowCheck.checks }, null, 2));
+    } else {
+      console.error('Guard checks failed:');
+      for (const c of workflowCheck.checks) {
+        for (const f of c.failures) {
+          console.error(`  [FAIL] ${c.dimension}: ${f}`);
+        }
+      }
+    }
+    process.exit(1);
+  }
+
+  if (dimensions.length === 0) {
+    const result = { pass: true, checks: [] };
+    if (useJson) console.log(JSON.stringify(result));
+    else console.log('All checks passed (no checks required for this transition).');
+    process.exit(0);
+  }
+
+  const CHECK_RUNNERS = {
+    'artifacts-exist': (dir) => checkArtifactsExist(dir),
+    'schema-valid': async (dir) => (await import('./checks/schema-valid.mjs')).checkSchemaValid(dir),
+    'contract-fresh': (dir) => checkContractFresh(dir),
+    'contract-current': (dir) => checkContractCurrent(dir),
+    'tasks-complete': (dir) => checkTasksComplete(dir),
+    'tests-passing': (dir) => checkTestsPassing(dir),
+    'specs-merged': (dir) => checkSpecsMerged(dir),
+    'dp-gate-passed': (dir) => checkDpGate(dir, fromState, toState),
+    'dp3-approved': (dir) => checkDp3Approved(dir),
+    'execution-plan-ready': (dir) => checkExecutionPlanReady(dir),
+    'execution-reviews-passed': (dir) => checkExecutionReviewsPassed(dir),
+  };
+
+  const checks = [];
+  let pass = true;
+
+  for (const dim of dimensions) {
+    const runner = CHECK_RUNNERS[dim];
+    const result = runner
+      ? await runner(changeDir)
+      : { pass: false, failures: [`Unknown dimension: ${dim}`] };
+    checks.push({ dimension: dim, pass: result.pass, failures: result.failures || [] });
+    if (!result.pass) pass = false;
+  }
+
+  pass = checks.every(c => c.pass);
+
+  if (useJson) {
+    console.log(JSON.stringify({ pass, checks }, null, 2));
+  } else {
+    if (pass) {
+      console.log('All checks passed.');
+    } else {
+      console.error('Guard checks failed:');
+      for (const c of checks) {
+        if (!c.pass) {
+          for (const f of c.failures) {
+            console.error(`  [FAIL] ${c.dimension}: ${f}`);
+          }
+        }
+      }
+    }
+  }
+
+  process.exit(pass ? 0 : 1);
+}
+
+main().catch(err => {
+  console.error('Guard error:', err.message);
+  process.exit(1);
+});