@revola-ai/video-craft 0.2.1

package/src/sourceCitations.ts

@@ -0,0 +1,217 @@
+/**
+ * Citations carried in SOURCE COMMENTS, extracted so they can be checked.
+ *
+ * This codebase cites heavily and on purpose: a comment names the bd issue that
+ * motivated the code, or the design doc that settled it, so a reader can get to
+ * the reasoning instead of re-deriving it. A manual sweep before this guard
+ * existed found no typos in any of them - the discipline is real, and this only
+ * has to keep it that way.
+ *
+ * On the numbers in this file: none of them counts the CURRENT corpus. A census
+ * ("this repo has N citations") is a derived number that goes stale on the next
+ * commit, and CLAUDE.md's Comments section tells everyone else not to write one
+ * - an earlier version of this file shipped three that were wrong. What remains
+ * is the other thing that section asks for: a record of what a past defect
+ * cost, which is fixed once it has happened and is the number that stops the
+ * next person undoing the fix.
+ *
+ * Nothing checked any of it. `drift.test.ts`, `anchors.test.ts` and
+ * `learnedFrom.test.ts` already guard the equivalent references in RULE prose;
+ * source comments were the uncovered case, and the 2026-08-25 extraction left
+ * ten doc citations dangling before anyone noticed.
+ *
+ * Pure: the callers read the files.
+ */
+
+import { ts } from "ts-morph";
+
+/**
+ * The parser to read a file with, from its name.
+ *
+ * This is not a detail. TSX cannot parse the generic arrow `<T>(x) => x`, which
+ * is ordinary TypeScript, and the parser does not throw on it - it recovers by
+ * reading `<T>` as an unterminated JSX element and loses most, though not all,
+ * of the comments after that point. Parsing everything as TSX cost four real
+ * files in this repo between 12% and 49% of their comment text, and hid a live
+ * `remotion-videos-b4pq` citation from the guard entirely.
+ *
+ * That is the same failure the hand-rolled scanner had (a stray opener eating
+ * the rest of the file), reintroduced one layer down, in the fix for it.
+ *
+ * NOTE ON THE PARSER VERSION. `ts` here is whatever TypeScript ts-morph bundles,
+ * which is NOT the version the repo compiles with - today 5.6.2 against a 5.9.3
+ * tsc. Since a parse diagnostic now throws, syntax newer than the bundled
+ * parser hard-fails this guard even though `npm run typecheck` accepts it. If
+ * that ever bites, bump ts-morph rather than softening the throw: silently
+ * reading fewer comments is the failure this module exists to prevent.
+ */
+function scriptKindFor(fileName: string): ts.ScriptKind {
+  if (fileName.endsWith(".tsx")) return ts.ScriptKind.TSX;
+  if (fileName.endsWith(".jsx")) return ts.ScriptKind.JSX;
+  if (/\.(?:m|c)?js$/.test(fileName)) return ts.ScriptKind.JS;
+  return ts.ScriptKind.TS;
+}
+
+/**
+ * Just the comment text of a JS/TS source file.
+ *
+ * PARSED, not scanned. Two hand-rolled heuristics were tried first and both
+ * were wrong in the same direction - a comment opener inside a literal:
+ *
+ *   - naive: `joinShell.test.ts:1838` writes a gitignore glob whose `/*`
+ *     opened a block comment that never closed and swallowed the 600 lines
+ *     after it;
+ *   - "opener must follow whitespace or a delimiter": `costShell.ts:115`
+ *     interpolates a `/*.json` glob where the `/` follows a `}` - legal by that
+ *     rule - and reopened the same hole.
+ *
+ * Both put string literals back in citation scope and produced false failures.
+ * A third patch would have been a third hole, so this uses the real TypeScript
+ * parser, which ts-morph already brings in as a dependency of this package.
+ *
+ * `fileName` is REQUIRED because two things depend on it: the parser choice
+ * (see scriptKindFor - defaulting it cost a live citation) and the error below,
+ * which is raised at the caller's module scope where the path is the only clue
+ * a reader gets.
+ *
+ * THROWS on a parse error rather than returning what it managed to read. A file
+ * the parser cannot read is a file this module cannot vouch for, and returning
+ * partial comments is precisely the "reports clean while covering less than it
+ * claims" failure the whole module exists to prevent.
+ */
+export function commentsOnly(text: string, fileName: string): string {
+  const source = ts.createSourceFile(
+    fileName, text, ts.ScriptTarget.Latest, /* setParentNodes */ false, scriptKindFor(fileName));
+  const diagnostics =
+    (source as unknown as { parseDiagnostics?: readonly ts.DiagnosticWithLocation[] })
+      .parseDiagnostics ?? [];
+  const first = diagnostics[0];
+  if (first) {
+    const { line } = source.getLineAndCharacterOfPosition(first.start);
+    throw new Error(
+      `${fileName}:${line + 1} cannot be parsed as ${ts.ScriptKind[scriptKindFor(fileName)]}: ` +
+      `${ts.flattenDiagnosticMessageText(first.messageText, " ")}. The citation guard reads ` +
+      "comments by parsing, so an unparseable file would be scanned as if it had none.");
+  }
+
+  const ranges: ts.CommentRange[] = [];
+  const jsxText: ts.TextRange[] = [];
+  const seen = new Set<number>();
+  const take = (pos: number): void => {
+    for (const range of [
+      ...(ts.getLeadingCommentRanges(text, pos) ?? []),
+      ...(ts.getTrailingCommentRanges(text, pos) ?? []),
+    ]) {
+      if (seen.has(range.pos)) continue;
+      seen.add(range.pos);
+      ranges.push(range);
+    }
+  };
+  // getChildren, NOT forEachChild. forEachChild yields only syntactic children
+  // and never the punctuation tokens, so a comment in the leading trivia of a
+  // closing `}` / `]` / `)` was invisible - the last comment in a function
+  // body, an object literal, or a switch case, and every `{/* ... */}` in JSX,
+  // which is the only comment form JSX children have. 229 comments across the
+  // scanned tree were unreachable that way.
+  const walk = (node: ts.Node): void => {
+    if (node.kind === ts.SyntaxKind.JsxText) jsxText.push({ pos: node.pos, end: node.end });
+    take(node.pos);
+    for (const child of node.getChildren(source)) walk(child);
+  };
+  walk(source);
+
+  // JSX TEXT IS DATA, NOT CODE - the same rule as a string literal, and the
+  // third appearance of the same bug. `<div>/* x */</div>` renders those
+  // characters; they are not a comment. But the JSX children SyntaxList begins
+  // at the first character of the text run, so getLeading/TrailingCommentRanges
+  // reads an opener there and hands back "a comment". An unterminated `/*` in
+  // rendered text then swallows the file to EOF and puts every string literal
+  // below back in citation scope - exactly what the gitignore glob did to
+  // joinShell.test.ts before any of this was parsed rather than scanned.
+  //
+  // Dropping ranges that START inside a JsxText run is enough: a real
+  // `{/* ... */}` lives in a JsxExpression, never in JsxText, so it survives.
+  return ranges
+    .filter((r) => !jsxText.some((j) => r.pos >= j.pos && r.pos < j.end))
+    .map((r) => text.slice(r.pos, r.end))
+    .join("\n");
+}
+
+/** Punctuation a citation collects from the prose it sits in. */
+const TRAILING = /[.,;:!?)\]}`'"]+$/;
+
+/** Extensions a doc citation may end in. A path ending in none of these, and
+ *  not in a `/`, is a fragment - a wrapped comment line, or a path built at
+ *  runtime - not a resolvable file. */
+const DOC_EXTENSIONS = [".md", ".json", ".yaml", ".yml", ".txt"];
+
+/**
+ * A repo-root doc citation.
+ *
+ * The LEFT BOUNDARY is the load-bearing part. Without it `docs/` matches
+ * anywhere inside a longer path, which goes wrong in two directions at once:
+ *
+ *   - `https://remotion.dev/docs/lambda/bucket-security` yields
+ *     `docs/lambda/bucket-security` - a URL read as a local file. This is the
+ *     shape that actually occurs in this repo's comments;
+ *   - `qse-qguard-video/docs/motion-brand-spec.md` yields
+ *     `docs/motion-brand-spec.md`, a path that does not exist at the repo root.
+ *     This form appears inside the scanned trees in string literals - rule
+ *     `recordedIn:` fields and their test assertions - so it reaches the
+ *     extractor whenever a comment quotes one, and the anchor is what stops
+ *     that becoming a false failure.
+ *
+ * An earlier version required a subdirectory (`docs/<seg>/<rest>`), which
+ * masked both cases by accident - and silently dropped every single-segment
+ * citation the repo has, `docs/accounting.md` among them. Anchoring left is
+ * what lets the pattern accept those safely.
+ */
+const DOC_PATTERN = /(?<![\w/.-])docs\/[A-Za-z0-9._/*-]+/g;
+
+/**
+ * Doc paths cited in `text`, de-duplicated, in first-seen order.
+ *
+ * Accepts a trailing-slash directory (`docs/superpowers/`), which the prose
+ * convention uses and which resolves like any other path.
+ *
+ * Rejects two shapes that are NOT broken citations:
+ *   - a path split across two comment lines, which ends mid-token. This one
+ *     fires on real comments here;
+ *   - a runtime glob (`docs/headless/phase-*.md`) - never a single file. This
+ *     one is defensive today: the only such path in the tree is written
+ *     project-relative, so the left anchor rejects it before the glob branch
+ *     is reached. Keep it anyway - a repo-root glob is one comment away.
+ * Flagging either would train readers to ignore the check, which is worse than
+ * not having it. Both rejections are silent, which can hide a typo in the
+ * wrapped half of a long path (video-toolchain-2gw).
+ */
+export function extractDocCitations(text: string): string[] {
+  const out: string[] = [];
+  for (const raw of text.match(DOC_PATTERN) ?? []) {
+    const path = raw.replace(TRAILING, "");
+    if (path.includes("*")) continue;
+    const resolvable = path.endsWith("/") || DOC_EXTENSIONS.some((e) => path.endsWith(e));
+    if (!resolvable) continue;
+    if (!out.includes(path)) out.push(path);
+  }
+  return out;
+}
+
+/** The two bd id families this repo's comments cite. `remotion-videos-` ids are
+ *  kept on purpose after the extraction - source cites them by name. */
+const ISSUE_PATTERN = /\b(?:remotion-videos|video-toolchain)-[a-z0-9]{3,4}\b/g;
+
+/**
+ * bd issue ids cited in `text`, de-duplicated and sorted.
+ *
+ * The trailing `\b` is what stops `remotion-videos-abcdefg` (not an id) from
+ * matching its own first four characters. The bare repo name is excluded by the
+ * required `-[a-z0-9]{3,4}` suffix instead - there is nothing after it to bound
+ * - so loosening that suffix rule would start matching prose.
+ *
+ * A child id (`...-5ky3.1`) resolves to its parent, which is the record that
+ * has to exist.
+ */
+export function extractIssueCitations(text: string): string[] {
+  return [...new Set(text.match(ISSUE_PATTERN) ?? [])].sort();
+}

package/src/stageProjection.ts

@@ -0,0 +1,112 @@
+import { ALL_STAGES } from "./stages";
+import type { Rule, Stage } from "./types";
+
+/** Waiver lines, duplicated in shape from projectDoc's exceptionLines: a
+ *  stage sheet inside a waived project must carry the waiver too, or a
+ *  dispatched agent "fixes" the client's decision back out. */
+const exceptionLines = (r: Rule): string[] =>
+  (r.exceptions ?? []).map(
+    (ex) => `  - waived in \`${ex.project}\`: ${ex.decision} (recorded: \`${ex.recordedIn}\`)`,
+  );
+
+/**
+ * One stage's rule sheet: the markdown a dispatched agent for that stage
+ * reads instead of the full registry. Same tier ORDER as the CLAUDE.md
+ * projection - gates first, with their verify lines - but NOT the same
+ * shape, and deliberately so: a sheet carries every in-scope rule's full
+ * claim, where CLAUDE.md compacts unwaived craft and process rules to an id
+ * index (video-toolchain-cg6). CLAUDE.md can compact because it is a
+ * navigation surface for a session that can go read HOW_I_BUILD_VIDEOS.md;
+ * a sheet is inlined into a dispatched worker's prompt, which cannot. Do
+ * not "restore symmetry" by compacting sheets - that removes the fallback
+ * the CLAUDE.md compaction depends on.
+ */
+export function renderStageSheet(
+  rules: Rule[],
+  stages: Record<string, Stage[]>,
+  stage: Stage,
+): string {
+  const mine = rules
+    .filter((r) => r.scope.kind === "pipeline" && (stages[r.id] ?? []).includes(stage))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const of = (tier: Rule["tier"]) => mine.filter((r) => r.tier === tier);
+  const section = (heading: string, rs: Rule[], withVerify: boolean) =>
+    rs.length === 0
+      ? []
+      : [
+          heading,
+          ``,
+          ...rs.map((r) =>
+            [
+              `- ${r.claim} (\`${r.id}\`)`,
+              ...(withVerify && r.verify ? [`  - verify: ${r.verify}`] : []),
+              ...exceptionLines(r),
+            ].join("\n"),
+          ),
+          ``,
+        ];
+
+  return [
+    `<!-- Generated from packages/video-craft/src/rules/ + stages.ts. Do not edit. -->`,
+    ``,
+    `# Rules for the ${stage} stage`,
+    ``,
+    `These are the registry rules scoped to ${stage}-stage agents. Scoping narrows attention, never authority: every rule in the registry still applies to you. This sheet carries the full claim of each rule in scope; HOW_I_BUILD_VIDEOS.md carries every rule's claim, why and provenance, and is where to read one you meet only as an id (search for it in a \`Rule id:\` line). CLAUDE.md lists the out-of-scope rules by id rather than in full, so do not treat it as the place to go for a claim.`,
+    ``,
+    ...section(`## Gates - settled by running the check, not by reading the diff`, of("gate"), true),
+    ...section(`## Craft rules`, of("craft"), false),
+    ...section(`## Process rules`, of("process"), false),
+  ]
+    .join("\n")
+    .trimEnd();
+}
+
+/** Extracts the text between `<!-- edge:begin NAME -->` / `<!-- edge:end NAME -->`
+ *  in docs/style/CREATIVE_EDGE.md. Throws on a missing marker: a renamed or
+ *  deleted marker must fail generation, not silently ship an empty digest. */
+export function extractEdgeSection(doc: string, name: string): string {
+  const begin = `<!-- edge:begin ${name} -->`;
+  const end = `<!-- edge:end ${name} -->`;
+  const from = doc.indexOf(begin);
+  if (from === -1) throw new Error(`marker "edge:begin ${name}" not found in CREATIVE_EDGE.md`);
+  // A duplicated marker (paste error, the marker syntax quoted in prose)
+  // would silently select the wrong span; only absence is louder than that.
+  if (doc.indexOf(begin, from + begin.length) !== -1) {
+    throw new Error(`marker "edge:begin ${name}" appears more than once in CREATIVE_EDGE.md`);
+  }
+  const to = doc.indexOf(end, from);
+  if (to === -1) throw new Error(`marker "edge:end ${name}" not found in CREATIVE_EDGE.md`);
+  if (doc.indexOf(end, to + end.length) !== -1) {
+    throw new Error(`marker "edge:end ${name}" appears more than once in CREATIVE_EDGE.md`);
+  }
+  return doc.slice(from + begin.length, to).trim();
+}
+
+/**
+ * The generated artifact crossing the craft -> cli boundary (same mechanism
+ * and direction as waivers.generated.json): per-stage sheets plus the
+ * CREATIVE_EDGE digest the dispatch shell inlines for scene/amplify/review
+ * nodes. Stable key order so regeneration is byte-deterministic.
+ */
+export function renderRuleSheetsJson(
+  rules: Rule[],
+  stages: Record<string, Stage[]>,
+  creativeEdgeDoc: string,
+): string {
+  const sheets: Record<string, string> = {};
+  for (const stage of ALL_STAGES) {
+    sheets[stage] = renderStageSheet(rules, stages, stage);
+  }
+  return `${JSON.stringify(
+    {
+      stages: sheets,
+      creativeEdge: {
+        bar: extractEdgeSection(creativeEdgeDoc, "bar"),
+        checklist: extractEdgeSection(creativeEdgeDoc, "checklist"),
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}

package/src/stages.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "vitest";
+import { RULES } from "./registry";
+import { ALL_STAGES, STAGES, validateStages } from "./stages";
+import type { Rule, Stage } from "./types";
+
+const rule = (id: string, tier: Rule["tier"]): Rule => ({
+  id,
+  claim: "c",
+  why: "w",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier,
+  ...(tier === "gate" ? { verify: "v" } : {}),
+  scope: { kind: "pipeline" },
+  enforcement: { kind: "prose", unanchorable: "u" },
+});
+
+describe("validateStages", () => {
+  test("flags a pipeline rule with no stage entry", () => {
+    const errors = validateStages([rule("lonely-rule", "craft")], {});
+    expect(errors.some((e) => e.includes("lonely-rule"))).toBe(true);
+  });
+
+  test("flags an empty stage list", () => {
+    const errors = validateStages([rule("empty-rule", "craft")], { "empty-rule": [] });
+    expect(errors.some((e) => e.includes("empty-rule"))).toBe(true);
+  });
+
+  test("flags a stage entry for an id no pipeline rule carries", () => {
+    const errors = validateStages([], { "ghost-rule": ["scene"] });
+    expect(errors.some((e) => e.includes("ghost-rule"))).toBe(true);
+  });
+
+  test("flags a gate that carries neither review nor ship", () => {
+    const errors = validateStages([rule("author-only-gate", "gate")], {
+      "author-only-gate": ["scene"],
+    });
+    expect(errors.some((e) => e.includes("author-only-gate"))).toBe(true);
+  });
+
+  test("accepts a gate verified at review", () => {
+    expect(validateStages([rule("ok-gate", "gate")], { "ok-gate": ["scene", "review"] })).toEqual(
+      [],
+    );
+  });
+
+  test("accepts a gate verified at ship", () => {
+    expect(validateStages([rule("ship-gate", "gate")], { "ship-gate": ["ship"] })).toEqual([]);
+  });
+
+  test("flags an unknown stage name in a dynamically built table", () => {
+    const stages = { "typo-rule": ["scene "] } as unknown as Record<string, Stage[]>;
+    const errors = validateStages([rule("typo-rule", "craft")], stages);
+    expect(errors.some((e) => e.includes('unknown stage "scene "'))).toBe(true);
+  });
+});
+
+describe("the real stage table", () => {
+  test("the registry and STAGES validate together", () => {
+    expect(validateStages(RULES, STAGES)).toEqual([]);
+  });
+
+  test("every stage has at least one rule", () => {
+    for (const stage of ALL_STAGES) {
+      const count = Object.values(STAGES).filter((s) => s.includes(stage)).length;
+      expect(count, `stage "${stage}" has no rules`).toBeGreaterThan(0);
+    }
+  });
+});

package/src/stages.ts

@@ -0,0 +1,207 @@
+import type { Rule, Stage } from "./types";
+
+/**
+ * Stage assignment for every pipeline-scoped rule: which dispatched agents
+ * must read it. This is THE audit surface for scoping - review it as a
+ * table, not as 100 diffs. Component-scoped rules ride kit sidecars and
+ * carry no entry here.
+ *
+ * Conventions, enforced by validateStages:
+ * - every pipeline rule has an entry with at least one stage (a rule tagged
+ *   out of every view is a rule nobody reads);
+ * - every gate carries "review" or "ship" (someone downstream must be able
+ *   to verify it, not only the author who can violate it).
+ *
+ * When in doubt, tag broadly: the cost of an extra stage is a few lines of
+ * prompt; the cost of a missing one is the documented failure mode (the
+ * scene-root tag convention absent from the contract template cost a fix
+ * round on both build-2 first passes).
+ *
+ * Stage meanings map to graph node families (see nodeStage in
+ * video-cli/src/graph/ruleSheets.ts): recon = clarify + recon:*;
+ * plan = plan:draft/self-review/revise; scene = scene:* + transitions;
+ * amplify = amplify:*; review = coherence + review:consume; vo = vo:lock +
+ * vo recording; audio = sfx:place + music/mix; ship = operator-side release
+ * steps (freeze, pin, render, notes).
+ */
+export const STAGES: Record<string, Stage[]> = {
+  // gates
+  "audio-is-the-clock": ["vo", "review", "ship"],
+  "check-pin-before-ship": ["ship"],
+  "data-radar-tags-declared": ["scene", "amplify", "review"],
+  "derive-seams-dont-measure": ["scene", "amplify", "review"],
+  "deterministic-scene-source": ["scene", "amplify", "review"],
+  "element-onscreen-for-its-vo-sentence": ["plan", "scene", "amplify", "review"],
+  "geometric-seams-not-crossfades": ["plan", "scene", "review"],
+  "geometry-sidecar-exports-typed": ["scene", "amplify", "review"],
+  "hero-fills-the-frame": ["scene", "amplify", "review"],
+  "interpolate-literal-keys-monotonic": ["scene", "amplify", "review"],
+  "master-mix-loudness-target": ["audio", "ship"],
+  "no-double-frame-shift": ["scene", "amplify", "review"],
+  "no-nested-svg-filters": ["scene", "amplify", "review"],
+  "no-shorthand-with-undefined-longhand": ["scene", "amplify", "review"],
+  "no-stacked-fades-at-a-cut": ["scene", "review"],
+  "no-static-holds": ["scene", "amplify", "review"],
+  "occlusion-visible-elements": ["scene", "amplify", "review"],
+  "predraw-content-present-at-the-cut": ["scene", "review"],
+  "radar-dispositions-are-human-only": ["review", "ship"],
+  "scene-root-tag-declared": ["scene", "amplify", "review"],
+  "source-archived-before-brief": ["recon", "review"],
+  "thesis-declared-in-brief": ["plan", "review"],
+  "tokens-not-raw-hexes": ["scene", "amplify", "review"],
+
+  // craft
+  "approved-sfx-palette-only": ["audio", "review"],
+  "atmosphere-gradients-fade-at-both-ends": ["scene", "amplify"],
+  "beats-derive-from-their-own-sequence": ["scene", "amplify"],
+  "camera-is-the-narrator": ["plan", "scene", "amplify", "review"],
+  "cold-viewer-clarity": ["plan", "scene", "review"],
+  "commit-or-cut-effects": ["scene", "amplify", "review"],
+  "convert-frames-across-clock-boundary": ["scene", "amplify"],
+  "cross-cut-elements-live-in-the-hud-layer": ["scene", "amplify"],
+  "cursor-clicks-real-controls": ["scene", "review"],
+  "cut-on-real-audio-pauses": ["plan", "vo"],
+  "dark-but-never-dim": ["scene", "amplify", "review"],
+  "declare-a-vertical-zone-map": ["scene", "amplify"],
+  "diegetic-sound-for-onscreen-actions": ["scene", "audio", "review"],
+  "distinct-transition-per-beat": ["scene", "amplify", "review"],
+  "download-or-draw-rich-assets": ["recon", "scene", "amplify", "review"],
+  "energy-from-timing-not-part-count": ["plan", "scene", "amplify", "review"],
+  "fix-crowding-by-rebanding-not-nudging": ["scene", "amplify"],
+  "floating-not-boxed": ["scene", "amplify", "review"],
+  "focus-beats-recede-the-context": ["scene", "amplify"],
+  "font-vars-brand-remocn": ["scene"],
+  "glow-is-a-focal-accent": ["scene", "amplify", "review"],
+  "html-masks-for-animated-counters": ["scene", "amplify"],
+  "impact-stack-on-payoffs": ["scene", "amplify"],
+  "interactive-targets-are-declared-data": ["plan", "scene"],
+  "lateness-is-structural-overlap-the-beats": ["plan", "scene", "amplify"],
+  "less-text-more-visualizations": ["plan", "scene", "amplify", "review"],
+  "make-2d-elements-3d": ["scene", "amplify", "review"],
+  "motion-carries-weight-and-meaning": ["scene", "amplify", "review"],
+  "motion-density-floor": ["scene", "amplify", "review"],
+  "never-restate-derived-frame-numbers-in-comments": ["scene", "amplify"],
+  "no-ai-gradient-look": ["scene", "amplify", "review"],
+  "no-colored-flash-to-hide-a-cut": ["scene", "review"],
+  "no-linear-motion": ["scene", "amplify", "review"],
+  "no-repeated-asset-across-shots": ["plan", "scene", "review"],
+  "one-continuous-vo-track": ["vo", "scene"],
+  "one-punch-per-moment-class": ["scene", "amplify", "review"],
+  "open-static-after-a-hard-cut": ["scene", "review"],
+  "openings-and-closings-carry-more": ["plan", "scene", "amplify", "review"],
+  "persistent-device-frames": ["plan", "scene"],
+  "premium-surfaces-not-flat-borders": ["scene", "amplify"],
+  "real-assets-not-placeholders": ["recon", "scene", "review"],
+  "rebuild-ui-from-recon-not-screenshots": ["recon", "scene"],
+  "remap-rate-endpoint-formula": ["scene"],
+  "remocn-content-tailwind-chrome": ["scene", "amplify"],
+  "retime-only-via-playback-or-design-tokens": ["scene", "vo"],
+  "sample-brand-from-product": ["recon", "scene"],
+  "sample-velocity-from-previous-frame-position": ["scene", "amplify"],
+  "scrub-demo-data-to-generic-roles": ["recon", "scene", "review"],
+  "statistics-self-explanatory": ["plan", "vo", "scene", "review"],
+  "stops-as-relative-spacing": ["scene"],
+  "the-whole-canvas-works": ["scene", "amplify", "review"],
+  "theme-per-section": ["plan", "scene"],
+  "tiny-body-copy-as-ruled-lines": ["scene"],
+  "titles-pinned-outside-camera-push": ["scene", "review"],
+  "type-token-defaulted-params-as-string": ["scene"],
+  "vary-kit-choreography-across-sections": ["plan", "scene", "amplify", "review"],
+  "vary-the-visualization-grammar": ["plan", "scene", "amplify", "review"],
+  "vo-addresses-the-viewer": ["plan", "vo"],
+  "vo-is-a-performance": ["vo", "review"],
+  "wrappers-preserve-child-geometry": ["scene", "amplify"],
+
+  // process
+  "best-scene-sets-the-bar": ["amplify", "review"],
+  "bump-before-refreeze": ["ship"],
+  "delete-rejected-rigs-completely": ["scene", "amplify"],
+  "emit-build-notes": ["review", "ship"],
+  // egw3: NOT in scene/amplify. Dispatched scene/fix/amplify agents are
+  // author-once - their task bodies command "typecheck only, no render, no
+  // stills" - so shipping a render-evidence rule in the same prompt made the
+  // two contradict; whichever the worker obeyed, it violated the other. The
+  // review/fix-round driver renders, so evidence rules live there.
+  "evidence-before-claiming-fixed": ["review"],
+  "exact-peer-lockstep": ["ship"],
+  "first-pass-is-a-draft": ["plan", "amplify"],
+  "fixes-preserve-approved-elements": ["scene", "amplify", "review"],
+  "live-link-duplicate-react-alias": ["scene"],
+  "measure-alignment-dont-eyeball": ["scene", "amplify", "review"],
+  "never-edit-tier-b-vendored": ["scene", "amplify"],
+  "no-duplicate-motion-primitives": ["scene"],
+  "one-render-per-round": ["review", "ship"],
+  "pixel-diff-an-empty-band-first": ["review"],
+  "plan-is-published-not-gating": ["plan"],
+  "powered-by-revola-watermark": ["plan", "scene", "review"],
+  "recon-strands-run-in-parallel": ["recon"],
+  "registry-before-handrolling": ["scene"],
+  "review-the-render-by-frame-sweep": ["review"],
+  "same-family-same-project": ["plan"],
+  "self-review-the-plan-for-gaps": ["plan"],
+  "tier-a-requires-prop-unreachable-edit": ["scene", "ship"],
+  // egw3: NOT in scene/amplify, same contradiction as
+  // evidence-before-claiming-fixed above - the rule's "run the full render
+  // only on demand" framing presumes a driver that CAN render.
+  "verify-cheap-render-dear": ["review", "ship"],
+  "vo-script-locks-spoken-words": ["plan", "vo"],
+};
+
+/**
+ * The scoping invariants. Run by generate.ts (fail fast, never project a
+ * mis-scoped table) and by stages.test.ts. Errors, not throws, so callers
+ * can report all problems at once.
+ */
+export function validateStages(rules: Rule[], stages: Record<string, Stage[]>): string[] {
+  const errors: string[] = [];
+  const pipelineIds = new Set(rules.filter((r) => r.scope.kind === "pipeline").map((r) => r.id));
+
+  for (const rule of rules) {
+    if (rule.scope.kind !== "pipeline") continue;
+    const assigned = stages[rule.id];
+    if (!assigned || assigned.length === 0) {
+      errors.push(`pipeline rule "${rule.id}" has no stage assignment`);
+      continue;
+    }
+    // TS catches typos in the literal table, but a dynamically built or
+    // cast table would not be checked; a rule tagged with an unknown stage
+    // drops out of every generated sheet.
+    for (const s of assigned) {
+      if (!(ALL_STAGES as readonly string[]).includes(s)) {
+        errors.push(`rule "${rule.id}" carries unknown stage "${s}"`);
+      }
+    }
+    // A gate blocks the ship, so it must sit in a view someone downstream of
+    // the author reads: review (per-round verification) or ship (release
+    // checks). An author-only gate is a claim nobody re-checks.
+    if (rule.tier === "gate" && !assigned.includes("review") && !assigned.includes("ship")) {
+      errors.push(`gate "${rule.id}" carries neither "review" nor "ship"`);
+    }
+  }
+
+  for (const id of Object.keys(stages)) {
+    if (!pipelineIds.has(id)) {
+      errors.push(`stage entry "${id}" matches no pipeline rule`);
+    }
+  }
+
+  return errors;
+}
+
+export const ALL_STAGES = [
+  "recon",
+  "plan",
+  "scene",
+  "amplify",
+  "review",
+  "vo",
+  "audio",
+  "ship",
+] as const satisfies readonly Stage[];
+
+// Compile-time exhaustiveness: a Stage variant added to the union in types.ts
+// but missing from ALL_STAGES would otherwise silently get no generated
+// sheet, no drift test, and no rules (every consumer iterates ALL_STAGES).
+type MissingStage = Exclude<Stage, (typeof ALL_STAGES)[number]>;
+const _allStagesExhaustive: [MissingStage] extends [never] ? true : MissingStage = true;
+void _allStagesExhaustive;

package/src/testSupport.ts

@@ -0,0 +1,16 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * TEST SUPPORT ONLY. The absolute root of THIS repository's checkout, for the
+ * package's own tests (and only them) to pass as the explicit scan root.
+ *
+ * Library code must never import this: computing a root by walking up from
+ * the module's own location is exactly what breaks when the package is
+ * installed inside a consumer repo (the walk lands in node_modules, or in the
+ * consumer's tree, depending on layout). Every library entry point takes the
+ * root as an explicit parameter instead; scripts compute theirs at the script
+ * boundary; the CLI derives its from the operator's arguments.
+ */
+// this file -> packages/video-craft/src -> packages/video-craft -> packages -> repo root
+export const toolchainRepoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");