hyper-animator-codex 0.7.1 → 0.8.1

package/skills/hyper-animator-codex/scripts/generate_subtitles.mjs

@@ -15,6 +15,7 @@ function requireValue(args, index, flag) {
 function parseArgs(args) {
   const parsed = {
     narration: undefined,
+    timing_manifest: undefined,
     output_dir: join(process.cwd(), "hyper-animator-output", "subtitles"),
     style: "default",
   };
@@ -30,6 +31,9 @@ function parseArgs(args) {
     } else if (arg === "--style") {
       parsed.style = requireValue(args, index, arg);
       index += 1;
+    } else if (arg === "--timing-manifest") {
+      parsed.timing_manifest = requireValue(args, index, arg);
+      index += 1;
     } else if (arg === "--help" || arg === "-h") {
       parsed.help = true;
     } else {
@@ -71,14 +75,43 @@ function roundTime(value) {
   return Number(value.toFixed(3));
 }
 
-function buildCues(narration) {
+function validateTimingManifest(manifest, narration) {
+  if (!manifest || typeof manifest !== "object" || !Array.isArray(manifest.scenes)) {
+    throw new Error("timing manifest must include scenes[]");
+  }
+  if (manifest.provider !== "minimax_cn") {
+    throw new Error("timing manifest provider must be minimax_cn");
+  }
+  if (manifest.scenes.length !== narration.scenes.length) {
+    throw new Error("timing manifest scene count must match narration scenes");
+  }
+
+  let expectedStart = 0;
+  manifest.scenes.forEach((scene, index) => {
+    if (!Number.isFinite(scene.start_seconds) || !Number.isFinite(scene.end_seconds)
+      || scene.start_seconds < 0 || scene.end_seconds <= scene.start_seconds) {
+      throw new Error(`timing manifest scenes[${index}] must have valid start_seconds/end_seconds`);
+    }
+    if (Math.abs(scene.start_seconds - expectedStart) > 0.001) {
+      throw new Error(`timing manifest scenes[${index}] must be contiguous`);
+    }
+    expectedStart = scene.end_seconds;
+  });
+}
+
+function buildCues(narration, timingManifest) {
   const cues = [];
   let cursor = 0;
 
   narration.scenes.forEach((scene, sceneIndex) => {
     const parts = splitNarration(scene.narration);
-    const duration = Number(scene.duration_estimate) || Math.max(parts.length * 2, 2);
+    const timing = timingManifest?.scenes?.[sceneIndex];
+    const sceneStart = timing?.start_seconds ?? cursor;
+    const duration = timing
+      ? timing.end_seconds - timing.start_seconds
+      : Number(scene.duration_estimate) || Math.max(parts.length * 2, 2);
     const cueDuration = duration / Math.max(parts.length, 1);
+    cursor = sceneStart;
 
     parts.forEach((text) => {
       const start = cursor;
@@ -124,8 +157,12 @@ async function generateSubtitles(options) {
 
   const narration = JSON.parse(await readFile(options.narration, "utf8"));
   validateNarration(narration);
+  const timingManifest = options.timing_manifest
+    ? JSON.parse(await readFile(options.timing_manifest, "utf8"))
+    : null;
+  if (timingManifest) validateTimingManifest(timingManifest, narration);
 
-  const cues = buildCues(narration);
+  const cues = buildCues(narration, timingManifest);
   await mkdir(options.output_dir, { recursive: true });
 
   const jsonPath = join(options.output_dir, "subtitles.json");
@@ -134,6 +171,7 @@ async function generateSubtitles(options) {
     ok: true,
     style: options.style,
     source: options.narration,
+    timing_source: options.timing_manifest ?? null,
     cues,
   };
 
@@ -153,6 +191,7 @@ function printHelp() {
 
 Options:
   --narration <file>    Narration JSON file
+  --timing-manifest <file>  MiniMax narration-manifest.json with exact scene timing
   --output-dir <dir>    Output directory, default hyper-animator-output/subtitles
   --style <name>        Subtitle style label for downstream HTML/render steps
 `);

package/skills/hyper-animator-codex/scripts/git_checkpoint.mjs

@@ -193,7 +193,7 @@ function parsePorcelainLine(line) {
 }
 
 function porcelainLines(pathspecs = []) {
-  const args = ["status", "--porcelain=v1", "--untracked-files=all"];
+  const args = ["-c", "core.quotePath=false", "status", "--porcelain=v1", "--untracked-files=all"];
 
   if (pathspecs.length > 0) {
     args.push("--", ...pathspecs);
@@ -230,7 +230,7 @@ function trackedOrUntrackedMatching(pathspecs) {
 }
 
 function stagedFiles() {
-  return git(["diff", "--cached", "--name-only", "--diff-filter=ACDMR"], { check: true }).stdout
+  return git(["-c", "core.quotePath=false", "diff", "--cached", "--name-only", "--diff-filter=ACDMR"], { check: true }).stdout
     .split("\n")
     .map((line) => line.trim())
     .filter(Boolean)

package/skills/hyper-animator-codex/scripts/minimax_runtime_config.mjs

@@ -1,8 +1,8 @@
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 
-export const DEFAULT_MINIMAX_MODEL = "music-2.6-free";
-export const TEXT_MUSIC_MODELS = new Set(["music-2.6", "music-2.6-free"]);
+export const DEFAULT_MINIMAX_MODEL = "music-2.6";
+export const TEXT_MUSIC_MODELS = new Set(["music-3.0", "music-2.6", "music-2.6-free"]);
 
 async function pathExists(path) {
   try {
@@ -61,7 +61,7 @@ export function validateMinimaxConfig(config = {}) {
   const model = normalized.model || DEFAULT_MINIMAX_MODEL;
 
   if (!TEXT_MUSIC_MODELS.has(model)) {
-    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-2.6 or music-2.6-free.`);
+    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-3.0, music-2.6, or music-2.6-free.`);
   }
 
   return {

package/skills/hyper-animator-codex/scripts/query_shotcraft.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const catalogPath = join(dirname(scriptDir), "references", "shotcraft", "catalog.json");
+
+function requireValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parseArgs(args) {
+  const parsed = { limit: 8, json: false, include_reference_only: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--query" || arg === "-q") {
+      parsed.query = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--limit") {
+      parsed.limit = Number.parseInt(requireValue(args, index, arg), 10);
+      index += 1;
+    } else if (arg === "--json") {
+      parsed.json = true;
+    } else if (arg === "--include-reference-only") {
+      parsed.include_reference_only = true;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  return parsed;
+}
+
+function tokens(value) {
+  return String(value)
+    .toLowerCase()
+    .split(/[\s,，。:：;；/|()[\]{}"'`_-]+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+}
+
+function scoreText(queryTokens, fields) {
+  const haystack = fields.filter(Boolean).join("\n").toLowerCase();
+  return queryTokens.reduce((score, token) => {
+    if (!haystack.includes(token)) return score;
+    const exactWord = new RegExp(`(^|[^a-z0-9])${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^a-z0-9]|$)`, "i");
+    return score + (exactWord.test(haystack) ? 4 : 2);
+  }, 0);
+}
+
+function rankCard(card, queryTokens, includeReferenceOnly) {
+  const eligibleStyles = card.styles.filter((style) => (
+    includeReferenceOnly || style.implementation_status === "implemented"
+  ));
+  if (eligibleStyles.length === 0) return null;
+
+  const styleScores = eligibleStyles.map((style) => ({
+    style,
+    score: scoreText(queryTokens, [
+      style.key,
+      style.label,
+      style.description,
+      style.use,
+    ]),
+  })).sort((left, right) => right.score - left.score || left.style.key.localeCompare(right.style.key));
+
+  const cardScore = scoreText(queryTokens, [
+    card.name,
+    card.summary,
+    card.use,
+    card.energy,
+    card.intention,
+  ]);
+  const bestStyle = styleScores[0];
+  const slugBonus = queryTokens.some((token) => card.name.includes(token)) ? 3 : 0;
+  return {
+    score: cardScore + bestStyle.score + slugBonus,
+    card: card.name,
+    summary: card.summary,
+    use: card.use,
+    duration: card.duration,
+    energy: card.energy,
+    code_status: card.code_status,
+    style: bestStyle.style.key,
+    implementation_status: bestStyle.style.implementation_status,
+    usage_document: bestStyle.style.usage_document || card.usage_document,
+    source_files: bestStyle.style.source_files,
+  };
+}
+
+function printHuman(results) {
+  for (const [index, result] of results.entries()) {
+    console.log(`${index + 1}. ${result.card} / ${result.style} (score ${result.score})`);
+    console.log(`   ${result.summary}`);
+    console.log(`   use: ${result.use}`);
+    console.log(`   source: ${result.source_files.join(", ")}`);
+  }
+}
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log("Usage: query_shotcraft.mjs --query <text> [--limit 8] [--json] [--include-reference-only]");
+      return;
+    }
+    if (!args.query?.trim()) throw new Error("--query is required");
+    if (!Number.isInteger(args.limit) || args.limit < 1 || args.limit > 50) {
+      throw new Error("--limit must be an integer from 1 to 50");
+    }
+
+    const catalog = JSON.parse(await readFile(catalogPath, "utf8"));
+    const queryTokens = tokens(args.query);
+    const results = catalog.cards
+      .map((card) => rankCard(card, queryTokens, args.include_reference_only))
+      .filter((result) => result && result.score > 0)
+      .sort((left, right) => right.score - left.score || left.card.localeCompare(right.card))
+      .slice(0, args.limit);
+
+    if (args.json) {
+      console.log(JSON.stringify({
+        ok: true,
+        query: args.query,
+        source_revision: catalog.source_revision,
+        results,
+      }, null, 2));
+    } else {
+      printHuman(results);
+    }
+  } catch (error) {
+    console.log(JSON.stringify({ ok: false, error: error.message }, null, 2));
+    process.exitCode = 1;
+  }
+}
+
+main();

package/skills/hyper-animator-codex/scripts/validate_hyperframes_html.py

@@ -13,6 +13,20 @@ def has_attr(html: str, name: str) -> bool:
     return re.search(rf"\b{name}\s*=\s*['\"]?[^'\"\s>]+", html, re.IGNORECASE) is not None
 
 
+def numeric_attr(html: str, name: str) -> float | None:
+    match = re.search(
+        rf"\b{name}\s*=\s*(?:['\"]([^'\"]+)['\"]|([^\s>]+))",
+        html,
+        re.IGNORECASE,
+    )
+    if not match:
+        return None
+    try:
+        return float(match.group(1) or match.group(2))
+    except ValueError:
+        return None
+
+
 def check_html(
     html: str,
     *,
@@ -26,6 +40,11 @@ def check_html(
         for attr in ("data-width", "data-height", "data-duration", "data-composition-id"):
             if not has_attr(html, attr):
                 failures.append(f"missing {attr}")
+        for attr in ("data-width", "data-height", "data-duration"):
+            if has_attr(html, attr):
+                value = numeric_attr(html, attr)
+                if value is None or value <= 0:
+                    failures.append(f"{attr} must be a positive number")
 
     if "<!-- paste from " in html:
         failures.append("unresolved component paste placeholder")
@@ -47,6 +66,9 @@ def check_html(
     if re.search(r"\bsetInterval\s*\(", html):
         failures.append("uses setInterval(); primary render progress must be timeline-driven")
 
+    if re.search(r"\bMath\s*\.\s*random\s*\(", html):
+        failures.append("uses Math.random(); visual generation must use a fixed-seed deterministic PRNG")
+
     if re.search(r"\brequestAnimationFrame\s*\(", html) and "fallback" not in html.lower():
         warnings.append("requestAnimationFrame found; ensure it is not the primary render clock and has render fallback")
 

package/skills/hyper-animator-codex/scripts/validate_provider_policy.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const policyPath = join(dirname(scriptDir), "contracts", "workflow-policy.json");
+
+function requireValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parseArgs(args) {
+  const parsed = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (["--kind", "--provider", "--endpoint"].includes(arg)) {
+      parsed[arg.slice(2)] = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  return parsed;
+}
+
+function output(payload, exitCode = 0) {
+  console.log(JSON.stringify(payload, null, 2));
+  process.exitCode = exitCode;
+}
+
+function reject(code, message, details = {}) {
+  output({ ok: false, error: { code, message, ...details } }, 1);
+}
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log("Usage: validate_provider_policy.mjs --kind <narration|bgm> --provider <name> --endpoint <url>");
+      return;
+    }
+
+    if (!["narration", "bgm"].includes(args.kind)) {
+      reject("invalid_kind", "--kind must be narration or bgm");
+      return;
+    }
+    if (!args.provider) {
+      reject("missing_provider", "--provider is required");
+      return;
+    }
+    if (!args.endpoint || !URL.canParse(args.endpoint)) {
+      reject("invalid_endpoint", "--endpoint must be a valid URL");
+      return;
+    }
+
+    const policy = JSON.parse(await readFile(policyPath, "utf8"));
+    const normalizedProvider = args.provider.trim().toLowerCase();
+    if (policy.audio.forbidden_providers.includes(normalizedProvider)) {
+      reject("forbidden_provider", `${args.provider} is forbidden by the generated-audio policy`, {
+        provider: normalizedProvider,
+      });
+      return;
+    }
+
+    const route = args.kind === "narration"
+      ? policy.audio.generated_narration
+      : policy.audio.generated_bgm;
+    if (normalizedProvider !== route.provider) {
+      reject("provider_mismatch", `${args.kind} generation requires provider ${route.provider}`, {
+        expected: route.provider,
+        actual: normalizedProvider,
+      });
+      return;
+    }
+
+    const actual = new URL(args.endpoint);
+    const expected = new URL(route.endpoint);
+    const allowedEndpoints = [route.endpoint, ...(route.backup_endpoints || [])]
+      .map((endpoint) => new URL(endpoint));
+    if (!allowedEndpoints.some((allowed) => (
+      actual.origin === allowed.origin && actual.pathname === allowed.pathname
+    ))) {
+      reject("endpoint_mismatch", `${args.kind} generation requires the MiniMax mainland endpoint`, {
+        expected: route.endpoint,
+        actual: args.endpoint,
+      });
+      return;
+    }
+
+    output({
+      ok: true,
+      kind: args.kind,
+      provider: route.provider,
+      endpoint: args.endpoint,
+      primary_endpoint: route.endpoint,
+      region: "cn",
+    });
+  } catch (error) {
+    reject("validation", error.message);
+  }
+}
+
+main();

package/skills/hyper-animator-codex/scripts/validate_shot_plan.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const skillRoot = dirname(scriptDir);
+const WORKFLOW_STAGES = new Set(["visual_draft", "audio_integrated", "render_ready"]);
+const AUDIO_MODES = new Set(["generated", "user_local_file", "none", "deferred"]);
+const ENERGY_LEVELS = new Set(["quiet", "balanced", "high", "cinematic"]);
+const MOTION_PRESETS = new Set([
+  "none",
+  "slam-entrance",
+  "whip-transition",
+  "crash-zoom",
+  "push-stack-wipe",
+  "dataviz-landscape-open",
+  "panel-grid-reflow",
+  "brand-resolve",
+]);
+const SHOTCRAFT_MOTION_PRESETS = new Map([
+  ["slam-entrance-moves", "slam-entrance"],
+  ["shot-transitions", "whip-transition"],
+  ["crash-zoom-punch", "crash-zoom"],
+  ["bottom-push-stack-wipe", "push-stack-wipe"],
+  ["dataviz-landscape-open", "dataviz-landscape-open"],
+  ["panel-grid-moves", "panel-grid-reflow"],
+  ["ui-to-brand-morph", "brand-resolve"],
+]);
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateAudioTrack(track, label, errors) {
+  if (!isObject(track)) {
+    errors.push(`audio.${label} must be an object`);
+    return;
+  }
+
+  if (!AUDIO_MODES.has(track.mode)) {
+    errors.push(`audio.${label}.mode must be generated, user_local_file, none, or deferred`);
+  }
+  if (track.mode === "generated" && track.provider !== "minimax_cn") {
+    errors.push(`audio.${label}.provider must be minimax_cn when mode is generated`);
+  }
+  if (track.mode === "user_local_file" && (typeof track.path !== "string" || !track.path.trim())) {
+    errors.push(`audio.${label}.path is required when mode is user_local_file`);
+  }
+  if ((track.mode === "none" || track.mode === "deferred") && track.provider !== undefined) {
+    errors.push(`audio.${label}.provider must be omitted when mode is ${track.mode}`);
+  }
+  if ((track.mode === "none" || track.mode === "deferred") && track.path !== undefined) {
+    errors.push(`audio.${label}.path must be omitted when mode is ${track.mode}`);
+  }
+}
+
+function validateMotionContract(contract, label, shotcraftRefs, errors) {
+  if (!isObject(contract)) {
+    errors.push(`${label}.motion_contract is required`);
+    return;
+  }
+
+  if (!MOTION_PRESETS.has(contract.motion_preset)) {
+    errors.push(`${label}.motion_contract.motion_preset must be one of ${[...MOTION_PRESETS].join(", ")}`);
+  }
+  const expectedPresets = shotcraftRefs
+    .map((reference) => SHOTCRAFT_MOTION_PRESETS.get(reference))
+    .filter(Boolean);
+  if (expectedPresets.length > 0 && !expectedPresets.includes(contract.motion_preset)) {
+    errors.push(`${label}.motion_contract.motion_preset must use ${expectedPresets.join(" or ")} for selected ShotCraft refs`);
+  }
+  if (!ENERGY_LEVELS.has(contract.energy)) {
+    errors.push(`${label}.motion_contract.energy must be quiet, balanced, high, or cinematic`);
+  }
+  for (const field of ["camera", "transition"]) {
+    if (typeof contract[field] !== "string" || !contract[field].trim()) {
+      errors.push(`${label}.motion_contract.${field} is required`);
+    }
+  }
+  if (!Array.isArray(contract.shotcraft_commitments) || contract.shotcraft_commitments.length === 0) {
+    errors.push(`${label}.motion_contract.shotcraft_commitments must contain at least one item`);
+  } else {
+    contract.shotcraft_commitments.forEach((commitment, index) => {
+      if (typeof commitment !== "string" || !commitment.trim()) {
+        errors.push(`${label}.motion_contract.shotcraft_commitments[${index}] must be a non-empty string`);
+      }
+    });
+  }
+  if (!Number.isFinite(contract.readable_rest_seconds) || contract.readable_rest_seconds < 0) {
+    errors.push(`${label}.motion_contract.readable_rest_seconds must be zero or greater`);
+  }
+}
+
+function validateShotPlan(plan, catalogs) {
+  const errors = [];
+
+  if (!isObject(plan)) return ["plan must be a JSON object"];
+  if (plan.schema_version !== "1.0.0") errors.push("schema_version must be 1.0.0");
+  if (!WORKFLOW_STAGES.has(plan.workflow_stage)) {
+    errors.push("workflow_stage must be visual_draft, audio_integrated, or render_ready");
+  }
+  if (!["assemble_existing_catalog_items", "generate_new_hyperframes_html"].includes(plan.generation_mode)) {
+    errors.push("generation_mode is invalid");
+  }
+  if (plan.catalog_strategy !== "dual_catalog") errors.push("catalog_strategy must be dual_catalog");
+
+  if (!isObject(plan.dimensions)
+    || !Number.isInteger(plan.dimensions.width)
+    || !Number.isInteger(plan.dimensions.height)
+    || plan.dimensions.width <= 0
+    || plan.dimensions.height <= 0) {
+    errors.push("dimensions.width and dimensions.height must be positive integers");
+  }
+  if (!Number.isFinite(plan.duration_seconds) || plan.duration_seconds <= 0) {
+    errors.push("duration_seconds must be a positive number");
+  }
+
+  if (!isObject(plan.audio)) {
+    errors.push("audio must be an object");
+  } else {
+    validateAudioTrack(plan.audio.narration, "narration", errors);
+    validateAudioTrack(plan.audio.bgm, "bgm", errors);
+    if (plan.workflow_stage === "visual_draft" && plan.audio.narration?.mode === "generated") {
+      errors.push("audio.narration must not be generated before visual confirmation");
+    }
+    if (plan.workflow_stage !== "visual_draft" && plan.audio.narration?.mode === "deferred") {
+      errors.push("audio.narration.mode cannot stay deferred after visual confirmation");
+    }
+  }
+
+  if (!isObject(plan.model_routing)) {
+    errors.push("model_routing must be an object");
+  } else {
+    if (plan.model_routing.page_animation_authoring !== "gpt-5.6-sol") {
+      errors.push("model_routing.page_animation_authoring must be gpt-5.6-sol");
+    }
+    if (!plan.model_routing.planning_and_validation) {
+      errors.push("model_routing.planning_and_validation is required");
+    } else if (plan.model_routing.planning_and_validation === "gpt-5.6-sol") {
+      errors.push("model_routing.planning_and_validation must not use gpt-5.6-sol");
+    }
+  }
+
+  if (!Array.isArray(plan.shots) || plan.shots.length === 0) {
+    errors.push("shots must contain at least one shot");
+    return errors;
+  }
+
+  const ids = new Set();
+  plan.shots.forEach((shot, index) => {
+    const label = `shots[${index}]`;
+    if (!isObject(shot)) {
+      errors.push(`${label} must be an object`);
+      return;
+    }
+    if (typeof shot.id !== "string" || !/^[a-z][a-z0-9-]*$/.test(shot.id)) {
+      errors.push(`${label}.id must be a kebab-case identifier`);
+    } else if (ids.has(shot.id)) {
+      errors.push(`${label}.id must be unique`);
+    } else {
+      ids.add(shot.id);
+    }
+    if (!Number.isFinite(shot.start_seconds) || shot.start_seconds < 0) {
+      errors.push(`${label}.start_seconds must be zero or greater`);
+    }
+    if (!Number.isFinite(shot.end_seconds) || shot.end_seconds <= shot.start_seconds) {
+      errors.push(`${label}.end_seconds must be greater than start_seconds`);
+    }
+    if (typeof shot.purpose !== "string" || !shot.purpose.trim()) {
+      errors.push(`${label}.purpose is required`);
+    }
+    if (!Array.isArray(shot.hyperframes_refs)) {
+      errors.push(`${label}.hyperframes_refs must be an array`);
+    } else {
+      if (shot.hyperframes_refs.length === 0) {
+        errors.push(`${label}.hyperframes_refs must contain at least one HyperFrames reference`);
+      }
+      for (const reference of shot.hyperframes_refs) {
+        if (!catalogs.hyperframes.has(reference)) {
+          errors.push(`${label} has unknown HyperFrames reference: ${reference}`);
+        }
+      }
+    }
+    if (!Array.isArray(shot.shotcraft_refs)) {
+      errors.push(`${label}.shotcraft_refs must be an array`);
+    } else {
+      if (shot.shotcraft_refs.length === 0) {
+        errors.push(`${label}.shotcraft_refs must contain at least one ShotCraft reference`);
+      }
+      for (const reference of shot.shotcraft_refs) {
+        if (!catalogs.shotcraft.has(reference)) {
+          errors.push(`${label} has unknown ShotCraft reference: ${reference}`);
+        }
+      }
+    }
+    validateMotionContract(shot.motion_contract, label, Array.isArray(shot.shotcraft_refs) ? shot.shotcraft_refs : [], errors);
+
+    if (index === 0 && shot.start_seconds !== 0) {
+      errors.push("shots must start at 0 seconds");
+    }
+    if (index > 0 && Number.isFinite(shot.start_seconds)) {
+      const previous = plan.shots[index - 1];
+      if (Number.isFinite(previous?.end_seconds) && Math.abs(shot.start_seconds - previous.end_seconds) > 0.001) {
+        errors.push(`shots must be contiguous: ${label}.start_seconds must equal shots[${index - 1}].end_seconds`);
+      }
+    }
+  });
+
+  const lastEnd = plan.shots.at(-1)?.end_seconds;
+  if (Number.isFinite(lastEnd)
+    && Number.isFinite(plan.duration_seconds)
+    && Math.abs(lastEnd - plan.duration_seconds) > 0.001) {
+    errors.push("last shot end_seconds must equal duration_seconds");
+  }
+
+  return errors;
+}
+
+function output(payload, code = 0) {
+  console.log(JSON.stringify(payload, null, 2));
+  process.exitCode = code;
+}
+
+async function main() {
+  try {
+    const path = process.argv[2];
+    if (!path || path === "--help" || path === "-h") {
+      console.log("Usage: validate_shot_plan.mjs <shot-plan.json>");
+      process.exitCode = path ? 0 : 1;
+      return;
+    }
+    const plan = JSON.parse(await readFile(path, "utf8"));
+    const hyperframesCatalog = JSON.parse(await readFile(
+      join(skillRoot, "references", "hyperframes-catalog-map.json"),
+      "utf8",
+    ));
+    const shotcraftCatalog = JSON.parse(await readFile(
+      join(skillRoot, "references", "shotcraft", "catalog.json"),
+      "utf8",
+    ));
+    const catalogs = {
+      hyperframes: new Set(hyperframesCatalog.items.map((item) => item.id)),
+      shotcraft: new Set(shotcraftCatalog.cards.flatMap((card) => [
+        card.name,
+        ...card.styles.map((style) => style.key),
+      ])),
+    };
+    const errors = validateShotPlan(plan, catalogs);
+    if (errors.length > 0) {
+      output({ ok: false, path, errors }, 1);
+      return;
+    }
+    output({
+      ok: true,
+      path,
+      shot_count: plan.shots.length,
+      duration_seconds: plan.duration_seconds,
+      catalog_strategy: plan.catalog_strategy,
+    });
+  } catch (error) {
+    output({ ok: false, errors: [error.message] }, 1);
+  }
+}
+
+main();