@revola-ai/video-craft 0.2.1

package/src/rules/dataRadarTagsDeclared.ts

@@ -0,0 +1,341 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { globSync } from "tinyglobby";
+import { SyntaxKind, type JsxAttribute, type SourceFile } from "ts-morph";
+import { parse as parseYaml } from "yaml";
+import { matchedFiles } from "../sourceCheck";
+import type { Rule, SourceCheck, SourceFinding } from "../types";
+
+/**
+ * Mined from docs/superpowers/specs/2026-07-31-defect-radar-design.md: "the
+ * hero and every element the plan's `names:` map declares carry `data-radar`
+ * attributes; the source-level vitest gate in packages/video-craft checks
+ * scene source against the declared element ids, so the gate verifies the
+ * binding, not merely that some tag exists." (line 334). The runtime
+ * counterpart is the `tag-coverage` radar check, which verifies the same
+ * binding against SAMPLED frames; this rule is the free, no-render
+ * precondition - a typo'd or forgotten `data-radar` attribute is a build-time
+ * fact, not something that needs a render to discover.
+ *
+ * SCOPE: PER PROJECT, NOT PER SCENE FILE (final-review I4).
+ *
+ * The first implementation asked "does THIS file carry a `data-radar` for
+ * every element the plan binds to the section THIS file implements", matching
+ * file to section by `exportedNames.has(section.component)`. Both halves were
+ * wrong against the first real adopter:
+ *
+ *  1. The name match never fired. `qse-qguard-video/plan.qguard.yaml` declares
+ *     `component: S1LoginChecksOnce` while the module exports `S1Once` (and
+ *     five more in the same shape), so the rule returned zero findings on the
+ *     pilot and read as clean. `video lint` now emits a WARNING for exactly
+ *     that mismatch - it is also the root cause of the fabricated `where.file`
+ *     path on every QGuard finding (`sceneFileOf` returns `component`
+ *     verbatim) - but it is a plan-hygiene defect, not this rule's subject.
+ *  2. Even with a correct file match, per-file scope would produce FALSE
+ *     POSITIVES. A section's declared element is routinely tagged in a child
+ *     component, not in the scene module: QGuard's `login-scanner` lives in
+ *     `src/artifacts/Stations.tsx`, its `branch-*` ids in `Theft.tsx`. Which
+ *     module renders inside a scene at runtime is not decidable from JSX text,
+ *     and guessing it would make a Gate-tier rule fire on correct code.
+ *
+ * So the honest source-level claim is the project-wide one: every id the plan
+ * declares is tagged SOMEWHERE in that project's source. Binding a tag to the
+ * right scene, at the right frame, is what the runtime `tag-coverage` check
+ * settles against sampled geometry - and it cannot be settled here.
+ *
+ * WHAT IS AND IS NOT PINNED, since project-wide is the weaker claim and a
+ * future reader should not over-read the evidence:
+ *
+ *  - The CLEAN side on the pilot IS continuously checked. `corpus.test.ts`
+ *    runs every source rule over every matched file, qse-qguard-video
+ *    included, and fails on any finding that is not a justified
+ *    KNOWN_EXCEPTIONS entry. If QGuard ever declares an id nothing tags, the
+ *    suite goes red on the real project, not just on a fixture.
+ *
+ *    What keeps that pin from being hollow: this rule carries NO
+ *    KNOWN_EXCEPTIONS rows at all, so nothing on the pilot is excused. An
+ *    exception added here would quietly convert "the pilot is clean" into
+ *    "the pilot's failures are listed elsewhere" - which is the same
+ *    green-because-nobody-looked state the include-glob drift gate
+ *    (`includeCoverage.test.ts`) exists to prevent. Add one only with a
+ *    reason that survives being read back a year later.
+ *  - The RED side is pinned on FIXTURES only (`../fixtures/data-radar-*`: a
+ *    missing tag, a sibling-file tag, a template family, a forwarded prop,
+ *    an uninterpretable expression). The equivalent demonstration on the
+ *    pilot - typo one declared id, get exactly one finding - was run by hand
+ *    at the final-review fix wave and is deliberately not committed: the
+ *    only way to assert it would be to keep a broken copy of a client plan
+ *    in the tree.
+ */
+
+type PlanSection = {
+  id?: string;
+  component?: string;
+  names?: { element?: string | null }[];
+};
+
+type PlanLike = { sections?: PlanSection[] };
+
+const toPosix = (p: string): string => p.split(sep).join("/");
+
+/**
+ * Every project layout, enumerated explicitly - the silent-default trap
+ * `deterministic-scene-source` was already bitten by once (act854-video's
+ * scenes live under qpa-video/03_scenes/act854, and
+ * klaviyo-segments-video/radar-fixture-video were never added to any rule's
+ * include list). Ten entries: `ls -d *-video spec-videos` at implementation
+ * time (2026-08-02) plus datapeak-usecases, which that glob does not match but
+ * which other source-check rules already cover.
+ */
+export const INCLUDE = [
+  "qpa-video/03_scenes/**/*.{js,jsx,ts,tsx}",
+  "revola-video/src/scenes/**/*.{js,jsx,ts,tsx}", "workday-dple-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}",
+  "spec-videos/**/*.{js,jsx,ts,tsx}",
+  "klaviyo-segments-video/**/*.{js,jsx,ts,tsx}",
+  "radar-fixture-video/src/**/*.{js,jsx,ts,tsx}",
+  "rcp-fund7-video/src/**/*.{ts,tsx}",
+  "expanse-video/src/**/*.{ts,tsx}",
+  "reverence-video/src/**/*.{ts,tsx}",
+];
+
+/**
+ * Walks up from `startDir` toward `root`, returning the first directory
+ * (inclusive of `startDir`) that contains at least one `plan*.yaml`. A
+ * project's plan lives at its own root (`qse-qguard-video/plan.qguard.yaml`),
+ * not necessarily next to the scene file that implements one of its
+ * sections, so this looks upward rather than assuming a fixed depth.
+ */
+export function findPlanDir(startDir: string, root: string): string | null {
+  let dir = startDir;
+  for (;;) {
+    if (globSync("plan*.yaml", { cwd: dir }).length > 0) return dir;
+    if (dir === root || !dir.startsWith(root)) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** Every `names:`-declared, non-null element id in `planDir`'s plans, with the
+ *  section that declared it. Null bindings (`element: null`, an honest "no
+ *  single subject") are excluded, same as the runtime `tag-coverage` check. */
+export function declaredElements(planDir: string, root: string): { sectionId: string; elementId: string; planFile: string }[] {
+  const out: { sectionId: string; elementId: string; planFile: string }[] = [];
+  for (const planFile of globSync("plan*.yaml", { cwd: planDir, absolute: true })) {
+    let plan: PlanLike;
+    try {
+      plan = parseYaml(readFileSync(planFile, "utf8")) as PlanLike;
+    } catch {
+      continue; // A malformed plan is `lint`'s problem, not this check's.
+    }
+    for (const section of plan.sections ?? []) {
+      for (const binding of section.names ?? []) {
+        if (typeof binding.element !== "string") continue;
+        out.push({
+          sectionId: section.id ?? "(unnamed section)",
+          elementId: binding.element,
+          planFile: toPosix(relative(root, planFile)),
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/** What a project's source says about `data-radar`. */
+type TagIndex = {
+  /** Statically known tag values. */
+  literals: Set<string>;
+  /** Templates with substitutions, e.g. `` `branch-${kind}` `` -> /^branch-.+$/.
+   *  A declared id matching one is accepted: the source demonstrably tags a
+   *  family the id belongs to, and refusing it would be a false positive. */
+  patterns: RegExp[];
+  /** `data-radar={expr}` sites this analysis could not turn into any value.
+   *  A project with one cannot be checked honestly, so it is reported as a
+   *  finding of its own rather than silently reading as clean. */
+  opaque: { file: string; line: number; text: string }[];
+};
+
+const isTagAttrName = (name: string): boolean => name === "data-radar";
+
+/** The prop-passthrough convention: a component that forwards a tag takes it
+ *  as a prop named `dataRadar` (`data-radar={dataRadar}`), and the real ids
+ *  are the string literals its CALL SITES pass. Resolving those is what keeps
+ *  a forwarding component from making the whole project unverifiable. */
+const attrLiteralsByName = (files: SourceFile[]): Map<string, Set<string>> => {
+  const byName = new Map<string, Set<string>>();
+  for (const file of files) {
+    for (const attr of file.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      const value = literalOf(attr.getInitializer());
+      if (value === null) continue;
+      const name = attr.getNameNode().getText();
+      const set = byName.get(name) ?? new Set<string>();
+      set.add(value);
+      byName.set(name, set);
+    }
+  }
+  return byName;
+};
+
+/** The string value of a JSX attribute initializer, when it has one:
+ *  `x="s"`, `x={"s"}`, and `` x={`s`} `` (no substitutions) all count. */
+function literalOf(init: ReturnType<JsxAttribute["getInitializer"]>): string | null {
+  if (!init) return null;
+  if (init.isKind(SyntaxKind.StringLiteral)) return init.getLiteralValue();
+  if (init.isKind(SyntaxKind.JsxExpression)) {
+    const expr = init.getExpression();
+    if (!expr) return null;
+    if (expr.isKind(SyntaxKind.StringLiteral)) return expr.getLiteralValue();
+    if (expr.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)) return expr.getLiteralValue();
+  }
+  return null;
+}
+
+/** A template with substitutions as a pattern: every `${...}` becomes `.+`,
+ *  every literal chunk is escaped. `` `branch-${kind}` `` -> /^branch-.+$/. */
+function templatePattern(text: string): RegExp | null {
+  const body = text.replace(/^`|`$/g, "");
+  if (!body.includes("${")) return null;
+  const escaped = body
+    .split(/\$\{[^}]*\}/g)
+    .map((chunk) => chunk.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".+");
+  return new RegExp(`^${escaped}$`);
+}
+
+function buildTagIndex(files: SourceFile[], root: string): TagIndex {
+  const literals = new Set<string>();
+  const patterns: RegExp[] = [];
+  const opaque: { file: string; line: number; text: string }[] = [];
+  const byAttrName = attrLiteralsByName(files);
+
+  for (const file of files) {
+    const rel = toPosix(relative(root, file.getFilePath()));
+    for (const attr of file.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      if (!isTagAttrName(attr.getNameNode().getText())) continue;
+      const init = attr.getInitializer();
+      const literal = literalOf(init);
+      if (literal !== null) { literals.add(literal); continue; }
+      const expr = init?.isKind(SyntaxKind.JsxExpression) ? init.getExpression() : undefined;
+      if (expr?.isKind(SyntaxKind.TemplateExpression)) {
+        const pattern = templatePattern(expr.getText());
+        if (pattern) { patterns.push(pattern); continue; }
+      }
+      if (expr?.isKind(SyntaxKind.Identifier)) {
+        // A forwarded tag: take the literals its call sites pass for the
+        // prop of the same name. Empty means nothing in the project ever
+        // passes it a literal, which is genuinely unverifiable here.
+        const forwarded = byAttrName.get(expr.getText());
+        if (forwarded?.size) { for (const v of forwarded) literals.add(v); continue; }
+      }
+      opaque.push({ file: rel, line: attr.getStartLineNumber(), text: attr.getText().slice(0, 60) });
+    }
+  }
+  return { literals, patterns, opaque };
+}
+
+const IGNORES = ["**/node_modules/**", "**/.worktrees/**", "**/04_exports/**", "**/*.test.{ts,tsx,jsx}", "**/build/**"];
+
+/** The project's own source files that this rule's `include` globs reach. */
+const includedUnder = (planDir: string, check: SourceCheck, root: string): string[] =>
+  matchedFiles(check, root).filter((f) => f.startsWith(planDir + sep));
+
+/**
+ * Every source file of the project, because a declared id is routinely tagged
+ * in a child component rather than in the scene module.
+ *
+ * Falls back to a plain walk of `planDir` when the rule's own `include` globs
+ * reach nothing there - the `checkFile()` unit-test path, whose fixture
+ * projects live under packages/video-craft/src/fixtures and are deliberately
+ * outside the corpus globs. Without the fallback a fixture would be checked
+ * against its own single file and report every id its siblings tag.
+ */
+export function projectSourceFiles(planDir: string, check: SourceCheck, root: string): string[] {
+  const included = includedUnder(planDir, check, root);
+  if (included.length) return included;
+  return globSync("**/*.{js,jsx,ts,tsx}", { cwd: planDir, absolute: true, ignore: IGNORES }).sort();
+}
+
+/**
+ * The one file per project that reports its project-wide findings.
+ *
+ * `runSourceCheck` calls `run` once per matched file, in sorted order, so a
+ * project-wide finding emitted from every file would appear once per file.
+ * The first matched file under the project is a stable, deterministic
+ * reporter. A file outside the include set entirely (the unit-test path
+ * above) reports for itself, so a fixture is never silently unchecked.
+ */
+export function isReporterFile(planDir: string, absPath: string, check: SourceCheck, root: string): boolean {
+  const included = includedUnder(planDir, check, root);
+  return included.length === 0 || included[0] === absPath;
+}
+
+export const dataRadarTagsDeclared: Rule = {
+  id: "data-radar-tags-declared",
+  claim: "Every element id a plan's `names:` binding declares carries a matching `data-radar` attribute somewhere in that project's source.",
+  why: "vo-element-sync joins a declared binding to speech-map timings and geometry samples; a declared element-id with no matching data-radar tag anywhere in the project is a certain finding, and catching it at authoring time (no render, no sampler) is strictly cheaper than catching it at radar:scene time.",
+  learnedFrom: "docs/superpowers/specs/2026-07-31-defect-radar-design.md",
+  tier: "gate",
+  verify: "`vitest run packages/video-craft` (source-level, no render) - `video radar:scene --project <dir> --comp <id> --check tag-coverage` re-verifies the same binding against sampled frames at runtime",
+  owner: "tag-coverage",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "source",
+    check: {
+      include: INCLUDE,
+      run(file, relPath, root): SourceFinding[] {
+        const absPath = join(root, relPath);
+        const planDir = findPlanDir(dirname(absPath), root);
+        if (!planDir || !existsSync(planDir)) return [];
+        if (dataRadarTagsDeclared.enforcement.kind !== "source") return [];
+        const selfCheck = dataRadarTagsDeclared.enforcement.check;
+        if (!isReporterFile(planDir, absPath, selfCheck, root)) return [];
+
+        const declared = declaredElements(planDir, root);
+        if (declared.length === 0) return [];
+
+        // Parsed in the SAME ts-morph Project the runner already built
+        // (re-adding an open file is a no-op), so the whole-project scan
+        // costs one parse per file per pass, not one per file per file.
+        const project = file.getProject();
+        const index = buildTagIndex(
+          projectSourceFiles(planDir, selfCheck, root).map((f) => project.addSourceFileAtPath(f)),
+          root,
+        );
+
+        const findings: SourceFinding[] = [];
+        for (const site of index.opaque) {
+          findings.push({
+            file: site.file,
+            line: site.line,
+            match: site.text,
+            message: `data-radar is bound to an expression this gate cannot evaluate (${site.text}), so no declared `
+              + `element id in ${toPosix(relative(root, planDir))} can be verified from source. Use a string `
+              + `literal, a template whose literal prefix is stable, or forward it through a prop named `
+              + `\`dataRadar\` that call sites pass a literal to.`,
+          });
+        }
+        if (findings.length) return findings;
+
+        for (const { sectionId, elementId, planFile } of declared) {
+          if (index.literals.has(elementId)) continue;
+          if (index.patterns.some((p) => p.test(elementId))) continue;
+          findings.push({
+            file: planFile,
+            line: 1,
+            match: elementId,
+            message: `plan section "${sectionId}" declares names: element "${elementId}", but no data-radar="${elementId}" `
+              + `attribute exists anywhere in ${toPosix(relative(root, planDir))}'s source. Tag the element the cue `
+              + `names, or make the binding an explained \`element: null\`.`,
+          });
+        }
+        return findings;
+      },
+    },
+  },
+};

package/src/rules/declareAVerticalZoneMap.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "ZONE MAP now declared at the
+ * top of S3Line.tsx (same device as S1's): copy 96-290 · BREATH 290-420
+ * (nothing may enter) · stage 420-840".
+ */
+export const declareAVerticalZoneMap: Rule = {
+  id: "declare-a-vertical-zone-map",
+  claim: "Declare a vertical zone map at the top of each scene file - copy band, breath band (nothing may enter), stage band - and make camera keys and world layout enforce that animation never rises into the copy band.",
+  why: "Without declared bands, text and animation collide (a tag overlapping the headline, fog slicing the clock) and each collision gets patched ad hoc.",
+  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/deleteRejectedRigsCompletely.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "LightBridge + BRIDGE_* + the
+ * CraftStage overlay prop: deleted, not left dead. S2's overlay usage
+ * reverted."
+ */
+export const deleteRejectedRigsCompletely: Rule = {
+  id: "delete-rejected-rigs-completely",
+  claim: "When a transition or effect is rejected in review, delete the rig, its tokens, and its plumbing (props, overlay slots) entirely; revert call sites rather than leaving the machinery dead.",
+  why: "The rejected light bridge left LightBridge, BRIDGE_* tokens, and the CraftStage overlay prop as attractive dead plumbing; deleting it and reverting S2's usage is what makes the rejection stick.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The artifact of following this rule is the absence of code; there is no symbol to point at.",
+  },
+};

package/src/rules/deriveSeamsDontMeasure.ts

@@ -0,0 +1,23 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md, "S2 pass 3 - the seam is now
+ * DERIVED, not measured". Pass 2 hard-coded ROPE_Y = 224, read off a render.
+ * S1 was then recut three times (D_S1 400 -> 396 -> 348, the strike moved from
+ * world to HUD space, STRIKE_AT 352 -> 348 -> 300) and every one of those
+ * silently invalidated the number.
+ */
+export const deriveSeamsDontMeasure: Rule = {
+  id: "derive-seams-dont-measure",
+  claim: "Derive a cross-scene seam from the neighbouring scene's exported geometry, never from a number measured off a render.",
+  why: "A measured constant is a bug with a delay fuse: it stays correct until the neighbouring scene is recut, then silently misplaces the seam with nothing failing. Deriving it means a recut re-derives the seam for free.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "gate",
+  verify: "`video radar:film --project <dir> --video <mp4> --comp <id> --check seam-fidelity`",
+  owner: "seam-fidelity",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/S1Graveyard.tsx", symbol: "STRIKE_PTS" },
+  },
+};

package/src/rules/deterministicSceneSource.test.ts

@@ -0,0 +1,58 @@
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { toolchainRepoRoot as repoRoot } from "../testSupport";
+import { checkFile } from "../sourceCheck";
+import { deterministicSceneSource } from "./deterministicSceneSource";
+
+const check = () => {
+  if (deterministicSceneSource.enforcement.kind !== "source") throw new Error("expected a source rule");
+  return deterministicSceneSource.enforcement.check;
+};
+
+const run = (name: string) => {
+  const rel = `packages/video-craft/src/fixtures/${name}`;
+  return checkFile(check(), join(repoRoot, rel), rel, repoRoot);
+};
+
+describe("deterministicSceneSource", () => {
+  test("fires once per nondeterministic call: Math.random(), Date.now(), argless new Date() with and without parens", () => {
+    const findings = run("nondeterministic-scene.tsx");
+    expect(findings).toHaveLength(4);
+    expect(findings.map((f) => f.match)).toEqual(["Math.random()", "Date.now()", "new Date()", "new Date"]);
+    for (const f of findings) {
+      expect(f.message).toMatch(/nondeterministic/);
+      expect(f.match.length).toBeLessThanOrEqual(60);
+    }
+  });
+
+  test("does not fire on seeded randomness, dated Date construction, or string mentions", () => {
+    expect(run("deterministic-scene.tsx")).toEqual([]);
+  });
+
+  test("deliberate limitation: aliased/destructured/prefixed/element-access spellings are not flagged", () => {
+    // If the check learns symbol resolution, flip these expectations.
+    expect(run("nondeterministic-variants.tsx")).toEqual([]);
+  });
+
+  test("covers every scene tree and the kit", () => {
+    expect(check().include).toEqual([
+      "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}",
+      "klaviyo-segments-video/src/**/*.{js,jsx,ts,tsx}",
+      "radar-fixture-video/src/**/*.{js,jsx,ts,tsx}",
+      "packages/video-kit/src/**/*.{ts,tsx}",
+    ]);
+    expect(check().exclude).toBeUndefined();
+  });
+});

package/src/rules/deterministicSceneSource.ts

@@ -0,0 +1,82 @@
+import { Node, SyntaxKind } from "ts-morph";
+import type { Rule, SourceFinding } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-usecase-book-meeting.md: the
+ * build sessions ran an explicit grep gate for Math.random / Date.now /
+ * new Date() after edits, because a nondeterministic scene renders
+ * differently on every Remotion render pass (flicker between frames, and
+ * un-reproducible output across renders). Remotion's own docs state the
+ * constraint; this makes it machine-checked over our scene and kit source.
+ *
+ * `new Date(...)` WITH arguments is fine - only the argless form reads the
+ * wall clock. String mentions never match: the check walks call/new
+ * expressions, not text.
+ *
+ * Deliberate limitation: only the canonical spellings are flagged (callee
+ * text compared literally). Aliased receivers (`const M = Math; M.random()`),
+ * destructuring, `globalThis.`/`window.` prefixes, and element access
+ * (`Math["random"]()`) evade it. Those are evasion shapes, not accidental
+ * usage; resolving them would need symbol analysis for no observed payoff.
+ * The boundary is pinned by deterministicSceneSource.test.ts.
+ */
+export const deterministicSceneSource: Rule = {
+  id: "deterministic-scene-source",
+  claim: "Scene and kit source must be render-deterministic: no Math.random(), no Date.now(), no argless new Date(); use seeded randomness and explicit dates.",
+  why: "A nondeterministic value is re-evaluated on every render pass, so elements jitter between frames and two renders of the same composition differ; the sessions caught these only via an ad-hoc grep gate after the fact.",
+  learnedFrom: "claude-sessions-digest/revola-usecase-book-meeting.md",
+  upstream: "remotion:@remotion/eslint-plugin/deterministic-randomness",
+  tier: "gate",
+  verify: "render the same frame range twice and diff every frame; all must report YMAX=0 (automation owed: remotion-videos-5oi)",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "source",
+    check: {
+      // Determinism is a crash-class invariant, not a per-project doctrine,
+      // so the blast radius matches interpolate-literal-keys-monotonic: every
+      // scene tree plus the kit. The corpus runs clean across all of them.
+      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 (this list said "every scene tree" but named
+        // neither) - the exact silent-default trap this rule's own claim
+        // exists to catch, applied to the checker itself.
+        "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[] = [];
+        const report = (node: Node, what: string) => {
+          findings.push({
+            file: relPath,
+            line: node.getStartLineNumber(),
+            match: node.getText().slice(0, 60),
+            message: `nondeterministic ${what} in scene/kit source; seed it or pass an explicit value`,
+          });
+        };
+        for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+          const callee = call.getExpression().getText();
+          if (callee === "Math.random" || callee === "Date.now") report(call, `${callee}()`);
+        }
+        for (const nw of file.getDescendantsOfKind(SyntaxKind.NewExpression)) {
+          if (nw.getExpression().getText() === "Date" && nw.getArguments().length === 0) {
+            report(nw, "new Date()");
+          }
+        }
+        return findings;
+      },
+    },
+  },
+};

package/src/rules/diegeticSoundForOnscreenActions.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 16 ("use asmr-typing.wav
+ * anywhere that shows typing - I liked it a lot", "I want the sound effects
+ * to give an ASMR style ... very satisfying sounds", "use a more upbeat bg,
+ * maybe the one used in the Linear reel"). approved-sfx-palette-only owns
+ * the palette and mix hierarchy; this rule owns diegetic sync and the bed.
+ */
+export const diegeticSoundForOnscreenActions: Rule = {
+  id: "diegetic-sound-for-onscreen-actions",
+  claim: "On-screen actions are heard: typing on screen plays asmr-typing.wav in sync, clicks land a soft UI click on the click frame, seams never cross in dead silence, and the music bed is an upbeat tech-reveal track (the Linear-reel EDM track is the reference), subtle and ducked under payoffs.",
+  why: "'Use asmr-typing.wav anywhere that shows typing' canonized the diegetic-sync expectation, and 'use a more upbeat bg, maybe the one used in the Linear reel' pinned the bed genre; the palette rule alone let silent typing and a wrong-genre bed through.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "An audio-to-visual sync judgment against the render; no single code location expresses it.",
+  },
+};

package/src/rules/distinctTransitionPerBeat.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-usecase-book-meeting.md ("just
+ * fix the transition, one should leave from the left and the other should
+ * come from the right, or up/down"; "overall make all transitions super
+ * smooth, zoom in, leave left appear right, any cinematic move") and the
+ * win-booth taste summary ("distinct transition per beat").
+ */
+export const distinctTransitionPerBeat: Rule = {
+  id: "distinct-transition-per-beat",
+  claim: "Adjacent beats use distinct, directionally coherent transitions (exit left pairs with enter right, exit up with enter down); never the same transition twice in a row, never an unmotivated hard swap.",
+  why: "Back-to-back identical transitions read as template output, and directionally incoherent exits/entries were flagged as 'half left, half middle' confusion; direction logic is what makes cuts feel authored.",
+  learnedFrom: "claude-sessions-digest/revola-usecase-book-meeting.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is a sequencing judgment across scene boundaries; no single code location expresses it.",
+  },
+};

package/src/rules/downloadOrDrawRichAssets.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 21: the standing operator
+ * instruction issued per build - download anything you want, or make custom
+ * SVGs - plus "the map could look more sleek and more like a map (can use
+ * any external package)" and "replace the gradient boxes with animations,
+ * icons, real stuff". The builds that looked best treated asset acquisition
+ * as expected work, not as an exception to ask about.
+ */
+export const downloadOrDrawRichAssets: Rule = {
+  id: "download-or-draw-rich-assets",
+  claim: "When a beat needs an element, download the real asset (brand SVG, icon set, map or geo data, texture, 3D model, font) at authoring time and commit it, or hand-author a detailed custom SVG; a styled-div rectangle, basic shape, or emoji standing in for art is a defect, and render-time fetching is banned so renders stay deterministic.",
+  why: "The gap between prompted builds that looked professional and pipeline builds that looked flat was largely asset quality: agents defaulted to CSS primitives unless told downloading was allowed, while the standing instruction 'download anything you want, or make custom SVGs' produced rich marks every time it was issued.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "An asset-quality judgment per visible element; no single code location expresses it.",
+  },
+};

package/src/rules/elementOnscreenForItsVoSentence.ts

@@ -0,0 +1,25 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/act854-qpa-video.md: "the voice comes
+ * before what's shown and it doesn't really match"; "the governance, risk
+ * and compliance finished before the compliance card loads .. so that part
+ * needs to go faster"; "the NACSA logo at the beginning should come 3-4 s
+ * in, not at the same time as the opening". The visual-lag family of
+ * defects, distinct from audio-is-the-clock (which fixes the clock) - this
+ * fixes what must be on screen while the clock runs.
+ */
+export const elementOnscreenForItsVoSentence: Rule = {
+  id: "element-onscreen-for-its-vo-sentence",
+  claim: "The element a voiceover sentence names is fully on screen, build-in complete, for the whole duration of that sentence; secondary marks (partner logos) enter when mentioned, not at frame zero.",
+  why: "Visuals lagging or leading their VO line was the dominant ACT854 feedback category, re-broken by every new voiceover take; the sentence-to-element contract is what re-timing must preserve.",
+  learnedFrom: "claude-sessions-digest/act854-qpa-video.md",
+  tier: "gate",
+  verify: "`video radar:scene --project <dir> --comp <id> --check vo-element-sync --check edge-touch`",
+  owner: "vo-element-sync",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/measure.ts" },
+  },
+};

package/src/rules/emitBuildNotes.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from HOW_I_BUILD_VIDEOS.md: "Keep BUILD_NOTES.md as the source of
+ * truth ... An automated pipeline should emit the equivalent artifact, or
+ * nobody can pick the project up later."
+ */
+export const emitBuildNotes: Rule = {
+  id: "emit-build-notes",
+  claim: "Maintain BUILD_NOTES.md (or the automated equivalent) per video: current wired WAV, frame layout, and every feedback decision, newest round on top.",
+  why: "Without it nobody, human or agent, can pick the project up later; the notes are the only record of why timings and content are what they are.",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A documentation convention; its exemplars are docs, not live code.",
+  },
+};