@revola-ai/video-craft 0.2.1

package/src/rules/selfReviewThePlanForGaps.ts

@@ -0,0 +1,47 @@
+import type { Rule } from "../types";
+
+/**
+ * The cheap half of what the removed sign-off barrier was doing, kept without
+ * the wait.
+ *
+ * The QGuard plan was 33 KB and read as thorough. Two of the three defects the
+ * first human viewing found were not mistakes IN it - they were subjects it
+ * never mentioned. It bound colour, vertical layout, theme-per-section and
+ * motion density, and said nothing about typographic case, emphasis, or whether
+ * the copy in a fixed-size panel fits it. Seven scenes then each decided those
+ * locally, seven ways, and no scene file could see the divergence.
+ *
+ * So the pass is not "read it again", which finds nothing. It is one adversarial
+ * question - *what does this plan leave to per-scene judgement?* - because a
+ * plan that permits a judgement will get that judgement made once per scene, and
+ * the drift is invisible from inside any single one of them.
+ *
+ * Checklist, from the rulebook's own declare-shaped rules, plus the two the
+ * QGuard round found missing:
+ *
+ *   - colour            (`tokens-not-raw-hexes`)
+ *   - vertical layout   (`declare-a-vertical-zone-map`)
+ *   - theme per section (`theme-per-section`)
+ *   - seam per cut, and the object that carries it
+ *                       (`geometric-seams-not-crossfades`)
+ *   - typographic case and emphasis per text tier
+ *   - a fit budget for every fixed-size panel that holds copy
+ *   - which kit component and variant each section leans on
+ *                       (`vary-kit-choreography-across-sections`)
+ *
+ * A subject not on the plan is not automatically a defect - it is a decision
+ * that has to be made somewhere, and the plan is the only place it can be made
+ * once.
+ */
+export const selfReviewThePlanForGaps: Rule = {
+  id: "self-review-the-plan-for-gaps",
+  claim: "Before building, run one adversarial pass over the scene-flow plan asking what it leaves undeclared, and bind anything it leaves to per-scene judgement.",
+  why: "A plan can be detailed and still be silent: the QGuard plan bound colour, layout, theme and motion density but never mentioned typographic case or panel fit, so seven scenes each decided those separately and both defects reached the viewer.",
+  learnedFrom: "qse-qguard-video/BUILD_NOTES.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/planmd.ts" },
+  },
+};

package/src/rules/sourceArchivedBeforeBrief.ts

@@ -0,0 +1,24 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/superpowers/specs/2026-07-31-defect-radar-design.md: "a
+ * browsed-and-gone URL is not a source". The recon dir's own honesty is the
+ * gate a brief's claims can be checked against later - a source that was
+ * read but never saved leaves every downstream fidelity check (thesis
+ * derivation, scene-serves-thesis) with nothing but the brief's own word for
+ * what the source said.
+ */
+export const sourceArchivedBeforeBrief: Rule = {
+  id: "source-archived-before-brief",
+  claim: "The recon dir contains a verbatim-saved copy of the source material (article text, transcript, etc.) before the brief is written, not only screenshots of it.",
+  why: "A brief written against a browsed-and-gone source cannot be checked against anything once the tab is closed; screenshots preserve a layout, not the words a thesis-fidelity read needs to compare against.",
+  learnedFrom: "docs/superpowers/specs/2026-07-31-defect-radar-design.md",
+  tier: "gate",
+  verify: "`video radar:plan --project <dir>` (check: `brief-structure`)",
+  owner: "brief-structure",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is about what an operator saves into a recon dir before writing a brief; no single code location expresses it.",
+  },
+};

package/src/rules/statisticsSelfExplanatory.ts

@@ -0,0 +1,18 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-craft-video.md: boss feedback "we
+ * say something- 5%, what is that. 5% of their day or what, it's confusing".
+ */
+export const statisticsSelfExplanatory: Rule = {
+  id: "statistics-self-explanatory",
+  claim: "Every statistic on screen or in the voiceover names its denominator in context ('5% of their day', not '5%'); orphan numbers are a defect.",
+  why: "An unexplained '5%' reached the boss review before anyone caught it; a number without its base confuses exactly the executive audience the video targets.",
+  learnedFrom: "claude-sessions-digest/revola-craft-video.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/voice.ts" },
+  },
+};

package/src/rules/stopsAsRelativeSpacing.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md ("authored from values are treated as
+ * relative spacing and rescaled to fill the scene ... a re-measure, not a
+ * re-authoring of every stop"), merged with act854-video/BUILD_NOTES.md
+ * ("Re-timing is now a 5-number change. The stops inside each walk scene
+ * AUTO-DISTRIBUTE to fill the scene duration").
+ */
+export const stopsAsRelativeSpacing: Rule = {
+  id: "stops-as-relative-spacing",
+  claim: "Author walkthrough stop from values as relative spacing and rescale them with distributeStops; never as absolute frame positions.",
+  why: "Absolute stop frames make every VO re-record a re-authoring of every stop instead of a re-measure; with relative spacing a re-time collapses to changing the per-section durations.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-kit/src/pure/walk.ts", symbol: "distributeStops" },
+  },
+};

package/src/rules/theWholeCanvasWorks.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 6 ("the whole scene only
+ * takes the middle of the screen - take this scene up a notch", "make the
+ * SVGs bigger, they look so small compared to their containers", "make the
+ * text bigger"). hero-fills-the-frame owns hero scale; this rule owns the
+ * rest of the canvas and the type floor.
+ */
+export const theWholeCanvasWorks: Rule = {
+  id: "the-whole-canvas-works",
+  claim: "Compose across the whole frame: a scene that lives only in the middle band with the outer thirds idle reads as low effort, small art never sits inside a big container, and type scales up whenever legibility is questioned - at 1080p, text under roughly 15px is a defect.",
+  why: "'The whole scene only takes the middle of the screen' and 'make the text bigger' recurred even when the hero itself passed its size check; hero scale alone did not catch compositions that centered everything in a small band of the canvas.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A whole-frame composition judgment per shot; no single code location expresses it.",
+  },
+};

package/src/rules/themePerSection.ts

@@ -0,0 +1,28 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md: "Theme | dark · light · mixed (act854:
+ * dark intro/outro + light pages) | Must be per-section, token-driven".
+ * Token modules are the mechanism that makes per-section theming a data
+ * change.
+ */
+export const themePerSection: Rule = {
+  id: "theme-per-section",
+  claim: "Treat theme (dark or light) as a per-section, token-driven variable, never a per-video constant.",
+  why: "Real briefs mix themes within one video (act854: dark intro/outro plus light pages); a per-video theme assumption forces a structural rewrite mid-build.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "craft",
+  exceptions: [
+    {
+      project: "qse-qguard-video",
+      decision:
+        "client chose one dark canvas across all seven sections for the QGuard restyle; light survives as panel surfaces inside the dark shell, not as a per-section world",
+      recordedIn: "qse-qguard-video/docs/motion-brand-spec.md",
+    },
+  ],
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/tokens.ts" },
+  },
+};

package/src/rules/thesisDeclaredInBrief.ts

@@ -0,0 +1,25 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/superpowers/specs/2026-07-31-defect-radar-design.md: the
+ * Klaviyo round-4 escaped defect ("the v1 brief transcribed the source's
+ * facts but buried its thesis") cost a rewritten scene, a full VO regen, and
+ * a re-render, because the misread was authored before any scene was built.
+ * `brief-structure`'s `missing-thesis` finding is the check that would have
+ * caught it: a brief with no `Thesis:` line has, structurally, no argument to
+ * check every scene against.
+ */
+export const thesisDeclaredInBrief: Rule = {
+  id: "thesis-declared-in-brief",
+  claim: "Every brief opens with a \"Thesis: <one sentence>\" line stating the video's one-sentence argument, before any step-by-step content.",
+  why: "A brief that transcribes the source's facts without stating its own argument reads as complete while leaving every scene to guess what it is supposed to prove; the Klaviyo v1 plan walked the UI and never argued the payoff, discovered only after a full build.",
+  learnedFrom: "docs/superpowers/specs/2026-07-31-defect-radar-design.md",
+  tier: "gate",
+  verify: "`video radar:plan --project <dir>` (check: `brief-structure`)",
+  owner: "brief-structure",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is a document-structure judgment over prose the brief author writes; no single code location expresses it.",
+  },
+};

package/src/rules/tierARequiresPropUnreachableEdit.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md: "Recurrence across videos makes a
+ * component a Tier A CANDIDATE, never an automatic port ... a fork must buy
+ * something props cannot." The anchor is the Tier A home the rule gates
+ * entry to.
+ */
+export const tierARequiresPropUnreachableEdit: Rule = {
+  id: "tier-a-requires-prop-unreachable-edit",
+  claim: "Promote a component to Tier A only when it needs an internal edit that props, CSS vars, or the variant API cannot reach; recurrence across videos alone never justifies a port.",
+  why: "Unnecessary ports create owned forks that must be manually rebased forever, for zero gain, since props already brand a Tier B component with zero source changes.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-kit/src/motion/index.ts" },
+  },
+};

package/src/rules/tinyBodyCopyAsRuledLines.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "Body copy stays as fine
+ * ruled lines (real text is noise at that size); everything else is genuine
+ * content." The exemplar is DocStrip in S1Graveyard.tsx.
+ */
+export const tinyBodyCopyAsRuledLines: Rule = {
+  id: "tiny-body-copy-as-ruled-lines",
+  claim: "In miniature document props, render body copy as fine ruled lines and reserve real text for headings, numbers, and callouts.",
+  why: "Real body text at that scale is visual noise; the hero PDF reads as a genuine dense document precisely because the unreadable parts are abstracted to lines while every scannable element is real content.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/S1Graveyard.tsx", symbol: "DocStrip" },
+  },
+};

package/src/rules/titlesPinnedOutsideCameraPush.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-usecase-win-booth.md ("when
+ * zoomed in, the text overflows the screen"; the locked taste summary:
+ * "titles pinned outside camera push") and portfolio-reels.md's overflow
+ * family ("Everything is overflowing at the sides"). Narrower than
+ * cross-cut-elements-live-in-the-hud-layer, which covers seam contracts at
+ * cuts; this covers titles during in-scene camera travel.
+ */
+export const titlesPinnedOutsideCameraPush: Rule = {
+  id: "titles-pinned-outside-camera-push",
+  claim: "Render titles and captions in screen space outside the camera transform, so a camera push can never scale them off screen; verify framing with stills at the camera's extreme positions.",
+  why: "Titles placed inside the camera transform overflowed the frame at zoom peaks in two videos; screen-space pinning removes the whole defect class instead of re-tuning per zoom.",
+  learnedFrom: "claude-sessions-digest/revola-usecase-win-booth.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-kit/src/react/motion.ts" },
+  },
+};

package/src/rules/tokensNotRawHexes.test.ts

@@ -0,0 +1,51 @@
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { toolchainRepoRoot as repoRoot } from "../testSupport";
+import { checkFile } from "../sourceCheck";
+import { tokensNotRawHexes } from "./tokensNotRawHexes";
+
+const check = () => {
+  if (tokensNotRawHexes.enforcement.kind !== "source") throw new Error("expected a source rule");
+  return tokensNotRawHexes.enforcement.check;
+};
+
+const run = (name: string) => {
+  const rel = `packages/video-craft/src/fixtures/${name}`;
+  return checkFile(check(), join(repoRoot, rel), rel, repoRoot);
+};
+
+describe("tokensNotRawHexes", () => {
+  test("fires once per raw palette hex, in strings and templates, skipping white/black", () => {
+    const findings = run("raw-hex-scene.tsx");
+    expect(findings).toHaveLength(2);
+    expect(findings[0].line).toBe(6);
+    expect(findings[0].match).toBe("#0E1420");
+    expect(findings[1].line).toBe(7);
+    expect(findings[1].match).toBe("#9C33FF");
+    for (const f of findings) expect(f.message).toMatch(/hex/);
+  });
+
+  test("does not fire on token references or rgba() strings", () => {
+    expect(run("token-scene.tsx")).toEqual([]);
+  });
+
+  test("scopes to the films that adopted the tokens doctrine", () => {
+    // Older projects and revola-video's pre-craft scenes are frozen shipped
+    // films; sweeping them in floods the check with pre-doctrine code
+    // (corpus calibration hit ~150 findings there). New projects enroll from
+    // day one, scenes only - the token module itself lives outside scenes/.
+    expect(check().include).toEqual([
+      "revola-video/src/scenes/craft/**/*.tsx",
+      "rcp-fund7-video/src/scenes/**/*.{ts,tsx}",
+      "expanse-video/src/scenes/**/*.{ts,tsx}",
+      "reverence-video/src/scenes/**/*.{ts,tsx}",
+      "workday-dple-video/src/scenes/**/*.{ts,tsx}",
+    ]);
+    // Rebuilt product-UI mocks carry their own in-file demo palettes by
+    // design (sample-brand-from-product content, not film styling).
+    expect(check().exclude).toEqual([
+      "revola-video/src/scenes/craft/NorthwindUI.tsx",
+      "revola-video/src/scenes/craft/RestyleScenes.tsx",
+    ]);
+  });
+});

package/src/rules/tokensNotRawHexes.ts

@@ -0,0 +1,89 @@
+import { SyntaxKind } from "ts-morph";
+import type { Rule, SourceFinding } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md ("Palette centralized in CK
+ * (src/tokensCraft.ts) - scenes reference only CK tokens, no raw hexes") and
+ * HOW_I_BUILD_VIDEOS.md ("Tokens everywhere. One theme.js per look; scenes
+ * never hard-code a color. Dark/light/brand then costs one file.").
+ *
+ * Scoped to the craft film only: that is the build that adopted the tokens
+ * doctrine. Older projects AND revola-video's pre-craft scenes are frozen
+ * shipped films; corpus calibration proved sweeping them in floods the check
+ * with ~150 pre-doctrine findings. rgba()/hsl() strings are deliberately not
+ * flagged - hex only. Pure white/black (#fff, #000) is also not flagged:
+ * those are specular/glint constants, not palette - the dark regrade shipped
+ * with dozens of them unchanged, which is the rule's own test of what
+ * "palette" means.
+ */
+
+const HEX = /#[0-9a-fA-F]{3,8}\b/g;
+
+const WHITE_BLACK = new Set(["#fff", "#ffffff", "#000", "#000000"]);
+
+/** The palette hexes (not pure white/black) in the text, in order. */
+function paletteHexes(text: string): string[] {
+  return [...text.matchAll(HEX)].map((m) => m[0]).filter((h) => !WHITE_BLACK.has(h.toLowerCase()));
+}
+
+// Template literals with substitutions are scanned through their text chunks
+// (head/middle/tail), never as the whole TemplateExpression: scanning the
+// whole expression would double-count a hex that sits inside a substitution's
+// own string literal.
+const LITERAL_KINDS = [
+  SyntaxKind.StringLiteral,
+  SyntaxKind.NoSubstitutionTemplateLiteral,
+  SyntaxKind.TemplateHead,
+  SyntaxKind.TemplateMiddle,
+  SyntaxKind.TemplateTail,
+];
+
+export const tokensNotRawHexes: Rule = {
+  id: "tokens-not-raw-hexes",
+  claim: "Never hard-code a hex color in a scene file; every color comes from the token module.",
+  why: "A regrade (light-to-dark) is a one-file change when the palette is centralized; scattered hexes make every restyle a hunt. Melisa's dark-regrade was one file because of this.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "gate",
+  // The old wording promised "machine-checked over scene and kit source". It
+  // never covered kit source (no packages/ glob has ever been in `include`),
+  // and after the 2026-08-24 extraction its four film roots stayed upstream,
+  // so in this repo it reaches zero files while still reading as an enforced
+  // gate. `includeCoverage.test.ts` now fails on any source rule that matches
+  // nothing, so this cannot go quiet again without a declared reason.
+  verify: "`vitest run packages/video-craft` - machine-checked over projects carrying a committed token module; the fixture projects in this repo have none, so it currently reaches no file",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "source",
+    check: {
+      include: ["revola-video/src/scenes/craft/**/*.tsx", "rcp-fund7-video/src/scenes/**/*.{ts,tsx}", "expanse-video/src/scenes/**/*.{ts,tsx}", "reverence-video/src/scenes/**/*.{ts,tsx}", "workday-dple-video/src/scenes/**/*.{ts,tsx}"],
+      exclude: [
+        // Rebuilt product-UI mocks: their palettes are scene CONTENT (an
+        // in-file light/dark/warm theme demo, a restyle showcase), sampled
+        // per sample-brand-from-product, not the film's own styling.
+        "revola-video/src/scenes/craft/NorthwindUI.tsx",
+        "revola-video/src/scenes/craft/RestyleScenes.tsx",
+      ],
+      run: (file, relPath): SourceFinding[] => {
+        const findings: SourceFinding[] = [];
+        for (const kind of LITERAL_KINDS) {
+          for (const literal of file.getDescendantsOfKind(kind)) {
+            // One finding per hex occurrence, not per literal: a gradient
+            // string with two palette hexes is two findings, so a second hex
+            // is never silently carried by an exception for the first.
+            for (const hex of paletteHexes(literal.getText())) {
+              findings.push({
+                file: relPath,
+                line: literal.getStartLineNumber(),
+                match: hex,
+                message:
+                  "raw hex color in a scene file. Move it into the token module and reference the token; " +
+                  "a centralized palette makes a regrade a one-file change.",
+              });
+            }
+          }
+        }
+        return findings;
+      },
+    },
+  },
+};

package/src/rules/typeTokenDefaultedParamsAsString.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "ink() helper defaulted
+ * stroke = CK.ink; CK is as const so TS narrowed the param to that one
+ * literal hex and rejected every other colour. Typed stroke: string." Same
+ * class as the earlier row.n literal-union guard - it recurs whenever
+ * as-const tokens seed defaults.
+ */
+export const typeTokenDefaultedParamsAsString: Rule = {
+  id: "type-token-defaulted-params-as-string",
+  claim: "Explicitly type any parameter whose default is a token from an as-const object (e.g. stroke: string = CK.ink).",
+  why: "Without the annotation TS narrows the parameter to that single literal and rejects every other value; the ink() helper's defaulted stroke accepted exactly one hex until typed string.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/tokensCraft.ts", symbol: "CK" },
+  },
+};

package/src/rules/varyKitChoreographyAcrossSections.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * The machine-checked companion of distinct-transition-per-beat and
+ * one-punch-per-moment-class: those govern transitions and punches as prose;
+ * this covers only what they do not, component/variant repetition across a
+ * plan's sections, and is enforced by lint (adjacent-section and
+ * share-of-sections warnings over uses[] component+variant pairs).
+ */
+export const varyKitChoreographyAcrossSections: Rule = {
+  id: "vary-kit-choreography-across-sections",
+  claim: "Never lean on the same kit component+variant pair in adjacent sections or in more than half of a video's sections; vary the variant or the component so each beat reads authored.",
+  why: "Kit primitives make repetition frictionless, and a video whose every section opens with the same odometer or the same bar-grow reads as template output; the WS3 spec makes this the plan-stage de-sameness gate.",
+  learnedFrom: "docs/superpowers/specs/2026-07-24-ws3-theme-variant-api-design.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/lint.ts", symbol: "lint" },
+  },
+};

package/src/rules/varyTheVisualizationGrammar.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 5 ("research any new
+ * packages on react that will look good for visualizations. like heatmaps,
+ * 3d stuff", "use different visualizations, be creative", "professional
+ * custom SVG animations that represent maturing debt and new lending
+ * properly" - never "just some lines and shapes"). The harbor-map pattern
+ * is the approved shape for external packages: pull data at authoring time.
+ */
+export const varyTheVisualizationGrammar: Rule = {
+  id: "vary-the-visualization-grammar",
+  claim: "Every concept gets its own visual form - heatmap, real-geography map, dial, ledger, odometer, glyph field, architectural elevation - that genuinely depicts the concept; never two adjacent beats in the same grammar, never abstract lines-and-shapes filler, and external visualization packages are sanctioned with their data and assets pulled at authoring time so renders stay deterministic.",
+  why: "'Use different visualizations, be creative' and the demand for SVG animations that 'represent maturing debt and new lending properly' recurred across builds; same-grammar adjacent beats and abstract filler both drew the template verdict.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A concept-to-form mapping judgment across beats; no single code location expresses it.",
+  },
+};

package/src/rules/verifyCheapRenderDear.ts

@@ -0,0 +1,18 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md: "Verify cheap, render dear. esbuild
+ * bundle + typecheck as the CI-style gate ... full render only on request."
+ */
+export const verifyCheapRenderDear: Rule = {
+  id: "verify-cheap-render-dear",
+  claim: "Gate every change with the cheap checks (bundle + typecheck, Studio scrub, per-beat stills) and run the full render only on demand, last.",
+  why: "A full render costs minutes of CPU; using it as a routine check turns every iteration loop from seconds into minutes and starves the machine.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/typecheckAll.ts" },
+  },
+};

package/src/rules/voAddressesTheViewer.ts

@@ -0,0 +1,18 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-craft-video.md: "why do you say
+ * we send them a long pdf,.. it should be 'you send them a long pdf'".
+ */
+export const voAddressesTheViewer: Rule = {
+  id: "vo-addresses-the-viewer",
+  claim: "The voiceover addresses the viewer as 'you'; the pain is something you experience, never something 'we' do to them.",
+  why: "A 'we send them a long pdf' line made the vendor the villain of its own pitch; point of view is a one-word bug with a whole-script blast radius.",
+  learnedFrom: "claude-sessions-digest/revola-craft-video.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/voice.ts" },
+  },
+};

package/src/rules/voIsAPerformance.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 17 ("consistent and
+ * confident throughout", "don't use [calm], it sounds boring", never
+ * "fluctuating like describing a fairytale"). Full takes were re-recorded
+ * over tone alone; the wording rules live in vo-script-locks-spoken-words
+ * and vo-addresses-the-viewer - this rule owns the performance.
+ */
+export const voIsAPerformance: Rule = {
+  id: "vo-is-a-performance",
+  claim: "The read is steady, confident, and energetic - never robotic, never fairytale-fluctuating, never tagged [calm] - and the VO never reads the screen: it adds the aside and the why, and deliberately goes silent under hero visuals.",
+  why: "'Don't use [calm], it sounds boring' and 'consistent and confident throughout' triggered full re-records on tone alone; a technically clean take with the wrong performance cost the same round a broken one would.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A performance judgment on the recorded read; no single code location expresses it.",
+  },
+};

package/src/rules/voScriptLocksSpokenWords.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md ("Write the script so acronyms are spelled
+ * the way you want them spoken ... the recording bakes it in"), merged with
+ * act854-video/BUILD_NOTES.md's recorded instance ("speech 9 was recorded
+ * from the 'Bill of Materials' spelled-out variant - re-record from v6 if you
+ * want the acronyms spoken"). Covers acronym spelling AND final wording.
+ */
+export const voScriptLocksSpokenWords: Rule = {
+  id: "vo-script-locks-spoken-words",
+  claim: "Finalize the exact spoken wording in the VO script before recording, including spelling acronyms the way they must be spoken.",
+  why: "The recording bakes the words in: audio that says 'Bill of Materials' when the client expects the acronym spoken is discovered only after the build is wired to that WAV, and the fix is a re-record.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/voice.ts" },
+  },
+};

package/src/rules/wrappersPreserveChildGeometry.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from the product-room build: swapping hand-built cards for a shared
+ * GlassPanel broke two invariants at once. Padding moved to the outer element
+ * (so callers' spacing vanished) and the content wrapper had no height (so a
+ * child at `inset: 24` collapsed and an entire micro-walkthrough rendered as
+ * an empty rectangle). Wrapper components are exactly where a single edit
+ * reaches every scene, so their geometry contract has to be explicit.
+ */
+export const wrappersPreserveChildGeometry: Rule = {
+  id: "wrappers-preserve-child-geometry",
+  claim: "A shared surface or wrapper component must preserve its children's geometry: keep the padding semantics its callers expect and give its content box the panel's full size so absolutely positioned children still resolve against it.",
+  why: "A glass wrapper introduced mid-build put padding on the outer box and wrapped children in a zero-height div, which silently removed every panel's padding and collapsed every absolutely positioned child across all five scenes at once - one component, whole-film blast radius.",
+  learnedFrom: "claude-sessions-digest/product-room-video.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/productroom/Glass.tsx" },
+  },
+};

package/src/sourceCheck.test.ts

@@ -0,0 +1,50 @@
+import { join } from "node:path";
+import { SyntaxKind } from "ts-morph";
+import { describe, expect, test } from "vitest";
+import { toolchainRepoRoot as repoRoot } from "./testSupport";
+import { checkFile, runSourceCheck } from "./sourceCheck";
+import type { SourceCheck } from "./types";
+
+const countJsxElements: SourceCheck = {
+  include: ["packages/video-craft/src/fixtures/*.tsx"],
+  run: (file, relPath) =>
+    file.getDescendantsOfKind(SyntaxKind.JsxOpeningElement).map((node) => ({
+      file: relPath,
+      line: node.getStartLineNumber(),
+      match: node.getText().slice(0, 60),
+      message: "element",
+    })),
+};
+
+describe("checkFile", () => {
+  test("reports findings with the repo-relative path, not the absolute one", () => {
+    const rel = "packages/video-craft/src/fixtures/nested-filters-fixed.tsx";
+    const findings = checkFile(countJsxElements, join(repoRoot, rel), rel, repoRoot);
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings.every((f) => f.file === rel)).toBe(true);
+  });
+});
+
+describe("runSourceCheck", () => {
+  test("visits every file matched by the globs", () => {
+    const files = new Set(runSourceCheck(countJsxElements, repoRoot).map((f) => f.file));
+    expect(files).toContain("packages/video-craft/src/fixtures/nested-filters-broken.tsx");
+    expect(files).toContain("packages/video-craft/src/fixtures/nested-filters-fixed.tsx");
+  });
+
+  test("returns nothing when the globs match nothing", () => {
+    expect(runSourceCheck({ ...countJsxElements, include: ["no/such/dir/*.tsx"] }, repoRoot)).toEqual([]);
+  });
+
+  test("never descends into node_modules", () => {
+    const check: SourceCheck = { ...countJsxElements, include: ["**/*.tsx"] };
+    expect(runSourceCheck(check, repoRoot).every((f) => !f.file.includes("node_modules"))).toBe(true);
+  });
+
+  test("honors a per-check exclude glob", () => {
+    const check: SourceCheck = { ...countJsxElements, exclude: ["**/nested-filters-broken.tsx"] };
+    const files = new Set(runSourceCheck(check, repoRoot).map((f) => f.file));
+    expect(files).not.toContain("packages/video-craft/src/fixtures/nested-filters-broken.tsx");
+    expect(files).toContain("packages/video-craft/src/fixtures/nested-filters-fixed.tsx");
+  });
+});