@revola-ai/video-craft 0.2.1

package/dist/rules/sceneRootTagDeclared.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { declaredElements, findPlanDir, INCLUDE, isReporterFile, projectSourceFiles } from "./dataRadarTagsDeclared.js";
+const sceneRootTagDeclared = {
+  id: "scene-root-tag-declared",
+  claim: 'A scene declares its scene-space contract: the root AbsoluteFill carries data-radar-scene-root="static" when the scene has no whole-scene camera transform; when it has one, the innermost full-bleed camera layer carries data-radar-scene-root instead.',
+  why: "radar:scene derives every geometry number from the [data-radar-scene-root] element and refuses at setup without it; both build2 first passes (Claude's fan-out and the Gemini replays) shipped scenes missing the tag and cost a dedicated fix round (c662df7) before the first sweep could run.",
+  learnedFrom: "docs/superpowers/specs/2026-08-08-build2-track-b-round2-report.md",
+  tier: "gate",
+  verify: "`vitest run packages/video-craft` (source-level, no render) - at runtime `video radar:scene --project <dir> --comp <id>` refuses at setup naming the missing tag",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "source",
+    check: {
+      include: INCLUDE,
+      run(_file, relPath, root) {
+        const absPath = join(root, relPath);
+        const planDir = findPlanDir(dirname(absPath), root);
+        if (!planDir || !existsSync(planDir)) return [];
+        if (sceneRootTagDeclared.enforcement.kind !== "source") return [];
+        const selfCheck = sceneRootTagDeclared.enforcement.check;
+        if (!isReporterFile(planDir, absPath, selfCheck, root)) return [];
+        const declared = declaredElements(planDir, root);
+        if (declared.length === 0) return [];
+        const tagged = projectSourceFiles(planDir, selfCheck, root).some((f) => readFileSync(f, "utf8").includes("data-radar-scene-root"));
+        if (tagged) return [];
+        const planFile = declared[0].planFile;
+        const projRel = relative(root, planDir).split(sep).join("/");
+        return [{
+          file: planFile,
+          line: 1,
+          match: "data-radar-scene-root",
+          message: `${projRel} declares names: bindings but no data-radar-scene-root attribute exists anywhere in its source, so radar:scene refuses at setup on every scene. Put data-radar-scene-root="static" on the scene's root AbsoluteFill when the scene has no whole-scene camera transform; when it has one, tag the innermost full-bleed camera layer instead.`
+        }];
+      }
+    }
+  }
+};
+export {
+  sceneRootTagDeclared
+};

package/dist/rules/scrubDemoDataToGenericRoles.js

@@ -0,0 +1,15 @@
+const scrubDemoDataToGenericRoles = {
+  id: "scrub-demo-data-to-generic-roles",
+  claim: "Scrub all demo data visible in rebuilt UI to generic role placeholders (A. Admin, A. Auditor) before render; never carry real names, emails, or org data from recon captures into panels.",
+  why: "Recon captures come from a live authenticated portal, so copied-in table rows are real PII by default; unscrubbed panels leak a client's real user data into a marketing video.",
+  learnedFrom: "act854-video/BUILD_NOTES.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: {
+    kind: "prose",
+    anchor: { file: "qpa-video/03_scenes/act854/panels.jsx" }
+  }
+};
+export {
+  scrubDemoDataToGenericRoles
+};

package/dist/rules/selfReviewThePlanForGaps.js

@@ -0,0 +1,15 @@
+const selfReviewThePlanForGaps = {
+  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" }
+  }
+};
+export {
+  selfReviewThePlanForGaps
+};

package/dist/rules/sourceArchivedBeforeBrief.js

@@ -0,0 +1,17 @@
+const sourceArchivedBeforeBrief = {
+  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."
+  }
+};
+export {
+  sourceArchivedBeforeBrief
+};

package/dist/rules/statisticsSelfExplanatory.js

@@ -0,0 +1,15 @@
+const statisticsSelfExplanatory = {
+  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" }
+  }
+};
+export {
+  statisticsSelfExplanatory
+};

package/dist/rules/stopsAsRelativeSpacing.js

@@ -0,0 +1,15 @@
+const stopsAsRelativeSpacing = {
+  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" }
+  }
+};
+export {
+  stopsAsRelativeSpacing
+};

package/dist/rules/theWholeCanvasWorks.js

@@ -0,0 +1,15 @@
+const theWholeCanvasWorks = {
+  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."
+  }
+};
+export {
+  theWholeCanvasWorks
+};

package/dist/rules/themePerSection.js

@@ -0,0 +1,22 @@
+const themePerSection = {
+  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" }
+  }
+};
+export {
+  themePerSection
+};

package/dist/rules/thesisDeclaredInBrief.js

@@ -0,0 +1,17 @@
+const thesisDeclaredInBrief = {
+  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."
+  }
+};
+export {
+  thesisDeclaredInBrief
+};

package/dist/rules/tierARequiresPropUnreachableEdit.js

@@ -0,0 +1,15 @@
+const tierARequiresPropUnreachableEdit = {
+  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" }
+  }
+};
+export {
+  tierARequiresPropUnreachableEdit
+};

package/dist/rules/tinyBodyCopyAsRuledLines.js

@@ -0,0 +1,15 @@
+const tinyBodyCopyAsRuledLines = {
+  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" }
+  }
+};
+export {
+  tinyBodyCopyAsRuledLines
+};

package/dist/rules/titlesPinnedOutsideCameraPush.js

@@ -0,0 +1,15 @@
+const titlesPinnedOutsideCameraPush = {
+  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" }
+  }
+};
+export {
+  titlesPinnedOutsideCameraPush
+};

package/dist/rules/tokensNotRawHexes.js

@@ -0,0 +1,60 @@
+import { SyntaxKind } from "ts-morph";
+const HEX = /#[0-9a-fA-F]{3,8}\b/g;
+const WHITE_BLACK = /* @__PURE__ */ new Set(["#fff", "#ffffff", "#000", "#000000"]);
+function paletteHexes(text) {
+  return [...text.matchAll(HEX)].map((m) => m[0]).filter((h) => !WHITE_BLACK.has(h.toLowerCase()));
+}
+const LITERAL_KINDS = [
+  SyntaxKind.StringLiteral,
+  SyntaxKind.NoSubstitutionTemplateLiteral,
+  SyntaxKind.TemplateHead,
+  SyntaxKind.TemplateMiddle,
+  SyntaxKind.TemplateTail
+];
+const tokensNotRawHexes = {
+  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) => {
+        const findings = [];
+        for (const kind of LITERAL_KINDS) {
+          for (const literal of file.getDescendantsOfKind(kind)) {
+            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;
+      }
+    }
+  }
+};
+export {
+  tokensNotRawHexes
+};

package/dist/rules/typeTokenDefaultedParamsAsString.js

@@ -0,0 +1,15 @@
+const typeTokenDefaultedParamsAsString = {
+  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" }
+  }
+};
+export {
+  typeTokenDefaultedParamsAsString
+};

package/dist/rules/varyKitChoreographyAcrossSections.js

@@ -0,0 +1,15 @@
+const varyKitChoreographyAcrossSections = {
+  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" }
+  }
+};
+export {
+  varyKitChoreographyAcrossSections
+};

package/dist/rules/varyTheVisualizationGrammar.js

@@ -0,0 +1,15 @@
+const varyTheVisualizationGrammar = {
+  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."
+  }
+};
+export {
+  varyTheVisualizationGrammar
+};

package/dist/rules/verifyCheapRenderDear.js

@@ -0,0 +1,15 @@
+const verifyCheapRenderDear = {
+  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" }
+  }
+};
+export {
+  verifyCheapRenderDear
+};

package/dist/rules/voAddressesTheViewer.js

@@ -0,0 +1,15 @@
+const voAddressesTheViewer = {
+  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" }
+  }
+};
+export {
+  voAddressesTheViewer
+};

package/dist/rules/voIsAPerformance.js

@@ -0,0 +1,15 @@
+const voIsAPerformance = {
+  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."
+  }
+};
+export {
+  voIsAPerformance
+};

package/dist/rules/voScriptLocksSpokenWords.js

@@ -0,0 +1,15 @@
+const voScriptLocksSpokenWords = {
+  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" }
+  }
+};
+export {
+  voScriptLocksSpokenWords
+};

package/dist/rules/wrappersPreserveChildGeometry.js

@@ -0,0 +1,15 @@
+const wrappersPreserveChildGeometry = {
+  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" }
+  }
+};
+export {
+  wrappersPreserveChildGeometry
+};

package/dist/sourceCheck.js

@@ -0,0 +1,47 @@
+import { relative, sep } from "node:path";
+import { globSync } from "tinyglobby";
+import { Project, ts } from "ts-morph";
+const toPosix = (p) => p.split(sep).join("/");
+const newProject = () => new Project({
+  skipAddingFilesFromTsConfig: true,
+  compilerOptions: { allowJs: true, jsx: ts.JsxEmit.ReactJSX }
+});
+function checkFile(check, absPath, relPath, root) {
+  return check.run(newProject().addSourceFileAtPath(absPath), relPath, root);
+}
+function matchedFiles(check, root) {
+  return globSync(check.include, {
+    cwd: root,
+    absolute: true,
+    ignore: [
+      // Test files are not scenes; broad per-project globs would otherwise
+      // sweep them into every check's blast radius.
+      "**/node_modules/**",
+      "**/.worktrees/**",
+      "**/04_exports/**",
+      "**/*.test.{ts,tsx,jsx}",
+      // Webpack output is not scene source either. build/ is gitignored, so
+      // whether it exists depends on what was last run on this machine: a
+      // locally bundled qse-investor-video put 161 minified-bundle findings
+      // into the corpus and turned the suite red only where someone had
+      // happened to run `npm run build`. A check whose verdict varies by
+      // machine is a flake, not a guard.
+      "**/build/**",
+      ...check.exclude ?? []
+    ]
+  }).sort();
+}
+function runSourceCheck(check, root) {
+  const project = newProject();
+  const findings = [];
+  for (const abs of matchedFiles(check, root)) {
+    const file = project.addSourceFileAtPath(abs);
+    findings.push(...check.run(file, toPosix(relative(root, abs)), root));
+  }
+  return findings;
+}
+export {
+  checkFile,
+  matchedFiles,
+  runSourceCheck
+};

package/dist/sourceCitations.js

@@ -0,0 +1,68 @@
+import { ts } from "ts-morph";
+function scriptKindFor(fileName) {
+  if (fileName.endsWith(".tsx")) return ts.ScriptKind.TSX;
+  if (fileName.endsWith(".jsx")) return ts.ScriptKind.JSX;
+  if (/\.(?:m|c)?js$/.test(fileName)) return ts.ScriptKind.JS;
+  return ts.ScriptKind.TS;
+}
+function commentsOnly(text, fileName) {
+  const source = ts.createSourceFile(
+    fileName,
+    text,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */
+    false,
+    scriptKindFor(fileName)
+  );
+  const diagnostics = source.parseDiagnostics ?? [];
+  const first = diagnostics[0];
+  if (first) {
+    const { line } = source.getLineAndCharacterOfPosition(first.start);
+    throw new Error(
+      `${fileName}:${line + 1} cannot be parsed as ${ts.ScriptKind[scriptKindFor(fileName)]}: ${ts.flattenDiagnosticMessageText(first.messageText, " ")}. The citation guard reads comments by parsing, so an unparseable file would be scanned as if it had none.`
+    );
+  }
+  const ranges = [];
+  const jsxText = [];
+  const seen = /* @__PURE__ */ new Set();
+  const take = (pos) => {
+    for (const range of [
+      ...ts.getLeadingCommentRanges(text, pos) ?? [],
+      ...ts.getTrailingCommentRanges(text, pos) ?? []
+    ]) {
+      if (seen.has(range.pos)) continue;
+      seen.add(range.pos);
+      ranges.push(range);
+    }
+  };
+  const walk = (node) => {
+    if (node.kind === ts.SyntaxKind.JsxText) jsxText.push({ pos: node.pos, end: node.end });
+    take(node.pos);
+    for (const child of node.getChildren(source)) walk(child);
+  };
+  walk(source);
+  return ranges.filter((r) => !jsxText.some((j) => r.pos >= j.pos && r.pos < j.end)).map((r) => text.slice(r.pos, r.end)).join("\n");
+}
+const TRAILING = /[.,;:!?)\]}`'"]+$/;
+const DOC_EXTENSIONS = [".md", ".json", ".yaml", ".yml", ".txt"];
+const DOC_PATTERN = /(?<![\w/.-])docs\/[A-Za-z0-9._/*-]+/g;
+function extractDocCitations(text) {
+  const out = [];
+  for (const raw of text.match(DOC_PATTERN) ?? []) {
+    const path = raw.replace(TRAILING, "");
+    if (path.includes("*")) continue;
+    const resolvable = path.endsWith("/") || DOC_EXTENSIONS.some((e) => path.endsWith(e));
+    if (!resolvable) continue;
+    if (!out.includes(path)) out.push(path);
+  }
+  return out;
+}
+const ISSUE_PATTERN = /\b(?:remotion-videos|video-toolchain)-[a-z0-9]{3,4}\b/g;
+function extractIssueCitations(text) {
+  return [...new Set(text.match(ISSUE_PATTERN) ?? [])].sort();
+}
+export {
+  commentsOnly,
+  extractDocCitations,
+  extractIssueCitations
+};

package/dist/stageProjection.js

@@ -0,0 +1,69 @@
+import { ALL_STAGES } from "./stages.js";
+const exceptionLines = (r) => (r.exceptions ?? []).map(
+  (ex) => `  - waived in \`${ex.project}\`: ${ex.decision} (recorded: \`${ex.recordedIn}\`)`
+);
+function renderStageSheet(rules, stages, stage) {
+  const mine = rules.filter((r) => r.scope.kind === "pipeline" && (stages[r.id] ?? []).includes(stage)).sort((a, b) => a.id.localeCompare(b.id));
+  const of = (tier) => mine.filter((r) => r.tier === tier);
+  const section = (heading, rs, withVerify) => rs.length === 0 ? [] : [
+    heading,
+    ``,
+    ...rs.map(
+      (r) => [
+        `- ${r.claim} (\`${r.id}\`)`,
+        ...withVerify && r.verify ? [`  - verify: ${r.verify}`] : [],
+        ...exceptionLines(r)
+      ].join("\n")
+    ),
+    ``
+  ];
+  return [
+    `<!-- Generated from packages/video-craft/src/rules/ + stages.ts. Do not edit. -->`,
+    ``,
+    `# Rules for the ${stage} stage`,
+    ``,
+    `These are the registry rules scoped to ${stage}-stage agents. Scoping narrows attention, never authority: every rule in the registry still applies to you. This sheet carries the full claim of each rule in scope; HOW_I_BUILD_VIDEOS.md carries every rule's claim, why and provenance, and is where to read one you meet only as an id (search for it in a \`Rule id:\` line). CLAUDE.md lists the out-of-scope rules by id rather than in full, so do not treat it as the place to go for a claim.`,
+    ``,
+    ...section(`## Gates - settled by running the check, not by reading the diff`, of("gate"), true),
+    ...section(`## Craft rules`, of("craft"), false),
+    ...section(`## Process rules`, of("process"), false)
+  ].join("\n").trimEnd();
+}
+function extractEdgeSection(doc, name) {
+  const begin = `<!-- edge:begin ${name} -->`;
+  const end = `<!-- edge:end ${name} -->`;
+  const from = doc.indexOf(begin);
+  if (from === -1) throw new Error(`marker "edge:begin ${name}" not found in CREATIVE_EDGE.md`);
+  if (doc.indexOf(begin, from + begin.length) !== -1) {
+    throw new Error(`marker "edge:begin ${name}" appears more than once in CREATIVE_EDGE.md`);
+  }
+  const to = doc.indexOf(end, from);
+  if (to === -1) throw new Error(`marker "edge:end ${name}" not found in CREATIVE_EDGE.md`);
+  if (doc.indexOf(end, to + end.length) !== -1) {
+    throw new Error(`marker "edge:end ${name}" appears more than once in CREATIVE_EDGE.md`);
+  }
+  return doc.slice(from + begin.length, to).trim();
+}
+function renderRuleSheetsJson(rules, stages, creativeEdgeDoc) {
+  const sheets = {};
+  for (const stage of ALL_STAGES) {
+    sheets[stage] = renderStageSheet(rules, stages, stage);
+  }
+  return `${JSON.stringify(
+    {
+      stages: sheets,
+      creativeEdge: {
+        bar: extractEdgeSection(creativeEdgeDoc, "bar"),
+        checklist: extractEdgeSection(creativeEdgeDoc, "checklist")
+      }
+    },
+    null,
+    2
+  )}
+`;
+}
+export {
+  extractEdgeSection,
+  renderRuleSheetsJson,
+  renderStageSheet
+};