@revola-ai/video-craft 0.2.1

package/src/projectDoc.ts

@@ -0,0 +1,152 @@
+import type { Rule } from "./types";
+
+/**
+ * One line per waiver, appended to a rule's claim in both projections. The
+ * claims are what future sessions read, so a waiver that lives only in the rule
+ * file is invisible exactly where it matters: a session inside the waived
+ * project would read the unqualified claim and "fix" the client's decision
+ * back out.
+ */
+const exceptionLines = (r: Rule, indent: string): string[] =>
+  (r.exceptions ?? []).map(
+    (ex) => `${indent}- waived in \`${ex.project}\`: ${ex.decision} (recorded: \`${ex.recordedIn}\`)`,
+  );
+
+/**
+ * Replaces the text between `<!-- craft:begin NAME -->` and
+ * `<!-- craft:end NAME -->`. Throws on a missing marker rather than appending,
+ * because silently appending would duplicate the block on every run and the
+ * drift test would then never converge.
+ */
+export function spliceBlock(doc: string, marker: string, body: string): string {
+  const begin = `<!-- craft:begin ${marker} -->`;
+  const end = `<!-- craft:end ${marker} -->`;
+
+  const from = doc.indexOf(begin);
+  if (from === -1) throw new Error(`marker "craft:begin ${marker}" not found`);
+
+  const to = doc.indexOf(end, from);
+  if (to === -1) throw new Error(`marker "craft:end ${marker}" not found`);
+
+  return doc.slice(0, from + begin.length) + "\n" + body + "\n" + doc.slice(to);
+}
+
+/**
+ * Compact projection for the repo-root CLAUDE.md. CLAUDE.md is injected into
+ * every Claude Code session's context (and re-injected after compaction);
+ * HOW_I_BUILD_VIDEOS.md is read only when a session touches pipeline
+ * behaviour. Measured 2026-08-27: all 107 pipeline claims appeared VERBATIM in
+ * both, so a pipeline session paid ~6k tokens to read the same sentences
+ * twice (video-toolchain-cg6).
+ *
+ * Dropping the craft rules outright would have been the wrong trade - a
+ * session that never opens HOW_I_BUILD would not know they exist. So the split
+ * is by what a session must be able to act on WITHOUT another read:
+ *
+ *  - gates keep their full claim and `verify` line: these cost rebuild rounds,
+ *    and each is settled by running something the line names.
+ *  - waived rules keep their full claim at ANY tier. `exceptionLines` above
+ *    records why: a waiver invisible in the projection is exactly how a
+ *    session inside the waived project "fixes" the client's decision back out.
+ *    A bare id cannot carry that, so waived rules are never compacted.
+ *  - every other rule is named by id. The ids are written as claims
+ *    (`no-static-holds`, `tokens-not-raw-hexes`), so an agent can never not
+ *    know a rule exists; it fetches the full claim when the id looks relevant.
+ */
+export function renderClaudeMdBlock(
+  rules: Rule[],
+  // Compaction is only sound where HOW_I_BUILD_VIDEOS.md exists to look an id
+  // up in. `syncProjectedDocs` passes false for a consumer that carries no
+  // workflow doc - its contract explicitly allows that - because an id index
+  // pointing at an absent document is strictly worse than the full block it
+  // replaced. Defaults to true: the toolchain repo always has HOW.
+  { compact = true }: { compact?: boolean } = {},
+): string {
+  const pipeline = rules
+    .filter((r) => r.scope.kind === "pipeline")
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const of = (tier: Rule["tier"]) => pipeline.filter((r) => r.tier === tier);
+  const isWaived = (r: Rule) => (r.exceptions ?? []).length > 0;
+
+  // Headings are emitted only for tiers that have members. An empty "Gates"
+  // heading reads as "there are no gates", which is a different and much more
+  // reassuring claim than "this projection has nothing to put here".
+  const section = (heading: string[], body: string[]) =>
+    body.length === 0 ? [] : [...heading, ``, ...body, ``];
+
+  const full = (r: Rule) => [`- ${r.claim} (\`${r.id}\`)`, ...exceptionLines(r, "  ")].join("\n");
+
+  /** Waived rules in full, then one line naming every other id in the tier. */
+  const compacted = (rs: Rule[], label: string): string[] => {
+    if (rs.length === 0) return [];
+    if (!compact) return rs.map(full);
+    const waived = rs.filter(isWaived);
+    const plain = rs.filter((r) => !isWaived(r));
+    return [
+      ...waived.map(full),
+      ...(waived.length && plain.length ? [``] : []),
+      ...(plain.length
+        ? [
+          // Wording is load-bearing and was wrong in review twice over. "further"
+          // dangles in a tier with no waived rules above it (process has none).
+          // And the lookup recipe must key on what the reader HOLDS - an id -
+          // not on the heading text: renderPipelineBlock emits `### <claim>`, so
+          // the id appears only in the `Rule id:` line two lines below. Naming
+          // the wrong token would send every lookup into a 139 KB scan, which is
+          // the one thing this compaction cannot afford to get wrong.
+          `${plain.length} more ${label} rule${plain.length === 1 ? "" : "s"} `
+          + `bind${plain.length === 1 ? "s" : ""} this work, listed by id below. `
+          + `To read one, search HOW_I_BUILD_VIDEOS.md for its id in a \`Rule id:\` line - the headings there are the `
+          + `claims themselves, so the id is not a heading. That is the only doc carrying each rule's why and `
+          + `provenance; the per-stage sheets under \`docs/rules/stages/\` carry the claims, scoped by stage. `
+          + `Every id here is a rule you are accountable to, not a suggestion.`,
+          ``,
+          plain.map((r) => `\`${r.id}\``).join(", "),
+        ]
+        : []),
+    ];
+  };
+
+  return [
+    `<!-- This block is generated from packages/video-craft/src/rules/. Do not edit it here. -->`,
+    ``,
+    ...section(
+      [
+        `### Gates - if you remember nothing else`,
+        ``,
+        `Each line below has cost a rebuild round. Every one is settled by running something, not by reading the diff: run the check.`,
+      ],
+      of("gate").map((r) =>
+        [`- ${r.claim} (\`${r.id}\`)`, `  - verify: ${r.verify}`, ...exceptionLines(r, "  ")].join("\n"),
+      ),
+    ),
+    ...section([`### Craft rules`], compacted(of("craft"), "craft")),
+    ...section([`### Process rules`], compacted(of("process"), "process")),
+  ].join("\n").trimEnd();
+}
+
+export function renderPipelineBlock(rules: Rule[]): string {
+  const pipeline = rules
+    .filter((r) => r.scope.kind === "pipeline")
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  return [
+    `<!-- This block is generated from packages/video-craft/src/rules/. Do not edit it here. -->`,
+    ``,
+    ...pipeline.flatMap((r) => [
+      `### ${r.claim}`,
+      ``,
+      r.why,
+      ``,
+      // The tier is restated here rather than only in the CLAUDE.md projection
+      // so the reference doc and the injected block cannot disagree about how
+      // much a rule weighs - a reader who arrives via a rule id from a build
+      // note lands here, not there.
+      `Learned from \`${r.learnedFrom}\`. Rule id: \`${r.id}\`. Tier: ${r.tier}.`,
+      ...(r.verify ? [``, `Verify: ${r.verify}`] : []),
+      ...((r.exceptions ?? []).length > 0 ? [``, ...exceptionLines(r, "")] : []),
+      ``,
+    ]),
+  ].join("\n").trimEnd();
+}

package/src/projectDocSync.test.ts

@@ -0,0 +1,152 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { syncProjectedDocs } from "./projectDocSync";
+
+const CLAUDE_WITH_MARKERS = [
+  "# Consumer repo",
+  "",
+  "<!-- craft:begin claude-md -->",
+  "OLD-BLOCK-SENTINEL",
+  "<!-- craft:end claude-md -->",
+  "",
+  "tail text stays",
+  "",
+].join("\n");
+
+const HOW_WITH_MARKERS = [
+  "# How I build videos",
+  "",
+  "<!-- craft:begin pipeline -->",
+  "OLD-BLOCK-SENTINEL",
+  "<!-- craft:end pipeline -->",
+  "",
+].join("\n");
+
+let dirs: string[] = [];
+const targetRoot = (): string => {
+  const d = mkdtempSync(join(tmpdir(), "doc-sync-"));
+  dirs.push(d);
+  return d;
+};
+afterEach(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  dirs = [];
+});
+
+describe("syncProjectedDocs", () => {
+  test("splices both docs when both carry markers", () => {
+    const root = targetRoot();
+    writeFileSync(join(root, "CLAUDE.md"), CLAUDE_WITH_MARKERS);
+    writeFileSync(join(root, "HOW_I_BUILD_VIDEOS.md"), HOW_WITH_MARKERS);
+
+    const result = syncProjectedDocs(root);
+
+    expect(result.updated).toEqual(["CLAUDE.md", "HOW_I_BUILD_VIDEOS.md"]);
+    expect(result.skipped).toEqual([]);
+    const claude = readFileSync(join(root, "CLAUDE.md"), "utf8");
+    expect(claude).not.toContain("OLD-BLOCK-SENTINEL");
+    // A real rule claim landed inside the markers, and text outside survived.
+    expect(claude).toContain("audio-is-the-clock");
+    expect(claude).toContain("tail text stays");
+    const how = readFileSync(join(root, "HOW_I_BUILD_VIDEOS.md"), "utf8");
+    expect(how).not.toContain("OLD-BLOCK-SENTINEL");
+    expect(how).toContain("<!-- craft:begin pipeline -->");
+  });
+
+  test("skips a target with no HOW_I_BUILD_VIDEOS.md at all, with a reason", () => {
+    const root = targetRoot();
+    writeFileSync(join(root, "CLAUDE.md"), CLAUDE_WITH_MARKERS);
+
+    const result = syncProjectedDocs(root);
+
+    expect(result.updated).toEqual(["CLAUDE.md"]);
+    expect(result.skipped).toEqual([
+      { file: "HOW_I_BUILD_VIDEOS.md", reason: "not present in target" },
+    ]);
+  });
+
+  // CLAUDE.md compacts unwaived craft and process rules to an id index
+  // (video-toolchain-cg6), which only works because HOW_I_BUILD_VIDEOS.md is
+  // there to look an id up in. A consumer may legitimately carry no workflow
+  // doc - this function's own contract allows it - and compacting into that
+  // target would leave ~78 ids pointing at nothing. So the projection adapts
+  // to whether its fallback exists rather than emitting a dangling pointer.
+  test("writes CLAUDE.md UNCOMPACTED when the target has no HOW_I_BUILD_VIDEOS.md to look ids up in", () => {
+    const root = targetRoot();
+    writeFileSync(join(root, "CLAUDE.md"), CLAUDE_WITH_MARKERS);
+
+    syncProjectedDocs(root);
+
+    const claude = readFileSync(join(root, "CLAUDE.md"), "utf8");
+    expect(claude).not.toMatch(/rules? bind|binds this work, listed by id/);
+    // A known craft rule renders as a full claim line, not a bare id.
+    expect(claude).toContain("- Never hard-code a hex color in a scene file");
+    expect(claude).toContain("- Never style with generic blue-purple gradient washes");
+  });
+
+  test("writes CLAUDE.md compacted when HOW_I_BUILD_VIDEOS.md IS present", () => {
+    const root = targetRoot();
+    writeFileSync(join(root, "CLAUDE.md"), CLAUDE_WITH_MARKERS);
+    writeFileSync(join(root, "HOW_I_BUILD_VIDEOS.md"), HOW_WITH_MARKERS);
+
+    syncProjectedDocs(root);
+
+    const claude = readFileSync(join(root, "CLAUDE.md"), "utf8");
+    expect(claude).toMatch(/binds? this work, listed by id/);
+    expect(claude).toContain("`no-ai-gradient-look`");
+    expect(claude).not.toContain("- Never style with generic blue-purple gradient washes");
+  });
+
+  test("throws when CLAUDE.md is missing entirely", () => {
+    const root = targetRoot();
+    expect(() => syncProjectedDocs(root)).toThrow(/CLAUDE\.md/);
+  });
+
+  test("throws the spliceBlock error when CLAUDE.md exists without markers - never appends", () => {
+    const root = targetRoot();
+    writeFileSync(join(root, "CLAUDE.md"), "# no markers here\n");
+    expect(() => syncProjectedDocs(root)).toThrow('marker "craft:begin claude-md" not found');
+    // The file is untouched: no append, no partial write.
+    expect(readFileSync(join(root, "CLAUDE.md"), "utf8")).toBe("# no markers here\n");
+  });
+
+  test("throws the spliceBlock error when HOW_I_BUILD_VIDEOS.md exists without markers", () => {
+    const root = targetRoot();
+    writeFileSync(join(root, "CLAUDE.md"), CLAUDE_WITH_MARKERS);
+    writeFileSync(join(root, "HOW_I_BUILD_VIDEOS.md"), "# no markers\n");
+    expect(() => syncProjectedDocs(root)).toThrow('marker "craft:begin pipeline" not found');
+  });
+
+  // rulesSyncShell.ts re-splices CLAUDE.md after materializing a packaged
+  // HOW_I_BUILD_VIDEOS.md so one rules:sync run leaves the compact block a
+  // second run would (Task 5 review, bd video-toolchain-zaaz). That re-splice
+  // must never touch the manual: it is the packaged release artifact, and
+  // rendering renderPipelineBlock(RULES) against it here would diverge from
+  // whatever shipped.
+  test("claudeMdOnly splices CLAUDE.md and leaves an existing HOW_I_BUILD_VIDEOS.md byte-identical", () => {
+    const root = targetRoot();
+    writeFileSync(join(root, "CLAUDE.md"), CLAUDE_WITH_MARKERS);
+    const packagedHow = [
+      "# HOW (packaged)",
+      "",
+      "<!-- craft:begin pipeline -->",
+      "RELEASE-PIPELINE-BLOCK",
+      "<!-- craft:end pipeline -->",
+      "",
+    ].join("\n");
+    writeFileSync(join(root, "HOW_I_BUILD_VIDEOS.md"), packagedHow);
+
+    const result = syncProjectedDocs(root, { claudeMdOnly: true });
+
+    expect(result.updated).toEqual(["CLAUDE.md"]);
+    expect(result.skipped).toEqual([]);
+    const claude = readFileSync(join(root, "CLAUDE.md"), "utf8");
+    expect(claude).not.toContain("OLD-BLOCK-SENTINEL");
+    // Compact, because the manual is present.
+    expect(claude).toMatch(/binds? this work, listed by id/);
+    // The manual itself is untouched: no re-render of the pipeline block.
+    expect(readFileSync(join(root, "HOW_I_BUILD_VIDEOS.md"), "utf8")).toBe(packagedHow);
+  });
+});

package/src/projectDocSync.ts

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { renderClaudeMdBlock, renderPipelineBlock, spliceBlock } from "./projectDoc";
+import { RULES } from "./registry";
+
+export type DocSyncResult = {
+  /** Root-relative names of the files whose generated blocks were rewritten. */
+  updated: string[];
+  /** Files legitimately absent from the target, with why they were skipped. */
+  skipped: { file: string; reason: string }[];
+};
+
+/**
+ * Splices the generated consumer-doc projections (the CLAUDE.md craft block
+ * and the HOW_I_BUILD_VIDEOS.md pipeline block) into `targetRoot`'s files.
+ * This is the consumer half of the rules generator: package-internal
+ * projections (kit meta files, stage sheets, ruleSheets.generated.json) run
+ * at toolchain release time via scripts/generate.ts, while this function runs
+ * inside any consumer repo via `video rules:sync`.
+ *
+ * Splice-only, never append: a target file must already carry the craft
+ * markers, and a missing marker throws spliceBlock's error rather than
+ * duplicating the block on every run. A target with no HOW_I_BUILD_VIDEOS.md
+ * at all is skipped with a reason - consumers may not carry the workflow doc -
+ * but CLAUDE.md is where the rules become binding for sessions in the target
+ * repo, so its absence (like a missing marker in it) is an error.
+ *
+ * `opts.claudeMdOnly` renders and splices CLAUDE.md exactly as above but
+ * never touches HOW_I_BUILD_VIDEOS.md. rulesSyncShell.ts needs this for the
+ * re-splice it runs after materializing a missing manual: CLAUDE.md's compact
+ * block must be rendered against the now-present HOW, but the manual itself
+ * is the packaged release artifact (cpSync'd verbatim, pipeline block
+ * included) and re-splicing it here would render the pipeline block from the
+ * live RULES instead, which could diverge from what shipped (Task 5 review,
+ * bd video-toolchain-zaaz).
+ */
+export function syncProjectedDocs(targetRoot: string, opts?: { claudeMdOnly?: boolean }): DocSyncResult {
+  const updated: string[] = [];
+  const skipped: { file: string; reason: string }[] = [];
+
+  const claudePath = join(targetRoot, "CLAUDE.md");
+  if (!existsSync(claudePath)) {
+    throw new Error(
+      `CLAUDE.md does not exist in ${targetRoot} - rules:sync splices into existing files and never creates them. `
+      + `Create CLAUDE.md with the craft markers (<!-- craft:begin claude-md --> / <!-- craft:end claude-md -->) first.`,
+    );
+  }
+  // Resolved BEFORE CLAUDE.md is written, because it decides how CLAUDE.md is
+  // rendered: the compacted block names unwaived craft and process rules by id
+  // only, which is sound exactly when HOW_I_BUILD_VIDEOS.md is there to look an
+  // id up in. A target without it gets the full claims instead - an id index
+  // pointing at an absent document is worse than the block it replaced.
+  const howPath = join(targetRoot, "HOW_I_BUILD_VIDEOS.md");
+  const hasHow = existsSync(howPath);
+
+  writeFileSync(
+    claudePath,
+    spliceBlock(readFileSync(claudePath, "utf8"), "claude-md", renderClaudeMdBlock(RULES, { compact: hasHow })),
+    "utf8",
+  );
+  updated.push("CLAUDE.md");
+
+  if (opts?.claudeMdOnly) {
+    return { updated, skipped };
+  }
+
+  if (!hasHow) {
+    skipped.push({ file: "HOW_I_BUILD_VIDEOS.md", reason: "not present in target" });
+  } else {
+    writeFileSync(
+      howPath,
+      spliceBlock(readFileSync(howPath, "utf8"), "pipeline", renderPipelineBlock(RULES)),
+      "utf8",
+    );
+    updated.push("HOW_I_BUILD_VIDEOS.md");
+  }
+
+  return { updated, skipped };
+}

package/src/projectMeta.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "vitest";
+import { componentSlugs, renderComponentMeta } from "./projectMeta";
+import { RULES } from "./registry";
+import type { Rule } from "./types";
+
+const rule = (id: string, field: "whenToUse" | "whenNotToUse" | "gotcha", claim: string): Rule => ({
+  id,
+  claim,
+  why: "because",
+  learnedFrom: "HOW_I_BUILD_VIDEOS.md",
+  tier: "craft",
+  scope: { kind: "component", slug: "demo", field },
+  enforcement: { kind: "prose", unanchorable: "test fixture" },
+});
+
+describe("componentSlugs", () => {
+  test("lists each component once, sorted", () => {
+    const rules = [rule("b", "gotcha", "B."), rule("a", "whenToUse", "A.")];
+    expect(componentSlugs(rules)).toEqual(["demo"]);
+  });
+
+  test("ignores pipeline rules", () => {
+    expect(componentSlugs(RULES.filter((r) => r.scope.kind === "pipeline"))).toEqual([]);
+  });
+});
+
+describe("renderComponentMeta", () => {
+  const text = () => renderComponentMeta(
+    [
+      rule("use", "whenToUse", "Use it for counters."),
+      rule("avoid", "whenNotToUse", "Not for text."),
+      rule("g1", "gotcha", "Wrap it."),
+      rule("g2", "gotcha", "Use speed."),
+    ],
+    "demo",
+  );
+
+  test("marks the file as generated and names its source", () => {
+    expect(text()).toContain("GENERATED FILE - DO NOT EDIT");
+    expect(text()).toContain("packages/video-craft");
+  });
+
+  test("emits the ComponentMeta fields WS1 expects", () => {
+    const out = text();
+    expect(out).toContain('whenToUse: "Use it for counters."');
+    expect(out).toContain('whenNotToUse: "Not for text."');
+    expect(out).toContain('gotchas: [');
+    expect(out).toContain('"Wrap it."');
+    expect(out).toContain('"Use speed."');
+    expect(out).toContain("variants: []");
+  });
+
+  test("projects COMPONENT_VARIANTS for a declared Tier A slug", () => {
+    const out = renderComponentMeta(
+      [rule("use", "whenToUse", "Use it for counters.")],
+      "rolling-number",
+    );
+    expect(out).toContain('variants: ["odometer", "slam"] as string[]');
+  });
+
+  test("emits empty strings when a component has no whenToUse or whenNotToUse", () => {
+    const out = renderComponentMeta([rule("g1", "gotcha", "Wrap it.")], "demo");
+    expect(out).toContain('whenToUse: ""');
+    expect(out).toContain('whenNotToUse: ""');
+  });
+
+  test("imports nothing, so it cannot couple the kit to this package", () => {
+    expect(text()).not.toContain("import ");
+  });
+
+  test("orders gotchas by rule id so regeneration is stable", () => {
+    const out = text();
+    expect(out.indexOf('"Wrap it."')).toBeLessThan(out.indexOf('"Use speed."'));
+  });
+});

package/src/projectMeta.ts

@@ -0,0 +1,53 @@
+import type { Rule } from "./types";
+import { COMPONENT_VARIANTS } from "./variants";
+
+const forComponent = (rules: Rule[], slug: string, field: "whenToUse" | "whenNotToUse" | "gotcha") =>
+  rules
+    .filter((r) => r.scope.kind === "component" && r.scope.slug === slug && r.scope.field === field)
+    // Sorted by id, not by registry order, so regeneration is stable under
+    // registry reordering and the drift test does not fire spuriously.
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((r) => r.claim);
+
+export function componentSlugs(rules: Rule[]): string[] {
+  const slugs = new Set<string>();
+  for (const rule of rules) {
+    if (rule.scope.kind === "component") slugs.add(rule.scope.slug);
+  }
+  return [...slugs].sort();
+}
+
+/** A TS string literal with quotes and backslashes escaped. */
+const lit = (s: string) => JSON.stringify(s);
+
+/**
+ * Renders a complete `.meta.ts` file. The output imports nothing: WS1's
+ * ComponentMeta type does not exist yet, and the kit must not depend on this
+ * package. WS1's registry imports this object and TypeScript checks it
+ * structurally.
+ */
+export function renderComponentMeta(rules: Rule[], slug: string): string {
+  const whenToUse = forComponent(rules, slug, "whenToUse")[0] ?? "";
+  const whenNotToUse = forComponent(rules, slug, "whenNotToUse")[0] ?? "";
+  const gotchas = forComponent(rules, slug, "gotcha");
+
+  const name = slug.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase()) + "Meta";
+  const variants = COMPONENT_VARIANTS[slug] ?? [];
+
+  return [
+    `// GENERATED FILE - DO NOT EDIT.`,
+    `// Source of truth: packages/video-craft/src/rules/. Regenerate with:`,
+    `//   npx tsx packages/video-craft/scripts/generate.ts`,
+    `// Edits here are reverted by the drift test in packages/video-craft/src/drift.test.ts.`,
+    ``,
+    `export const ${name} = {`,
+    `  whenToUse: ${lit(whenToUse)},`,
+    `  whenNotToUse: ${lit(whenNotToUse)},`,
+    `  gotchas: [`,
+    ...gotchas.map((g) => `    ${lit(g)},`),
+    `  ],`,
+    `  variants: [${variants.map((v) => lit(v)).join(", ")}] as string[],`,
+    `};`,
+    ``,
+  ].join("\n");
+}

package/src/provenance.ts

@@ -0,0 +1,85 @@
+/**
+ * This repo was extracted from remotion-videos: the toolchain moved here, the
+ * video projects and the pre-split history stayed behind. Rules whose
+ * provenance (learnedFrom, prose anchors, waiver records) points into one of
+ * the roots below is citing the upstream repo, where those files still live
+ * with their full history. Such paths are validated as citations - format
+ * only - instead of being resolved on this repo's disk.
+ *
+ * qse-qguard-video/ and radar-fixture-video/ moved WITH the toolchain and are
+ * deliberately absent from this list: paths into them must still resolve
+ * locally, and a missing one is still a failure.
+ *
+ * docs/superpowers/ and docs/plans/ were on this list until the design record
+ * followed the code across. They are absent for the same reason: the specs and
+ * plans that rules cite as learnedFrom now live here, so a citation into them
+ * is resolved on disk instead of merely format-checked. Adding a root back
+ * silently downgrades every citation under it from "the file exists" to "the
+ * string is shaped like a path" - only do it for a tree that genuinely stayed
+ * upstream.
+ */
+export const UPSTREAM_PROVENANCE_ROOTS = [
+  // Video projects that stayed in remotion-videos.
+  "revola-video",
+  "expanse-video",
+  "qse-video",
+  "act854-video",
+  "datapeak-video",
+  "klaviyo-segments-video",
+  "qpa-video",
+  "reverence-video",
+  "enjamb-teaser",
+  "workday-harness-video",
+  "rcp-fund7-video",
+  // Pre-split working documents that stayed with the video projects.
+  "claude-sessions-digest",
+] as const;
+
+/**
+ * The bd id prefix of the upstream repo. Source comments cite issues by id, and
+ * the migration deliberately brought only the OPEN issues across - so a comment
+ * naming an issue that was closed upstream has no record here, and that is not
+ * a broken citation.
+ *
+ * Those citations are not broken: they point at a real, readable record in
+ * remotion-videos. They simply cannot be resolved against this repo's DB.
+ *
+ * They ARE resolved, though - against `.beads/upstream-issue-ids.txt`, a
+ * committed snapshot of the upstream backlog, so the check runs in CI without
+ * the other repo on disk. An earlier version validated them on FORM instead,
+ * with a regex that extractIssueCitations already guaranteed by construction:
+ * a tautology that could not fail, standing over exactly the ids nothing else
+ * verified. Do not reintroduce a shape check here and call it verification.
+ *
+ * A `video-toolchain-` id has no such excuse: it is this repo's own work and
+ * must resolve locally.
+ */
+export const UPSTREAM_ISSUE_PREFIX = "remotion-videos-";
+
+/** True when the id names an issue that may live only in the upstream repo. */
+export function isUpstreamIssue(id: string): boolean {
+  return id.startsWith(UPSTREAM_ISSUE_PREFIX);
+}
+
+/** True when the path cites the upstream remotion-videos repo. */
+export function isUpstreamProvenance(path: string): boolean {
+  return UPSTREAM_PROVENANCE_ROOTS.some(
+    (root) => path === root || path.startsWith(`${root}/`),
+  );
+}
+
+/**
+ * Format check for an upstream citation. The file cannot be resolved here, so
+ * the only guard left is that the citation is a well-formed repo-relative
+ * path: a typo that breaks the shape still fails, but existence is upstream's
+ * problem. Returns the reason the citation is malformed, or undefined.
+ */
+export function upstreamCitationError(path: string): string | undefined {
+  if (path.includes("\\")) return "contains a backslash";
+  const segments = path.split("/");
+  if (segments.some((s) => s === "")) return "has an empty path segment";
+  if (segments.some((s) => s === "." || s === "..")) {
+    return "contains a relative segment";
+  }
+  return undefined;
+}

package/src/radar-check-ids.json

@@ -0,0 +1,34 @@
+[
+  "alignment-group",
+  "attachment-offset",
+  "band-breach",
+  "blank-region-hold",
+  "brand-provenance",
+  "brief-structure",
+  "case-system",
+  "contract-satisfiable",
+  "copy-tracks-the-read",
+  "crowding-legibility",
+  "dead-frame-at-cut",
+  "edge-touch",
+  "fade-stack-at-cut",
+  "frame-count",
+  "group-member-count",
+  "hero-regression",
+  "hero-size",
+  "loudness",
+  "occlusion",
+  "placeholder-content",
+  "rebanding-conflict",
+  "scene-serves-thesis",
+  "seam-continuity",
+  "seam-fidelity",
+  "sibling-overlap",
+  "snap",
+  "static-hold",
+  "tag-coverage",
+  "text-fit",
+  "thesis-fidelity",
+  "viz-declared",
+  "vo-element-sync"
+]