@revola-ai/video-craft 0.2.1

package/dist/stages.js

@@ -0,0 +1,163 @@
+const STAGES = {
+  // gates
+  "audio-is-the-clock": ["vo", "review", "ship"],
+  "check-pin-before-ship": ["ship"],
+  "data-radar-tags-declared": ["scene", "amplify", "review"],
+  "derive-seams-dont-measure": ["scene", "amplify", "review"],
+  "deterministic-scene-source": ["scene", "amplify", "review"],
+  "element-onscreen-for-its-vo-sentence": ["plan", "scene", "amplify", "review"],
+  "geometric-seams-not-crossfades": ["plan", "scene", "review"],
+  "geometry-sidecar-exports-typed": ["scene", "amplify", "review"],
+  "hero-fills-the-frame": ["scene", "amplify", "review"],
+  "interpolate-literal-keys-monotonic": ["scene", "amplify", "review"],
+  "master-mix-loudness-target": ["audio", "ship"],
+  "no-double-frame-shift": ["scene", "amplify", "review"],
+  "no-nested-svg-filters": ["scene", "amplify", "review"],
+  "no-shorthand-with-undefined-longhand": ["scene", "amplify", "review"],
+  "no-stacked-fades-at-a-cut": ["scene", "review"],
+  "no-static-holds": ["scene", "amplify", "review"],
+  "occlusion-visible-elements": ["scene", "amplify", "review"],
+  "predraw-content-present-at-the-cut": ["scene", "review"],
+  "radar-dispositions-are-human-only": ["review", "ship"],
+  "scene-root-tag-declared": ["scene", "amplify", "review"],
+  "source-archived-before-brief": ["recon", "review"],
+  "thesis-declared-in-brief": ["plan", "review"],
+  "tokens-not-raw-hexes": ["scene", "amplify", "review"],
+  // craft
+  "approved-sfx-palette-only": ["audio", "review"],
+  "atmosphere-gradients-fade-at-both-ends": ["scene", "amplify"],
+  "beats-derive-from-their-own-sequence": ["scene", "amplify"],
+  "camera-is-the-narrator": ["plan", "scene", "amplify", "review"],
+  "cold-viewer-clarity": ["plan", "scene", "review"],
+  "commit-or-cut-effects": ["scene", "amplify", "review"],
+  "convert-frames-across-clock-boundary": ["scene", "amplify"],
+  "cross-cut-elements-live-in-the-hud-layer": ["scene", "amplify"],
+  "cursor-clicks-real-controls": ["scene", "review"],
+  "cut-on-real-audio-pauses": ["plan", "vo"],
+  "dark-but-never-dim": ["scene", "amplify", "review"],
+  "declare-a-vertical-zone-map": ["scene", "amplify"],
+  "diegetic-sound-for-onscreen-actions": ["scene", "audio", "review"],
+  "distinct-transition-per-beat": ["scene", "amplify", "review"],
+  "download-or-draw-rich-assets": ["recon", "scene", "amplify", "review"],
+  "energy-from-timing-not-part-count": ["plan", "scene", "amplify", "review"],
+  "fix-crowding-by-rebanding-not-nudging": ["scene", "amplify"],
+  "floating-not-boxed": ["scene", "amplify", "review"],
+  "focus-beats-recede-the-context": ["scene", "amplify"],
+  "font-vars-brand-remocn": ["scene"],
+  "glow-is-a-focal-accent": ["scene", "amplify", "review"],
+  "html-masks-for-animated-counters": ["scene", "amplify"],
+  "impact-stack-on-payoffs": ["scene", "amplify"],
+  "interactive-targets-are-declared-data": ["plan", "scene"],
+  "lateness-is-structural-overlap-the-beats": ["plan", "scene", "amplify"],
+  "less-text-more-visualizations": ["plan", "scene", "amplify", "review"],
+  "make-2d-elements-3d": ["scene", "amplify", "review"],
+  "motion-carries-weight-and-meaning": ["scene", "amplify", "review"],
+  "motion-density-floor": ["scene", "amplify", "review"],
+  "never-restate-derived-frame-numbers-in-comments": ["scene", "amplify"],
+  "no-ai-gradient-look": ["scene", "amplify", "review"],
+  "no-colored-flash-to-hide-a-cut": ["scene", "review"],
+  "no-linear-motion": ["scene", "amplify", "review"],
+  "no-repeated-asset-across-shots": ["plan", "scene", "review"],
+  "one-continuous-vo-track": ["vo", "scene"],
+  "one-punch-per-moment-class": ["scene", "amplify", "review"],
+  "open-static-after-a-hard-cut": ["scene", "review"],
+  "openings-and-closings-carry-more": ["plan", "scene", "amplify", "review"],
+  "persistent-device-frames": ["plan", "scene"],
+  "premium-surfaces-not-flat-borders": ["scene", "amplify"],
+  "real-assets-not-placeholders": ["recon", "scene", "review"],
+  "rebuild-ui-from-recon-not-screenshots": ["recon", "scene"],
+  "remap-rate-endpoint-formula": ["scene"],
+  "remocn-content-tailwind-chrome": ["scene", "amplify"],
+  "retime-only-via-playback-or-design-tokens": ["scene", "vo"],
+  "sample-brand-from-product": ["recon", "scene"],
+  "sample-velocity-from-previous-frame-position": ["scene", "amplify"],
+  "scrub-demo-data-to-generic-roles": ["recon", "scene", "review"],
+  "statistics-self-explanatory": ["plan", "vo", "scene", "review"],
+  "stops-as-relative-spacing": ["scene"],
+  "the-whole-canvas-works": ["scene", "amplify", "review"],
+  "theme-per-section": ["plan", "scene"],
+  "tiny-body-copy-as-ruled-lines": ["scene"],
+  "titles-pinned-outside-camera-push": ["scene", "review"],
+  "type-token-defaulted-params-as-string": ["scene"],
+  "vary-kit-choreography-across-sections": ["plan", "scene", "amplify", "review"],
+  "vary-the-visualization-grammar": ["plan", "scene", "amplify", "review"],
+  "vo-addresses-the-viewer": ["plan", "vo"],
+  "vo-is-a-performance": ["vo", "review"],
+  "wrappers-preserve-child-geometry": ["scene", "amplify"],
+  // process
+  "best-scene-sets-the-bar": ["amplify", "review"],
+  "bump-before-refreeze": ["ship"],
+  "delete-rejected-rigs-completely": ["scene", "amplify"],
+  "emit-build-notes": ["review", "ship"],
+  // egw3: NOT in scene/amplify. Dispatched scene/fix/amplify agents are
+  // author-once - their task bodies command "typecheck only, no render, no
+  // stills" - so shipping a render-evidence rule in the same prompt made the
+  // two contradict; whichever the worker obeyed, it violated the other. The
+  // review/fix-round driver renders, so evidence rules live there.
+  "evidence-before-claiming-fixed": ["review"],
+  "exact-peer-lockstep": ["ship"],
+  "first-pass-is-a-draft": ["plan", "amplify"],
+  "fixes-preserve-approved-elements": ["scene", "amplify", "review"],
+  "live-link-duplicate-react-alias": ["scene"],
+  "measure-alignment-dont-eyeball": ["scene", "amplify", "review"],
+  "never-edit-tier-b-vendored": ["scene", "amplify"],
+  "no-duplicate-motion-primitives": ["scene"],
+  "one-render-per-round": ["review", "ship"],
+  "pixel-diff-an-empty-band-first": ["review"],
+  "plan-is-published-not-gating": ["plan"],
+  "powered-by-revola-watermark": ["plan", "scene", "review"],
+  "recon-strands-run-in-parallel": ["recon"],
+  "registry-before-handrolling": ["scene"],
+  "review-the-render-by-frame-sweep": ["review"],
+  "same-family-same-project": ["plan"],
+  "self-review-the-plan-for-gaps": ["plan"],
+  "tier-a-requires-prop-unreachable-edit": ["scene", "ship"],
+  // egw3: NOT in scene/amplify, same contradiction as
+  // evidence-before-claiming-fixed above - the rule's "run the full render
+  // only on demand" framing presumes a driver that CAN render.
+  "verify-cheap-render-dear": ["review", "ship"],
+  "vo-script-locks-spoken-words": ["plan", "vo"]
+};
+function validateStages(rules, stages) {
+  const errors = [];
+  const pipelineIds = new Set(rules.filter((r) => r.scope.kind === "pipeline").map((r) => r.id));
+  for (const rule of rules) {
+    if (rule.scope.kind !== "pipeline") continue;
+    const assigned = stages[rule.id];
+    if (!assigned || assigned.length === 0) {
+      errors.push(`pipeline rule "${rule.id}" has no stage assignment`);
+      continue;
+    }
+    for (const s of assigned) {
+      if (!ALL_STAGES.includes(s)) {
+        errors.push(`rule "${rule.id}" carries unknown stage "${s}"`);
+      }
+    }
+    if (rule.tier === "gate" && !assigned.includes("review") && !assigned.includes("ship")) {
+      errors.push(`gate "${rule.id}" carries neither "review" nor "ship"`);
+    }
+  }
+  for (const id of Object.keys(stages)) {
+    if (!pipelineIds.has(id)) {
+      errors.push(`stage entry "${id}" matches no pipeline rule`);
+    }
+  }
+  return errors;
+}
+const ALL_STAGES = [
+  "recon",
+  "plan",
+  "scene",
+  "amplify",
+  "review",
+  "vo",
+  "audio",
+  "ship"
+];
+const _allStagesExhaustive = true;
+void _allStagesExhaustive;
+export {
+  ALL_STAGES,
+  STAGES,
+  validateStages
+};

package/dist/testSupport.js

@@ -0,0 +1,6 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const toolchainRepoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+export {
+  toolchainRepoRoot
+};

package/dist/variants.js

@@ -0,0 +1,8 @@
+const COMPONENT_VARIANTS = {
+  "rolling-number": ["odometer", "slam"],
+  "animated-bar-chart": ["grow", "cascade"],
+  "animated-line-chart": ["draw", "sweep"]
+};
+export {
+  COMPONENT_VARIANTS
+};

package/dist/waiverProjection.js

@@ -0,0 +1,20 @@
+function renderWaivers(rules) {
+  return rules.flatMap(
+    (rule) => (rule.exceptions ?? []).map((ex) => ({
+      ruleId: rule.id,
+      project: ex.project,
+      ...ex.element !== void 0 ? { element: ex.element } : {},
+      ...ex.seam !== void 0 ? { seam: ex.seam } : {},
+      recordedIn: ex.recordedIn
+    }))
+  );
+}
+const sortKey = (w) => `${w.ruleId ?? w.checkId ?? ""}:${w.project}:${w.element ?? ""}:${w.seam ?? ""}`;
+function renderWaiversJson(rules) {
+  const sorted = [...renderWaivers(rules)].sort((a, b) => sortKey(a) < sortKey(b) ? -1 : sortKey(a) > sortKey(b) ? 1 : 0);
+  return JSON.stringify(sorted, null, 2) + "\n";
+}
+export {
+  renderWaivers,
+  renderWaiversJson
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@revola-ai/video-craft",
+  "version": "0.2.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    "./corpus": "./src/corpus.ts",
+    "./projectDocSync": "./src/projectDocSync.ts",
+    "./types": "./src/types.ts",
+    "./dist/*": "./dist/*"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "scripts": {
+    "build": "node scripts/build-dist.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "node -e \"if (process.env.REVOLA_RELEASE !== '1') { console.error('publish only through npm run release:publish'); process.exit(1) }\""
+  },
+  "dependencies": {
+    "ts-morph": "^24.0.0",
+    "tinyglobby": "^0.2.10",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.1"
+  }
+}

package/src/anchors.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, test } from "vitest";
+import { verifyAnchors } from "./anchors";
+import { toolchainRepoRoot } from "./testSupport";
+import { RULES } from "./registry";
+import type { Rule } from "./types";
+
+const prose = (anchor: Rule["enforcement"]): Rule => ({
+  id: "a-rule",
+  claim: "Do the thing.",
+  why: "Otherwise the other thing breaks.",
+  learnedFrom: "revola-video/BUILD_NOTES_CRAFT.md",
+  tier: "craft",
+  scope: { kind: "pipeline" },
+  enforcement: anchor,
+});
+
+describe("verifyAnchors", () => {
+  test("accepts an anchor whose file and symbol both exist", () => {
+    const rule = prose({
+      kind: "prose",
+      anchor: { file: "packages/video-craft/src/provenance.ts", symbol: "isUpstreamProvenance" },
+    });
+    expect(verifyAnchors([rule], toolchainRepoRoot)).toEqual([]);
+  });
+
+  test("accepts a file-only anchor", () => {
+    const rule = prose({
+      kind: "prose",
+      anchor: { file: "packages/video-craft/src/provenance.ts" },
+    });
+    expect(verifyAnchors([rule], toolchainRepoRoot)).toEqual([]);
+  });
+
+  test("reports a missing file", () => {
+    const rule = prose({
+      kind: "prose",
+      anchor: { file: "packages/video-craft/src/Deleted.tsx" },
+    });
+    expect(verifyAnchors([rule], toolchainRepoRoot)[0]).toMatch(
+      /rule "a-rule": anchor file "packages\/video-craft\/src\/Deleted.tsx" does not exist/,
+    );
+  });
+
+  test("reports a missing symbol in a file that still exists", () => {
+    const rule = prose({
+      kind: "prose",
+      anchor: { file: "packages/video-craft/src/provenance.ts", symbol: "renamedAway" },
+    });
+    expect(verifyAnchors([rule], toolchainRepoRoot)[0]).toMatch(
+      /rule "a-rule": anchor symbol "renamedAway" no longer exists in "packages\/video-craft\/src\/provenance.ts"/,
+    );
+  });
+
+  test("ignores unanchorable rules", () => {
+    const rule = prose({ kind: "prose", unanchorable: "process guidance" });
+    expect(verifyAnchors([rule], toolchainRepoRoot)).toEqual([]);
+  });
+
+  test("reports a learnedFrom file that does not exist", () => {
+    const rule = {
+      ...prose({ kind: "prose", unanchorable: "process guidance" }),
+      learnedFrom: "packages/video-craft/DELETED_NOTES.md",
+    };
+    expect(verifyAnchors([rule], toolchainRepoRoot)[0]).toMatch(
+      /rule "a-rule": learnedFrom "packages\/video-craft\/DELETED_NOTES.md" does not exist/,
+    );
+  });
+
+  test("ignores source rules", () => {
+    const rule: Rule = {
+      ...prose({ kind: "prose", unanchorable: "x" }),
+      enforcement: { kind: "source", check: { include: [], run: () => [] } },
+    };
+    expect(verifyAnchors([rule], toolchainRepoRoot)).toEqual([]);
+  });
+});
+
+describe("upstream provenance (extracted from remotion-videos)", () => {
+  test("accepts a learnedFrom citing an upstream project without touching disk", () => {
+    // The prose helper's learnedFrom already cites revola-video, which stayed
+    // upstream; a clean run proves it is treated as a citation, not a path.
+    const rule = prose({ kind: "prose", unanchorable: "process guidance" });
+    expect(verifyAnchors([rule], toolchainRepoRoot)).toEqual([]);
+  });
+
+  test("accepts an upstream anchor file and skips its symbol", () => {
+    const rule = prose({
+      kind: "prose",
+      anchor: { file: "revola-video/src/scenes/craft/ink.tsx", symbol: "wobbled" },
+    });
+    expect(verifyAnchors([rule], toolchainRepoRoot)).toEqual([]);
+  });
+
+  test("rejects a malformed upstream citation", () => {
+    const rule = {
+      ...prose({ kind: "prose", unanchorable: "process guidance" }),
+      learnedFrom: "revola-video/../secrets.md",
+    };
+    expect(verifyAnchors([rule], toolchainRepoRoot)[0]).toMatch(
+      /rule "a-rule": learnedFrom "revola-video\/\.\.\/secrets.md" is a malformed upstream citation/,
+    );
+  });
+
+  test("qse-qguard-video moved with this repo, so its paths must still resolve", () => {
+    const rule = {
+      ...prose({ kind: "prose", unanchorable: "process guidance" }),
+      learnedFrom: "qse-qguard-video/DELETED_NOTES.md",
+    };
+    expect(verifyAnchors([rule], toolchainRepoRoot)[0]).toMatch(
+      /rule "a-rule": learnedFrom "qse-qguard-video\/DELETED_NOTES.md" does not exist/,
+    );
+  });
+});
+
+describe("the real registry", () => {
+  test("every prose anchor resolves", () => {
+    expect(verifyAnchors(RULES, toolchainRepoRoot)).toEqual([]);
+  });
+});

package/src/anchors.ts

@@ -0,0 +1,110 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { Project, ts } from "ts-morph";
+import { isUpstreamProvenance, upstreamCitationError } from "./provenance";
+import type { Rule } from "./types";
+
+/**
+ * Resolves every prose rule's anchor, and every rule's learnedFrom provenance.
+ * A dangling anchor means the rule is making a claim about code that no longer
+ * exists, which is the exact failure mode that turned BUILD_NOTES into a
+ * document you cannot trust. A dangling learnedFrom means the rule cites an
+ * origin that is gone - and a rule with no origin is an opinion.
+ *
+ * Paths under UPSTREAM_PROVENANCE_ROOTS cite the pre-split remotion-videos
+ * repo and are format-checked instead of resolved on disk; everything else
+ * must exist here, and a missing local path is still a failure.
+ */
+
+// A provenance path either cites upstream (format check only) or must
+// resolve locally. Returns the failure reason, or undefined when the path
+// is acceptable.
+function provenanceError(path: string, root: string): string | undefined {
+  if (isUpstreamProvenance(path)) {
+    const malformed = upstreamCitationError(path);
+    return malformed ? `is a malformed upstream citation (${malformed})` : undefined;
+  }
+  return existsSync(join(root, path)) ? undefined : "does not exist";
+}
+
+export function verifyAnchors(rules: Rule[], root: string): string[] {
+  const errors: string[] = [];
+
+  // One Project for the whole pass; adding a file is cheap, constructing a
+  // compiler host is not.
+  const project = new Project({
+    useInMemoryFileSystem: false,
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: { allowJs: true, jsx: ts.JsxEmit.ReactJSX },
+  });
+
+  for (const rule of rules) {
+    if (rule.learnedFrom) {
+      const bad = provenanceError(rule.learnedFrom, root);
+      if (bad) {
+        errors.push(`rule "${rule.id}": learnedFrom "${rule.learnedFrom}" ${bad}`);
+      }
+    }
+
+    // Same failure mode as a dangling learnedFrom: a waiver citing a decision
+    // record that is gone is an opinion wearing a client's name.
+    for (const ex of rule.exceptions ?? []) {
+      const badRecord = provenanceError(ex.recordedIn, root);
+      if (badRecord) {
+        errors.push(
+          `rule "${rule.id}": exception recordedIn "${ex.recordedIn}" ${badRecord}`,
+        );
+      }
+      const badProject = provenanceError(ex.project, root);
+      if (badProject) {
+        errors.push(`rule "${rule.id}": exception project "${ex.project}" ${badProject}`);
+      }
+    }
+
+    if (rule.enforcement.kind !== "prose") continue;
+    if (!("anchor" in rule.enforcement)) continue;
+
+    const { file, symbol } = rule.enforcement.anchor;
+
+    // An upstream anchor file cannot be opened here, so its symbol cannot be
+    // resolved either; the citation's shape is the whole check.
+    if (isUpstreamProvenance(file)) {
+      const malformed = upstreamCitationError(file);
+      if (malformed) {
+        errors.push(
+          `rule "${rule.id}": anchor file "${file}" is a malformed upstream citation (${malformed})`,
+        );
+      }
+      continue;
+    }
+
+    const abs = join(root, file);
+
+    if (!existsSync(abs)) {
+      errors.push(`rule "${rule.id}": anchor file "${file}" does not exist`);
+      continue;
+    }
+    if (!symbol) continue;
+
+    // Add-or-get: two rules may anchor into the same file, and re-adding a
+    // path must not depend on ts-morph's re-add semantics.
+    const source = project.getSourceFile(abs) ?? project.addSourceFileAtPath(abs);
+    // Exported declarations cover the single-source-of-truth exports these
+    // rules point at. A top-level non-exported name is also accepted, because
+    // some anchors are internal invariants rather than public surface.
+    const exported = source.getExportedDeclarations().has(symbol);
+    const local = source.getVariableDeclaration(symbol) !== undefined
+      || source.getFunction(symbol) !== undefined
+      || source.getInterface(symbol) !== undefined
+      || source.getTypeAlias(symbol) !== undefined;
+
+    if (!exported && !local) {
+      errors.push(
+        `rule "${rule.id}": anchor symbol "${symbol}" no longer exists in "${file}"` +
+        ` - re-anchor the rule to where the evidence now lives; do not flip it to unanchorable`,
+      );
+    }
+  }
+
+  return errors;
+}

package/src/corpus.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "vitest";
+import { corpusFindings, KNOWN_EXCEPTIONS } from "./corpus";
+import { isUpstreamProvenance } from "./provenance";
+import { RULES } from "./registry";
+import { matchedFiles } from "./sourceCheck";
+import { toolchainRepoRoot } from "./testSupport";
+
+const key = (f: { rule: string; file: string; match: string }) => `${f.rule}|${f.file}|${f.match}`;
+
+const REMEDIATE =
+  "Narrow the rule, add a justified KNOWN_EXCEPTIONS entry in src/corpus.ts naming a recorded " +
+  "follow-up, or fix the flagged video in a separate change. See the package README.";
+
+/**
+ * Rule ids allowed to match zero files today. This test's whole purpose is
+ * catching a typo'd include glob that silently checks nothing and looks like
+ * coverage, so this list must stay tiny and each entry must be a genuine
+ * forward-declared convention, not a typo in hiding.
+ *
+ * `geometry-sidecar-exports-typed` (Task 6 of
+ * docs/superpowers/plans/2026-07-30-video-task-graph-phase1.md) checks each
+ * project's "src/scenes/scene.<id>.geometry.ts" sidecars (see the rule's own
+ * `include`) - a convention this same task introduces
+ * (packages/video-kit/src/pure/geometry.ts's `geometrySidecarPath`) with no
+ * adopters yet; scene authoring against it is later work (Tasks 3, 11, 18).
+ * Remove this entry once any project ships its first sidecar.
+ */
+const NOT_YET_ADOPTED = new Set(["geometry-sidecar-exports-typed"]);
+
+/** The top-level directory a glob reaches. */
+const globHead = (glob: string): string => {
+  // "docs/superpowers"-style upstream roots are two segments deep, so match
+  // against the provenance list with the longest prefix the glob spells out
+  // literally (a `*`/`**` head is never upstream - it reaches local files).
+  const segments = glob.split("/");
+  return segments[0] === "docs" && segments.length > 1 ? `${segments[0]}/${segments[1]}` : segments[0]!;
+};
+
+/** A rule whose every include glob points into upstream project roots has
+ *  nothing to scan in THIS repo - its corpus stayed in remotion-videos at the
+ *  2026-08-24 extraction. It is not a typo'd include list; scanning those
+ *  files again in consumer repos is the `craft:check --project` seam. */
+const upstreamOnlyRule = (include: string[]): boolean =>
+  include.length > 0 && include.every((glob) => isUpstreamProvenance(globHead(glob)));
+
+describe("source checks against the existing scene corpus", () => {
+  test("every source rule's globs match at least one file", () => {
+    // A typo'd include list silently checks nothing and looks like coverage.
+    const empty = RULES.filter(
+      (r) =>
+        r.enforcement.kind === "source" &&
+        !NOT_YET_ADOPTED.has(r.id) &&
+        !upstreamOnlyRule(r.enforcement.check.include) &&
+        matchedFiles(r.enforcement.check, toolchainRepoRoot).length === 0,
+    );
+    expect(empty.map((r) => r.id)).toEqual([]);
+  });
+
+  test("every finding is a justified known exception", () => {
+    const excused = new Set(KNOWN_EXCEPTIONS.map(key));
+    const unexplained = corpusFindings(toolchainRepoRoot).filter((f) => !excused.has(key(f)));
+
+    // Printed in full so a failure tells you what to look at rather than just
+    // that a count moved.
+    expect(
+      unexplained.map((f) => `${f.rule} ${f.file}:${f.line} [${f.match}] - ${f.message}`),
+      REMEDIATE,
+    ).toEqual([]);
+    // corpusFindings(toolchainRepoRoot) parses every source-check rule's matched files with a
+    // fresh ts-morph Project (one per rule) across ~10 project layouts;
+    // vitest's 30s default is comfortably enough on an idle machine but flakes
+    // under concurrent load (observed 40-90s wall time with other heavy
+    // processes running). Generous, like the browser/spawning tests
+    // (global-constraints.md) - this is real ts-morph work, not a hang.
+  }, 120_000);
+
+  test("every known exception carries a justification", () => {
+    expect(KNOWN_EXCEPTIONS.filter((e) => !e.justification.trim())).toEqual([]);
+  });
+
+  test("no known exception is stale", () => {
+    const live = new Set(corpusFindings(toolchainRepoRoot).map(key));
+    // Exceptions keyed to upstream files cannot yield findings here (the
+    // files stayed in remotion-videos), so staleness is only checkable for
+    // local files. The upstream entries stay in the data on purpose: the
+    // rules travel to consumer repos where those files DO exist, and the
+    // excuses must travel with them.
+    const stale = KNOWN_EXCEPTIONS.filter(
+      (e) => !isUpstreamProvenance(e.file) && !live.has(key(e)),
+    );
+    expect(
+      stale.map((e) => `${e.rule} ${e.file} [${e.match}]`),
+      "A stale entry usually means the matched text was fixed or rewritten - delete the entry or re-key it to the new text.",
+    ).toEqual([]);
+  }, 120_000); // same corpusFindings(toolchainRepoRoot) sweep cost as the test above
+});