@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/threejs/.claude/hooks/gate-runner.mjs

@@ -0,0 +1,557 @@
+#!/usr/bin/env node
+/**
+ * Growth-ring gate runner — runs objective DoD verifiers for a growth ring.
+ *
+ * Usage:
+ *   npm run ring:gate -- --iteration 1
+ *   node .claude/hooks/gate-runner.mjs --iteration 1 [--project <dir>]
+ *
+ * Exit 0 = all DoD checks pass (canAskUser=yes)
+ * Exit 2 = one or more checks failed
+ */
+import fs from 'node:fs';
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import {
+  DOD_LABELS,
+  REVIEW_VERIFIERS,
+  ROUTE_PRIORITY,
+  SCRIPT_VERIFIERS,
+  allDoDPassed,
+  isPassed,
+  normalizeIteration,
+  routeForFailedDoDKeys,
+  ringDoDKeysForIteration,
+} from '../../skills/_shared/scripts/ring-config.mjs';
+import { checkEnv } from '../../skills/_shared/scripts/verify-env.mjs';
+import {
+  evaluateSliceQueueForRingGate,
+  readState,
+  setRingArtifacts,
+  setRingDoD,
+  setRingGateRunner,
+  stateExists,
+} from '../../skills/_shared/scripts/state-store.mjs';
+import {
+  evaluateBuildEvidenceForRingGate,
+  shouldAggregateGateEvidence,
+} from '../../skills/_shared/scripts/build-evidence-gate.mjs';
+import {
+  collectRingArtifactPaths,
+  writeRingArtifactSync,
+} from '../../skills/_shared/scripts/lib/validator-artifacts.mjs';
+
+/**
+ * Extra args to pass to npm scripts for programmatic artifact output.
+ * Keys with --json <path>: run_all.py writes directly to file.
+ * Keys with --json only: script outputs JSON to stdout; gate-runner captures it.
+ * Keys with --out/--name: record:mp4 writes mp4 to validate/ringN/.
+ * @param {number} iteration
+ */
+function artifactWriteArgs(key, iteration) {
+  switch (key) {
+    case 'oneClickEndcard':
+      return [`--out=validate/ring${iteration}`, `--name=one-click`];
+    case 'fullPlaythrough':
+      return [`--out=validate/ring${iteration}`, `--name=full-playthrough`];
+    case 'verifyUi':
+      return [`--json`, `validate/ring${iteration}/ui.json`];
+    case 'assetBudget':
+      return [`--json`, `validate/ring${iteration}/ui-assets.json`];
+    case 'bgClean':
+    case 'tileConsistency':
+    case 'textOverlap':
+      return ['--json'];
+    case 'vlmVideo':
+      return [`--ring=${iteration}`];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Which DoD key maps to which artifact JSON name under validate/ringN/.
+ * Keys backed by mp4 or already self-writing scripts map to null.
+ */
+const KEY_ARTIFACT_NAME = {
+  contract: 'contract',
+  lifecycle: 'lifecycle',
+  firstLevelWin: 'firstwin',
+  placeholders: 'placeholders',
+  fusion: 'fusion',
+  visualDiff: 'visual-diff',
+  vlmVideo: 'vlm-video',
+  bgClean: 'bg-clean',
+  tileConsistency: 'tile-consistency',
+  textOverlap: 'text-overlap',
+  assetReview: 'asset-review',
+  assetCodeSync: 'asset-code-sync',
+  atomConformance: 'atom-conformance',
+};
+
+/** DoD keys that spawn a full browser recording — need extended timeout (360 s). */
+const RECORDING_KEYS = new Set([
+  'ring1Visual',
+  'ring2Visual',
+  'ring3Visual',
+  'vlmVideo',
+  'oneClickEndcard',
+  'fullPlaythrough',
+]);
+
+/** DoD keys backed by Python visual scripts — all need python3 + Pillow. */
+const PYTHON_VISUAL_KEYS = new Set([
+  'verifyUi',
+  'assetBudget',
+  'visualDiff',
+  'bgClean',
+  'tileConsistency',
+  'textOverlap',
+  'assetReview',
+  'ring1Visual',
+]);
+
+function normalizeProjectDir(projectDir) {
+  if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(projectDir)) {
+    return projectDir[1].toUpperCase() + ':' + projectDir.slice(2).replace(/\//g, '\\');
+  }
+  return path.resolve(projectDir);
+}
+
+function parseArgs(argv) {
+  const args = { iteration: null, project: null };
+  for (let i = 2; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--iteration' || token === '--ring') {
+      let value = argv[i + 1] || null;
+      // Tolerate duplicated flag from npm script + CLI: `--iteration --iteration 1`
+      while (value === '--iteration' || value === '--ring') {
+        i += 1;
+        value = argv[i + 1] || null;
+      }
+      args.iteration = value;
+      i += 1;
+      continue;
+    }
+    // Legacy --gate alias maps iteration 1 only for transitional tooling
+    if (token === '--gate') {
+      args.iteration = argv[i + 1] || null;
+      i += 1;
+      continue;
+    }
+    if (token === '--project') {
+      args.project = argv[i + 1] || null;
+      i += 1;
+    }
+  }
+  return args;
+}
+
+function readFileSafe(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function getSection(content, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`(^## ${escaped}[\\s\\S]*?)(?=^## |\\Z)`, 'm');
+  const match = content.match(re);
+  return match ? match[1] : null;
+}
+
+function parseKeyValueTable(section) {
+  const map = new Map();
+  if (!section) return map;
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    const parts = trimmed
+      .split('|')
+      .map((part) => part.trim())
+      .filter((_, index, arr) => index > 0 && index < arr.length - 1);
+    if (parts.length < 2) continue;
+    const key = parts[0];
+    if (/^(field|owner|verifier)$/i.test(key)) continue;
+    const value = parts.length >= 3 ? parts[parts.length - 1] : parts[1];
+    map.set(key, value);
+  }
+  return map;
+}
+
+function parseReviewRingDoD(reviewContent, iteration) {
+  if (!reviewContent) return {};
+  const section = getSection(reviewContent, 'Ring DoD Fields');
+  if (!section) return {};
+  const table = parseKeyValueTable(section);
+  const iterationField = String(table.get('iteration') || '').trim();
+  if (iterationField && Number(iterationField) !== iteration) return {};
+
+  const result = {};
+  for (const [key, cfg] of Object.entries(REVIEW_VERIFIERS)) {
+    const verdict = String(table.get(cfg.field) || table.get(key) || '').trim().toLowerCase();
+    if (verdict === 'pass' || verdict === 'passed') result[key] = 'passed';
+    else if (verdict === 'fail' || verdict === 'failed') result[key] = 'failed';
+    else if (verdict) result[key] = verdict;
+  }
+  return result;
+}
+
+function runNpmScript(projectDir, scriptName, extraArgs = [], timeoutMs = 180_000) {
+  const isWin = process.platform === 'win32';
+  const cmd = isWin ? 'npm.cmd' : 'npm';
+  const args = ['run', scriptName, '--', ...extraArgs];
+  const result = spawnSync(cmd, args, {
+    cwd: projectDir,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: isWin,
+  });
+  const stdoutFull = result.stdout || '';
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: stdoutFull.slice(-2000),
+    stdoutFull,
+    stderr: (result.stderr || '').slice(-2000),
+    error: result.error?.message || null,
+  };
+}
+
+function baseExtraArgsForKey(key) {
+  if (key === 'fullPlaythrough') return ['--tail-delay=3000'];
+  if (key === 'visualDiff') return ['--strict'];
+  if (key === 'textOverlap') return ['--strict'];
+  return [];
+}
+
+function runScriptVerifier(projectDir, key) {
+  const scriptName = SCRIPT_VERIFIERS[key];
+  if (!scriptName) return { ok: false, reason: `no script verifier for ${key}` };
+
+  const result = runNpmScript(
+    projectDir,
+    scriptName,
+    baseExtraArgsForKey(key),
+    RECORDING_KEYS.has(key) ? 360_000 : 180_000,
+  );
+  if (!result.ok) {
+    const detail = result.stderr || result.stdout || result.error || `exit ${result.status}`;
+    return { ok: false, reason: `${DOD_LABELS[key]} failed: ${detail.split('\n').slice(-3).join(' ')}` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Like runScriptVerifier but also writes artifact JSON to validate/ringN/.
+ * Used for the ACTIVE ring's verifiers (not for non-regression re-runs).
+ */
+function runScriptVerifierForRing(projectDir, key, iteration) {
+  const scriptName = SCRIPT_VERIFIERS[key];
+  if (!scriptName) return { ok: false, reason: `no script verifier for ${key}` };
+
+  const extraArgs = [...baseExtraArgsForKey(key), ...artifactWriteArgs(key, iteration)];
+
+  // Ensure validate/ringN dir exists before passing --json path to Python scripts
+  if (key === 'verifyUi' || key === 'assetBudget') {
+    try {
+      mkdirSync(path.join(projectDir, `validate/ring${iteration}`), { recursive: true });
+    } catch {}
+  }
+
+  const result = runNpmScript(
+    projectDir,
+    scriptName,
+    extraArgs,
+    RECORDING_KEYS.has(key) ? 360_000 : 180_000,
+  );
+
+  // Write JSON artifact from stdout (keys that output JSON to stdout)
+  const artifactName = KEY_ARTIFACT_NAME[key];
+  if (artifactName) {
+    let artifactData;
+    try {
+      artifactData = JSON.parse(result.stdoutFull);
+    } catch {
+      artifactData = { ok: result.ok, exitCode: result.status, rawStdout: result.stdout };
+    }
+    try {
+      writeRingArtifactSync(projectDir, iteration, artifactName, artifactData);
+    } catch {}
+  }
+
+  if (!result.ok) {
+    const detail = result.stderr || result.stdout || result.error || `exit ${result.status}`;
+    return { ok: false, reason: `${DOD_LABELS[key]} failed: ${detail.split('\n').slice(-3).join(' ')}` };
+  }
+  return { ok: true };
+}
+
+function checkNonRegression(archivedRings, iteration, projectDir) {
+  if (iteration <= 1) return { ok: true, failures: [] };
+
+  const failures = [];
+  for (let ring = 1; ring < iteration; ring += 1) {
+    const snapshot = archivedRings[ring];
+    if (!snapshot) {
+      failures.push(`ring ${ring} not archived`);
+      continue;
+    }
+    const keys = ringDoDKeysForIteration(ring, projectDir);
+    if (!allDoDPassed(snapshot, keys)) {
+      failures.push(`ring ${ring} archived DoD incomplete`);
+      continue;
+    }
+    // Re-run script verifiers for prior rings (cheap regression guard)
+    for (const key of keys) {
+      if (!SCRIPT_VERIFIERS[key]) continue;
+      const result = runScriptVerifier(projectDir, key);
+      if (!result.ok) failures.push(`ring ${ring} regression: ${result.reason}`);
+    }
+  }
+  return { ok: failures.length === 0, failures };
+}
+
+function routeForVlmVideoArtifact(projectDir, iteration) {
+  const artifactPath = path.join(projectDir, `validate/ring${iteration}/vlm-video.json`);
+  if (!fs.existsSync(artifactPath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+    const findings = Array.isArray(data.findings) ? data.findings : [];
+    const failed = findings.filter((f) => f.status === 'fail' || f.severity === 'P0');
+    const skills = [...new Set(failed.map((f) => f.recommendedSkill).filter(Boolean))];
+    if (skills.length === 0) return null;
+    skills.sort((a, b) => ROUTE_PRIORITY.indexOf(a) - ROUTE_PRIORITY.indexOf(b));
+    const primary = skills[0];
+    return {
+      routeTo: primary,
+      nextAction: `VLM video review found ${failed.length} issue(s); route to @${primary} and inspect validate/ring${iteration}/vlm-video.json`,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function computeRingResult({ iteration, projectDir, state, reviewContent }) {
+  const activeKeys = ringDoDKeysForIteration(iteration, projectDir);
+  const archivedRings = state.archivedRings || {};
+  const ringDoD = { ...(state.ringDoD || {}), ...parseReviewRingDoD(reviewContent, iteration) };
+
+  const failures = [];
+  const blockingIssues = [];
+  const failedKeys = new Set();
+
+  // slice-axis-v1 (Knife 9): aggregate slice queue — never substitute verify:slice.
+  const sliceGate = evaluateSliceQueueForRingGate(state.sliceState);
+  if (sliceGate.applicable) {
+    ringDoD.sliceQueue = sliceGate.ok ? 'passed' : 'failed';
+    if (!sliceGate.ok) {
+      failures.push(...sliceGate.blockingIssues);
+      blockingIssues.push(...sliceGate.blockingIssues);
+      failedKeys.add('sliceQueue');
+    }
+  }
+
+  const aggregateBuild = shouldAggregateGateEvidence(state.sliceState);
+  const buildEvidence = aggregateBuild
+    ? evaluateBuildEvidenceForRingGate(projectDir, iteration, state.sliceState)
+    : { applicable: false, ok: true, blockingIssues: [] };
+  if (buildEvidence.applicable) {
+    ringDoD.buildEvidence = buildEvidence.ok ? 'passed' : 'failed';
+    if (!buildEvidence.ok) {
+      failures.push(...buildEvidence.blockingIssues);
+      blockingIssues.push(...buildEvidence.blockingIssues);
+      failedKeys.add('buildEvidence');
+    }
+  }
+
+  const SKIP_WHEN_AGGREGATING = new Set(['contract', 'lifecycle', 'vlmVideo']);
+
+  // Python-deps preflight: when any Python visual gate is active, a missing
+  // toolchain (python3 / Pillow / pyyaml / jsonschema) must surface as one clear
+  // block + route — not N opaque "Pillow required" failures or a silent skip.
+  const pythonGates = activeKeys.filter((key) => PYTHON_VISUAL_KEYS.has(key));
+  let pythonDepsOk = true;
+  if (pythonGates.length > 0) {
+    const env = checkEnv(projectDir, { playwright: false });
+    const missing = env.checks.filter((c) => c.required && c.status === 'fail');
+    if (missing.length > 0) {
+      pythonDepsOk = false;
+      const detail = missing.map((c) => c.message).join('; ');
+      const reason =
+        `Python deps missing for visual gates (${pythonGates.join(', ')}): ${detail}. ` +
+        'Run `npm run verify:env` then install per skills/playable-verify-ui/requirements.txt';
+      failures.push(reason);
+      blockingIssues.push(reason);
+      for (const key of pythonGates) {
+        ringDoD[key] = 'failed';
+        failedKeys.add(key);
+      }
+    }
+  }
+
+  // Non-regression
+  const regression = checkNonRegression(archivedRings, iteration, projectDir);
+  if (!regression.ok) {
+    failures.push(...regression.failures);
+    blockingIssues.push(...regression.failures);
+    failedKeys.add('nonRegression');
+  }
+
+  // Script verifiers — use ring-aware runner to persist artifacts
+  for (const key of activeKeys) {
+    if (!SCRIPT_VERIFIERS[key]) continue;
+    if (aggregateBuild && SKIP_WHEN_AGGREGATING.has(key)) {
+      const aggregateOk = buildEvidence.ok && (!sliceGate.applicable || sliceGate.ok);
+      ringDoD[key] = aggregateOk ? 'passed' : 'failed';
+      if (!aggregateOk) {
+        const reason = `build evidence aggregation failed for ${key} (set PLAYCRAFT_GATE_RERUN=1 to re-run ${SCRIPT_VERIFIERS[key]})`;
+        failures.push(reason);
+        blockingIssues.push(reason);
+        failedKeys.add(key);
+      }
+      continue;
+    }
+    // Already marked failed by the deps preflight — don't run with a broken toolchain.
+    if (!pythonDepsOk && PYTHON_VISUAL_KEYS.has(key)) continue;
+    const result = runScriptVerifierForRing(projectDir, key, iteration);
+    ringDoD[key] = result.ok ? 'passed' : 'failed';
+    if (!result.ok) {
+      failures.push(result.reason);
+      blockingIssues.push(result.reason);
+      failedKeys.add(key);
+    }
+  }
+
+  // Review verifiers
+  for (const key of activeKeys) {
+    if (!REVIEW_VERIFIERS[key]) continue;
+    const status = ringDoD[key];
+    if (!isPassed(status)) {
+      const label = DOD_LABELS[key];
+      failures.push(`${label} not passed (set logs/review-report.md § Ring DoD Fields)`);
+      blockingIssues.push(`${key} review pending`);
+      failedKeys.add(key);
+    }
+  }
+
+  const verdict = failures.length === 0 && allDoDPassed(ringDoD, activeKeys) ? 'pass' : 'fail';
+  const canAskUser = verdict === 'pass';
+
+  const failedKeyList = [...failedKeys];
+  const vlmRoute = failedKeys.has('vlmVideo')
+    ? routeForVlmVideoArtifact(projectDir, iteration)
+    : null;
+  const sliceRoute =
+    failedKeys.has('sliceQueue') && sliceGate.applicable
+      ? { routeTo: sliceGate.routeTo, nextAction: sliceGate.nextAction }
+      : null;
+  const route = canAskUser
+    ? { routeTo: 'none', nextAction: `Run Ring Gate AskUserQuestion for iteration ${iteration}` }
+    : sliceRoute || vlmRoute || routeForFailedDoDKeys(failedKeyList);
+
+  return {
+    iteration,
+    verdict,
+    checkedAt: new Date().toISOString(),
+    ringDoD,
+    activeKeys,
+    failedKeys: failedKeyList,
+    blockingIssues: blockingIssues.length,
+    canAskUser: canAskUser ? 'yes' : 'no',
+    routeTo: route.routeTo,
+    nextAction: route.nextAction,
+    failReason: verdict === 'pass' ? 'none' : failures.slice(0, 5).join('; '),
+    nonRegression: regression.ok ? 'pass' : 'fail',
+    sliceGate: sliceGate.applicable ? sliceGate.summary : null,
+    summary: { ringDoD, failures, activeKeys, sliceGate: sliceGate.applicable ? sliceGate : null },
+  };
+}
+
+/**
+ * Parse review-report.md reviewer verdicts and write validate/ringN/review.json.
+ * Tier B: structured reviewer-door artifact for discoverability.
+ */
+function persistReviewArtifact(projectDir, iteration, reviewContent) {
+  if (!reviewContent) return;
+  const section = getSection(reviewContent, 'Ring DoD Fields');
+  if (!section) return;
+  const table = parseKeyValueTable(section);
+  const verdicts = {};
+  for (const [key, cfg] of Object.entries(REVIEW_VERIFIERS)) {
+    const raw = String(table.get(cfg.field) || table.get(key) || '').trim().toLowerCase();
+    verdicts[key] = raw || 'pending';
+  }
+  const reviewData = {
+    ok: Object.values(verdicts).every((v) => v === 'passed' || v === 'pass'),
+    iteration,
+    verdicts,
+  };
+  try {
+    writeRingArtifactSync(projectDir, iteration, 'review', reviewData);
+  } catch {}
+}
+
+function emitResult(result) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const iteration = normalizeIteration(args.iteration);
+  if (!iteration) {
+    process.stderr.write(
+      'Usage: node .claude/hooks/gate-runner.mjs --iteration 1|2|3|4 [--project <dir>]\n',
+    );
+    process.exit(1);
+  }
+
+  const projectDir = normalizeProjectDir(
+    args.project || process.env.CODEBUDDY_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.env.CURSOR_PROJECT_DIR || process.cwd(),
+  );
+  if (!stateExists(projectDir)) {
+    process.stderr.write('Missing docs/project-state.json (run npm run ensure:project)\n');
+    process.exit(1);
+  }
+
+  const reviewReportPath = path.join(projectDir, 'logs/review-report.md');
+  const state = readState(projectDir);
+  const reviewContent = readFileSafe(reviewReportPath);
+
+  const result = computeRingResult({
+    iteration,
+    projectDir,
+    state,
+    reviewContent,
+  });
+
+  // Persist ringDoD (merge computed statuses) then ring-gate runner fields.
+  setRingDoD(projectDir, result.ringDoD);
+  // Tier B: write reviewer-door artifact before collecting paths.
+  persistReviewArtifact(projectDir, iteration, reviewContent);
+  // Collect and persist all artifact paths for this ring.
+  setRingArtifacts(projectDir, iteration, collectRingArtifactPaths(projectDir, iteration));
+  setRingGateRunner(projectDir, {
+    ringGateCurrent: String(iteration),
+    ringGateVerdict: result.verdict,
+    ringGateCheckedAt: result.checkedAt,
+    ringGateBlockingIssues: String(result.blockingIssues),
+    ringGateCanAskUser: result.canAskUser,
+    ringGateRouteTo: result.routeTo,
+    ringGateFailReason: result.failReason,
+    ringGateNonRegression: result.nonRegression,
+  });
+
+  emitResult(result);
+  process.exit(result.verdict === 'pass' ? 0 : 2);
+}
+
+export { computeRingResult, parseReviewRingDoD };
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main();
+}