@norskvideo/ctl-dev-kit 0.1.13 → 0.1.14

package/build/build-image.bootstrap.sh

@@ -0,0 +1,18 @@
+# The one forced copy inside every product's deployment/build-image.sh: the
+# bootstrap that locates this package before it can source anything from it.
+# check-drift.ts extracts the find_dev_kit function below and requires it
+# verbatim in each product's script (which must also `source` a script from
+# this package's build/). The surrounding wrapper is per-product: tag, port,
+# and — for studio's sanctioned bespoke build — which build/ script it sources.
+find_dev_kit() {
+  local dir="$1"
+  while [ "${dir}" != "/" ]; do
+    if [ -d "${dir}/node_modules/@norskvideo/ctl-dev-kit" ]; then
+      printf '%s' "${dir}/node_modules/@norskvideo/ctl-dev-kit"
+      return 0
+    fi
+    dir="$(dirname "${dir}")"
+  done
+  echo "could not find @norskvideo/ctl-dev-kit — run bun install" >&2
+  return 1
+}

package/conventions/CLAUDE.core.md

@@ -51,15 +51,19 @@
   diverges. Only the `product:` key is per-repo. Never hand-edit the copy — edit
   the dev-kit source and re-sync.
 - **A config-driven workflow needs a parity-checked invariant contract.** If this
-  product emits its Studio graph dynamically from config, every config dimension's
-  rules are documented as stable-ID statements in
-  `shared/src/schemas/INVARIANTS.md`, and every ID has an executable rule in the
-  composer rule-sweep (`shared/src/workflow/composer-rules.test.ts`). A parity
-  guard in that suite fails CI on any drift — a documented ID with no rule, or a
-  rule with no doc ID. So a config change is never done until the invariant is in
-  BOTH the doc and its test (same ID, added together); a runtime-only invariant
-  the emitted graph can't show goes in the explicit untestable-IDs set
-  (`COMPOSER_UNTESTABLE_IDS`), still parity-checked. `norsk-ctl-product-playout`
-  and `-commentary` are the worked examples.
+  product emits its Studio graph dynamically from config, its load-bearing rules
+  are documented as stable-ID statements (`INV-<AREA>-<NNN>`) in an
+  `INVARIANTS.md`, and every ID is cited verbatim by an executable rule that
+  guards it. The parity guard — `invariantParityFromDisk` from
+  `@norskvideo/ctl-dev-kit/testing/invariants` (template + copy-paste test in
+  `testing/INVARIANTS.template.md`) — fails CI on any drift: a documented ID
+  with no citing rule, or a rule citing an ID the doc doesn't define. A config
+  change is never done until the invariant is in BOTH the doc and its rule
+  (same ID, added together); a runtime-only invariant the emitted graph can't
+  show is declared in the guard's `untestableIds`, still parity-checked. Where
+  the doc lives and whether rules sit in one sweep suite
+  (`norsk-ctl-product-playout`, `-commentary`) or beside the code they guard
+  (`-probe`, `-turnkey-funke-pegasus`) is the repo's choice — the contract is
+  the IDs and the guard, not the layout.
 
 <!-- END ctl-shared-conventions v1 -->

package/conventions/biome.base.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.5/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "files": {
+    "includes": [
+      "**/*.ts",
+      "**/*.tsx",
+      "**/*.js",
+      "**/*.json",
+      "!**/node_modules",
+      "!**/dist",
+      "!**/generated",
+      "!**/_gen",
+      "!**/worker-mode/proto",
+      "!**/dashboards/*/assets",
+      "!**/website",
+      "!.longshot",
+      "!**/mcp/resources/plugin-template"
+    ]
+  }
+}

package/conventions/check-drift.ts

@@ -1,17 +1,24 @@
 // Workstream I drift gate. Fails a product repo whose forced copies of the
-// shared conventions have diverged from this dev-kit's canonical source:
-//   - the fenced `ctl-shared-conventions v1` core inside its CLAUDE.md, and
-//   - its root flake.nix.
+// shared conventions have diverged from this dev-kit's canonical source. Each
+// gated file uses the loosest mechanism that still pins what is shared:
+//   - byte-verbatim: CLAUDE.md fenced core, flake.nix, biome.json,
+//     tsconfig.base.json, the .gitignore core block
+//   - masked per-repo line: checks.yml + upgrade-latest.yml (`product:` key)
+//   - base + sanctioned extension block: dprint.json (repo-specific excludes)
+//   - structural: root tsconfig.json (shape-dependent includes stay free),
+//     deployment/build-image.sh (per-product wrapper around a verbatim
+//     bootstrap), manifest.seed.json (per-product pins, SDK-schema shape)
 //
-// Both are copied verbatim (not @import-ed / not a dep) so a human reads them on
-// GitHub with no tooling — which is exactly where drift starts. The gate makes
-// "single-sourced in @norskvideo/ctl-dev-kit" true: a product runs it in CI
-// against the dev-kit version it has installed, so bumping the pinned dev-kit
-// forces a re-sync. Canonical bytes are the files shipped alongside this script
-// (conventions/CLAUDE.core.md + build/flake.nix), resolved package-relative so
-// they work both workspace-symlinked and installed from the published tarball.
+// Files are copied verbatim (not @import-ed / not a dep) so a human reads them
+// on GitHub with no tooling — which is exactly where drift starts. The gate
+// makes "single-sourced in @norskvideo/ctl-dev-kit" true: a product runs it in
+// CI against the dev-kit version it has installed, so bumping the pinned
+// dev-kit forces a re-sync. Canonical bytes ship alongside this script
+// (conventions/* + build/*), resolved package-relative so they work both
+// workspace-symlinked and installed from the published tarball.
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { parseManifestSeed } from "@norskvideo/ctl-sdk/manifest-seed";
 
 export interface DriftReport {
   ok: boolean;
@@ -36,20 +43,20 @@ function firstDiffLine(actual: string, expected: string): string {
   return "content differs";
 }
 
-// The one legitimately per-repo line in upgrade-latest.yml: the dashboard key
-// the nightly result is dispatched under. Everything else is verbatim-shared.
-const PRODUCT_LINE = /^(\s*product:\s*).*$/m;
+// The one legitimately per-repo line in the shared workflows: the dashboard key
+// the CI result is dispatched under. Everything else is verbatim-shared.
+const PRODUCT_LINE = /^(\s*product:\s*).*$/gm;
 const PRODUCT_SENTINEL = "__PRODUCT__";
 
-function workflowProblem(actual: string, canonical: string): string | undefined {
+function workflowProblem(relPath: string, canonicalRef: string, actual: string, canonical: string): string | undefined {
   // Compare structure with the product value masked so any real key passes, then
   // separately reject a copy that still carries the unfilled sentinel.
   const mask = (s: string) => s.replace(PRODUCT_LINE, `$1${PRODUCT_SENTINEL}`);
   if (mask(actual) !== mask(canonical)) {
-    return `.github/workflows/upgrade-latest.yml has drifted from @norskvideo/ctl-dev-kit conventions/upgrade-latest.yml (${firstDiffLine(mask(actual), mask(canonical))}). ${RESYNC}`;
+    return `${relPath} has drifted from @norskvideo/ctl-dev-kit ${canonicalRef} (${firstDiffLine(mask(actual), mask(canonical))}). ${RESYNC}`;
   }
   if (actual.match(/^\s*product:\s*(\S+)/m)?.[1] === PRODUCT_SENTINEL) {
-    return `.github/workflows/upgrade-latest.yml still has the ${PRODUCT_SENTINEL} placeholder — set \`product:\` to this repo's dashboard key.`;
+    return `${relPath} still has the ${PRODUCT_SENTINEL} placeholder — set \`product:\` to this repo's dashboard key.`;
   }
   return undefined;
 }
@@ -70,6 +77,124 @@ function flakeProblem(actual: string, canonical: string): string | undefined {
   return `flake.nix has drifted from @norskvideo/ctl-dev-kit build/flake.nix (${firstDiffLine(ma, mc)}). ${RESYNC}`;
 }
 
+// dprint.json is canonical-plus-extension: the shared config is verbatim, but a
+// repo may exclude paths only it has (e.g. probe's generated components/lib/)
+// inside a sanctioned marker block at the head of `excludes`. Everything outside
+// the block is byte-compared; inside, only well-formed `"entry",` lines are
+// allowed so the block can't smuggle arbitrary config past the byte check.
+const DPRINT_BEGIN = "// BEGIN repo-specific excludes";
+const DPRINT_END = "// END repo-specific excludes";
+
+function splitAtMarkers(s: string): { prefix: string; body: string[]; suffix: string } | undefined {
+  const lines = s.split("\n");
+  const begin = lines.findIndex((l) => l.trim() === DPRINT_BEGIN);
+  const end = lines.findIndex((l) => l.trim() === DPRINT_END);
+  if (begin === -1 || end === -1 || end < begin) return undefined;
+  return {
+    prefix: lines.slice(0, begin + 1).join("\n"),
+    body: lines.slice(begin + 1, end),
+    suffix: lines.slice(end).join("\n"),
+  };
+}
+
+function dprintProblem(actual: string, canonical: string): string | undefined {
+  const c = splitAtMarkers(canonical);
+  if (!c) throw new Error("canonical dprint.base.jsonc is missing its own marker block");
+  const a = splitAtMarkers(actual);
+  if (!a) {
+    return `dprint.json is missing the '${DPRINT_BEGIN}' / '${DPRINT_END}' marker lines inside "excludes". Re-sync from @norskvideo/ctl-dev-kit conventions/dprint.base.jsonc; repo-specific excludes go between the markers.`;
+  }
+  const masked = (x: { prefix: string; suffix: string }) => `${x.prefix}\n${x.suffix}`;
+  if (masked(a) !== masked(c)) {
+    return `dprint.json has drifted from @norskvideo/ctl-dev-kit conventions/dprint.base.jsonc outside the repo-specific excludes block (${firstDiffLine(masked(a), masked(c))}). ${RESYNC}`;
+  }
+  const badLine = a.body.find((l) => !/^\s*"[^"]*",$/.test(l));
+  if (badLine !== undefined) {
+    return `dprint.json repo-specific excludes block has a malformed line (${JSON.stringify(badLine.trim())}) — one double-quoted exclude entry per line, each ending with a comma.`;
+  }
+  return undefined;
+}
+
+// deployment/build-image.sh: the wrapper around the shared build is per-product
+// (tag, port, and studio's sanctioned bespoke build), but its dev-kit-locating
+// bootstrap is the one forced copy — it must find this package before it can
+// source anything from it, so it is kept identical everywhere and gated here.
+// The script must also actually source a build/ script from the located dev-kit.
+const SOURCES_DEV_KIT = /^source "\$\{dev_kit\}\/build\/[^"]+\.sh"$/m;
+
+function buildImageProblem(actual: string, canonicalBootstrap: string): string | undefined {
+  const fnStart = canonicalBootstrap.indexOf("find_dev_kit() {");
+  if (fnStart === -1) throw new Error("canonical build-image.bootstrap.sh is missing find_dev_kit()");
+  const fn = canonicalBootstrap.slice(fnStart);
+  if (!actual.includes(fn)) {
+    return `deployment/build-image.sh does not contain the canonical find_dev_kit bootstrap from @norskvideo/ctl-dev-kit build/build-image.bootstrap.sh. ${RESYNC}`;
+  }
+  if (!SOURCES_DEV_KIT.test(actual)) {
+    return `deployment/build-image.sh never sources a script from "\${dev_kit}/build/" — the build machinery is single-sourced in @norskvideo/ctl-dev-kit, not copied into the product.`;
+  }
+  return undefined;
+}
+
+// Root tsconfig.json is gated structurally, not byte-wise: its `include` list
+// legitimately differs by repo shape (probe adds scripts + a playwright config,
+// studio adds scripts/, the turnkeys are tests-only), so the gate pins what is
+// genuinely common — all compiler semantics live in the byte-gated
+// tsconfig.base.json, the root file only extends it and names the trees — and
+// leaves the include list free beyond the tests/**/* every repo carries.
+const ROOT_TSCONFIG_KEYS = new Set(["//", "extends", "include"]);
+
+function rootTsconfigProblem(actual: string): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(actual);
+  } catch (e) {
+    return `tsconfig.json at the repo root is not parseable JSON (${e instanceof Error ? e.message : String(e)}).`;
+  }
+  const cfg = parsed as Record<string, unknown>;
+  const extraKeys = Object.keys(cfg).filter((k) => !ROOT_TSCONFIG_KEYS.has(k));
+  if (extraKeys.includes("compilerOptions")) {
+    return `tsconfig.json must not carry compilerOptions — all compiler semantics live in the drift-gated tsconfig.base.json.`;
+  }
+  if (extraKeys.length > 0) {
+    return `tsconfig.json carries unexpected top-level keys (${extraKeys.join(", ")}) — only "//", "extends" and "include" are sanctioned; semantics belong in tsconfig.base.json.`;
+  }
+  if (cfg.extends !== "./tsconfig.base.json") {
+    return `tsconfig.json must have "extends": "./tsconfig.base.json" (found ${JSON.stringify(cfg.extends)}).`;
+  }
+  if (!Array.isArray(cfg.include) || !cfg.include.includes("tests/**/*")) {
+    return `tsconfig.json "include" must contain "tests/**/*" (every product typechecks its tests tree); shape-specific extras are fine.`;
+  }
+  return undefined;
+}
+
+// .gitignore is base-block-plus-additions: the canonical block must appear
+// verbatim (an unrecognised entry inside it would be drift), while entries a
+// repo's shape genuinely needs (build outputs, codegen trees) live freely
+// outside it — extra ignore lines for paths another repo lacks are inert, so
+// they need no sanctioning mechanism beyond staying out of the block.
+function gitignoreProblem(actual: string, canonicalBlock: string): string | undefined {
+  if (actual.includes(canonicalBlock)) return undefined;
+  return `.gitignore does not contain the ctl-shared-gitignore block verbatim. Copy conventions/gitignore.core from @norskvideo/ctl-dev-kit; repo-specific entries go outside the block. ${RESYNC}`;
+}
+
+// manifest.seed.json is conformance-checked, not byte-compared: its pins are
+// per-product by design, but the SHAPE is the SDK's SeedSchema. This is the CI
+// gate ctl-sdk/manifest-seed's comment always assumed — version.ts consumes the
+// JSON as typed data precisely because every seed is validated here.
+function seedProblem(actual: string): string | undefined {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(actual);
+  } catch (e) {
+    return `manifest.seed.json is not parseable JSON (${e instanceof Error ? e.message : String(e)}).`;
+  }
+  const parsed = parseManifestSeed(raw);
+  if (parsed.status === "error") {
+    return `manifest.seed.json does not conform to @norskvideo/ctl-sdk/manifest-seed's SeedSchema:\n${parsed.error}`;
+  }
+  return undefined;
+}
+
 function coreProblem(claude: string, canonicalCore: string): string | undefined {
   if (claude.includes(canonicalCore)) return undefined;
 
@@ -82,18 +207,47 @@ function coreProblem(claude: string, canonicalCore: string): string | undefined
   return `CLAUDE.md fenced core has drifted from @norskvideo/ctl-dev-kit conventions/CLAUDE.core.md (${firstDiffLine(region, canonicalCore.trimEnd())}). ${RESYNC}`;
 }
 
-export function checkDrift(
+export interface CanonicalBytes {
+  core: string;
+  flake: string;
+  upgradeLatest: string;
+  checks: string;
+  biome: string;
+  tsconfigBase: string;
+  dprint: string;
+  buildImageBootstrap: string;
+  gitignoreCore: string;
+}
+
+// A file that must be a verbatim, byte-for-byte copy of its dev-kit canonical.
+function verbatimProblem(
   repoRoot: string,
-  canonical: { core: string; flake: string; upgradeLatest: string },
-): DriftReport {
+  relPath: string,
+  canonicalRef: string,
+  canonical: string,
+): string | undefined {
+  const path = join(repoRoot, relPath);
+  if (!existsSync(path)) {
+    return `${relPath} not found at repo root (${path}). It is copied verbatim from @norskvideo/ctl-dev-kit ${canonicalRef}.`;
+  }
+  const actual = readFileSync(path, "utf8");
+  if (actual !== canonical) {
+    return `${relPath} has drifted from @norskvideo/ctl-dev-kit ${canonicalRef} (${firstDiffLine(actual, canonical)}). ${RESYNC}`;
+  }
+  return undefined;
+}
+
+export function checkDrift(repoRoot: string, canonical: CanonicalBytes): DriftReport {
   const problems: string[] = [];
+  const push = (problem: string | undefined) => {
+    if (problem) problems.push(problem);
+  };
 
   const claudePath = join(repoRoot, "CLAUDE.md");
   if (!existsSync(claudePath)) {
     problems.push(`CLAUDE.md not found at repo root (${claudePath}). It must embed the ctl-shared-conventions core.`);
   } else {
-    const problem = coreProblem(readFileSync(claudePath, "utf8"), canonical.core);
-    if (problem) problems.push(problem);
+    push(coreProblem(readFileSync(claudePath, "utf8"), canonical.core));
   }
 
   const flakePath = join(repoRoot, "flake.nix");
@@ -105,14 +259,81 @@ export function checkDrift(
     const problem = flakeProblem(readFileSync(flakePath, "utf8"), canonical.flake);
     if (problem) problems.push(problem);
   }
+  push(verbatimProblem(repoRoot, "biome.json", "conventions/biome.base.json", canonical.biome));
+  push(verbatimProblem(repoRoot, "tsconfig.base.json", "conventions/tsconfig.base.json", canonical.tsconfigBase));
+
+  const rootTsconfigPath = join(repoRoot, "tsconfig.json");
+  if (!existsSync(rootTsconfigPath)) {
+    problems.push(
+      `tsconfig.json not found at repo root (${rootTsconfigPath}). It must extend the drift-gated tsconfig.base.json and include tests/**/*.`,
+    );
+  } else {
+    push(rootTsconfigProblem(readFileSync(rootTsconfigPath, "utf8")));
+  }
+
+  const dprintPath = join(repoRoot, "dprint.json");
+  if (!existsSync(dprintPath)) {
+    problems.push(
+      `dprint.json not found at repo root (${dprintPath}). Copy conventions/dprint.base.jsonc from @norskvideo/ctl-dev-kit (repo-specific excludes go inside its marker block).`,
+    );
+  } else {
+    push(dprintProblem(readFileSync(dprintPath, "utf8"), canonical.dprint));
+  }
+
+  const seedPath = join(repoRoot, "manifest.seed.json");
+  if (!existsSync(seedPath)) {
+    problems.push(
+      `manifest.seed.json not found at repo root (${seedPath}). Every product pins its {media, studio} pair there (RFC 0001 Workstream C).`,
+    );
+  } else {
+    push(seedProblem(readFileSync(seedPath, "utf8")));
+  }
+
+  const gitignorePath = join(repoRoot, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    problems.push(
+      `.gitignore not found at repo root (${gitignorePath}). It must contain the ctl-shared-gitignore block from @norskvideo/ctl-dev-kit conventions/gitignore.core.`,
+    );
+  } else {
+    push(gitignoreProblem(readFileSync(gitignorePath, "utf8"), canonical.gitignoreCore));
+  }
+
+  const buildImagePath = join(repoRoot, "deployment", "build-image.sh");
+  if (!existsSync(buildImagePath)) {
+    problems.push(
+      `deployment/build-image.sh not found (${buildImagePath}). Every product ships the thin wrapper over the dev-kit build; see build/build-image.bootstrap.sh.`,
+    );
+  } else {
+    push(buildImageProblem(readFileSync(buildImagePath, "utf8"), canonical.buildImageBootstrap));
+  }
+
+  // checks.yml is REQUIRED — it is the CI entry point that runs this very gate
+  // (plus the shared quality jobs), so a repo without it never re-converges.
+  // Only the `product:` dispatch key is per-repo; it is masked like
+  // upgrade-latest.yml's.
+  const checksPath = join(repoRoot, ".github", "workflows", "checks.yml");
+  const checksRel = ".github/workflows/checks.yml";
+  if (!existsSync(checksPath)) {
+    problems.push(
+      `${checksRel} not found (${checksPath}). Copy conventions/checks.yml from @norskvideo/ctl-dev-kit and set \`product:\` to this repo's dashboard key.`,
+    );
+  } else {
+    push(workflowProblem(checksRel, "conventions/checks.yml", readFileSync(checksPath, "utf8"), canonical.checks));
+  }
 
   // upgrade-latest.yml is OPTIONAL — a product may ship without a nightly bump
   // (e.g. until it has an integration tier). But when present it is the shared,
   // single-sourced workflow and must not diverge.
   const workflowPath = join(repoRoot, ".github", "workflows", "upgrade-latest.yml");
   if (existsSync(workflowPath)) {
-    const problem = workflowProblem(readFileSync(workflowPath, "utf8"), canonical.upgradeLatest);
-    if (problem) problems.push(problem);
+    push(
+      workflowProblem(
+        ".github/workflows/upgrade-latest.yml",
+        "conventions/upgrade-latest.yml",
+        readFileSync(workflowPath, "utf8"),
+        canonical.upgradeLatest,
+      ),
+    );
   }
 
   return { ok: problems.length === 0, problems };
@@ -120,14 +341,20 @@ export function checkDrift(
 
 if (import.meta.main) {
   const repoRoot = process.argv[2] ?? process.cwd();
-  const canonical = {
+  const canonical: CanonicalBytes = {
     core: readFileSync(join(import.meta.dir, "CLAUDE.core.md"), "utf8"),
     flake: readFileSync(join(import.meta.dir, "..", "build", "flake.nix"), "utf8"),
     upgradeLatest: readFileSync(join(import.meta.dir, "upgrade-latest.yml"), "utf8"),
+    checks: readFileSync(join(import.meta.dir, "checks.yml"), "utf8"),
+    biome: readFileSync(join(import.meta.dir, "biome.base.json"), "utf8"),
+    tsconfigBase: readFileSync(join(import.meta.dir, "tsconfig.base.json"), "utf8"),
+    dprint: readFileSync(join(import.meta.dir, "dprint.base.jsonc"), "utf8"),
+    buildImageBootstrap: readFileSync(join(import.meta.dir, "..", "build", "build-image.bootstrap.sh"), "utf8"),
+    gitignoreCore: readFileSync(join(import.meta.dir, "gitignore.core"), "utf8"),
   };
   const report = checkDrift(repoRoot, canonical);
   if (report.ok) {
-    console.log("drift-check: CLAUDE.md core + flake.nix + upgrade-latest.yml match @norskvideo/ctl-dev-kit.");
+    console.log("drift-check: all shared-convention copies match @norskvideo/ctl-dev-kit.");
     process.exit(0);
   }
   console.error(

package/conventions/checks.yml

@@ -0,0 +1,77 @@
+# Pre-merge gates, single-sourced in @norskvideo/ctl-dev-kit (conventions/checks.yml)
+# and drift-checked — only the ci-status-dispatch `product:` key is per-repo.
+#
+# Two jobs:
+#   - drift: the RFC 0001 Workstream I shared-conventions drift-check. Fails if
+#     this repo's forced copies have diverged from the pinned dev-kit — the
+#     fenced CLAUDE.md core, flake.nix, the shared config files, the manifest
+#     seed. Copies exist so a human reads them on GitHub with no tooling; the
+#     gate is the only thing keeping them true.
+#   - quality: the repo's own lint + typecheck + unit tests, via the shared
+#     package.json script interface every product carries. The "whole project
+#     clean" convention in the CLAUDE core has no teeth without this.
+#
+# Both run the same proven way build-image does — inside `nix develop .#build`
+# (which provides bun) on the x64 self-hosted pool — but skip the Docker image
+# build, so they also gate pull requests. To re-sync after a legitimate dev-kit
+# change: bump the @norskvideo/ctl-dev-kit pin, then copy the new files in.
+name: checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  drift:
+    runs-on: x64
+    steps:
+      - uses: actions/checkout@v5
+      - name: Shared-conventions drift-check (Workstream I)
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bun install --frozen-lockfile
+            bun run check:drift
+          '
+
+  quality:
+    runs-on: x64
+    steps:
+      - uses: actions/checkout@v5
+      - name: Lint + typecheck + unit tests
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bun install --frozen-lockfile
+            bun run lint
+            bun run typecheck
+            bun run test:unit
+          '
+
+  # Report this pipeline's result to the aggregated product CI dashboard
+  # (id3as/ci-workflows) instead of posting its own pony — the dashboard renders
+  # the pony/emoji from the dispatched result. always() so a red or manual run
+  # still reports.
+  notify:
+    needs: [drift, quality]
+    if: always() && github.event_name == 'push'
+    runs-on: x64
+    steps:
+      - uses: actions/checkout@v5
+      - id: meta
+        run: |
+          if [ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" = "true" ]; then
+            echo "state=failure" >> "$GITHUB_OUTPUT"
+          else
+            echo "state=success" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: ./.github/actions/ci-status-dispatch
+        with:
+          token: ${{ secrets.CI_DISPATCH_TOKEN }}
+          product: __PRODUCT__
+          pipeline: checks
+          status: ${{ steps.meta.outputs.state }}

package/conventions/dprint.base.jsonc

@@ -0,0 +1,37 @@
+{
+  // Dprint owns Markdown + YAML only. Biome stays the formatter/linter for
+  // everything it supports (JS/TS/JSON/CSS) — see biome.json. Migrate YAML to
+  // Biome once it ships a YAML formatter (https://biomejs.dev/blog/roadmap-2026/).
+  "markdown": {
+    "textWrap": "maintain"
+  },
+  "yaml": {
+    // No trailing comma in expanded flow sequences — kubb's OpenAPI YAML parser
+    // rejects `[a, b,]` (Unexpected token), which broke `bun run gen`.
+    "trailingComma": false,
+    "flowSequence.preferSingleLine": true
+  },
+  "includes": ["**/*.{md,yaml,yml}"],
+  "excludes": [
+    // BEGIN repo-specific excludes
+    // END repo-specific excludes
+    "node_modules/",
+    "**/dist/",
+    "**/dist-embedded/",
+    "**/build/",
+    "**/src/generated/",
+    "**/test-temp/",
+    ".longshot/",
+    ".ai/",
+    ".claude/",
+    "**/docs/generated/",
+    "**/docs/committed/",
+    "**/studio-save-files/",
+    "**/starter-pack/",
+    "**/terraform/templates/"
+  ],
+  "plugins": [
+    "https://plugins.dprint.dev/markdown-0.22.1.wasm",
+    "https://plugins.dprint.dev/g-plane/pretty_yaml-v0.6.0.wasm"
+  ]
+}

package/conventions/gitignore.core

@@ -0,0 +1,18 @@
+# BEGIN ctl-shared-gitignore v1 (do not edit — drift-gated; repo-specific entries go outside this block)
+node_modules/
+dist/
+generated
+logs/
+test-temp/
+test-results/
+.DS_Store
+.bun_audit
+.envrc
+.vscode
+.claude/
+*.pem
+*.log
+*.tgz
+.env
+.env.local
+# END ctl-shared-gitignore v1

package/conventions/tsconfig.base.json

@@ -0,0 +1,14 @@
+{
+  "//": "Shared TS config for the server/library packages in the norsk-ctl compile graph (its sub-projects + the @product/* libs). Packages extend this and set only their own lib/jsx/outDir/include/exclude. `types` is pinned explicitly on purpose: auto-inclusion of @types walks node_modules/@types, which is unreliable under bun's isolated linker + scoped --filter installs, so ambient node/bun globals must be named here to be deterministic. Browser/frontend and product packages keep their own configs.",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "types": ["node", "bun"]
+  }
+}