@revola-ai/video-craft 0.2.1

package/src/rules/noNestedSvgFilters.ts

@@ -0,0 +1,138 @@
+import { Node, SyntaxKind } from "ts-morph";
+import type { Rule, SourceFinding } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md, "S2 pass 2": a CSS-filtered
+ * <g> wrapping children that also carry CSS filters makes Chrome drop those
+ * children silently. The first cursor build rendered nothing while its group
+ * rendered fine, and it took a debug rect to prove it.
+ */
+
+/**
+ * True when a JSX element's `style` prop sets an active `filter`. Looks through
+ * the attribute's own expression (bare object literals, conditionals, nested
+ * literals, shorthand), skips `filter: "none"` (that resets a filter), and
+ * deliberately does not chase styles imported from helpers or spread from
+ * constants - see the fixtures note above.
+ */
+function hasStyleFilter(element: Node): boolean {
+  const attributes = Node.isJsxOpeningElement(element) || Node.isJsxSelfClosingElement(element)
+    ? element.getAttributes()
+    : [];
+
+  for (const attribute of attributes) {
+    if (!Node.isJsxAttribute(attribute)) continue;
+    if (attribute.getNameNode().getText() !== "style") continue;
+
+    const initializer = attribute.getInitializer();
+    if (!initializer || !Node.isJsxExpression(initializer)) continue;
+
+    const expression = initializer.getExpression();
+    if (!expression) continue;
+
+    const literals = Node.isObjectLiteralExpression(expression)
+      ? [expression]
+      : expression.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression);
+
+    for (const literal of literals) {
+      for (const property of literal.getProperties()) {
+        if (Node.isShorthandPropertyAssignment(property) && property.getName() === "filter") return true;
+        if (!Node.isPropertyAssignment(property)) continue;
+        if (property.getName() !== "filter") continue;
+        const value = property.getInitializer()?.getText() ?? "";
+        if (value !== `"none"` && value !== `'none'`) return true;
+      }
+    }
+  }
+  return false;
+}
+
+const ELEMENT_KINDS = [SyntaxKind.JsxOpeningElement, SyntaxKind.JsxSelfClosingElement];
+
+export const noNestedSvgFilters: Rule = {
+  id: "no-nested-svg-filters",
+  claim: "Never nest CSS filters in SVG. Put one flat filter on one layer.",
+  why: "Chrome silently drops the children of a CSS-filtered group when those children also carry CSS filters. Nothing errors and nothing warns: the elements simply do not render, which reads as a logic bug and costs a debugging session to localise.",
+  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: {
+      include: [
+        "qpa-video/03_scenes/**/*.jsx",
+        "reverence-video/src/scenes/**/*.tsx",
+        "workday-dple-video/src/scenes/**/*.tsx",
+        "revola-video/src/scenes/**/*.tsx",
+        "datapeak-video/**/*.{jsx,tsx}",
+        "datapeak-usecases/**/*.{jsx,tsx}",
+        "qse-video/**/*.{jsx,tsx}",
+        "qse-investor-video/**/*.{jsx,tsx}",
+        "qse-qguard-video/src/**/*.tsx",
+        "rcp-fund7-video/src/**/*.tsx",
+        "expanse-video/src/**/*.tsx",
+        "reverence-video/src/**/*.tsx",
+        "spec-videos/**/*.{jsx,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/**/*.tsx",
+        "radar-fixture-video/src/**/*.tsx",
+        "packages/video-kit/src/**/*.tsx",
+      ],
+      run: (file, relPath): SourceFinding[] => {
+        const findings: SourceFinding[] = [];
+
+        for (const kind of ELEMENT_KINDS) {
+          for (const element of file.getDescendantsOfKind(kind)) {
+            if (!hasStyleFilter(element)) continue;
+
+            // A JsxOpeningElement's direct parent is its OWN JsxElement, and
+            // that JsxElement's opening element is this very node - walking
+            // from getParent() would match the element against itself. Start
+            // strictly above the element's own JSX node.
+            const own = Node.isJsxOpeningElement(element) ? element.getParent() : element;
+
+            // Walk up through the enclosing JSX elements looking for another
+            // filtered layer, stopping at the enclosing <svg>: the Chrome
+            // failure is a filtered SVG container (a <g>) wrapping filtered
+            // children INSIDE the svg subtree. A CSS filter on the <svg>
+            // element itself or on an HTML wrapper around it composites the
+            // rendered svg at the HTML level and is fine - corpus calibration
+            // hit that shape three times in shipped, correctly-rendering
+            // scenes (see fixtures/nested-filters-html-wrapper.tsx). Only the
+            // opening element carries the attributes, so a JsxElement
+            // ancestor is read through its opening tag.
+            let insideSvg = false;
+            let filteredAncestor = false;
+            let ancestor = own.getParent();
+            while (ancestor) {
+              if (Node.isJsxElement(ancestor)) {
+                const opening = ancestor.getOpeningElement();
+                if (opening.getTagNameNode().getText() === "svg") {
+                  insideSvg = true;
+                  break;
+                }
+                if (hasStyleFilter(opening)) filteredAncestor = true;
+              }
+              ancestor = ancestor.getParent();
+            }
+
+            if (insideSvg && filteredAncestor) {
+              findings.push({
+                file: relPath,
+                line: element.getStartLineNumber(),
+                match: element.getText().replace(/\s+/g, " ").slice(0, 60),
+                message:
+                  `nested CSS filter in SVG: this element sets style.filter inside an ancestor that also does. ` +
+                  `Chrome drops the inner content silently. Flatten to one filter on one layer.`,
+              });
+            }
+          }
+        }
+
+        return findings;
+      },
+    },
+  },
+};

package/src/rules/noRepeatedAssetAcrossShots.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-usecase-book-meeting.md: "In
+ * scene 2, the third animation is the video again, but it was shown in the
+ * first animation."
+ */
+export const noRepeatedAssetAcrossShots: Rule = {
+  id: "no-repeated-asset-across-shots",
+  claim: "Never show the same asset (a product video, screenshot, or illustration) in two shots of one video; each shot earns its screen time with new material.",
+  why: "A repeated asset reads as filler and was flagged the moment it appeared; the fix was always replacing the repeat with new content, never keeping it.",
+  learnedFrom: "claude-sessions-digest/revola-usecase-book-meeting.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is a cross-shot content judgment; no single code location expresses it.",
+  },
+};

package/src/rules/noShorthandWithUndefinedLonghand.test.ts

@@ -0,0 +1,35 @@
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { toolchainRepoRoot as repoRoot } from "../testSupport";
+import { checkFile } from "../sourceCheck";
+import { noShorthandWithUndefinedLonghand } from "./noShorthandWithUndefinedLonghand";
+
+const check = () => {
+  if (noShorthandWithUndefinedLonghand.enforcement.kind !== "source") throw new Error("expected a source rule");
+  return noShorthandWithUndefinedLonghand.enforcement.check;
+};
+
+const run = (name: string) => {
+  const rel = `packages/video-craft/src/fixtures/${name}`;
+  return checkFile(check(), join(repoRoot, rel), rel, repoRoot);
+};
+
+describe("noShorthandWithUndefinedLonghand", () => {
+  test("fires on an explicit undefined AND on a forwarded longhand beside its shorthand", () => {
+    const findings = run("shorthand-undefined-longhand.tsx");
+    expect(findings.map((f) => f.match)).toEqual([
+      "paddingTop",
+      "paddingLeft: undefined",
+      "marginRight: undefined",
+      "backgroundColor: undefined",
+    ]);
+    for (const f of findings) {
+      expect(f.message).toMatch(/clears the shorthand/);
+      expect(f.match.length).toBeLessThanOrEqual(60);
+    }
+  });
+
+  test("does not fire on ternaries, lone longhands, defined pairs, or borderRadius beside border", () => {
+    expect(run("shorthand-undefined-clean.tsx")).toEqual([]);
+  });
+});

package/src/rules/noShorthandWithUndefinedLonghand.ts

@@ -0,0 +1,140 @@
+import { SyntaxKind } from "ts-morph";
+import type { Rule, SourceFinding } from "../types";
+
+/**
+ * Mined from the product-room build. A shared panel component forwarded style
+ * as `{ padding, paddingTop, paddingRight, paddingBottom, paddingLeft }` after
+ * destructuring them out of a caller's style object. When a caller passed only
+ * the `padding` shorthand, the four longhands were `undefined` - and React
+ * applies style keys in order, so writing `style.paddingTop = ""` after
+ * `style.padding = "18px 20px"` clears it. Every panel in the film silently
+ * lost its padding; the defect was invisible in source review and only showed
+ * up as "the blocks aren't centered correctly".
+ *
+ * Two shapes fire, both only when the same object literal also carries that
+ * property's own shorthand: an explicit `paddingLeft: undefined`, and a
+ * forwarded identifier (`{ padding, paddingTop }`) whose definedness cannot be
+ * known here - the shape that actually caused the bug.
+ *
+ * A ternary yielding undefined (`filter: blur > 0.5 ? ... : undefined`) is the
+ * sanctioned omit-a-value shape, appears throughout the corpus, and is
+ * deliberately left alone; so is a literal, which is definitely defined.
+ *
+ * The identifier case is an over-approximation, stated plainly: ANY bare
+ * identifier counts, not only one destructured from a caller's style, because
+ * definedness is not knowable here without type information. It returns zero
+ * findings across the current corpus. If it ever gets noisy, narrow it to
+ * identifiers bound by a destructure rather than loosening the family table.
+ *
+ * Known boundary: spreading a partially-undefined object (`{...pad}`) has the
+ * same effect and is not detectable here without type information. The fix
+ * shape the rule pushes toward - build the style object with only the keys you
+ * actually have - is immune to both.
+ */
+
+/**
+ * Shorthand -> longhands it resets. Listed explicitly rather than derived by
+ * prefix because CSS does not follow the prefix: `border` does NOT reset
+ * `borderRadius`, `borderCollapse` or `borderSpacing`, so a prefix rule would
+ * fire on legal code.
+ */
+const FAMILIES: Record<string, RegExp> = {
+  padding: /^padding(Top|Right|Bottom|Left|Block|Inline)/,
+  margin: /^margin(Top|Right|Bottom|Left|Block|Inline)/,
+  // `background` resets image/position/size/repeat/origin/clip/attachment/color.
+  // It does NOT reset background-blend-mode (CSS Backgrounds L3).
+  background: /^background(Color|Image|Position|Size|Repeat|Attachment|Clip|Origin)/,
+  // Ordered before `border` so the corner spellings can never be claimed by it.
+  borderRadius: /^border(Top|Bottom)(Left|Right)Radius$/,
+  // The negative lookahead is load-bearing: without it `^border(Top` also
+  // matches `borderTopLeftRadius`, and `border` does not reset border-radius.
+  border: /^border(Top|Right|Bottom|Left|Width|Style|Color|Block|Inline)(?!.*Radius)/,
+  font: /^font(Size|Weight|Family|Style|Variant|Stretch)/,
+  flex: /^flex(Grow|Shrink|Basis)$/,
+  overflow: /^overflow(X|Y)$/,
+  transition: /^transition(Property|Duration|TimingFunction|Delay)$/,
+  animation: /^animation(Name|Duration|TimingFunction|Delay|IterationCount|Direction|FillMode|PlayState)$/,
+  gap: /^(row|column)Gap$/,
+};
+
+export const noShorthandWithUndefinedLonghand: Rule = {
+  id: "no-shorthand-with-undefined-longhand",
+  claim:
+    "Never put a longhand style property explicitly set to `undefined` in the same object as its shorthand; build the style object from only the keys you actually have.",
+  why: "React writes style keys in order, so an undefined longhand clears the shorthand that preceded it - one forwarded style object silently removed the padding from every panel in a film, and the source read as correct.",
+  learnedFrom: "claude-sessions-digest/product-room-video.md",
+  tier: "gate",
+  verify: "`vitest run packages/video-craft` - machine-checked over scene and kit source",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "source",
+    check: {
+      // Scene trees plus the kit: anywhere a style object is composed or
+      // forwarded. Same blast radius as the other geometry-class checks.
+      include: [
+        "revola-video/src/**/*.{ts,tsx}",
+        "workday-dple-video/src/**/*.{ts,tsx}",
+        "spec-videos/src/**/*.{ts,tsx}",
+        "qpa-video/03_scenes/**/*.{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}",
+        // Added Task 23: klaviyo-segments-video and radar-fixture-video were
+        // silently excluded - the same gap deterministic-scene-source had.
+        "klaviyo-segments-video/src/**/*.{ts,tsx}",
+        "radar-fixture-video/src/**/*.{ts,tsx}",
+        "packages/video-kit/src/**/*.{ts,tsx}",
+      ],
+      run(file, relPath): SourceFinding[] {
+        const findings: SourceFinding[] = [];
+        for (const obj of file.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
+          const props = obj.getProperties().filter(
+            (p) => p.isKind(SyntaxKind.PropertyAssignment) || p.isKind(SyntaxKind.ShorthandPropertyAssignment),
+          );
+          const unquote = (n: string) => n.replace(/^["']|["']$/g, "");
+          const names = new Set(
+            props.map((p) =>
+              unquote(
+                p.isKind(SyntaxKind.PropertyAssignment)
+                  ? p.getName()
+                  : p.asKindOrThrow(SyntaxKind.ShorthandPropertyAssignment).getName(),
+              ),
+            ),
+          );
+          for (const prop of props) {
+            const shorthandSyntax = prop.isKind(SyntaxKind.ShorthandPropertyAssignment);
+            const name = unquote(
+              shorthandSyntax
+                ? prop.asKindOrThrow(SyntaxKind.ShorthandPropertyAssignment).getName()
+                : prop.asKindOrThrow(SyntaxKind.PropertyAssignment).getName(),
+            );
+            // A value is "possibly undefined" when it is the bare `undefined`
+            // identifier, or any forwarded identifier (`{ padding, paddingTop }`
+            // out of a destructure - the shape that actually caused the bug).
+            // A literal is definitely defined; a ternary is the sanctioned
+            // omit-a-value shape and is left alone deliberately.
+            let possiblyUndefined = shorthandSyntax;
+            if (!shorthandSyntax) {
+              const init = prop.asKindOrThrow(SyntaxKind.PropertyAssignment).getInitializer();
+              possiblyUndefined = init?.getKind() === SyntaxKind.Identifier;
+            }
+            if (!possiblyUndefined) continue;
+            for (const [shorthand, longhands] of Object.entries(FAMILIES)) {
+              if (!longhands.test(name)) continue;
+              if (!names.has(shorthand)) continue;
+              findings.push({
+                file: relPath,
+                line: prop.getStartLineNumber(),
+                match: prop.getText().slice(0, 60),
+                message: `\`${name}\` may be undefined beside the \`${shorthand}\` shorthand in the same object, which clears the shorthand; omit the key instead of passing it undefined`,
+              });
+              break;
+            }
+          }
+        }
+        return findings;
+      },
+    },
+  },
+};

package/src/rules/noStackedFadesAtACut.ts

@@ -0,0 +1,30 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "S3 opacity fade-in. S2
+ * already fades out; two stacked fades = the film dips through a black hole.
+ * ... Never fade in here." Proved by render: f584 violet bloom, f590
+ * near-black. The outgoing-fade mechanism is CraftStage's exitOpacity prop.
+ */
+export const noStackedFadesAtACut: Rule = {
+  id: "no-stacked-fades-at-a-cut",
+  claim: "Never stack the outgoing scene's fade-out with an incoming fade-in at a cut; at most one side of a seam may fade.",
+  why: "Two stacked fades multiply to near-zero and the film dips through a black hole at the seam; no easing can fix a cut that happens in black.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "gate",
+  verify: "`video radar:film --project <dir> --video <mp4> --check fade-stack-at-cut`",
+  owner: "fade-stack-at-cut",
+  exceptions: [
+    {
+      project: "qse-qguard-video",
+      decision:
+        "client chose ACT854's paired 14f exit-fade + 14f enter-fade at every seam for the QGuard restyle; the black-dip risk is accepted and checked with stills at each seam",
+      recordedIn: "qse-qguard-video/docs/motion-brand-spec.md",
+    },
+  ],
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/craftKit.tsx" },
+  },
+};

package/src/rules/noStaticHolds.ts

@@ -0,0 +1,24 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/portfolio-reels.md ("The dashboard scene
+ * is too static - when the camera zooms in, something should happen"; "Too
+ * static - the bg should move too, throughout the video") and
+ * revola-usecase-book-meeting.md ("the one scene that says 'a meeting you
+ * did nothing to get' has no animation, just text. looks empty"). "Too
+ * static" was raised for at least five different scenes.
+ */
+export const noStaticHolds: Rule = {
+  id: "no-static-holds",
+  claim: "No shot holds fully static for more than about two seconds: the background always has subtle continuous motion, and idle hero objects get living motion (drift, rotate, breathe).",
+  why: "Every static hold in the corpus was eventually flagged as boring or empty; continuous low-amplitude motion is what separates a motion-graphics video from a slideshow.",
+  learnedFrom: "claude-sessions-digest/portfolio-reels.md",
+  tier: "gate",
+  verify: "`video radar:film --project <dir> --video <mp4> --check static-hold`",
+  owner: "static-hold",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is a motion-over-time judgment; it is not expressible as a single code location.",
+  },
+};

package/src/rules/occlusionVisibleElements.ts

@@ -0,0 +1,26 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/superpowers/specs/2026-07-31-defect-radar-design.md: QGuard
+ * r1 printed station labels through every panel at their station; QGuard r3
+ * painted S2's lane labels under theft strip 2, where they were never seen.
+ * Both defects passed every existing check because nothing tested whether a
+ * tagged element was actually VISIBLE, only whether it existed and sat in
+ * its declared band. New doctrine - no prior violation site to anchor
+ * against, since nothing in the corpus checked this before the radar's
+ * `occlusion` check existed.
+ */
+export const occlusionVisibleElements: Rule = {
+  id: "occlusion-visible-elements",
+  claim: "A tagged element stays visibly on top for the whole duration it is meant to be read; another element must never paint over enough of it, for long enough, that it reads as buried rather than merely overlapping.",
+  why: "A label that exists, sits in its correct band, and is fully painted over by a later layer looks identical to a correct scene in source and in every geometry check that only reasons about position - the QGuard station labels and S2 lane labels were both invisible in the shipped render while every positional check stayed clean.",
+  learnedFrom: "docs/superpowers/specs/2026-07-31-defect-radar-design.md",
+  tier: "gate",
+  verify: "`video radar:scene --project <dir> --comp <id> --check occlusion`",
+  owner: "occlusion",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is a paint-order judgment across a shot's whole sampled range; no single code location expresses it.",
+  },
+};

package/src/rules/oneContinuousVoTrack.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md. The old build sliced the read
+ * into five chunks (VO_S1...VO_S5) and started each at its scene's first frame;
+ * the scenes ran longer than their slices, so every seam padded the read with
+ * dead air - 252f (9s) across four seams.
+ */
+export const oneContinuousVoTrack: Rule = {
+  id: "one-continuous-vo-track",
+  claim: "Play the narration as one continuous Audio track from frame 0 and make the film exactly its length; never slice the VO into per-scene chunks that start at scene boundaries.",
+  why: "Per-scene VO slices start at each scene's first frame while scenes run longer than their slices, silently inserting dead air at every seam - the sliced build padded the read with 9s across four seams and the film read as padded.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/RevolaCraft.tsx" },
+  },
+};

package/src/rules/onePunchPerMomentClass.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/portfolio-reels.md: "THE 'TO DONE IN
+ * SECONDS' BEAT ZOOM-IN ON EVERY PRESS IS UNNECESSARY" and "It zooms in and
+ * suddenly zooms out". Over-animation was rejected as firmly as static
+ * scenes; the counterweight to no-static-holds.
+ */
+export const onePunchPerMomentClass: Rule = {
+  id: "one-punch-per-moment-class",
+  claim: "Use a beat punch (zoom-in, scale pop, flash) at most once per class of moment; never repeat the same punch on every keypress, card, or list item.",
+  why: "A punch repeated on every event stops reading as emphasis and starts reading as a bug; repeated beat zooms were rejected twice in caps.",
+  learnedFrom: "claude-sessions-digest/portfolio-reels.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is an emphasis-budget judgment across a scene's events; no single code location expresses it.",
+  },
+};

package/src/rules/oneRenderPerRound.ts

@@ -0,0 +1,46 @@
+import type { Rule } from "../types";
+
+/**
+ * `verify-cheap-render-dear` says the full render runs "on demand, last". This
+ * is what makes that operational, because "last" turns out to be ambiguous the
+ * moment a render surfaces more than one defect.
+ *
+ * QGuard round 2 spent three full renders - about 21 minutes of an 85-second
+ * film at 1080p - and only one of them was necessary:
+ *
+ *   render 2  swept, found two defects (a retracting rule striking through the
+ *             wordmark, a request card off frame left)
+ *             -> fixed one, verified it, rendered again
+ *   render 3  found the second fix incomplete: it corrected the card's resting
+ *             position but not its travel, which the single verifying still
+ *             had not covered
+ *             -> fixed properly, rendered again
+ *   render 4  clean
+ *
+ * Two failures, both cheap to avoid. Fixes were verified one at a time when the
+ * render had already listed them all; and each fix was checked at ONE frame when
+ * the thing it changed spanned a hundred. A still costs seconds and a render
+ * costs minutes, so the still should cover the whole window the fix touches -
+ * the beginning, the middle and the end of any motion it alters - and every
+ * defect from a render should be closed before the next one starts.
+ *
+ * For scale, the corpus in `claude-sessions-digest/` ran 9 full renders across
+ * 3,208 recorded actions, against 103 stills and 231 typechecks.
+ *
+ * This does not weaken `review-the-render-by-frame-sweep`: the sweep still
+ * gates the round, and it still has to happen on a rendered file. It defines
+ * what a round IS - one render, one complete review of it, one batch of fixes -
+ * rather than letting a round quietly become one render per fix.
+ */
+export const oneRenderPerRound: Rule = {
+  id: "one-render-per-round",
+  claim: "Close every defect a render surfaced before rendering again, and verify each fix with stills spanning the whole window it changes, not a single frame.",
+  why: "Rendering per fix instead of per round cost QGuard round 2 two extra full renders (~14 minutes), one of them because a fix was verified at a single frame while the motion it altered spanned a hundred.",
+  learnedFrom: "qse-qguard-video/BUILD_NOTES.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/review.ts" },
+  },
+};

package/src/rules/openStaticAfterAHardCut.ts

@@ -0,0 +1,29 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "Momentum entry (over-scale +
+ * blur decelerating). Theoretically correct ... in practice reads as the
+ * camera drifting on the opening frames instead of the scene being *there*."
+ * The live example is the duplicated camTarget(0), camTarget(0) opening keys
+ * in S3Line's CAM_X.
+ */
+export const openStaticAfterAHardCut: Rule = {
+  id: "open-static-after-a-hard-cut",
+  claim: "After a hard cut, open the incoming scene static and at full opacity: no entry zoom, no entry blur, and the first two camera keys equal so nothing moves until the first deliberate travel.",
+  why: "A momentum entry is theoretically correct continuation but on screen reads as the camera drifting; the landing element must be the first thing the eye finds, and it must be still.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  exceptions: [
+    {
+      project: "qse-qguard-video",
+      decision:
+        "client chose ACT854's 0.97-to-1 entry settle at every seam for the QGuard restyle; scenes still hold their first camera key static underneath it",
+      recordedIn: "qse-qguard-video/docs/motion-brand-spec.md",
+    },
+  ],
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/S3Line.tsx" },
+  },
+};

package/src/rules/openingsAndClosingsCarryMore.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from docs/style/CREATIVE_EDGE.md directive 2 ("first scene is too
+ * boring for an opening", "make it an amazing closing scene", "upscale the
+ * final animation to look better and close with a good impact and a good
+ * professional layout"). The opening drew its own dedicated feedback rounds
+ * in session after session; no other scene position did.
+ */
+export const openingsAndClosingsCarryMore: Rule = {
+  id: "openings-and-closings-carry-more",
+  claim: "The opening and closing scenes out-spectacle the middle: frame one already carries the film's biggest visual statement, and the close lands one deliberate, composed payoff instead of fizzling.",
+  why: "'First scene is too boring for an opening' and 'make it an amazing closing scene' recurred across builds as their own feedback rounds; a strong middle never rescued a film whose first seconds read as template.",
+  learnedFrom: "docs/style/CREATIVE_EDGE.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "A relative-spectacle judgment across scene positions; no single code location expresses it.",
+  },
+};

package/src/rules/persistentDeviceFrames.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from claude-sessions-digest/revola-intro-video.md and
+ * revola-usecase-win-booth.md, where the identical complaint appeared in
+ * both: "why does the laptop keep reappearing, i hate the transitions.. it
+ * should just change content".
+ */
+export const persistentDeviceFrames: Rule = {
+  id: "persistent-device-frames",
+  claim: "A device frame (laptop, phone, browser chrome) enters the video once; subsequent shots swap only the content inside it, never re-animate the frame's entrance.",
+  why: "A frame that re-enters on every shot reads as a reset and was hated on sight in two separate videos; persistence is what makes a sequence feel like one continuous product story.",
+  learnedFrom: "claude-sessions-digest/revola-intro-video.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    unanchorable: "The rule is a cross-shot continuity judgment; no single code location expresses it.",
+  },
+};

package/src/rules/pixelDiffAnEmptyBandFirst.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../types";
+
+/**
+ * Mined from revola-video/BUILD_NOTES_CRAFT.md: "Raw per-pixel delta is
+ * ~120/255, but it's identical in empty regions of the frame - that's
+ * FilmGrain/DustMotes, which re-randomise every frame by design. Not a seam
+ * artifact." Those layers render inside CraftStage.
+ */
+export const pixelDiffAnEmptyBandFirst: Rule = {
+  id: "pixel-diff-an-empty-band-first",
+  claim: "When pixel-diffing rendered frames across a seam, measure an empty region of frame first; per-frame randomized layers (film grain, dust motes) produce large raw deltas by design.",
+  why: "A raw ~120/255 per-pixel delta at a verified-perfect seam was entirely FilmGrain/DustMotes re-randomizing; without the empty-band control you chase a phantom seam artifact.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "revola-video/src/scenes/craft/craftKit.tsx" },
+  },
+};

package/src/rules/planIsPublishedNotGating.ts

@@ -0,0 +1,32 @@
+import type { Rule } from "../types";
+
+/**
+ * Replaces `plan-signoff-before-scenes`, which held all scene work behind a
+ * human approval.
+ *
+ * The reason for the original rule was sound and is preserved here: structural
+ * feedback is cheapest against a markdown plan. What was wrong was making it a
+ * BARRIER. Measured on the QGuard build, the wait cost 40 minutes before a
+ * single scene file existed, against 8.9 minutes in the reference sessions in
+ * `claude-sessions-digest/` - and nothing behind the barrier depended on the
+ * answers. The tokens, the theme, the layout module and every artifact
+ * component were buildable the whole time.
+ *
+ * It also did not buy correctness where it mattered. The approved QGuard plan
+ * specified the S1 seam exactly right ("the second cookie chip is snatched
+ * upward out of frame and the camera follows it up into the dark"), and the
+ * build silently did something else. Sign-off certified a document; it could
+ * not certify the film.
+ */
+export const planIsPublishedNotGating: Rule = {
+  id: "plan-is-published-not-gating",
+  claim: "Publish the scene-flow plan with its open questions and keep building; never hold scene work waiting for sign-off, and when an answer arrives, change the plan and re-derive from it.",
+  why: "A plan used as a barrier stops all downstream work for feedback that is usually orthogonal to it - the QGuard build spent 40 minutes before its first scene against 8.9 in the reference sessions - while the things sign-off cannot catch (a plan the build silently does not honour) pass it anyway.",
+  learnedFrom: "qse-qguard-video/BUILD_NOTES.md",
+  tier: "process",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "packages/video-cli/src/planmd.ts" },
+  },
+};