@revola-ai/video-craft 0.2.1

package/src/corpus.ts

@@ -0,0 +1,149 @@
+import { RULES } from "./registry";
+import { matchedFiles, runSourceCheck } from "./sourceCheck";
+import type { SourceFinding } from "./types";
+
+export type Exception = {
+  rule: string;
+  file: string;
+  /**
+   * The exact matched source text the rule reported (SourceFinding.match),
+   * e.g. the hex literal. Keyed on text, not line number: an entry excuses
+   * ALL occurrences of that exact text in that file for that rule. That is
+   * the deliberate tradeoff - a palette hex restated three times is one
+   * decision, not three, and unrelated edits above it can never invalidate
+   * the entry or block pushes. A NEW hex or a different violation is never
+   * silently excused, which line-keying could not guarantee.
+   */
+  match: string;
+  /** Why this finding is acceptable. An empty justification is not allowed. */
+  justification: string;
+};
+
+/**
+ * Findings in existing, shipped video that we have looked at and accepted.
+ * Every entry is a small admission that a rule is imprecise, so this list
+ * staying short is itself a signal. An entry with no justification fails the
+ * corpus test.
+ */
+const HEX_RULE = "tokens-not-raw-hexes";
+const PANEL_FILL = "dark panel fill predates the rule; follow-up: tokenize into CK";
+const BG_RESTATED = "raw restatement of CK.bg (#0b0b0d) predates the rule; follow-up: reference the token";
+const HUE_RESTATED = "avatar hue pair restates CK accent tokens raw; predates the rule; follow-up: reference the tokens";
+const LAVENDER = "lavender text tint (#c9b8fb) has no CK token yet; predates the rule; follow-up: tokenize into CK";
+const ROCKET = "rocket illustration fill has no CK token yet; predates the rule; follow-up: tokenize into CK";
+
+export const KNOWN_EXCEPTIONS: Exception[] = [
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S3Line.tsx", match: "#15141d", justification: PANEL_FILL },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S3Line.tsx", match: "#1c1a26", justification: PANEL_FILL },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S3Line.tsx", match: "#14131c", justification: PANEL_FILL },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S4Proof.tsx", match: "#16151e", justification: PANEL_FILL },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S2Turn.tsx", match: "#0b0b0d", justification: BG_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S4Proof.tsx", match: "#0b0b0d", justification: BG_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/craftKit.tsx", match: "#0b0b0d", justification: BG_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#8B5CF6", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#5CA4F6", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#5fd39a", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#f8b8aa", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#f5d67a", justification: HUE_RESTATED },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/S5Mirror.tsx", match: "#c9b8fb", justification: LAVENDER },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/ink.tsx", match: "#f5c66d", justification: ROCKET },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/ink.tsx", match: "#2a2833", justification: ROCKET },
+  { rule: HEX_RULE, file: "revola-video/src/scenes/craft/ink.tsx", match: "#bda6ff", justification: ROCKET },
+  // v2 (build2) frame-windowed carrier/hero binding: the tag is gated off over
+  // the seam-flight/vacate window (so hero-size never measures the shrinking
+  // carrier and no post-cue pose trips a geometry check), which a string literal
+  // cannot express; the runtime tag coverage (radar:scene tag-coverage, 22/22)
+  // still verifies every binding against sampled frames during its cues.
+  // Follow-up: remotion-videos-emp (source-evaluable hero/carrier windows).
+  {
+    rule: "data-radar-tags-declared", file: "rcp-fund7-video/src/scenes/insurers.tsx",
+    match: 'data-radar={f < T_VACATE ? "insurer-edifice" : undefined}',
+    justification: "frame-windowed carrier tag gated off during the closing travel; runtime tag-coverage (22/22) verifies insurer-edifice during its cues. follow-up: remotion-videos-s300",
+  },
+  {
+    rule: "data-radar-tags-declared", file: "rcp-fund7-video/src/surfaces.tsx",
+    match: "data-radar={radarId}",
+    justification: "Panel forwards its tag via the radarId prop (call sites pass literals); the gate only traces props named dataRadar. Runtime tag-coverage verifies the bindings. follow-up: remotion-videos-s300 (rename prop to dataRadar)",
+  },
+];
+
+export function corpusFindings(root: string): (SourceFinding & { rule: string })[] {
+  const out: (SourceFinding & { rule: string })[] = [];
+  for (const rule of RULES) {
+    if (rule.enforcement.kind !== "source") continue;
+    for (const finding of runSourceCheck(rule.enforcement.check, root)) {
+      out.push({ ...finding, rule: rule.id });
+    }
+  }
+  return out;
+}
+
+/** How a finding is matched against KNOWN_EXCEPTIONS: exact rule, file, and
+ *  matched text - deliberately not the line number (see Exception above). */
+export const findingKey = (f: { rule: string; file: string; match: string }): string =>
+  `${f.rule}|${f.file}|${f.match}`;
+
+/**
+ * A check's include globs narrowed to one project directory under the root.
+ * A glob whose head segment IS the project name is kept verbatim; a glob with
+ * a wildcard head (`*` or `**`) reaches any project, so its head is pinned to
+ * the named project to keep siblings out of the scan. Everything else is
+ * dropped: the include lists name their projects explicitly (see
+ * SourceCheck.include's rationale), so a head that names a different project
+ * is a claim about that project, not this one.
+ */
+const scopedInclude = (include: string[], projectName: string): string[] =>
+  include.flatMap((glob) => {
+    const [head, ...rest] = glob.split("/");
+    if (head === projectName) return [glob];
+    if (head === "*" || head === "**") return [[projectName, ...rest].join("/")];
+    return [];
+  });
+
+export type ProjectScan = {
+  /** Findings NOT excused by KNOWN_EXCEPTIONS - the set that fails a gate. */
+  findings: (SourceFinding & { rule: string })[];
+  /** Findings a justified KNOWN_EXCEPTIONS entry excuses. */
+  excused: (SourceFinding & { rule: string })[];
+  /** Source-rule ids whose include globs reach this project. */
+  coveredRules: string[];
+  /** Source-rule ids with no include glob into this project: their claims go
+   *  unchecked here, which the caller must surface rather than read as clean. */
+  uncoveredRules: string[];
+  /** Distinct files scanned across all covered rules. */
+  scannedFiles: number;
+};
+
+/**
+ * The `video craft:check --project <dir>` seam: runs every source-check rule
+ * over ONE project directory under an explicit root, so a consumer repo can
+ * run the craft gate against the installed package with no vitest wiring of
+ * its own. `root` is the directory containing the project; `projectName` is
+ * the project directory's name, matched against each include glob's head.
+ */
+export function scanProject(root: string, projectName: string): ProjectScan {
+  const findings: (SourceFinding & { rule: string })[] = [];
+  const excused: (SourceFinding & { rule: string })[] = [];
+  const coveredRules: string[] = [];
+  const uncoveredRules: string[] = [];
+  const scanned = new Set<string>();
+  const excusedKeys = new Set(KNOWN_EXCEPTIONS.map(findingKey));
+
+  for (const rule of RULES) {
+    if (rule.enforcement.kind !== "source") continue;
+    const include = scopedInclude(rule.enforcement.check.include, projectName);
+    if (include.length === 0) {
+      uncoveredRules.push(rule.id);
+      continue;
+    }
+    coveredRules.push(rule.id);
+    const check = { ...rule.enforcement.check, include };
+    for (const abs of matchedFiles(check, root)) scanned.add(abs);
+    for (const finding of runSourceCheck(check, root)) {
+      const f = { ...finding, rule: rule.id };
+      (excusedKeys.has(findingKey(f)) ? excused : findings).push(f);
+    }
+  }
+
+  return { findings, excused, coveredRules, uncoveredRules, scannedFiles: scanned.size };
+}

package/src/corpusProject.test.ts

@@ -0,0 +1,103 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { scanProject } from "./corpus";
+
+/** A consumer-shaped root: project dirs at the top level, like the upstream
+ *  repo the include globs were written against. The scene file carries a raw
+ *  hex, which `tokens-not-raw-hexes` (include head `revola-video/`) flags. */
+const HEX_SCENE = [
+  "export const Bad = () => {",
+  '  const fill = "#ff0000";',
+  "  return fill;",
+  "};",
+  "",
+].join("\n");
+
+let dirs: string[] = [];
+const consumerRoot = (): string => {
+  const d = mkdtempSync(join(tmpdir(), "craft-scan-"));
+  dirs.push(d);
+  return d;
+};
+afterEach(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  dirs = [];
+});
+
+const writeScene = (root: string, project: string, rel: string, text: string) => {
+  const abs = join(root, project, rel);
+  mkdirSync(join(abs, ".."), { recursive: true });
+  writeFileSync(abs, text);
+};
+
+describe("scanProject", () => {
+  test("reports findings from the named project only, in root-relative paths", () => {
+    const root = consumerRoot();
+    writeScene(root, "revola-video", "src/scenes/craft/bad.tsx", HEX_SCENE);
+    // A sibling project with the same defect must stay out of scope.
+    writeScene(root, "expanse-video", "src/scenes/bad.tsx", HEX_SCENE);
+
+    const scan = scanProject(root, "revola-video");
+
+    expect(scan.coveredRules).toContain("tokens-not-raw-hexes");
+    const hexFindings = scan.findings.filter((f) => f.rule === "tokens-not-raw-hexes");
+    expect(hexFindings).toHaveLength(1);
+    expect(hexFindings[0].file).toBe("revola-video/src/scenes/craft/bad.tsx");
+    expect(hexFindings[0].match).toBe("#ff0000");
+    expect(scan.findings.every((f) => f.file.startsWith("revola-video/"))).toBe(true);
+  });
+
+  test("scopes wildcard-headed include globs to the named project", () => {
+    const root = consumerRoot();
+    // geometry-sidecar-exports-typed includes "*/src/scenes/scene.*.geometry.ts":
+    // the wildcard head must be pinned to the named project, so the sibling's
+    // equally-broken sidecar stays out of this project's scan.
+    writeScene(root, "revola-video", "src/scenes/scene.s1.geometry.ts", "export const geometry = {};\n");
+    writeScene(root, "expanse-video", "src/scenes/scene.s1.geometry.ts", "export const geometry = {};\n");
+
+    const scan = scanProject(root, "revola-video");
+
+    const geo = scan.findings.filter((f) => f.rule === "geometry-sidecar-exports-typed");
+    expect(geo.length).toBeGreaterThan(0);
+    expect(geo.every((f) => f.file.startsWith("revola-video/"))).toBe(true);
+  });
+
+  test("splits KNOWN_EXCEPTIONS-excused findings out of the failing set", () => {
+    const root = consumerRoot();
+    // corpus.ts excuses #f5c66d in exactly this file for tokens-not-raw-hexes.
+    writeScene(root, "revola-video", "src/scenes/craft/ink.tsx", HEX_SCENE.replace("#ff0000", "#f5c66d"));
+
+    const scan = scanProject(root, "revola-video");
+
+    expect(scan.findings.filter((f) => f.rule === "tokens-not-raw-hexes")).toEqual([]);
+    const excused = scan.excused.filter((f) => f.rule === "tokens-not-raw-hexes");
+    expect(excused).toHaveLength(1);
+    expect(excused[0].match).toBe("#f5c66d");
+  });
+
+  test("a project no include glob covers reports zero covered rules, never a silent clean", () => {
+    const root = consumerRoot();
+    writeScene(root, "acme-video", "src/scenes/craft/bad.tsx", HEX_SCENE);
+
+    const scan = scanProject(root, "acme-video");
+
+    // Only the wildcard-headed geometry glob can reach an arbitrary project
+    // name; every fixed-head rule is uncovered and must say so.
+    expect(scan.coveredRules).not.toContain("tokens-not-raw-hexes");
+    expect(scan.uncoveredRules).toContain("tokens-not-raw-hexes");
+  });
+
+  test("a clean covered project scans files and finds nothing", () => {
+    const root = consumerRoot();
+    writeScene(root, "revola-video", "src/scenes/craft/clean.tsx",
+      'import { CK } from "./craftKit";\nexport const Clean = () => CK;\n');
+
+    const scan = scanProject(root, "revola-video");
+
+    expect(scan.findings).toEqual([]);
+    expect(scan.excused).toEqual([]);
+    expect(scan.scannedFiles).toBeGreaterThan(0);
+  });
+});

package/src/creativeEdge.test.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { RULES } from "./registry";
+import { toolchainRepoRoot as repoRoot } from "./testSupport";
+import { extractEdgeSection } from "./stageProjection";
+
+const DOC = "docs/style/CREATIVE_EDGE.md";
+const doc = readFileSync(join(repoRoot, DOC), "utf8");
+
+/**
+ * CREATIVE_EDGE.md is hand-maintained and links to the registry only through
+ * hand-typed ids on its `Codified:` lines. Nothing else verifies them: a
+ * renamed or deleted rule would silently orphan its directive, and a typo'd
+ * id would send a reviewer citing it into a dead end. This test is the whole
+ * guard.
+ */
+describe("CREATIVE_EDGE.md registry cross-references", () => {
+  test("every id on a Codified: line exists in the registry", () => {
+    const known = new Set(RULES.map((r) => r.id));
+    const codifiedLines = doc.split("\n").filter((l) => l.includes("**Codified:**"));
+    expect(codifiedLines.length).toBeGreaterThan(0);
+
+    // Every backticked token on a Codified line must be a well-formed rule id
+    // AND exist in the registry - a laxer id-shaped regex would silently skip
+    // malformed or single-word ids, defeating the guard.
+    const cited = codifiedLines.flatMap((l) => [...l.matchAll(/`([^`]+)`/g)].map((m) => m[1]));
+    expect(cited.length).toBeGreaterThan(0);
+
+    const ID_GRAMMAR = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+    const malformed = [...new Set(cited)].filter((id) => !ID_GRAMMAR.test(id));
+    expect(malformed, `non-id tokens backticked on Codified: lines`).toEqual([]);
+
+    const unknown = [...new Set(cited)].filter((id) => !known.has(id));
+    expect(unknown, `Codified: ids missing from the registry`).toEqual([]);
+  });
+
+  test("the edge markers extract non-empty bar and checklist sections", () => {
+    // The dispatch shell inlines these for scene/amplify/review agents; a
+    // moved heading that empties a section would ship silent blank prompts.
+    expect(extractEdgeSection(doc, "bar")).toContain("The bar");
+    expect(extractEdgeSection(doc, "checklist")).toContain("amplify-pass checklist");
+  });
+
+  test("the inlined sections stay prompt-sized", () => {
+    // Both sections ride inside EVERY scene/amplify/review dispatch prompt;
+    // unbounded growth silently inflates every dispatch's token bill.
+    expect(extractEdgeSection(doc, "bar").length).toBeLessThan(4000);
+    expect(extractEdgeSection(doc, "checklist").length).toBeLessThan(4000);
+  });
+
+  test("extractEdgeSection fails loud on missing or duplicated markers", () => {
+    expect(() => extractEdgeSection("no markers here", "bar")).toThrow(/edge:begin bar/);
+    expect(() => extractEdgeSection("<!-- edge:begin bar -->text", "bar")).toThrow(/edge:end bar/);
+    const dup = "<!-- edge:begin bar -->a<!-- edge:end bar --><!-- edge:begin bar -->b<!-- edge:end bar -->";
+    expect(() => extractEdgeSection(dup, "bar")).toThrow(/more than once/);
+  });
+});

package/src/distBuild.test.ts

@@ -0,0 +1,86 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { globSync } from "tinyglobby";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { withLockAt } from "../../video-cli/src/graph/worktreeShell";
+import { PACK_LOCK } from "../../../scripts/test-support/packLock";
+
+const exec = promisify(execFile);
+
+/**
+ * The installable dist/ (scripts/build-dist.mjs): the packed @revola-ai/video-cli
+ * bin loads craft's corpus scan and doc splice out of node_modules under plain
+ * node, so craft must ship transpiled JS the way the kit ships dist/pure. The
+ * spawns here run PLAIN node against dist/ - no tsx - because that is exactly
+ * the resolution mode the installed world runs in, and the one tsx's
+ * extensionless tolerance and TS loading would mask.
+ */
+describe("video-craft dist build", () => {
+  const pkgDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+  const distDir = join(pkgDir, "dist");
+
+  // PACK_LOCK held across the WHOLE describe, not only the build
+  // (scripts/test-support/packLock.ts names the race): create-video's
+  // pack.test.ts packs craft from another worker, and craft's prepack
+  // rm -rf's this very dist/ (scripts/dist-lib.mjs) - so a lock released
+  // after beforeAll would still let that rm land while an `it` below is
+  // executing dist/corpus.js under plain node. `withLockAt` is
+  // callback-shaped; the callback parks on a promise that afterAll resolves.
+  // The deadline covers waiting behind both pack tests (~20s each).
+  let release: () => void = () => {};
+  beforeAll(async () => {
+    await new Promise<void>((acquired, refused) => {
+      withLockAt(PACK_LOCK, () => new Promise<void>((done) => { release = done; acquired(); }), { deadlineMs: 170_000 })
+        .catch(refused);
+    });
+    await exec(process.execPath, [join(pkgDir, "scripts", "build-dist.mjs")]);
+  }, 180_000);
+  afterAll(() => { release(); });
+
+  it("transpiles the non-test source tree, data files included, tests and fixtures excluded", () => {
+    for (const rel of ["corpus.js", "projectDocSync.js", "registry.js", "types.js", "radar-check-ids.json"]) {
+      expect(existsSync(join(distDir, rel)), `dist/${rel} missing`).toBe(true);
+    }
+    expect(existsSync(join(distDir, "rules", "tokensNotRawHexes.js"))).toBe(true);
+    expect(globSync(["**/*.test.js", "**/*.ts", "fixtures/**"], { cwd: distDir })).toEqual([]);
+  });
+
+  it("dist/corpus.js scans a project under plain node - ts-morph, globs and the JSON registry import all resolve", async () => {
+    const root = mkdtempSync(join(tmpdir(), "craft-dist-"));
+    const scene = join(root, "revola-video", "src", "scenes", "craft", "bad.tsx");
+    mkdirSync(dirname(scene), { recursive: true });
+    writeFileSync(scene, 'export const Bad = () => "#ff0000";\n');
+
+    const { stdout } = await exec(process.execPath, [
+      "--input-type=module", "-e",
+      `const { scanProject } = await import(${JSON.stringify(join(distDir, "corpus.js"))});
+       console.log(JSON.stringify(scanProject(${JSON.stringify(root)}, "revola-video").findings));`,
+    ]);
+
+    const findings = JSON.parse(stdout);
+    expect(findings).toEqual(expect.arrayContaining([
+      expect.objectContaining({ rule: "tokens-not-raw-hexes", match: "#ff0000" }),
+    ]));
+  });
+
+  it("dist/projectDocSync.js splices the CLAUDE.md block under plain node", async () => {
+    const root = mkdtempSync(join(tmpdir(), "craft-dist-sync-"));
+    writeFileSync(join(root, "CLAUDE.md"),
+      "# t\n<!-- craft:begin claude-md -->\nOLD\n<!-- craft:end claude-md -->\n");
+
+    await exec(process.execPath, [
+      "--input-type=module", "-e",
+      `const { syncProjectedDocs } = await import(${JSON.stringify(join(distDir, "projectDocSync.js"))});
+       syncProjectedDocs(${JSON.stringify(root)});`,
+    ]);
+
+    const claude = readFileSync(join(root, "CLAUDE.md"), "utf8");
+    expect(claude).toContain("audio-is-the-clock");
+    expect(claude).not.toContain("OLD\n");
+  });
+});

package/src/docStatus.test.ts

@@ -0,0 +1,81 @@
+// Every spec and plan under docs/superpowers/ says whether it is finished, and
+// docs/superpowers/README.md indexes them with the same answer. Before this
+// check the only way to learn a plan's state was to read it end to end or
+// find its bd epic; the build-console work alone has four such documents in
+// three states. A document without a status line, a status outside the
+// vocabulary, an index row that disagrees with its document, a document with
+// no row, or a row naming a document that does not exist, all fail here
+// (bd video-toolchain-cs8i, the fourth review's closing accounting asked for
+// this tracking).
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { toolchainRepoRoot as repoRoot } from "./testSupport";
+
+const DOCS = join(repoRoot, "docs", "superpowers");
+export const STATUS_VOCABULARY = ["draft", "approved", "in progress", "done", "frozen", "superseded", "record"] as const;
+type Status = (typeof STATUS_VOCABULARY)[number];
+
+/** The token at the head of a `Status:` line, or null when the line is absent
+ *  or its token is outside the vocabulary. The status line must sit within
+ *  the twelve lines after the title so it is read before the document's body. */
+export const statusOf = (markdown: string): Status | null => {
+  const lines = markdown.split("\n");
+  const h1 = lines.findIndex((l) => l.startsWith("# "));
+  if (h1 < 0) return null;
+  const line = lines.slice(h1 + 1, h1 + 13).find((l) => l.startsWith("Status:"));
+  if (line === undefined) return null;
+  const rest = line.slice("Status:".length).trim();
+  const token = STATUS_VOCABULARY.find((t) => rest === t || rest.startsWith(`${t} - `));
+  return token ?? null;
+};
+
+/** `| \`plans/x.md\` | done | ... |` rows of the index, keyed by the document path. */
+export const indexRows = (readme: string): Map<string, string> => {
+  const rows = new Map<string, string>();
+  for (const line of readme.split("\n")) {
+    const m = /^\| `((?:plans|specs)\/[^`]+)` \| ([^|]+) \|/.exec(line);
+    if (m) rows.set(m[1], m[2].trim());
+  }
+  return rows;
+};
+
+const documents = (): string[] =>
+  (["plans", "specs"] as const).flatMap((kind) =>
+    readdirSync(join(DOCS, kind)).filter((f) => f.endsWith(".md")).sort().map((f) => `${kind}/${f}`),
+  );
+
+describe("every spec and plan carries a status, and the index agrees with it", () => {
+  const readme = readFileSync(join(DOCS, "README.md"), "utf8");
+  const rows = indexRows(readme);
+
+  test("the index names the vocabulary this test enforces", () => {
+    for (const s of STATUS_VOCABULARY) expect(readme).toContain(`| \`${s}\` |`);
+  });
+
+  test("every document has a Status line under its title whose token is in the vocabulary", () => {
+    const missing = documents().filter((d) => statusOf(readFileSync(join(DOCS, d), "utf8")) === null);
+    expect(missing).toEqual([]);
+  });
+
+  test("every document has exactly one index row, and the row's status is the document's", () => {
+    const docs = documents();
+    const disagreements = docs
+      .map((d) => ({ d, doc: statusOf(readFileSync(join(DOCS, d), "utf8")), row: rows.get(d) ?? null }))
+      .filter(({ doc, row }) => row === null || row !== doc);
+    expect(disagreements).toEqual([]);
+  });
+
+  test("every index row names a document that exists", () => {
+    const stale = [...rows.keys()].filter((d) => !existsSync(join(DOCS, d)));
+    expect(stale).toEqual([]);
+  });
+
+  test("statusOf reads the token and refuses anything else", () => {
+    expect(statusOf("# T\n\nStatus: done - landed\n")).toBe("done");
+    expect(statusOf("<!-- x -->\n# T\nStatus: in progress\n")).toBe("in progress");
+    expect(statusOf("# T\n\nStatus: finished\n")).toBeNull();
+    expect(statusOf("# T\n\nStatus: done-ish\n")).toBeNull();
+    expect(statusOf("# T\n\nno status here\n")).toBeNull();
+  });
+});

package/src/drift.test.ts

@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { globSync } from "tinyglobby";
+import { describe, expect, test } from "vitest";
+import { verifyAnchors } from "./anchors";
+import { renderClaudeMdBlock, renderPipelineBlock, spliceBlock } from "./projectDoc";
+import { componentSlugs, renderComponentMeta } from "./projectMeta";
+import { RULES } from "./registry";
+import { toolchainRepoRoot as repoRoot } from "./testSupport";
+import { ALL_STAGES, STAGES } from "./stages";
+import { renderRuleSheetsJson, renderStageSheet } from "./stageProjection";
+import { renderWaiversJson } from "./waiverProjection";
+
+const read = (rel: string) => readFileSync(join(repoRoot, rel), "utf8");
+
+const REGENERATE = "Run: npx tsx packages/video-craft/scripts/generate.ts";
+
+describe("drift guards", () => {
+  test("every generated kit sidecar matches the registry", () => {
+    for (const slug of componentSlugs(RULES)) {
+      const rel = `packages/video-kit/src/motion/${slug}.meta.ts`;
+      expect(read(rel), `${rel} is stale. ${REGENERATE}`).toBe(renderComponentMeta(RULES, slug));
+    }
+  });
+
+  test("no orphaned sidecar outlives its rules", () => {
+    // Regenerating only writes CURRENT slugs; deleting or renaming a
+    // component rule would otherwise leave the old .meta.ts behind, green.
+    const committed = globSync("packages/video-kit/src/motion/*.meta.ts", { cwd: repoRoot })
+      .map((p) => p.replace(/^.*\/(.*)\.meta\.ts$/, "$1"))
+      .sort();
+    expect(committed, `stale sidecar on disk. Delete it, then ${REGENERATE}`)
+      .toEqual(componentSlugs(RULES));
+  });
+
+  test("HOW_I_BUILD_VIDEOS.md's generated block matches the registry", () => {
+    const rel = "HOW_I_BUILD_VIDEOS.md";
+    const current = read(rel);
+    expect(current, `${rel} is stale. ${REGENERATE}`)
+      .toBe(spliceBlock(current, "pipeline", renderPipelineBlock(RULES)));
+  });
+
+  test("CLAUDE.md's generated block matches the registry", () => {
+    const rel = "CLAUDE.md";
+    const current = read(rel);
+    expect(current, `${rel} is stale. ${REGENERATE}`)
+      .toBe(spliceBlock(current, "claude-md", renderClaudeMdBlock(RULES)));
+  });
+
+  test("every prose anchor still resolves", () => {
+    expect(verifyAnchors(RULES, repoRoot)).toEqual([]);
+  });
+
+  test("radar's generated waivers.generated.json matches the registry", () => {
+    const rel = "packages/video-cli/src/radar/waivers.generated.json";
+    expect(read(rel), `${rel} is stale. ${REGENERATE}`).toBe(renderWaiversJson(RULES));
+  });
+
+  test("every stage sheet matches the registry and stage table", () => {
+    for (const stage of ALL_STAGES) {
+      const rel = `docs/rules/stages/${stage}.md`;
+      expect(read(rel), `${rel} is stale. ${REGENERATE}`)
+        .toBe(`${renderStageSheet(RULES, STAGES, stage)}\n`);
+    }
+  });
+
+  test("no orphaned stage sheet outlives its stage", () => {
+    const committed = globSync("docs/rules/stages/*.md", { cwd: repoRoot })
+      .map((p) => p.replace(/^.*\/(.*)\.md$/, "$1"))
+      .sort();
+    expect(committed, `stale stage sheet on disk. Delete it, then ${REGENERATE}`)
+      .toEqual([...ALL_STAGES].sort());
+  });
+
+  test("dispatch's generated ruleSheets.generated.json matches the registry", () => {
+    const rel = "packages/video-cli/src/graph/ruleSheets.generated.json";
+    const creativeEdgeDoc = read("docs/style/CREATIVE_EDGE.md");
+    expect(read(rel), `${rel} is stale. ${REGENERATE}`)
+      .toBe(renderRuleSheetsJson(RULES, STAGES, creativeEdgeDoc));
+  });
+});
+
+describe("hand-written back-references", () => {
+  // Notes files cite rules as (Rule: `<id>`.). Nothing else validates those
+  // citations, so a rule rename would orphan them silently. The upstream
+  // BUILD_NOTES files (revola-video/BUILD_NOTES_CRAFT.md,
+  // act854-video/BUILD_NOTES.md) stayed in remotion-videos at extraction and
+  // are guarded there, not here (see UPSTREAM_PROVENANCE_ROOTS); this scan
+  // covers only the notes files that live in this repo.
+  const CITED_FILES = [
+    "HOW_I_BUILD_VIDEOS.md",
+  ];
+
+  // Both the singular form (Rule: `id`.) and the plural (Rules: `a`, `b`.).
+  const CITATION = /\(Rules?: ([^)]+)\.\)/g;
+  const CITED_ID = /`([a-z0-9-]+)`/g;
+
+  /** The generated pipeline block cites ids by design and is already guarded. */
+  const stripGeneratedBlock = (doc: string): string =>
+    doc.replace(/<!-- craft:begin pipeline -->[\s\S]*?<!-- craft:end pipeline -->/, "");
+
+  const citations = CITED_FILES.flatMap((rel) => {
+    const doc = rel === "HOW_I_BUILD_VIDEOS.md" ? stripGeneratedBlock(read(rel)) : read(rel);
+    return [...doc.matchAll(CITATION)].flatMap((m) =>
+      [...m[1].matchAll(CITED_ID)].map((id) => ({ file: rel, id: id[1] })),
+    );
+  });
+
+  test("every citation names a registered rule", () => {
+    const ids = new Set(RULES.map((r) => r.id));
+    const orphaned = citations.filter((c) => !ids.has(c.id));
+    expect(
+      orphaned.map((c) => `${c.file}: (Rule: \`${c.id}\`.)`),
+      "Orphaned back-reference: the cited rule id no longer exists in RULES. Update the citation or restore the rule id.",
+    ).toEqual([]);
+  });
+
+  test("the citation regex actually finds the hand-written citations", () => {
+    // Guards against the regex silently matching nothing after a format
+    // change. HOW_I_BUILD_VIDEOS.md alone carries 26 citations today; the
+    // floor dropped from 40 when the upstream BUILD_NOTES files left the scan.
+    expect(citations.length).toBeGreaterThanOrEqual(20);
+  });
+});

package/src/fixtures/data-radar-dynamic/Branches.tsx

@@ -0,0 +1,14 @@
+import React from "react";
+import { AbsoluteFill } from "remotion";
+
+// The template-literal tag family. `qse-qguard-video/src/artifacts/Theft.tsx`
+// tags exactly this way (`data-radar={`branch-${kind}`}`), and the first
+// version of this rule read only bare StringLiteral initializers - so every
+// id in a family like this read as untagged. Three declared ids, one tag site.
+type BranchKind = "relay" | "export" | "forged";
+
+export const Branches: React.FC<{ kind: BranchKind }> = ({ kind }) => (
+  <AbsoluteFill>
+    <div data-radar={`branch-${kind}`} style={{ width: 100, height: 100 }} />
+  </AbsoluteFill>
+);

package/src/fixtures/data-radar-dynamic/plan.fixture.yaml

@@ -0,0 +1,16 @@
+doctrine: 1
+sections:
+  - id: stolen
+    kind: motion
+    component: Branches
+    vo: "A relay. An export. A forgery."
+    names:
+      - cue: 0
+        element: branch-relay
+        says: "a relay"
+      - cue: 1
+        element: branch-export
+        says: "an export"
+      - cue: 2
+        element: branch-forged
+        says: "a forgery"

package/src/fixtures/data-radar-forwarded/Scene.tsx

@@ -0,0 +1,19 @@
+import React from "react";
+import { AbsoluteFill } from "remotion";
+
+// The prop-passthrough convention, copied from
+// `qse-qguard-video/src/artifacts/RequestCard.tsx` + `src/scenes/S1Once.tsx`:
+// a reusable component forwards its tag (`data-radar={dataRadar}`) and the
+// real ids are the literals its CALL SITES pass. Neither half is a bare
+// string literal at the tag site, so a rule reading only the attribute would
+// call both declared ids untagged.
+const Chip: React.FC<{ dataRadar?: string }> = ({ dataRadar }) => (
+  <div data-radar={dataRadar} style={{ width: 40, height: 20 }} />
+);
+
+export const Scene: React.FC = () => (
+  <AbsoluteFill>
+    <Chip dataRadar="cookie-chip" />
+    <Chip dataRadar="cookie-chip-copy" />
+  </AbsoluteFill>
+);