@playcraft/cli 0.0.44 → 0.0.47

package/project-template/skills/playable-record/scripts/verify-visual-ring.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * Ring N visual gate (Ring 2 / 3) — record autoplay MP4 + keyframe CV basics.
+ *
+ * Flow:
+ *   1. npm run record:mp4 → validate/ring{N}/autoplay.mp4 (stable name)
+ *   2. Hard assert: file exists and size > 10 KB
+ *   3. Extract keyframes to validate/ring{N}/frames/
+ *   4. Run basic CV sanity check and write validate/ring{N}/video-cv.json
+ *   5. Write validate/ring{N}/visual.json artifact
+ *
+ * Usage (called by npm scripts verify:visual-ring2 / verify:visual-ring3):
+ *   node verify-visual-ring.mjs --ring=2 --root=. [--use-dev]
+ *
+ * Exit 0 = pass, 2 = fail, 1 = error
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { writeValidatorArtifact } from '../../_shared/scripts/lib/validator-artifacts.mjs';
+
+const MIN_MP4_BYTES = 10_240;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), ring: 2, useDev: false };
+  for (const arg of argv) {
+    if (arg === '--use-dev') opts.useDev = 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('--ring=')) {
+      const n = Number(arg.slice('--ring='.length));
+      if (n >= 2 && n <= 4) opts.ring = n;
+    }
+  }
+  return opts;
+}
+
+function run(cmd, args, runOpts = {}) {
+  const result = spawnSync(cmd, args, {
+    cwd: runOpts.cwd,
+    encoding: 'utf8',
+    timeout: runOpts.timeout ?? 300_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: process.platform === 'win32',
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    error: result.error?.message ?? null,
+  };
+}
+
+async function recordAutoplay(root, ring) {
+  const isWin = process.platform === 'win32';
+  const cmd = isWin ? 'npm.cmd' : 'npm';
+  const args = ['run', 'record:mp4', '--', `--out=validate/ring${ring}`, '--name=autoplay'];
+  return run(cmd, args, { cwd: root, timeout: 300_000 });
+}
+
+function ffprobeDurationSeconds(mp4Path) {
+  const result = run(
+    'ffprobe',
+    [
+      '-v',
+      'error',
+      '-show_entries',
+      'format=duration',
+      '-of',
+      'default=noprint_wrappers=1:nokey=1',
+      mp4Path,
+    ],
+    { timeout: 30_000 },
+  );
+  if (!result.ok) return null;
+  const duration = Number.parseFloat(result.stdout.trim());
+  return Number.isFinite(duration) && duration > 0 ? duration : null;
+}
+
+function extractFrame(mp4Path, seconds, outPath) {
+  const result = run(
+    'ffmpeg',
+    [
+      '-y',
+      '-ss',
+      String(Math.max(0, seconds)),
+      '-i',
+      mp4Path,
+      '-frames:v',
+      '1',
+      '-vf',
+      'scale=360:-1',
+      outPath,
+    ],
+    { timeout: 60_000 },
+  );
+  return result.ok && existsSync(outPath);
+}
+
+function runFrameCv(root, ring, framesRel) {
+  const script = resolve(__dirname, '../../playable-verify-ui/scripts/verify_ring1_visual.py');
+  const outRel = `validate/ring${ring}/video-cv.json`;
+  const result = run(
+    'python3',
+    [
+      script,
+      `--root=${root}`,
+      `--frames=${framesRel}`,
+      `--out=${outRel}`,
+      '--check-motion',
+      '--check-edge-density',
+      '--json',
+    ],
+    { cwd: root, timeout: 120_000 },
+  );
+  let report = null;
+  try {
+    report = JSON.parse(result.stdout);
+  } catch {
+    report = {
+      ok: false,
+      failures: [result.stderr || result.stdout || result.error || `exit ${result.status}`],
+      frames: [],
+    };
+  }
+  return { ok: result.ok && report?.ok === true, report, outRel, status: result.status };
+}
+
+/**
+ * @param {{ ring: number; root: string; useDev?: boolean }} opts
+ */
+export async function runVisualRingGate(opts) {
+  const ring = opts.ring ?? 2;
+  const root = resolve(opts.root ?? process.cwd());
+  const mp4Rel = `validate/ring${ring}/autoplay.mp4`;
+  const mp4Path = join(root, mp4Rel);
+  const framesRel = `validate/ring${ring}/frames`;
+  const framesDir = join(root, framesRel);
+  const problems = [];
+  const extractedFrames = [];
+
+  await mkdir(join(root, `validate/ring${ring}`), { recursive: true });
+  await mkdir(framesDir, { recursive: true });
+
+  const record = await recordAutoplay(root, ring);
+  if (!record.ok) {
+    problems.push(
+      `autoplay recording failed: ${(record.stderr || record.stdout || record.error || `exit ${record.status}`).split('\n').slice(-3).join(' ')}`,
+    );
+  }
+
+  if (!existsSync(mp4Path)) {
+    problems.push(
+      `missing autoplay video: ${mp4Rel} — Ring ${ring} gate requires scripted autoplay MP4 artifact`,
+    );
+  } else {
+    const size = statSync(mp4Path).size;
+    if (size < MIN_MP4_BYTES) {
+      problems.push(
+        `autoplay video too small (${size} bytes < ${MIN_MP4_BYTES}): ${mp4Rel}`,
+      );
+    }
+  }
+
+  let cv = null;
+  if (existsSync(mp4Path)) {
+    const duration = ffprobeDurationSeconds(mp4Path);
+    if (duration == null) {
+      problems.push(`unable to probe autoplay video duration: ${mp4Rel}`);
+    } else {
+      const positions = [0, duration * 0.5, Math.max(0, duration - 0.25)];
+      for (const [idx, seconds] of positions.entries()) {
+        const name = `${String(idx + 1).padStart(2, '0')}.png`;
+        const outPath = join(framesDir, name);
+        if (extractFrame(mp4Path, seconds, outPath)) {
+          extractedFrames.push(`${framesRel}/${name}`);
+        } else {
+          problems.push(`failed to extract keyframe ${name} from ${mp4Rel}`);
+        }
+      }
+      if (extractedFrames.length === 3) {
+        cv = runFrameCv(root, ring, framesRel);
+        if (!cv.ok) {
+          const failures = Array.isArray(cv.report?.failures) ? cv.report.failures : [];
+          problems.push(
+            failures.length > 0
+              ? `video CV failed: ${failures.slice(0, 3).join('; ')}`
+              : `video CV failed: ${cv.outRel}`,
+          );
+        }
+      }
+    }
+  }
+
+  const ok = problems.length === 0;
+  const payload = {
+    ok,
+    ring,
+    problems,
+    autoplayMp4: mp4Rel,
+    frames: extractedFrames,
+    videoCv: cv?.outRel ?? `validate/ring${ring}/video-cv.json`,
+    cv: cv?.report ?? null,
+    recordExit: record.status,
+  };
+
+  await writeValidatorArtifact(root, 'visual', payload, ring);
+
+  return { ok, problems, payload };
+}
+
+function printHuman(ring, result) {
+  console.log(`[verify:visual-ring${ring}] ${result.ok ? 'OK' : 'FAIL'}`);
+  if (result.payload.autoplayMp4) {
+    console.log(`  mp4: ${result.payload.autoplayMp4}`);
+  }
+  for (const p of result.problems) {
+    console.log(`  ✗ ${p}`);
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  try {
+    const result = await runVisualRingGate(opts);
+    if (opts.json) {
+      console.log(JSON.stringify(result.payload, null, 2));
+    } else {
+      printHuman(opts.ring, result);
+    }
+    process.exit(result.ok ? 0 : 2);
+  } catch (err) {
+    console.error(`[verify:visual-ring${opts.ring}] ${err.message}`);
+    process.exit(1);
+  }
+}
+
+const isMain =
+  process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main();
+}

package/project-template/skills/playable-record/scripts/verify-visual-ring1.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Ring 1 visual gate — autoplay MP4 artifact + reference-free CV on extracted frames.
+ *
+ * 1. Record autoplay → validate/ring1/autoplay.mp4 (hard requirement)
+ * 2. ffmpeg extract 3 frames → validate/ring1/frames/01|02|03.png
+ * 3. Python CV heuristics → validate/ring1/visual.json
+ *
+ * All artifacts are script-owned (no LLM writes).
+ *
+ * Exit 0 = pass, 2 = fail, 1 = error
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  RING1_AUTOPLAY_MP4,
+  RING1_FRAMES_DIR,
+  writeValidatorArtifact,
+} from '../../_shared/scripts/lib/validator-artifacts.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MIN_MP4_BYTES = 10_240;
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), useDev: false, json: false };
+  for (const arg of argv) {
+    if (arg === '--use-dev') opts.useDev = 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);
+    }
+  }
+  return opts;
+}
+
+function run(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, {
+    cwd: opts.cwd,
+    encoding: 'utf8',
+    timeout: opts.timeout ?? 300_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    error: result.error?.message ?? null,
+  };
+}
+
+function ffprobeDurationSeconds(mp4Path) {
+  const result = run('ffprobe', [
+    '-v',
+    'error',
+    '-show_entries',
+    'format=duration',
+    '-of',
+    'default=noprint_wrappers=1:nokey=1',
+    mp4Path,
+  ]);
+  if (!result.ok) return 0;
+  const n = Number.parseFloat(String(result.stdout).trim());
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+function extractFrame(mp4Path, seconds, outPath) {
+  const ss = Math.max(0, seconds).toFixed(3);
+  return run('ffmpeg', ['-y', '-ss', ss, '-i', mp4Path, '-frames:v', '1', outPath], {
+    timeout: 120_000,
+  });
+}
+
+async function recordAutoplay(root) {
+  const recordArgs = ['run', 'record:mp4', '--', '--out=validate/ring1', '--name=autoplay'];
+  const isWin = process.platform === 'win32';
+  const cmd = isWin ? 'npm.cmd' : 'npm';
+  return run(cmd, recordArgs, { cwd: root, timeout: 300_000 });
+}
+
+export async function runVisualRing1Gate(opts) {
+  const root = resolve(opts.root);
+  const mp4Rel = RING1_AUTOPLAY_MP4;
+  const mp4Path = join(root, mp4Rel);
+  const framesDir = join(root, RING1_FRAMES_DIR);
+  const problems = [];
+
+  await mkdir(join(root, 'validate/ring1'), { recursive: true });
+  await mkdir(framesDir, { recursive: true });
+
+  const record = await recordAutoplay(root);
+  if (!record.ok) {
+    problems.push(
+      `autoplay recording failed: ${(record.stderr || record.stdout || record.error || `exit ${record.status}`).split('\n').slice(-3).join(' ')}`,
+    );
+  }
+
+  if (!existsSync(mp4Path)) {
+    problems.push(`missing autoplay video: ${mp4Rel} — Ring 1 gate requires scripted autoplay MP4 artifact`);
+  } else {
+    const size = statSync(mp4Path).size;
+    if (size < MIN_MP4_BYTES) {
+      problems.push(`autoplay video too small (${size} bytes < ${MIN_MP4_BYTES}): ${mp4Rel}`);
+    }
+  }
+
+  const framePaths = [];
+  if (problems.length === 0) {
+    const duration = ffprobeDurationSeconds(mp4Path);
+    const positions = duration > 0 ? [0, duration * 0.5, Math.max(0, duration - 0.25)] : [0, 1, 2];
+    const names = ['01.png', '02.png', '03.png'];
+    for (let i = 0; i < names.length; i += 1) {
+      const outPath = join(framesDir, names[i]);
+      const extract = extractFrame(mp4Path, positions[i], outPath);
+      if (!extract.ok || !existsSync(outPath)) {
+        problems.push(`ffmpeg frame extract failed for ${names[i]}: ${extract.stderr.split('\n').slice(-2).join(' ')}`);
+      } else {
+        framePaths.push(`${RING1_FRAMES_DIR}/${names[i]}`);
+      }
+    }
+  }
+
+  let cvReport = null;
+  if (problems.length === 0) {
+    const py = run('python3', [
+      join(root, 'skills/playable-verify-ui/scripts/verify_ring1_visual.py'),
+      `--root=${root}`,
+      `--frames=${RING1_FRAMES_DIR}`,
+      '--json',
+    ], { cwd: root });
+    if (py.stdout.trim()) {
+      try {
+        cvReport = JSON.parse(py.stdout.trim());
+      } catch {
+        problems.push('verify_ring1_visual.py returned non-JSON output');
+      }
+    } else {
+      problems.push(`CV script failed: ${py.stderr.split('\n').slice(-3).join(' ')}`);
+    }
+    if (cvReport && !cvReport.ok) {
+      problems.push(...(cvReport.failures ?? []));
+    }
+  }
+
+  const ok = problems.length === 0 && cvReport?.ok === true;
+  const payload = {
+    ok,
+    problems,
+    autoplayMp4: mp4Rel,
+    frames: framePaths,
+    cv: cvReport,
+    recordExit: record.status,
+  };
+  await writeValidatorArtifact(root, 'visual', payload);
+
+  return { ok, problems, payload };
+}
+
+function printHuman(result) {
+  console.log(`[verify:visual-ring1] ${result.ok ? 'OK' : 'FAIL'}`);
+  if (result.payload.autoplayMp4) console.log(`  mp4: ${result.payload.autoplayMp4}`);
+  if (result.payload.frames?.length) console.log(`  frames: ${result.payload.frames.join(', ')}`);
+  for (const p of result.problems) console.log(`  ✗ ${p}`);
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  try {
+    const result = await runVisualRing1Gate(opts);
+    if (opts.json) {
+      console.log(JSON.stringify(result.payload, null, 2));
+    } else {
+      printHuman(result);
+    }
+    process.exit(result.ok ? 0 : 2);
+  } catch (err) {
+    console.error(`[verify:visual-ring1] ${err.message}`);
+    process.exit(1);
+  }
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main();
+}

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

@@ -0,0 +1,227 @@
+#!/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 { getActiveSlice, 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 = 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)
+    || getActiveSlice(state);
+  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();