@revola-ai/video-craft 0.2.1

package/src/rules/energyFromTimingNotPartCount.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 9's counter-failure ("it
+ * looks overwhelming, I wanted to do it more with the camera", "still
+ * AI-generated - less detailed, smoother"): the same corpus that demanded
+ * motion density also rejected scenes that answered it with more objects.
+ */
+export const energyFromTimingNotPartCount: Rule = {
+  id: "energy-from-timing-not-part-count",
+  claim: "Scene energy comes from timing and material, never from part count: one subject performing beautifully beats ten things wiggling, and a beat where several subjects compete for the eye at once is as much a defect as a static hold.",
+  why: "'It looks overwhelming, I wanted to do it more with the camera' arrived in the same corpus as the too-static notes; answering flatness by adding elements produced the opposite failure, so density must be bought with overlapping beats in time, not with simultaneous objects.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "An attention-competition judgment per beat; no single code location expresses it.",
+  },
+};

package/src/rules/evidenceBeforeClaimingFixed.ts

@@ -0,0 +1,23 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/portfolio-reels.md and
+ * act854-qpa-video.md: "it's still there" (the purple cursor ripple survived
+ * its own fix), "you didn't add it in the animation???" (BOMs edited into
+ * the script but not the scene), "I cannot hear any typewriter sound
+ * effect". The companion to verify-cheap-render-dear: that rule says which
+ * checks are cheap; this one says a fix is not done until a check confirmed
+ * it.
+ */
+export const evidenceBeforeClaimingFixed: Rule = {
+  id: "evidence-before-claiming-fixed",
+  claim: "Never report a fix without evidence from the artifact itself: a still at the affected frames, a grep proving the removed effect is gone, or an audio probe proving the sound is present.",
+  why: "Three separate 'fixes' shipped unverified and bounced with 'it's still there'; each unverified claim costs a full human review round, the most expensive resource in the loop.",
+  learnedFrom: "claude-sessions-digest/portfolio-reels.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule prescribes review-loop discipline; no repo code implements evidence capture to point at.",
+  },
+};

package/src/rules/exactPeerLockstep.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md: "Exact peers, lockstep releases. The kit
+ * pins its peers exactly; a project that bumps Remotion needs a matching kit
+ * release before its next freeze."
+ */
+export const exactPeerLockstep: Rule = {
+  id: "exact-peer-lockstep",
+  claim: "The kit pins its peers exactly; a project that bumps Remotion must get a matching kit release before its next freeze.",
+  why: "A peer-range mismatch lets a project silently render against a Remotion version the kit was never tested with, or blocks the freeze at the worst moment.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/kitShell.ts" },
+  },
+};

package/src/rules/firstPassIsADraft.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-craft-video.md: the identical
+ * "this needs to blow people away ... this looks too basic, like a template
+ * almost" upgrade prompt was issued for ALL five scenes; no first-pass scene
+ * ever shipped. The amplification pass is structural, not a correction.
+ */
+export const firstPassIsADraft: Rule = {
+  id: "first-pass-is-a-draft",
+  claim: "Treat every scene's first build as a draft: a dedicated amplification pass (faster, more detailed, more layered motion; unnecessary text removed) is a mandatory pipeline stage, not an optional polish.",
+  why: "In the best-documented build, all five scenes received the same 'too basic, blow people away' round; budgeting the second pass up front converts a guaranteed feedback round into a pipeline stage.",
+  learnedFrom: "claude-sessions-digest/revola-craft-video.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule prescribes a pipeline stage; no code location expresses it yet.",
+  },
+};

package/src/rules/fixCrowdingByRebandingNotNudging.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "Root cause was layout, not
+ * size - the spine was at y660, so every station was squeezed into the 360px
+ * between the copy and the line while the bottom ~240px of frame sat empty.
+ * Fixed by moving the whole stage down, not by nudging."
+ */
+export const fixCrowdingByRebandingNotNudging: Rule = {
+  id: "fix-crowding-by-rebanding-not-nudging",
+  claim: "When a layout reads crowded or crumbled, fix the band allocation by moving the whole stage, not by nudging individual elements.",
+  why: "The S3 spine at y660 squeezed every station into 360px while the bottom 240px of frame sat empty; the root cause was layout allocation, not element size, and shrinking elements would not have fixed it.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/S3Line.tsx" },
+  },
+};

package/src/rules/fixesPreserveApprovedElements.ts

@@ -0,0 +1,24 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-usecase-book-meeting.md ("nooo,
+ * the particle animation and the room appearing in a circle were amazing,
+ * why did you remove them? I meant that when the room is opened, the text on
+ * it and the animations looked bad") and portfolio-reels.md ("Yeah, but now
+ * it doesn't scroll the sidebar. Why are you acting like you're in a time
+ * crunch? Just have both."). The inverse of
+ * delete-rejected-rigs-completely: rejected work is deleted entirely,
+ * approved work is never deleted incidentally.
+ */
+export const fixesPreserveApprovedElements: Rule = {
+  id: "fixes-preserve-approved-elements",
+  claim: "A fix scoped to one complaint is a minimal diff against the approved baseline: additive unless removal was requested, and previously-praised elements are never deleted while fixing a neighbour.",
+  why: "Twice a scoped complaint was 'fixed' by deleting elements the reviewer loved, costing a restoration round each time; feedback on one aspect of a scene is not license to rebuild the scene.",
+  learnedFrom: "claude-sessions-digest/revola-usecase-book-meeting.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule prescribes diff discipline for feedback rounds; no code location expresses it.",
+  },
+};

package/src/rules/floatingNotBoxed.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 7 ("i prefer floating
+ * svgs instead of containers and i want everything to be bigger and more
+ * polished", "remove the ugly bg colors from the SVGs - let them float",
+ * "what if the card didn't have a bg and the content sat floating with a
+ * nice abstract hue in the bg").
+ */
+export const floatingNotBoxed: Rule = {
+  id: "floating-not-boxed",
+  claim: "Content floats free on the canvas, grounded by soft contact shadows, instead of sitting in boxed panels; every container must earn its chrome - a filler background rectangle behind an SVG is a defect, and when a panel does exist it is a premium layered surface.",
+  why: "'I prefer floating svgs instead of containers' and 'remove the ugly bg colors from the SVGs - let them float' were standing preferences across rounds; boxed content read as template while floating, shadow-grounded elements read as designed.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A does-this-container-earn-its-chrome judgment per element; no single code location expresses it.",
+  },
+};

package/src/rules/focusBeatsRecedeTheContext.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from the product-room build: the 'product brain' beat overlaid
+ * traces and a label on the live room. Feedback was that it 'covers the
+ * product room and overlaps highly with it so it's not very clear'. The fix
+ * was not to move the label - it was to make the beat its own shot.
+ */
+export const focusBeatsRecedeTheContext: Rule = {
+  id: "focus-beats-recede-the-context",
+  claim: "When a beat introduces a new subject over existing UI, recede the context behind it - dim, blur, scale back, scrim - and give the new subject cleared space; never draw the new layer on top of live content.",
+  why: "A diagram drawn over a fully lit room put its label character-for-character on top of a card's caption and its connector lines read as scratches across the UI; receding the room turned the same beat into a clean shot with no geometry changes.",
+  learnedFrom: "claude-sessions-digest/product-room-video.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A composition discipline spanning scene and overlay layers; no single symbol owns it.",
+  },
+};

package/src/rules/fontVarsBrandRemocn.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md: "Point those vars at the fonts the
+ * project already loads ... and every remocn component is branded at once,
+ * with zero source changes." A .css file cannot hold a ts-morph symbol, so
+ * the anchor is file-only by construction.
+ */
+export const fontVarsBrandRemocn: Rule = {
+  id: "font-vars-brand-remocn",
+  claim: "Brand all remocn components at once by pointing --font-geist-sans and --font-geist-mono at the project's loaded fonts in CSS; never touch font settings in component source.",
+  why: "Editing fonts per-component forfeits Tier B update-safety and reintroduces per-file drift; the CSS vars brand ~110 components with zero source changes.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/index.css" },
+  },
+};

package/src/rules/geometricSeamsNotCrossfades.ts

@@ -0,0 +1,28 @@
+import type { Rule } from "../types";
+
+/**
+ * Adopted from the reels and craft sessions ('cards physically combine into
+ * the next scene like a puzzle'; scenes overlap 12 frames). Applied in the
+ * product-room build by having the clicked intro card expand to fill the
+ * viewport and hand off to the explore grid.
+ */
+export const geometricSeamsNotCrossfades: Rule = {
+  id: "geometric-seams-not-crossfades",
+  claim: "Make a seam physical: the clicked element becomes the next scene, or the camera travels through it; overlap adjacent sections by a few frames so the handoff happens mid-air rather than as a dissolve between slides.",
+  why: "Praised cuts in the reference films are all motivated - a card expands into the next shot, the camera flies through a control - while crossfades read as slides advancing; the geometric handoff is also what makes a cut survive a re-time.",
+  learnedFrom: "claude-sessions-digest/product-room-video.md",
+  tier: "gate",
+  // Added by the codex red team round (2026-08-01): the r2 sudden-seams class
+  // (5 of 6 seams, BUILD_NOTES round 2 feedback item 1, bead
+  // remotion-videos-t0s) escaped every prior check because the two seam bans
+  // this rule states are satisfiable by doing nothing - `seam-continuity` is
+  // the check that verifies the CONSTRUCTIVE half: every seam carries either
+  // a shared geometry-sidecar carrier or a declared overlap of >=4 frames.
+  verify: "`video radar:film --project <dir> --video <mp4> --check seam-continuity`",
+  owner: "seam-continuity",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/productroom/PRColdOpen.tsx" },
+  },
+};

package/src/rules/geometrySidecarExportsTyped.test.ts

@@ -0,0 +1,37 @@
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { toolchainRepoRoot as repoRoot } from "../testSupport";
+import { checkFile } from "../sourceCheck";
+import { geometrySidecarExportsTyped } from "./geometrySidecarExportsTyped";
+
+const check = () => {
+  if (geometrySidecarExportsTyped.enforcement.kind !== "source") throw new Error("expected a source rule");
+  return geometrySidecarExportsTyped.enforcement.check;
+};
+
+const run = (name: string) => {
+  const rel = `packages/video-craft/src/fixtures/${name}`;
+  return checkFile(check(), join(repoRoot, rel), rel, repoRoot);
+};
+
+describe("geometrySidecarExportsTyped", () => {
+  test("does not fire on a sidecar exporting a typed geometry", () => {
+    expect(run("geometry-sidecar-valid.ts")).toEqual([]);
+  });
+
+  test("fires when the export is missing a `: SceneGeometry` type annotation", () => {
+    const findings = run("geometry-sidecar-missing-type.ts");
+    expect(findings).toHaveLength(1);
+    expect(findings[0].message).toMatch(/`: SceneGeometry`/);
+  });
+
+  test("fires when there is no `export const geometry` at all", () => {
+    const findings = run("geometry-sidecar-missing-export.ts");
+    expect(findings).toHaveLength(1);
+    expect(findings[0].message).toMatch(/`export const geometry`/);
+  });
+
+  test("owns the sidecar convention's include glob", () => {
+    expect(check().include).toEqual(["*/src/scenes/scene.*.geometry.ts"]);
+  });
+});

package/src/rules/geometrySidecarExportsTyped.ts

@@ -0,0 +1,59 @@
+import type { Rule, SourceFinding } from "../types";
+
+/**
+ * Task 6 of the task-graph phase-1 plan
+ * (docs/superpowers/plans/2026-07-30-video-task-graph-phase1.md) introduces
+ * `SceneGeometry` (packages/video-kit/src/pure/geometry.ts) as the typed
+ * seam-pose contract a scene's cross-cut sidecar carries, so that the
+ * `compose:registry` generator (Task 11) and film assembly (Task 18) can
+ * import a seam's exported geometry and have the compiler - not a render -
+ * catch a missing or mistyped export. The spec's decision 1 is "typed
+ * geometry so the compiler checks seam consumers": that only holds if every
+ * sidecar actually exports the typed shape, which is what this rule checks.
+ *
+ * The sidecar naming convention (`src/scenes/scene.<id>.geometry.ts`, one per
+ * project directory) is declared once, in `geometrySidecarPath()` in the same
+ * geometry.ts module this rule's `why` cites - this file enforces the
+ * convention, it does not restate it.
+ */
+export const geometrySidecarExportsTyped: Rule = {
+  id: "geometry-sidecar-exports-typed",
+  claim: "A scene's geometry sidecar exports `const geometry` typed as `SceneGeometry`.",
+  why:
+    "The compose:registry generator and film assembly import a seam's geometry sidecar by convention " +
+    "(src/scenes/scene.<id>.geometry.ts) and read its `geometry` export at compile time; an untyped or " +
+    "missing export turns that compile-time check into a silent `undefined` at runtime, at the exact " +
+    "moment - a scene cut - where the seam contract is supposed to be enforced.",
+  learnedFrom: "docs/superpowers/plans/2026-07-30-video-task-graph-phase1.md",
+  tier: "gate",
+  verify: "`vitest run packages/video-craft` - machine-checked over every geometry sidecar file",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "source",
+    check: {
+      // One level deep under each project directory, matching
+      // geometrySidecarPath()'s convention exactly: <project>/src/scenes/scene.<id>.geometry.ts.
+      include: ["*/src/scenes/scene.*.geometry.ts"],
+      run(file, relPath): SourceFinding[] {
+        const text = file.getFullText();
+        const hasExport = text.includes("export const geometry");
+        const hasType = text.includes(": SceneGeometry");
+        if (hasExport && hasType) return [];
+
+        const missing = [
+          !hasExport && "`export const geometry`",
+          !hasType && "`: SceneGeometry`",
+        ].filter((x): x is string => !!x).join(" and ");
+
+        return [{
+          file: relPath,
+          line: 1,
+          match: relPath.split("/").pop() ?? relPath,
+          message:
+            `geometry sidecar is missing ${missing}; a sidecar at this path must read ` +
+            `\`export const geometry: SceneGeometry = { ... }\` (packages/video-kit/src/pure/geometry.ts)`,
+        }];
+      },
+    },
+  },
+};

package/src/rules/glowIsAFocalAccent.ts

@@ -0,0 +1,28 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/portfolio-reels.md: uniform glows and
+ * boxShadow on every panel were called out as part of the "AI-generated and
+ * cheap" read; the fixes that worked removed glow everywhere except focal
+ * moments, keeping frosted glass as the liked signature surface.
+ */
+export const glowIsAFocalAccent: Rule = {
+  id: "glow-is-a-focal-accent",
+  claim: "Reserve glow and drop-shadow for one or two focal moments per scene; a uniform glow on every panel is banned, frosted-glass surfaces are the sanctioned depth cue.",
+  why: "Uniform glows read as cheap template styling; de-glowing was part of every de-AI-ification round in the reels.",
+  learnedFrom: "claude-sessions-digest/portfolio-reels.md",
+  tier: "craft",
+  exceptions: [
+    {
+      project: "qse-qguard-video",
+      decision:
+        "client chose ACT854's breathing accent bloom on every panel and glyph tile for the QGuard restyle; the bloom lives on rings and tiles, never behind body copy",
+      recordedIn: "qse-qguard-video/docs/motion-brand-spec.md",
+    },
+  ],
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is a styling-restraint judgment across scenes; no single code location expresses it.",
+  },
+};

package/src/rules/heroFillsTheFrame.ts

@@ -0,0 +1,24 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-usecase-win-booth.md ("the
+ * animations are too small ... it's big, cinematic, and engaging .. these
+ * are too small, hardly legible. play big") and
+ * revola-usecase-book-meeting.md ("the second animation only takes 1/3 of
+ * the screen"; "they are still tiny"). "Bigger" requests routinely took two
+ * rounds because the first enlargement undershot.
+ */
+export const heroFillsTheFrame: Rule = {
+  id: "hero-fills-the-frame",
+  claim: "The hero element of a shot fills roughly two thirds of the frame or more, legible at 1080p; a hero occupying a third of the screen is a defect, and when enlarging, overshoot rather than nudge.",
+  why: "Undersized heroes were flagged in five separate rounds across three videos, and every timid enlargement needed a second round; 'play big' is the single most repeated scale note in the corpus.",
+  learnedFrom: "claude-sessions-digest/revola-usecase-win-booth.md",
+  tier: "gate",
+  verify: "`video radar:scene --project <dir> --comp <id> --check hero-size`",
+  owner: "hero-size",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is a composition judgment per shot; no single code location expresses it.",
+  },
+};

package/src/rules/htmlMasksForAnimatedCounters.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "odometer rebuilt in HTML
+ * (SVG clipPath was unreliable in headless renders)". Narrowed to ANIMATED
+ * mask geometry on the extractor's own evidence: ink.tsx's static clipPath
+ * (InkFill) renders fine in the same pipeline, so the failure is specific to
+ * animated clipPath geometry, not clipPath per se.
+ */
+export const htmlMasksForAnimatedCounters: Rule = {
+  id: "html-masks-for-animated-counters",
+  claim: "Build animated sliding-mask counters (odometers, digit rolls) in HTML/CSS rather than SVG clipPath; animated clipPath geometry is unreliable in headless renders.",
+  why: "The S3 odometer built on SVG clipPath rendered inconsistently in headless Chrome and had to be rebuilt in HTML; static clipPath (e.g. InkFill) remains fine.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/S3Line.tsx" },
+  },
+};

package/src/rules/impactStackOnPayoffs.ts

@@ -0,0 +1,26 @@
+import type { Rule } from "../types";
+
+/**
+ * Reconciles with one-punch-per-moment-class rather than contradicting it:
+ * that rule bans repeating the SAME punch across instances within a class
+ * (every keypress, every card); this one says stack several signals on a
+ * payoff and vary the stack BETWEEN classes. Four payoffs of four classes
+ * satisfy both.
+ *
+ * Adopted from the reels sessions, where every beat frame layers punchScale
+ * + chromaKick + beatFlash + RingPulse + LightSweep plus a foley cue. The
+ * product-room first pass had payoffs that merely appeared, and read flat
+ * even though the underlying content was right.
+ */
+export const impactStackOnPayoffs: Rule = {
+  id: "impact-stack-on-payoffs",
+  claim: "Land each payoff with several simultaneous signals on the same frame - ring pulse, scale punch, light sweep, one approved foley hit - and vary which signals each class of payoff uses.",
+  why: "A single fade or count-up reads as a value changing; the stacked signal reads as a moment landing, and varying the stack per payoff class is what keeps four payoffs in one film from reading as the same template beat.",
+  learnedFrom: "claude-sessions-digest/product-room-video.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A choreography discipline composed per beat from several primitives; it has no single owning symbol.",
+  },
+};

package/src/rules/interactiveTargetsAreDeclaredData.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from the product-room build, and consistent with the digest note
+ * that hit geometry must be derived from layout constants: 'on a film with
+ * Pixel-perfect. on screen, that is the one mistake you cannot ship'. Two
+ * sources of truth (the control's flow position and the cursor's hardcoded
+ * coordinate) will always drift; one shared constant cannot.
+ */
+export const interactiveTargetsAreDeclaredData: Rule = {
+  id: "interactive-targets-are-declared-data",
+  claim: "A control the cursor clicks and the cursor path that clicks it must read the same declared coordinate; if a target is measured off a render instead, record the measurement and re-verify it after any layout change.",
+  why: "Cursor targets positioned by eye drifted out from under their controls as the layout changed - one click landed 122px right and 155px below its button while the button lit up on its own - and nothing in the build could detect it.",
+  learnedFrom: "claude-sessions-digest/product-room-video.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/components/Cursor.tsx" },
+  },
+};

package/src/rules/interpolateLiteralKeysMonotonic.test.ts

@@ -0,0 +1,49 @@
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { toolchainRepoRoot as repoRoot } from "../testSupport";
+import { checkFile } from "../sourceCheck";
+import { interpolateLiteralKeysMonotonic } from "./interpolateLiteralKeysMonotonic";
+
+const check = () => {
+  if (interpolateLiteralKeysMonotonic.enforcement.kind !== "source") {
+    throw new Error("expected a source rule");
+  }
+  return interpolateLiteralKeysMonotonic.enforcement.check;
+};
+
+const run = (name: string) => {
+  const rel = `packages/video-craft/src/fixtures/${name}`;
+  return checkFile(check(), join(repoRoot, rel), rel, repoRoot);
+};
+
+describe("interpolateLiteralKeysMonotonic", () => {
+  test("fires on non-ascending all-literal ranges, including unary minus", () => {
+    const findings = run("interpolate-descending.tsx");
+    expect(findings).toHaveLength(2);
+    expect(findings[0].line).toBe(7);
+    expect(findings[0].match).toBe("[0, 136, 134, 200]");
+    expect(findings[1].line).toBe(8);
+    expect(findings[1].match).toBe("[-10, -20]");
+    for (const f of findings) expect(f.message).toMatch(/ascending/);
+  });
+
+  test("does not fire on strictly ascending literal ranges", () => {
+    expect(run("interpolate-ascending.tsx")).toEqual([]);
+  });
+
+  test("does not fire on identifier-composed ranges (out of scope)", () => {
+    expect(run("interpolate-identifier-keys.tsx")).toEqual([]);
+  });
+
+  test("covers all project layouts plus the kit, including plain .ts/.js helpers", () => {
+    // interpolate() also lives in non-JSX helpers feeding scenes
+    // (spec-videos/src/lib/transitions.ts, packages/video-kit/src/react/motion.ts,
+    // qse-investor-video/03_scenes/_lib/motion.js), so this rule scans
+    // .js/.ts too, unlike the JSX-only source rules.
+    expect(check().include).toContain("qpa-video/03_scenes/**/*.{js,jsx,ts,tsx}");
+    expect(check().include).toContain("revola-video/src/scenes/**/*.{js,jsx,ts,tsx}");
+    expect(check().include).toContain("spec-videos/**/*.{js,jsx,ts,tsx}");
+    expect(check().include).toContain("qse-investor-video/**/*.{js,jsx,ts,tsx}");
+    expect(check().include).toContain("packages/video-kit/src/**/*.{ts,tsx}");
+  });
+});

package/src/rules/interpolateLiteralKeysMonotonic.ts

@@ -0,0 +1,98 @@
+import { Node, SyntaxKind } from "ts-morph";
+import type { Rule, SourceFinding } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "HERO_AT (134) is now
+ * *earlier* than TILT_END (136), so it can no longer be a CAM_KEYS entry -
+ * interpolate() needs a monotonic input range and will throw."
+ *
+ * Deliberate limitation: only ranges whose elements are ALL numeric literals
+ * (including unary minus) are evaluated. Identifier-composed arrays would
+ * need constant folding to prove monotonic, so they are out of scope; any
+ * literal hit is a real latent crash by construction.
+ */
+
+/** The numeric value of a literal element, or undefined when it is not one. */
+function literalValue(element: Node): number | undefined {
+  if (Node.isNumericLiteral(element)) return element.getLiteralValue();
+  if (Node.isPrefixUnaryExpression(element) && element.getOperatorToken() === SyntaxKind.MinusToken) {
+    const operand = element.getOperand();
+    if (Node.isNumericLiteral(operand)) return -operand.getLiteralValue();
+  }
+  return undefined;
+}
+
+export const interpolateLiteralKeysMonotonic: Rule = {
+  id: "interpolate-literal-keys-monotonic",
+  claim: "A literal input-range array passed to interpolate() must be strictly ascending.",
+  why: "interpolate() throws at runtime on a non-monotonic range; a literal non-ascending array is a latent crash that renders fine until that frame is reached. The HERO_AT(134)/TILT_END(136) retime would have thrown.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "gate",
+  verify: "`vitest run packages/video-craft` - machine-checked over scene and kit source",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "source",
+    check: {
+      // Unlike the JSX-only checks, this one also scans plain .ts/.js:
+      // interpolate() lives in non-JSX helpers feeding scenes
+      // (spec-videos/src/lib/transitions.ts, packages/video-kit/src/react/
+      // motion.ts, qse-investor-video/03_scenes/_lib/motion.js), and a
+      // non-monotonic literal range crashes wherever it is written.
+      include: [
+        "qpa-video/03_scenes/**/*.{js,jsx,ts,tsx}",
+        "reverence-video/src/scenes/**/*.{js,jsx,ts,tsx}", "workday-dple-video/src/scenes/**/*.{js,jsx,ts,tsx}",
+        "revola-video/src/scenes/**/*.{js,jsx,ts,tsx}",
+        "datapeak-video/**/*.{js,jsx,ts,tsx}",
+        "datapeak-usecases/**/*.{js,jsx,ts,tsx}",
+        "qse-video/**/*.{js,jsx,ts,tsx}",
+        "qse-investor-video/**/*.{js,jsx,ts,tsx}",
+        "qse-qguard-video/src/**/*.{ts,tsx}",
+        "rcp-fund7-video/src/**/*.{ts,tsx}",
+        "expanse-video/src/**/*.{ts,tsx}",
+        "reverence-video/src/**/*.{ts,tsx}",
+        "spec-videos/**/*.{js,jsx,ts,tsx}",
+        // Added Task 23: klaviyo-segments-video and radar-fixture-video were
+        // silently excluded - the same gap deterministic-scene-source had.
+        "klaviyo-segments-video/src/**/*.{js,jsx,ts,tsx}",
+        "radar-fixture-video/src/**/*.{js,jsx,ts,tsx}",
+        "packages/video-kit/src/**/*.{ts,tsx}",
+      ],
+      run: (file, relPath): SourceFinding[] => {
+        const findings: SourceFinding[] = [];
+
+        for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+          if (call.getExpression().getText() !== "interpolate") continue;
+
+          const range = call.getArguments()[1];
+          if (!range || !Node.isArrayLiteralExpression(range)) continue;
+
+          const values: number[] = [];
+          let allLiteral = true;
+          for (const element of range.getElements()) {
+            const value = literalValue(element);
+            if (value === undefined) {
+              allLiteral = false;
+              break;
+            }
+            values.push(value);
+          }
+          if (!allLiteral) continue;
+
+          const ascending = values.every((v, i) => i === 0 || values[i - 1] < v);
+          if (ascending) continue;
+
+          findings.push({
+            file: relPath,
+            line: call.getStartLineNumber(),
+            match: range.getText().replace(/\s+/g, " ").slice(0, 60),
+            message:
+              `interpolate() input range [${values.join(", ")}] is not strictly ascending; ` +
+              `interpolate() throws at runtime when this frame range is evaluated.`,
+          });
+        }
+
+        return findings;
+      },
+    },
+  },
+};

package/src/rules/latenessIsStructuralOverlapTheBeats.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "the delay was structural,
+ * not a timing offset: the clock hook, the tilt, and the *entire* field pop
+ * all had to finish before the deck could land. Sequential beats. Fix =
+ * overlap them."
+ */
+export const latenessIsStructuralOverlapTheBeats: Rule = {
+  id: "lateness-is-structural-overlap-the-beats",
+  claim: "When a key element arrives late, check whether the delay is structural (strictly sequential prerequisite beats) before shaving durations; the fix is to overlap beats, not to trim them.",
+  why: "Two shave passes (420f to 396f, deck 232 to 196) failed to fix a late deck because the hook, tilt, and field pop all had to finish first; overlapping them fixed it in one pass.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/S1Graveyard.tsx" },
+  },
+};