@playcraft/cli 0.1.54 → 0.1.56-beta

package/project-template-v2/skills/playable-record/scripts/verify-fusion.mjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * Gameplay fusion wiring probe — objective DoD for `fusion`.
+ *
+ * - <2 selected *.aigameplay atoms → PASS (no-op)
+ * - ≥2 atoms → DESIGN fusion type must be consistent + each mechanic wired in game/ source
+ *   + autoPlay path references both mechanics when publish contract is present
+ *
+ * Usage:
+ *   node skills/playable-record/scripts/verify-fusion.mjs --root=.
+ *   npm run verify:fusion
+ *
+ * Exit 0 = OK/pass
+ * Exit 2 = fusion contract broken
+ * Exit 1 = unexpected error
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { writeValidatorArtifact } from '../../_shared/scripts/lib/validator-artifacts.mjs';
+
+// `[*_\s]*` tolerates markdown emphasis in the §6 template form `- **Fusion type**:`.
+const FUSION_TYPE_RE =
+  /Fusion\s+type[*_\s]*:\s*(Single|A-Visual|B1-Passive|B2-Active|C-Sequential|D-Parallel)/i;
+const REAL_FUSION_TYPES = new Set(['A-Visual', 'B1-Passive', 'B2-Active', 'C-Sequential', 'D-Parallel']);
+
+/** Signature tokens per gameplay atom — at least one must appear under game/. */
+export const GAMEPLAY_SIGNATURES = {
+  'match3_core.aigameplay': [
+    'trySwap',
+    'applyGravity',
+    'refillBoard',
+    'minMatchCount',
+    'match3',
+    'match-3',
+  ],
+  'memory_match.aigameplay': [
+    'flipCard',
+    'checkMatch',
+    'face_up',
+    'pairId',
+    'memory_match',
+    'flipBack',
+  ],
+  'screw_puzzle.aigameplay': [
+    'removeScrew',
+    'canRemoveScrew',
+    'bufferSlots',
+    'screw_puzzle',
+    'colorMatchRequired',
+  ],
+  'arrow_escape_core.aigameplay': [
+    'arrow_escape',
+    'direction_arrow',
+    'escape_core',
+    'canMoveArrow',
+  ],
+};
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), json: false };
+  for (const arg of argv) {
+    if (arg === '--json') opts.json = true;
+    else if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    }
+  }
+  return opts;
+}
+
+/**
+ * @param {unknown} tree
+ * @returns {string[]}
+ */
+export function readSelectedGameplayAtoms(tree) {
+  const atoms = Array.isArray(tree?.meta?.selectedAtoms) ? tree.meta.selectedAtoms : [];
+  return atoms
+    .map((a) => (typeof a === 'string' ? a.trim() : ''))
+    .filter((a) => a.endsWith('.aigameplay'));
+}
+
+/**
+ * True only when a real pseudo-fusion / risk-accepted decision is documented.
+ *
+ * Judged by the *value* of the "Pseudo-fusion decision:" field — not the field
+ * label itself. The §6 template label always contains the word "pseudo-fusion"
+ * (and the placeholder hint contains "risk accepted: …"), so a naive substring
+ * match would make every fusion gate a no-op for any template-derived DESIGN.md.
+ *
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function hasPseudoFusionDecision(content) {
+  // Drop unfilled {…} template placeholders so their hint text cannot satisfy the gate.
+  const filled = content.replace(/\{[^}]*\}/g, '');
+  // `[*_\s]*` tolerates markdown emphasis in `- **Pseudo-fusion decision**:`.
+  const field = filled.match(/Pseudo-?fusion decision[*_\s]*:\s*(.*)/i);
+  if (field) {
+    const value = field[1].trim();
+    const lower = value.toLowerCase();
+    const isEmpty = lower === '' || lower === 'n/a' || lower === 'na' || lower === 'none';
+    if (!isEmpty) return true;
+    // Field present but n/a → no decision documented; fall through to scan the rest.
+  }
+  // No structured field (or n/a): scan with the bare label stripped so it cannot self-satisfy.
+  const scrubbed = filled.replace(/Pseudo-?fusion decision[*_\s]*:/gi, '');
+  return /pseudo-?fusion/i.test(scrubbed) || /risk\s+accepted/i.test(scrubbed);
+}
+
+/**
+ * @param {string} designContent
+ * @returns {{ type: string | null, isPseudoFusion: boolean }}
+ */
+export function parseDesignFusionType(designContent) {
+  const match = designContent.match(FUSION_TYPE_RE);
+  if (!match) return { type: null, isPseudoFusion: false };
+  const raw = match[1];
+  const type =
+    raw.startsWith('B1') ? 'B1-Passive' : raw.startsWith('B2') ? 'B2-Active' : raw;
+  const isPseudoFusion = hasPseudoFusionDecision(designContent);
+  return { type, isPseudoFusion };
+}
+
+/**
+ * @param {string} content
+ * @param {string} atomId
+ * @returns {string[]}
+ */
+export function matchedSignatures(content, atomId) {
+  const signatures = GAMEPLAY_SIGNATURES[atomId] ?? [
+    atomId.replace('.aigameplay', ''),
+    atomId.split('.')[0],
+  ];
+  return signatures.filter((sig) => content.includes(sig));
+}
+
+async function collectGameSource(root) {
+  const gameDir = join(root, 'game');
+  if (!existsSync(gameDir)) return '';
+  const chunks = [];
+
+  async function walk(dir) {
+    let entries = [];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(abs);
+        continue;
+      }
+      if (!/\.(ts|js|mjs|cjs)$/.test(entry.name)) continue;
+      try {
+        chunks.push(await readFile(abs, 'utf8'));
+      } catch {
+        // ignore unreadable files
+      }
+    }
+  }
+
+  await walk(gameDir);
+  return chunks.join('\n');
+}
+
+/**
+ * Extract the full `autoPlay(...) { ... }` body via brace balancing.
+ *
+ * A non-greedy regex stops at the first `\n}` and truncates the block whenever
+ * autoPlay contains nested `{}` (if/for blocks), which would drop later mechanic
+ * calls and cause false "missing mechanic" failures. This walks braces instead.
+ *
+ * @param {string} gameSource
+ * @returns {string}
+ */
+export function extractAutoPlayBlock(gameSource) {
+  const header = /autoPlay\s*\([^)]*\)\s*\{/g;
+  const m = header.exec(gameSource);
+  if (!m) return '';
+  const start = m.index;
+  let depth = 0;
+  for (let i = header.lastIndex - 1; i < gameSource.length; i += 1) {
+    const ch = gameSource[i];
+    if (ch === '{') depth += 1;
+    else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return gameSource.slice(start, i + 1);
+    }
+  }
+  // Unbalanced source — best effort: return from the header onward.
+  return gameSource.slice(start);
+}
+
+/**
+ * @param {string} root
+ * @param {{ gameplayAtoms?: string[], designContent?: string, gameSource?: string }} [overrides]
+ */
+export async function verifyFusion(root, overrides = {}) {
+  const problems = [];
+
+  let gameplayAtoms = overrides.gameplayAtoms;
+  if (!gameplayAtoms) {
+    const atomTreePath = join(root, 'docs/atom-tree.json');
+    if (!existsSync(atomTreePath)) {
+      return { ok: true, skipped: true, reason: 'no atom-tree.json — fusion no-op' };
+    }
+    const tree = JSON.parse(await readFile(atomTreePath, 'utf8'));
+    gameplayAtoms = readSelectedGameplayAtoms(tree);
+  }
+
+  if (gameplayAtoms.length < 2) {
+    return { ok: true, skipped: true, reason: 'single gameplay atom — fusion no-op PASS' };
+  }
+
+  const designPath = existsSync(join(root, 'docs/design.md'))
+    ? join(root, 'docs/design.md')
+    : join(root, 'docs/DESIGN.md');
+  const designContent =
+    overrides.designContent ??
+    (existsSync(designPath) ? await readFile(designPath, 'utf8') : '');
+  const { type, isPseudoFusion } = parseDesignFusionType(designContent);
+
+  if (!type) {
+    problems.push('DESIGN.md missing Fusion type: — classify fusion in ## 6. Gameplay Fusion');
+  } else if (type === 'Single' && !isPseudoFusion) {
+    problems.push(
+      `DESIGN.md Fusion type is Single but atom-tree selected ${gameplayAtoms.length} gameplay atoms — use a real fusion type or document pseudo-fusion`,
+    );
+  } else if (type !== 'Single' && !REAL_FUSION_TYPES.has(type) && !isPseudoFusion) {
+    problems.push(`DESIGN.md Fusion type "${type}" is not a recognized fusion classification`);
+  }
+
+  const gameSource = overrides.gameSource ?? (await collectGameSource(root));
+  if (!gameSource.trim()) {
+    problems.push('game/ source missing — cannot verify fusion wiring');
+    return { ok: false, problems, gameplayAtoms };
+  }
+
+  const wiring = {};
+  for (const atomId of gameplayAtoms) {
+    const hits = matchedSignatures(gameSource, atomId);
+    wiring[atomId] = hits;
+    if (hits.length === 0) {
+      problems.push(
+        `gameplay atom "${atomId}" has no wiring evidence in game/ (expected one of: ${(GAMEPLAY_SIGNATURES[atomId] ?? [atomId]).join(', ')})`,
+      );
+    }
+  }
+
+  const autoPlayBlock = extractAutoPlayBlock(gameSource);
+  if (autoPlayBlock) {
+    const autoPlayHits = gameplayAtoms.filter((atomId) =>
+      matchedSignatures(autoPlayBlock, atomId).length > 0,
+    );
+    if (autoPlayHits.length < gameplayAtoms.length) {
+      const missing = gameplayAtoms.filter((id) => !autoPlayHits.includes(id));
+      problems.push(
+        `autoPlay() does not reference all fused mechanics — missing evidence for: ${missing.join(', ')}`,
+      );
+    }
+  } else {
+    const referencedInSource = gameplayAtoms.filter((atomId) => gameSource.includes(atomId));
+    if (referencedInSource.length < gameplayAtoms.length) {
+      problems.push(
+        'autoPlay() block not found and not all selected gameplay atom ids appear in game/ source',
+      );
+    }
+  }
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    gameplayAtoms,
+    wiring,
+    fusionType: type,
+  };
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  try {
+    const result = await verifyFusion(opts.root);
+    const artifactPayload = result.skipped
+      ? { ok: true, skipped: true, reason: result.reason }
+      : result;
+    await writeValidatorArtifact(opts.root, 'fusion', artifactPayload).catch(() => {});
+    if (result.skipped) {
+      const msg = `[verify:fusion] OK — ${result.reason}\n`;
+      process.stdout.write(msg);
+      if (opts.json) process.stdout.write(`${JSON.stringify({ ok: true, skipped: true, reason: result.reason })}\n`);
+      process.exit(0);
+    }
+
+    if (result.ok) {
+      const msg = `[verify:fusion] OK — ${result.gameplayAtoms.length} gameplay atoms wired (${result.gameplayAtoms.join(', ')})\n`;
+      process.stdout.write(msg);
+      if (opts.json) process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+      process.exit(0);
+    }
+
+    const detail = result.problems.join('\n  - ');
+    process.stderr.write(`[verify:fusion] FAIL\n  - ${detail}\n`);
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify({ ok: false, problems: result.problems, ...result })}\n`);
+    }
+    process.exit(2);
+  } catch (err) {
+    process.stderr.write(`[verify:fusion] error: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+const isMain =
+  process.argv[1] && basename(process.argv[1]) === 'verify-fusion.mjs';
+
+if (isMain) {
+  main();
+}

package/project-template-v2/skills/playable-record/scripts/verify-lifecycle.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Iteration-2 lifecycle probe.
+ *
+ * Boots the game, triggers autoPlay, and verifies that the phase path is
+ * complete: starts at HOOK, passes through TUTORIAL and GAMEPLAY, reaches
+ * ENDCARD. Missing intermediate phases indicate an incomplete scene FSM —
+ * fix in the packaging-scene-fsm todo (game/ state machine entry points).
+ *
+ * iter-1 only required HOOK→ENDCARD; iter-2 requires all 4 waypoints.
+ */
+
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runFirstWinProbe } from './verify-firstwin.mjs';
+import { writeValidatorArtifact } from '../../_shared/scripts/lib/validator-artifacts.mjs';
+
+function parseArgs(argv) {
+  const opts = {
+    root: process.cwd(),
+    url: null,
+    useDev: false,
+    port: 8080,
+    scene: 'MainScene',
+    timeout: 30_000,
+    headed: false,
+    json: false,
+  };
+  for (const arg of argv) {
+    if (arg === '--use-dev') opts.useDev = true;
+    else if (arg === '--headed') opts.headed = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg.startsWith('--url=')) opts.url = arg.slice('--url='.length);
+    else if (arg.startsWith('--port=')) opts.port = Number(arg.slice('--port='.length));
+    else if (arg.startsWith('--scene=')) opts.scene = arg.slice('--scene='.length);
+    else if (arg.startsWith('--timeout=')) opts.timeout = Number(arg.slice('--timeout='.length));
+  }
+  return opts;
+}
+
+// Phases that must appear somewhere in phasePath (in order) for iter-2.
+const REQUIRED_WAYPOINTS = ['HOOK', 'TUTORIAL', 'GAMEPLAY', 'ENDCARD'];
+
+export function evaluateLifecycleResult(result) {
+  const problems = [...(result.problems || [])];
+  const path = result.phasePath || [];
+
+  if (result.ok) {
+    if (path[0] !== 'HOOK') {
+      problems.push(
+        `phase path must start at HOOK but started at "${path[0] ?? '(empty)'}" — ` +
+        'check that window.__playable.getState().currentPhase is "HOOK" on boot ' +
+        '(game/ state machine entry, typically game/scenes/MainScene or game/fsm/)',
+      );
+    }
+    const missing = REQUIRED_WAYPOINTS.filter((wp) => !path.includes(wp));
+    if (missing.length > 0) {
+      problems.push(
+        `phase path missing required waypoints: ${missing.join(', ')} — ` +
+        'autoPlay() did not drive through these phases; add scene transitions in ' +
+        'the packaging-scene-fsm todo (game/ state machine or scene manager)',
+      );
+    }
+    if (path[path.length - 1] !== 'ENDCARD') {
+      problems.push(
+        `phase path must end at ENDCARD but ended at "${path[path.length - 1] ?? '(empty)'}" — ` +
+        'check win/fail → ENDCARD transition in game/ scene FSM',
+      );
+    }
+  }
+  return { ok: result.ok && problems.length === 0, problems, phasePath: path };
+}
+
+function printHuman(result) {
+  const evaluated = evaluateLifecycleResult(result);
+  console.log(`[verify:lifecycle] ${evaluated.ok ? 'OK' : 'FAIL'} — ${result.url}`);
+  if (result.phasePath) console.log(`  phase path: ${result.phasePath.join(' → ')}`);
+  if (result.elapsedMs != null) console.log(`  elapsed: ${result.elapsedMs}ms`);
+  for (const p of evaluated.problems) console.log(`  ✗ ${p}`);
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = await runFirstWinProbe(opts);
+  const evaluated = evaluateLifecycleResult(result);
+  const payload = { ...result, ...evaluated };
+  await writeValidatorArtifact(opts.root, 'lifecycle', payload).catch(() => {});
+  if (opts.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    printHuman(result);
+  }
+  process.exit(evaluated.ok ? 0 : 2);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((err) => {
+    console.error(`[verify:lifecycle] ${err.message}`);
+    process.exit(1);
+  });
+}

package/project-template-v2/skills/playable-record/scripts/verify-vlm-video.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/**
+ * VLM-based video semantic verifier for growth-ring harness.
+ *
+ * Invokes `playcraft tools analyze-video` on the autoplay MP4 and writes
+ * findings to validate/ring{N}/vlm-video.json (or per-slice path when --slice-id set).
+ *
+ * Usage:
+ *   node skills/playable-record/scripts/verify-vlm-video.mjs --root=. --ring=2 [--record-first] [--slice-id=...] [--context-json=...]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readState } from '../../_shared/scripts/state-store.mjs';
+
+function parseArgs(argv) {
+  const opts = {
+    root: process.cwd(),
+    ring: null,
+    tier: null,
+    provider: null,
+    video: null,
+    contextFile: null,
+    contextJson: null,
+    sliceId: null,
+    recordFirst: false,
+  };
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) opts.root = arg.slice('--root='.length);
+    else if (arg.startsWith('--ring=')) opts.ring = arg.slice('--ring='.length);
+    else if (arg.startsWith('--tier=')) opts.tier = arg.slice('--tier='.length);
+    else if (arg.startsWith('--provider=')) opts.provider = arg.slice('--provider='.length);
+    else if (arg.startsWith('--video=')) opts.video = arg.slice('--video='.length);
+    else if (arg.startsWith('--context-file=')) opts.contextFile = arg.slice('--context-file='.length);
+    else if (arg.startsWith('--context-json=')) opts.contextJson = arg.slice('--context-json='.length);
+    else if (arg.startsWith('--slice-id=')) opts.sliceId = arg.slice('--slice-id='.length);
+    else if (arg === '--record-first' || arg === '--record-first=true') opts.recordFirst = true;
+  }
+  return opts;
+}
+
+function resolveRoot(root) {
+  return path.isAbsolute(root) ? root : path.resolve(process.cwd(), root);
+}
+
+function defaultTier(ring) {
+  const n = Number(ring);
+  if (Number.isFinite(n) && n >= 3) return 'thorough';
+  return 'fast';
+}
+
+function resolvePlaycraftCmd(projectRoot) {
+  const candidates = [
+    process.env.PLAYCRAFT_CLI_PATH,
+    path.join(projectRoot, 'node_modules/.bin/playcraft'),
+    'playcraft',
+  ].filter(Boolean);
+  for (const cmd of candidates) {
+    const result = spawnSync(cmd, ['--version'], {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      timeout: 10_000,
+    });
+    if (result.status === 0 || result.status === null) return cmd;
+  }
+  return process.platform === 'win32' ? 'npx.cmd' : 'npx';
+}
+
+function runPlaycraft(cmd, args, timeoutMs) {
+  const isNpx = cmd === 'npx' || cmd === 'npx.cmd';
+  const finalArgs = isNpx ? ['playcraft', ...args] : args;
+  return spawnSync(cmd, finalArgs, {
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function runNpmRecord(root, ring) {
+  return spawnSync(
+    'npm',
+    ['run', 'record:mp4', '--', `--out=validate/ring${ring}`, '--name=autoplay', '--use-dev'],
+    {
+      cwd: root,
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      timeout: 360_000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+}
+
+function extractDesignSummary(root, ring) {
+  const designPath = fs.existsSync(path.join(root, 'docs/design.md'))
+    ? path.join(root, 'docs/design.md')
+    : path.join(root, 'docs/DESIGN.md');
+  if (!fs.existsSync(designPath)) return undefined;
+  const text = fs.readFileSync(designPath, 'utf8');
+  const sections = [];
+  const pick = (label, re) => {
+    const m = text.match(re);
+    if (m) sections.push(`${label}: ${m[1].trim().slice(0, 200)}`);
+  };
+  pick('Player action', /##\s*Player Action\s*\n([\s\S]*?)(?=\n##|$)/i);
+  pick('First win', /##\s*First(?:[- ]Level)? Win\s*\n([\s\S]*?)(?=\n##|$)/i);
+  if (Number(ring) >= 3) {
+    pick('Hook', /##\s*Hook\s*\n([\s\S]*?)(?=\n##|$)/i);
+    pick('CTA', /##\s*CTA\s*\n([\s\S]*?)(?=\n##|$)/i);
+  }
+  return sections.join('\n') || undefined;
+}
+
+function buildContextFromSlice(root, sliceId, ring) {
+  const state = readState(root);
+  const slice =
+    (state.sliceState?.slices || []).find((s) => s.sliceId === sliceId)
+    || (state.sliceState?.slices || []).find((s) => s.sliceId === state.sliceState?.activeSliceId)
+    || null;
+  const designSummary = extractDesignSummary(root, ring);
+  const hypothesis = slice?.hypothesis ? `Slice hypothesis: ${slice.hypothesis}` : '';
+  const parts = [designSummary, hypothesis].filter(Boolean);
+  if (!parts.length) return undefined;
+  return {
+    designSummary: parts.join('\n'),
+    firstAction: slice?.doWhat || undefined,
+  };
+}
+
+/**
+ * @param {ReturnType<typeof parseArgs>} opts
+ */
+export function runVerifyVlmVideo(opts) {
+  const root = resolveRoot(opts.root);
+  const ring = opts.ring || '1';
+  const tier = opts.tier || defaultTier(ring);
+  const videoPath = opts.video || path.join(root, `validate/ring${ring}/autoplay.mp4`);
+
+  if (!fs.existsSync(videoPath)) {
+    if (opts.recordFirst) {
+      const rec = runNpmRecord(root, ring);
+      if (rec.status !== 0) {
+        return { ok: false, exitCode: 2, error: `record:mp4 failed: ${(rec.stderr || rec.stdout).slice(-300)}` };
+      }
+    }
+  }
+  if (!fs.existsSync(videoPath)) {
+    return { ok: false, exitCode: 2, error: `video not found: ${videoPath}` };
+  }
+
+  let context = undefined;
+  if (opts.contextJson) {
+    try {
+      context = JSON.parse(opts.contextJson);
+    } catch (err) {
+      return { ok: false, exitCode: 2, error: `invalid --context-json: ${err.message}` };
+    }
+  } else {
+    context = buildContextFromSlice(root, opts.sliceId, ring);
+  }
+
+  const outDir = path.join(root, `validate/ring${ring}`);
+  fs.mkdirSync(outDir, { recursive: true });
+  const outPath = opts.sliceId
+    ? path.join(root, 'validate/slice', `${opts.sliceId}.vlm-video.json`)
+    : path.join(outDir, 'vlm-video.json');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+
+  const cmd = resolvePlaycraftCmd(root);
+  const args = ['tools', 'analyze-video', '--video', videoPath, '--output', outPath, '--ring', String(ring)];
+  const contextFile = opts.contextFile || path.join(root, 'docs/DESIGN.md');
+  if (context) {
+    args.push('--context-json', JSON.stringify(context));
+  } else if (fs.existsSync(contextFile)) {
+    args.push('--context-file', contextFile);
+  }
+  if (tier) args.push('--tier', tier);
+  if (opts.provider) args.push('--provider', opts.provider);
+
+  const timeoutMs = tier === 'fast' ? 120_000 : 360_000;
+  const result = runPlaycraft(cmd, args, timeoutMs);
+
+  if (!fs.existsSync(outPath)) {
+    const detail = result.stderr || result.stdout || result.error || `exit ${result.status}`;
+    const errorArtifact = { ok: false, error: detail.slice(-500), findings: [] };
+    fs.writeFileSync(outPath, `${JSON.stringify(errorArtifact, null, 2)}\n`, 'utf8');
+    return { ok: false, exitCode: 2, artifact: errorArtifact, cliArgs: args };
+  }
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(outPath, 'utf8'));
+  } catch (err) {
+    const errorArtifact = { ok: false, error: err.message, findings: [] };
+    fs.writeFileSync(outPath, `${JSON.stringify(errorArtifact, null, 2)}\n`, 'utf8');
+    return { ok: false, exitCode: 2, artifact: errorArtifact, cliArgs: args };
+  }
+
+  const failed = (data.findings || []).filter((f) => f.status === 'fail' || f.severity === 'P0');
+  return {
+    ok: failed.length === 0,
+    exitCode: failed.length === 0 ? 0 : 2,
+    artifact: data,
+    outPath,
+    cliArgs: args,
+    ring,
+    tier,
+  };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = runVerifyVlmVideo(opts);
+  if (result.error && !result.artifact) {
+    console.error(`[verify-vlm-video] ${result.error}`);
+    process.exit(result.exitCode ?? 2);
+  }
+  const failed = (result.artifact?.findings || []).filter(
+    (f) => f.status === 'fail' || f.severity === 'P0',
+  );
+  console.log(
+    `[verify-vlm-video] ok=${result.ok} findings=${result.artifact?.findings?.length ?? 0} failed=${failed.length} ring=${result.ring} tier=${result.tier} → ${result.outPath || 'n/a'}`,
+  );
+  process.stdout.write(`${JSON.stringify(result.artifact, null, 2)}\n`);
+  process.exit(result.exitCode ?? (result.ok ? 0 : 2));
+}
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) main();