mandrel-platform 0.10.0 → 0.11.2

package/README.md

@@ -117,6 +117,93 @@ is detected by Renovate).
 
 ---
 
+## Renovate preset
+
+The shared Renovate preset (`default.json`, also exposed at
+`config/renovate.json`) is consumed by extending it from a consumer's
+`renovate.json`:
+
+```jsonc
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>dsj1984/mandrel-platform"]
+}
+```
+
+It sets a weekly Monday schedule, a 3-day `minimumReleaseAge`, patch/minor
+auto-merge with major updates gated behind the Dependency Dashboard, and
+grouping rules for the common dependency families (Cloudflare, Sentry, Clerk,
+ESLint, Vitest, Playwright, Astro).
+
+### Auto-bumping `mandrel-platform` `uses:` pins
+
+The preset ships a `github-actions` manager rule that bumps SHA-pinned
+references to this repo's reusable workflows and composite actions —
+`uses: dsj1984/mandrel-platform/...@<sha>` — so consumers stop drifting on
+stale pins (e.g. `pr-quality.yml@v0.3.1` while `deploy-cloudflare.yml@v0.9.0`).
+The bumps are grouped into a single **"mandrel-platform workflows"** PR and
+ride the preset's weekly window + 3-day `minimumReleaseAge`.
+
+**Required:** Renovate only updates a **bare-SHA** pin when the consumer adds a
+version comment after it. Pin with a trailing `# <tag>` comment so Renovate can
+resolve the current release and open the bump PR:
+
+```yaml
+# ✅ Renovate will bump this pin
+- uses: dsj1984/mandrel-platform/.github/actions/setup-toolchain@869bbbf21faa2cdf6045d64a9c3347b928e196fe # v0.10.0
+
+# ❌ Bare SHA without a version comment — Renovate leaves it alone
+- uses: dsj1984/mandrel-platform/.github/actions/setup-toolchain@869bbbf21faa2cdf6045d64a9c3347b928e196fe
+```
+
+See the [Dependency Update runbook](docs/runbooks/dependency-update.md) for the
+operator-facing review flow.
+
+---
+
+## Adoption CLI (`platform-sync`)
+
+`scripts/platform-sync.mjs` is the operator-facing analogue of `mandrel sync`:
+a single idempotent command a **consumer** repo runs to adopt mandrel-platform
+or to repair the three drift states the founding audit flagged (split pins,
+local-copy runbooks, un-simplified config). Run it from the consumer repo root:
+
+```bash
+# Pin every first-party `uses:` to a release and reconcile config + runbooks
+node node_modules/mandrel-platform/scripts/platform-sync.mjs --ref mandrel-platform-v0.10.0
+
+# Preview the plan without touching disk
+node node_modules/mandrel-platform/scripts/platform-sync.mjs --ref v1 --dry-run
+```
+
+What it does (each step is idempotent — a re-run on an already-synced repo
+reports `already in sync`):
+
+1. **Pins workflow SHAs.** Resolves `--ref` (a release tag, branch, or the
+   floating `@v1` tag once MP-13 ships it) to its commit SHA via
+   `git ls-remote`, then rewrites every
+   `uses: dsj1984/mandrel-platform/...@<sha>` reference in the consumer's
+   `.github/workflows/` and `.github/actions/` to that single SHA. External
+   actions (`actions/checkout`, …) are left untouched. The trailing
+   `# <ref>` comment is refreshed so the pin stays human-auditable and the
+   Renovate auto-bump rule above can track it.
+2. **Materializes runbook reference stubs** (§2.2 *link, don't copy*). Copies
+   the thin stubs from `templates/runbooks/` into the consumer's
+   `docs/runbooks/` **only when absent** — an already-adopted stub is skipped,
+   and a full local copy (no stub marker) is surfaced as a warning to
+   reconcile by hand, never silently overwritten.
+3. **Reconciles `extends`.** Prepends `github>dsj1984/mandrel-platform` to the
+   consumer's Renovate `extends` and `mandrel-platform/tsconfig.base.json` to
+   its `tsconfig.json` `extends`. The SSOT goes first so the consumer's own
+   later entries continue to override it.
+
+**Flags:** `--ref <ref>` (required), `--dry-run`, `--sha <40-hex>` (skip
+network ref resolution — offline/test mode), `--consumer <dir>` (default:
+cwd), `--templates <dir>`, `--repo <owner/repo>`, `--json` (machine-readable
+result envelope on stdout).
+
+---
+
 ## Development
 
 ```bash

package/default.json

@@ -24,6 +24,13 @@
       "dependencyDashboardApproval": true,
       "automerge": false
     },
+    {
+      "description": "Bump SHA-pinned mandrel-platform reusable-workflow and composite-action uses: pins (github-actions manager). Renovate only updates a bare-SHA pin when the consumer adds a version comment after it, e.g. uses: dsj1984/mandrel-platform/...@<sha> # v0.10.0 — see the dependency-update runbook. Grouped into one PR and scheduled via the preset's weekly window + 3-day minimumReleaseAge.",
+      "matchManagers": ["github-actions"],
+      "matchDepNames": ["dsj1984/mandrel-platform"],
+      "groupName": "mandrel-platform workflows",
+      "groupSlug": "mandrel-platform"
+    },
     {
       "description": "Group Astro packages",
       "matchPackagePatterns": ["^astro$", "^@astrojs/"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.10.0",
+  "version": "0.11.2",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "engines": {
@@ -24,7 +24,8 @@
   "scripts": {
     "typecheck": "node --input-type=module --eval 'process.exit(0)'",
     "lint": "node --input-type=module --eval 'process.exit(0)'",
-    "test": "node --input-type=module --eval 'process.exit(0)'",
+    "test": "node --test \"scripts/**/*.test.mjs\"",
+    "platform:sync": "node scripts/platform-sync.mjs",
     "sync:commands": "node .agents/scripts/sync-claude-commands.js",
     "bootstrap": "node .agents/scripts/bootstrap.js",
     "quality:preview": "node .agents/scripts/quality-preview.js --changed-since HEAD",

package/scripts/check-pin-drift.mjs

@@ -0,0 +1,546 @@
+#!/usr/bin/env node
+/**
+ * check-pin-drift.mjs
+ *
+ * Cross-consumer pin-drift dashboard for mandrel-platform (Story #67, MP-12).
+ *
+ * The split-pin / release-lag state across the three consumers (domio,
+ * athportal, swarm-os) went undetected and undocumented: every consumer
+ * pinned `pr-quality.yml@<shaA>` and `deploy-cloudflare.yml@<shaB>` — two
+ * different release SHAs per repo, neither on the current platform release,
+ * with no automated drift detection (roadmap.md §4.2 / §4.3). This script is
+ * the standing check that surfaces it automatically.
+ *
+ * For each consumer in `scripts/pin-drift-consumers.json` it:
+ *   1. Enumerates every workflow file under `.github/workflows/` (over the
+ *      GitHub contents API, against the consumer's default branch unless the
+ *      entry pins a `branch`).
+ *   2. Extracts every `uses:` ref that points at the platform repo
+ *      (`<platformRepo>/...@<ref>`) — reusable workflows AND composite
+ *      actions across ALL chains.
+ *   3. Asserts the consumer pins a SINGLE platform SHA across all of those
+ *      refs (a "split pin" is more than one distinct SHA in one consumer).
+ *   4. Flags lag: compares the pinned SHA against the latest platform release
+ *      commit. A consumer is `current` when its single pin equals the latest
+ *      release SHA, `lagging` when it pins an older release/SHA, and
+ *      `unknown` when the pinned SHA can't be matched to a release.
+ *
+ * Data-driven: a new consumer is one object in pin-drift-consumers.json.
+ *
+ * GitHub access is via the `gh` CLI (`gh api`), so the script inherits the
+ * caller's auth (a `GH_TOKEN`/`GITHUB_TOKEN` in CI, or `gh auth` locally).
+ * No secrets are read or printed by this script.
+ *
+ * Usage:
+ *   node scripts/check-pin-drift.mjs
+ *   node scripts/check-pin-drift.mjs --config scripts/pin-drift-consumers.json
+ *   node scripts/check-pin-drift.mjs --json            # machine-readable envelope
+ *   node scripts/check-pin-drift.mjs --strict          # exit 1 on any drift
+ *
+ * Exit codes:
+ *   0 — report emitted. Without --strict this is the default even when drift
+ *       is present (the dashboard reports; it does not block by default).
+ *   1 — with --strict: at least one consumer is split-pinned or lagging.
+ *       Without --strict: only on a fatal error (bad config, gh failure).
+ *
+ * GitHub Actions: when GITHUB_STEP_SUMMARY is set, the human-readable report
+ * is also appended there so it renders on the job summary page.
+ */
+
+import { readFileSync, appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string[]} argv
+ * @returns {{ config: string, json: boolean, strict: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let config = "scripts/pin-drift-consumers.json";
+  let json = false;
+  let strict = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--config") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        config = next;
+        i += 1;
+      }
+    } else if (a === "--json") {
+      json = true;
+    } else if (a === "--strict") {
+      strict = true;
+    }
+  }
+  return { config, json, strict };
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit-style probing without GitHub access)
+// ---------------------------------------------------------------------------
+
+const SHA_RE = /^[0-9a-f]{40}$/i;
+
+/**
+ * Is `ref` a full 40-char hex commit SHA?
+ * @param {string} ref
+ * @returns {boolean}
+ */
+export function isFullSha(ref) {
+  return SHA_RE.test(ref);
+}
+
+/**
+ * Extract every `uses:` ref that targets the platform repo from one workflow
+ * file's text. Matches both reusable-workflow refs
+ * (`<platformRepo>/.github/workflows/x.yml@<ref>`) and composite-action refs
+ * (`<platformRepo>/.github/actions/y@<ref>`).
+ *
+ * @param {string} file       Display label for the file (path in the repo).
+ * @param {string} text       File contents.
+ * @param {string} platformRepo  e.g. "dsj1984/mandrel-platform".
+ * @returns {Array<{ file: string, line: number, target: string, ref: string | null }>}
+ */
+export function extractPlatformPins(file, text, platformRepo) {
+  const pins = [];
+  const lines = text.split(/\r?\n/);
+  const usesRe = /^\s*(?:-\s*)?uses:\s*['"]?([^'"#\s]+)['"]?/;
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = usesRe.exec(lines[i]);
+    if (!m) continue;
+    const value = m[1];
+    // Only platform-repo refs: `<platformRepo>` or `<platformRepo>/<subpath>`.
+    if (value !== platformRepo && !value.startsWith(`${platformRepo}/`)) {
+      continue;
+    }
+    const atIndex = value.indexOf("@");
+    const target = atIndex === -1 ? value : value.slice(0, atIndex);
+    const ref = atIndex === -1 ? null : value.slice(atIndex + 1);
+    pins.push({ file, line: i + 1, target, ref });
+  }
+  return pins;
+}
+
+/**
+ * Classify one consumer's pin set into a drift verdict.
+ *
+ * @param {Array<{ file: string, line: number, target: string, ref: string | null }>} pins
+ * @param {string | null} latestReleaseSha  40-char SHA of the latest platform release commit, or null if unknown.
+ * @returns {{
+ *   pinCount: number,
+ *   distinctRefs: string[],
+ *   splitPinned: boolean,
+ *   floatingRefs: string[],
+ *   pinnedSha: string | null,
+ *   lagState: 'current' | 'lagging' | 'unknown' | 'no-pins',
+ *   drift: boolean,
+ * }}
+ */
+export function classifyConsumer(pins, latestReleaseSha) {
+  const refs = pins.map((p) => p.ref).filter((r) => r !== null);
+  const distinctRefs = [...new Set(refs)];
+  const floatingRefs = distinctRefs.filter((r) => !isFullSha(r));
+
+  if (pins.length === 0) {
+    return {
+      pinCount: 0,
+      distinctRefs: [],
+      splitPinned: false,
+      floatingRefs: [],
+      pinnedSha: null,
+      lagState: "no-pins",
+      drift: false,
+    };
+  }
+
+  const distinctShas = distinctRefs.filter((r) => isFullSha(r));
+  // "Split pin" = more than one distinct platform ref across all chains
+  // (multiple SHAs, or a mix of SHA + floating tag/branch).
+  const splitPinned = distinctRefs.length > 1;
+  const pinnedSha =
+    distinctShas.length === 1 && floatingRefs.length === 0
+      ? distinctShas[0].toLowerCase()
+      : null;
+
+  let lagState;
+  if (floatingRefs.length > 0 && distinctShas.length === 0) {
+    // Pinned only to floating refs (tags/branches) — can't verify lag by SHA.
+    lagState = "unknown";
+  } else if (pinnedSha === null) {
+    // Split or mixed — lag is moot until the split is resolved.
+    lagState = "unknown";
+  } else if (latestReleaseSha === null) {
+    lagState = "unknown";
+  } else if (pinnedSha === latestReleaseSha.toLowerCase()) {
+    lagState = "current";
+  } else {
+    lagState = "lagging";
+  }
+
+  const drift = splitPinned || lagState === "lagging";
+
+  return {
+    pinCount: pins.length,
+    distinctRefs,
+    splitPinned,
+    floatingRefs,
+    pinnedSha,
+    lagState,
+    drift,
+  };
+}
+
+/**
+ * Render the human-readable dashboard report.
+ *
+ * @param {{
+ *   platformRepo: string,
+ *   latestRelease: { tag: string | null, sha: string | null },
+ *   results: Array<{
+ *     name: string,
+ *     repo: string,
+ *     branch: string,
+ *     error?: string,
+ *     pins: Array<{ file: string, line: number, target: string, ref: string | null }>,
+ *     verdict: ReturnType<typeof classifyConsumer>,
+ *   }>,
+ * }} report
+ * @returns {string}
+ */
+export function renderReport(report) {
+  const { platformRepo, latestRelease, results } = report;
+  const out = [];
+  out.push("## Cross-consumer pin-drift dashboard");
+  out.push("");
+  out.push(`Platform: \`${platformRepo}\``);
+  const relLabel =
+    latestRelease.tag && latestRelease.sha
+      ? `\`${latestRelease.tag}\` (\`${latestRelease.sha.slice(0, 7)}\`)`
+      : "unknown";
+  out.push(`Latest release: ${relLabel}`);
+  out.push("");
+  out.push("| Consumer | Pins | Pinned SHA | Lag | Status |");
+  out.push("| -------- | ---- | ---------- | --- | ------ |");
+
+  const driftLines = [];
+  for (const r of results) {
+    if (r.error) {
+      out.push(`| \`${r.name}\` | — | — | — | ⚠️ error |`);
+      driftLines.push(`- \`${r.name}\` (${r.repo}): error — ${r.error}`);
+      continue;
+    }
+    const v = r.verdict;
+    const shaLabel = v.pinnedSha
+      ? `\`${v.pinnedSha.slice(0, 7)}\``
+      : v.splitPinned
+        ? `split (${v.distinctRefs.length})`
+        : v.floatingRefs.length > 0
+          ? v.floatingRefs.map((f) => `\`@${f}\``).join(", ")
+          : "—";
+    const lagLabel =
+      v.lagState === "current"
+        ? "current"
+        : v.lagState === "lagging"
+          ? "lagging"
+          : v.lagState === "no-pins"
+            ? "no pins"
+            : "unknown";
+    let status;
+    if (v.lagState === "no-pins") status = "➖ no platform pins";
+    else if (v.splitPinned) status = "❌ split pin";
+    else if (v.lagState === "lagging") status = "⚠️ lagging";
+    else if (v.lagState === "current") status = "✅ current";
+    else status = "❔ unknown";
+    out.push(
+      `| \`${r.name}\` | ${v.pinCount} | ${shaLabel} | ${lagLabel} | ${status} |`,
+    );
+
+    if (v.splitPinned) {
+      const refList = v.distinctRefs
+        .map((ref) => {
+          const where = r.pins
+            .filter((p) => p.ref === ref)
+            .map((p) => `${p.file}:${p.line}`)
+            .join(", ");
+          const short = isFullSha(ref) ? ref.slice(0, 7) : ref;
+          return `    - \`${short}\` ← ${where}`;
+        })
+        .join("\n");
+      driftLines.push(
+        `- \`${r.name}\` (${r.repo}): SPLIT PIN — ${v.distinctRefs.length} distinct platform refs across chains:\n${refList}`,
+      );
+    } else if (v.lagState === "lagging") {
+      driftLines.push(
+        `- \`${r.name}\` (${r.repo}): LAGGING — pins \`${v.pinnedSha.slice(0, 7)}\`, latest release is \`${(latestRelease.sha || "?").slice(0, 7)}\` (${latestRelease.tag || "?"}).`,
+      );
+    }
+  }
+
+  out.push("");
+  if (driftLines.length > 0) {
+    out.push("### Drift detected");
+    out.push("");
+    out.push(...driftLines);
+  } else {
+    out.push("### ✅ No drift");
+    out.push("");
+    out.push(
+      "Every consumer pins a single platform SHA on the latest release.",
+    );
+  }
+  out.push("");
+  return out.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// GitHub access (via gh CLI) — thin, injectable seam for testing
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `gh api <path>` and parse the JSON response.
+ *
+ * @param {string} apiPath  e.g. "repos/owner/repo/releases/latest".
+ * @param {(args: string[]) => string} runGh  Injectable runner (default execFileSync gh).
+ * @returns {unknown}
+ */
+function ghApiJson(apiPath, runGh) {
+  const raw = runGh(["api", apiPath, "-H", "Accept: application/vnd.github+json"]);
+  return JSON.parse(raw);
+}
+
+/**
+ * Default gh runner — shells out to the `gh` CLI.
+ * @param {string[]} args
+ * @returns {string}
+ */
+export function defaultGhRunner(args) {
+  return execFileSync("gh", args, {
+    encoding: "utf-8",
+    maxBuffer: 32 * 1024 * 1024,
+  });
+}
+
+/**
+ * Resolve the latest platform release tag + the commit SHA that tag points at.
+ * Falls back gracefully to { tag: null, sha: null } when the platform has no
+ * published release.
+ *
+ * @param {string} platformRepo
+ * @param {(args: string[]) => string} runGh
+ * @returns {{ tag: string | null, sha: string | null }}
+ */
+export function resolveLatestRelease(platformRepo, runGh) {
+  let release;
+  try {
+    release = ghApiJson(`repos/${platformRepo}/releases/latest`, runGh);
+  } catch {
+    return { tag: null, sha: null };
+  }
+  const tag = release && typeof release.tag_name === "string" ? release.tag_name : null;
+  if (!tag) return { tag: null, sha: null };
+  // Resolve the tag to its commit SHA. Tags may be lightweight (object is the
+  // commit) or annotated (object is the tag, deref to .object.sha).
+  try {
+    const refObj = ghApiJson(
+      `repos/${platformRepo}/git/ref/tags/${encodeURIComponent(tag)}`,
+      runGh,
+    );
+    let sha = refObj?.object?.sha ?? null;
+    if (refObj?.object?.type === "tag" && sha) {
+      const tagObj = ghApiJson(`repos/${platformRepo}/git/tags/${sha}`, runGh);
+      sha = tagObj?.object?.sha ?? sha;
+    }
+    return { tag, sha: sha ? sha.toLowerCase() : null };
+  } catch {
+    return { tag, sha: null };
+  }
+}
+
+/**
+ * Recursively list workflow files in a consumer's `.github/workflows/` dir and
+ * return [{ path, text }]. Uses the git trees API to enumerate, then the
+ * contents API to fetch each file. Returns [] when the dir is absent.
+ *
+ * @param {string} repo    "owner/name".
+ * @param {string} branch  Branch / ref to read.
+ * @param {(args: string[]) => string} runGh
+ * @returns {Array<{ path: string, text: string }>}
+ */
+export function fetchConsumerWorkflows(repo, branch, runGh) {
+  let listing;
+  try {
+    listing = ghApiJson(
+      `repos/${repo}/contents/.github/workflows?ref=${encodeURIComponent(branch)}`,
+      runGh,
+    );
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(listing)) return [];
+  const files = [];
+  for (const entry of listing) {
+    if (entry.type !== "file" || !/\.ya?ml$/i.test(entry.name)) continue;
+    // entry.content is base64 for the contents endpoint, but the dir listing
+    // omits it — fetch the blob via its git sha for an explicit decode.
+    let text = "";
+    if (typeof entry.content === "string" && entry.encoding === "base64") {
+      text = Buffer.from(entry.content, "base64").toString("utf-8");
+    } else {
+      try {
+        const blob = ghApiJson(`repos/${repo}/git/blobs/${entry.sha}`, runGh);
+        if (blob?.encoding === "base64" && typeof blob.content === "string") {
+          text = Buffer.from(blob.content, "base64").toString("utf-8");
+        }
+      } catch {
+        text = "";
+      }
+    }
+    files.push({ path: `.github/workflows/${entry.name}`, text });
+  }
+  return files;
+}
+
+/**
+ * Resolve a consumer's effective branch: the entry's `branch` if set, else the
+ * repo's default branch.
+ *
+ * @param {{ repo: string, branch?: string }} consumer
+ * @param {(args: string[]) => string} runGh
+ * @returns {string}
+ */
+export function resolveBranch(consumer, runGh) {
+  if (consumer.branch) return consumer.branch;
+  try {
+    const repoMeta = ghApiJson(`repos/${consumer.repo}`, runGh);
+    return repoMeta?.default_branch || "main";
+  } catch {
+    return "main";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full drift report for the configured consumers.
+ *
+ * @param {{ platformRepo: string, consumers: Array<{ name: string, repo: string, branch?: string }> }} config
+ * @param {(args: string[]) => string} runGh
+ * @returns {ReturnType<typeof renderReport> extends string ? object : never}
+ */
+export function buildReport(config, runGh) {
+  const platformRepo = config.platformRepo;
+  const latestRelease = resolveLatestRelease(platformRepo, runGh);
+  const results = [];
+  for (const consumer of config.consumers) {
+    try {
+      const branch = resolveBranch(consumer, runGh);
+      const files = fetchConsumerWorkflows(consumer.repo, branch, runGh);
+      const pins = [];
+      for (const f of files) {
+        pins.push(...extractPlatformPins(f.path, f.text, platformRepo));
+      }
+      const verdict = classifyConsumer(pins, latestRelease.sha);
+      results.push({ name: consumer.name, repo: consumer.repo, branch, pins, verdict });
+    } catch (err) {
+      results.push({
+        name: consumer.name,
+        repo: consumer.repo,
+        branch: consumer.branch || "?",
+        error: err instanceof Error ? err.message : String(err),
+        pins: [],
+        verdict: classifyConsumer([], latestRelease.sha),
+      });
+    }
+  }
+  return { platformRepo, latestRelease, results };
+}
+
+/**
+ * @param {object} report
+ * @returns {boolean} true when any consumer has drift or an error.
+ */
+export function hasDrift(report) {
+  return report.results.some((r) => r.error || r.verdict.drift);
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ *   runGh?: (args: string[]) => string,
+ *   summaryPath?: string | undefined,
+ * }} [opts]
+ * @returns {number} exit code
+ */
+export function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  runGh = defaultGhRunner,
+  summaryPath = process.env.GITHUB_STEP_SUMMARY,
+} = {}) {
+  const { config: configRel, json, strict } = parseArgv(argv);
+  const configPath = resolve(cwd, configRel);
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch (err) {
+    stderr.write(
+      `[pin-drift] ❌ failed to read config ${configPath}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return 1;
+  }
+  if (!config.platformRepo || !Array.isArray(config.consumers)) {
+    stderr.write(
+      `[pin-drift] ❌ config must define { platformRepo: string, consumers: [] }\n`,
+    );
+    return 1;
+  }
+
+  const report = buildReport(config, runGh);
+  const drift = hasDrift(report);
+
+  if (json) {
+    stdout.write(`${JSON.stringify({ kind: "pin-drift-report", drift, ...report }, null, 2)}\n`);
+  } else {
+    const text = renderReport(report);
+    stdout.write(`${text}\n`);
+    if (summaryPath) {
+      try {
+        appendFileSync(summaryPath, `${text}\n`);
+      } catch (err) {
+        stderr.write(
+          `[pin-drift] ⚠ could not write job summary: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+      }
+    }
+  }
+
+  if (strict && drift) {
+    stderr.write(`[pin-drift] ❌ drift detected (--strict)\n`);
+    return 1;
+  }
+  return 0;
+}
+
+// Direct-invocation guard (matches the repo's other scripts/*.mjs entry style).
+const invokedDirectly =
+  process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
+if (invokedDirectly) {
+  process.exit(runCli());
+}

package/scripts/pin-drift-consumers.json

@@ -0,0 +1,18 @@
+{
+  "$comment": "Data-driven consumer registry for scripts/check-pin-drift.mjs (Story #67, MP-12). Each entry is one downstream repo that pins mandrel-platform reusable workflows / composite actions via `uses: dsj1984/mandrel-platform/...@<sha>`. Adding a new consumer is a single object here — the drift checker enumerates `.github/workflows/*` in each repo over the GitHub API, extracts every mandrel-platform pin, and asserts a single SHA per consumer plus lag vs the latest mandrel-platform release. `branch` is optional (defaults to the repo's default branch).",
+  "platformRepo": "dsj1984/mandrel-platform",
+  "consumers": [
+    {
+      "name": "domio",
+      "repo": "dsj1984/domio"
+    },
+    {
+      "name": "athportal",
+      "repo": "dsj1984/athportal"
+    },
+    {
+      "name": "swarm-os",
+      "repo": "Beestera/swarm-os"
+    }
+  ]
+}

package/scripts/platform-sync.mjs

@@ -0,0 +1,450 @@
+#!/usr/bin/env node
+/**
+ * platform-sync.mjs — mandrel-platform adoption / drift-repair CLI (MP-14).
+ *
+ * The operator-facing analogue of `mandrel sync`. Run it from the root of a
+ * **consumer** repo to adopt mandrel-platform — or to repair the three drift
+ * states the founding audit (§4.1) called out:
+ *
+ *   1. SPLIT PINS — consumer workflows reference
+ *      `dsj1984/mandrel-platform/...@<sha>` at mixed/stale SHAs. This command
+ *      resolves a chosen release ref (e.g. `mandrel-platform-v0.10.0`, or the
+ *      `@v1` floating tag once MP-13 ships it) to its commit SHA and rewrites
+ *      every first-party `uses:` pin to that single SHA — leaving the
+ *      `# <ref>` trailing comment so the pin stays human-auditable and
+ *      Renovate's `helpers:pinGitHubActionDigests`-style bump rule can track
+ *      it (MP-11).
+ *
+ *   2. LOCAL-COPY RUNBOOKS — consumer holds full local copies of the shared
+ *      process runbooks instead of thin reference stubs (§2.2 "reference,
+ *      don't copy"). This command materializes the canonical reference stubs
+ *      from `templates/runbooks/` into the consumer's `docs/runbooks/`,
+ *      **link-only** — it never overwrites a stub the operator has already
+ *      filled in (idempotent by content-marker detection).
+ *
+ *   3. UN-SIMPLIFIED CONFIG — consumer's `renovate.json` / `tsconfig.json`
+ *      hand-reimplement what the shared preset / base config already provide.
+ *      This command reconciles the `extends` chains so the consumer extends
+ *      the SSOT (`github>dsj1984/mandrel-platform` for Renovate,
+ *      `mandrel-platform/tsconfig.base.json` for TypeScript).
+ *
+ * Idempotent: re-running on an already-synced consumer makes no changes and
+ * reports `unchanged`. `--dry-run` prints the planned diff without touching
+ * disk or the network mutation.
+ *
+ * Usage (from the consumer repo root):
+ *   node node_modules/mandrel-platform/scripts/platform-sync.mjs --ref mandrel-platform-v0.10.0
+ *   node .../platform-sync.mjs --ref v1 --dry-run
+ *   node .../platform-sync.mjs --ref <ref> --consumer /path/to/consumer --templates /path/to/mandrel-platform/templates
+ *
+ * Flags:
+ *   --ref <ref>          (required) release tag / branch / floating tag to pin to.
+ *   --dry-run            plan only; no disk writes, no SHA resolution network call
+ *                        when --sha is also supplied.
+ *   --sha <40-hex>       skip ref→SHA resolution and pin to this SHA directly
+ *                        (offline / test mode).
+ *   --consumer <dir>     consumer repo root (default: process.cwd()).
+ *   --templates <dir>    mandrel-platform templates/ dir (default: resolved
+ *                        relative to this script — works when run from
+ *                        node_modules/mandrel-platform/scripts/).
+ *   --repo <owner/repo>  first-party slug to pin (default: dsj1984/mandrel-platform).
+ *   --json               emit the result envelope as JSON on stdout.
+ *
+ * Exit codes:
+ *   0 — sync applied or already in sync (or dry-run printed cleanly).
+ *   1 — a fatal error (unresolvable ref, missing templates, malformed config).
+ */
+
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const opts = {
+  ref: null,
+  sha: null,
+  dryRun: false,
+  consumer: process.cwd(),
+  templates: null,
+  repo: "dsj1984/mandrel-platform",
+  json: false,
+};
+
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === "--ref" && args[i + 1]) opts.ref = args[++i];
+  else if (a === "--sha" && args[i + 1]) opts.sha = args[++i];
+  else if (a === "--dry-run") opts.dryRun = true;
+  else if (a === "--consumer" && args[i + 1]) opts.consumer = resolve(args[++i]);
+  else if (a === "--templates" && args[i + 1]) opts.templates = resolve(args[++i]);
+  else if (a === "--repo" && args[i + 1]) opts.repo = args[++i];
+  else if (a === "--json") opts.json = true;
+  else if (a === "--help" || a === "-h") {
+    printHelp();
+    process.exit(0);
+  } else {
+    fail(`Unknown argument: ${a}`);
+  }
+}
+
+function printHelp() {
+  // Echo the usage block from the file header so `--help` stays in sync.
+  process.stdout.write(
+    [
+      "platform-sync — mandrel-platform adoption / drift-repair CLI (MP-14)",
+      "",
+      "Usage (from the consumer repo root):",
+      "  node node_modules/mandrel-platform/scripts/platform-sync.mjs --ref <ref> [--dry-run]",
+      "",
+      "Flags:",
+      "  --ref <ref>          (required) release tag / branch / floating tag to pin to.",
+      "  --dry-run            plan only; no disk writes.",
+      "  --sha <40-hex>       skip ref->SHA resolution; pin to this SHA (offline mode).",
+      "  --consumer <dir>     consumer repo root (default: cwd).",
+      "  --templates <dir>    mandrel-platform templates/ dir (default: resolved from script).",
+      "  --repo <owner/repo>  first-party slug to pin (default: dsj1984/mandrel-platform).",
+      "  --json               emit the result envelope as JSON.",
+      "",
+    ].join("\n")
+  );
+}
+
+function fail(msg) {
+  process.stderr.write(`❌ platform-sync: ${msg}\n`);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Logging — quiet under --json (the envelope is the only stdout artifact).
+// ---------------------------------------------------------------------------
+
+function log(msg) {
+  if (!opts.json) process.stdout.write(`${msg}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Defaults requiring resolution
+// ---------------------------------------------------------------------------
+
+if (!opts.ref) fail("--ref <release-tag|branch|floating-tag> is required.");
+if (opts.sha && !/^[0-9a-fA-F]{40}$/.test(opts.sha)) {
+  fail(`--sha must be a 40-character hex commit SHA (got: ${opts.sha}).`);
+}
+
+// templates/ defaults to the dir adjacent to this script's package root.
+// When run from node_modules/mandrel-platform/scripts/, that is
+// node_modules/mandrel-platform/templates/.
+if (!opts.templates) {
+  opts.templates = resolve(__dirname, "..", "templates");
+}
+const runbookTemplatesDir = join(opts.templates, "runbooks");
+
+// ---------------------------------------------------------------------------
+// 1. Resolve the chosen ref → commit SHA
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve `ref` (tag/branch/floating tag) on the remote `repo` to its full
+ * 40-char commit SHA. Uses `git ls-remote`, which needs no checkout and works
+ * for tags, annotated tags (peeled `^{}`), and branches. In --dry-run with an
+ * explicit --sha we skip the network entirely.
+ */
+function resolveSha() {
+  if (opts.sha) return opts.sha;
+  const remote = `https://github.com/${opts.repo}.git`;
+  let out;
+  try {
+    out = execFileSync("git", ["ls-remote", remote, opts.ref, `${opts.ref}^{}`], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (err) {
+    fail(
+      `could not resolve ref '${opts.ref}' on ${opts.repo}: ${
+        (err && err.stderr) || err.message
+      }`
+    );
+  }
+  const lines = out.trim().split("\n").filter(Boolean);
+  if (lines.length === 0) {
+    fail(`ref '${opts.ref}' not found on ${opts.repo}.`);
+  }
+  // Prefer the peeled (`^{}`) line for annotated tags — that is the commit the
+  // tag ultimately points at, which is what a `uses: ...@<sha>` pin must use.
+  const peeled = lines.find((l) => l.endsWith(`^{}`));
+  const chosen = peeled || lines[0];
+  const sha = chosen.split(/\s+/)[0];
+  if (!/^[0-9a-fA-F]{40}$/.test(sha)) {
+    fail(`resolved ref '${opts.ref}' to a non-SHA value: '${sha}'.`);
+  }
+  return sha;
+}
+
+// ---------------------------------------------------------------------------
+// 2. Pin first-party `uses:` SHAs in consumer workflows
+// ---------------------------------------------------------------------------
+
+/** Recursively collect `.yml`/`.yaml` files under a directory. */
+function collectYaml(dir) {
+  const found = [];
+  if (!existsSync(dir)) return found;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) found.push(...collectYaml(full));
+    else if (/\.ya?ml$/.test(entry)) found.push(full);
+  }
+  return found;
+}
+
+/**
+ * Rewrite every first-party `uses: <repo>/<path>@<oldSha>` to the target SHA.
+ * The match mirrors check-workflow-portability.mjs's internal-pin regex but is
+ * scoped to the configured `repo` slug (the consumer's workflows reference
+ * mandrel-platform explicitly, so the slug is known). Preserves any trailing
+ * `# <comment>` but rewrites it to `# <ref>` so the human-readable annotation
+ * tracks the chosen release.
+ */
+function pinWorkflows(targetSha) {
+  const workflowsDir = join(opts.consumer, ".github", "workflows");
+  const actionsDir = join(opts.consumer, ".github", "actions");
+  const files = [...collectYaml(workflowsDir), ...collectYaml(actionsDir)];
+  const slug = opts.repo.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // uses: dsj1984/mandrel-platform/<subpath>@<40hex>   [optional trailing comment]
+  const pinRe = new RegExp(
+    `(uses:\\s*['"]?${slug}/[^@\\s'"]+@)([0-9a-fA-F]{40})(['"]?)([^\\n]*)`,
+    "g"
+  );
+  const changes = [];
+  for (const file of files) {
+    const before = readFileSync(file, "utf8");
+    let touched = false;
+    const after = before.replace(pinRe, (_m, head, oldSha, quote, trailing) => {
+      // Drop any existing trailing comment; re-attach a fresh `# <ref>`.
+      const newTrailing = ` # ${opts.ref}`;
+      if (oldSha.toLowerCase() === targetSha.toLowerCase()) {
+        // SHA already correct — but normalize the comment if it drifted.
+        const normalized = `${head}${oldSha}${quote}${newTrailing}`;
+        const current = `${head}${oldSha}${quote}${trailing}`;
+        if (normalized !== current) touched = true;
+        return normalized;
+      }
+      touched = true;
+      changes.push({ file: rel(file), from: oldSha.slice(0, 7), to: targetSha.slice(0, 7) });
+      return `${head}${targetSha}${quote}${newTrailing}`;
+    });
+    if (touched && after !== before) {
+      if (!opts.dryRun) writeFileSync(file, after);
+    }
+  }
+  return changes;
+}
+
+// ---------------------------------------------------------------------------
+// 3. Materialize runbook reference stubs (link, don't copy)
+// ---------------------------------------------------------------------------
+
+// Content marker every materialized stub carries so re-runs are idempotent and
+// operator-edited stubs are never clobbered.
+const STUB_MARKER = "> **Thin local stub.**";
+
+/**
+ * Copy each `templates/runbooks/*.md` (except the index README) into the
+ * consumer's `docs/runbooks/`, but only when the destination is ABSENT. An
+ * existing destination is left untouched — whether it is an already-adopted
+ * stub or a local copy the operator must reconcile by hand (we surface the
+ * latter as a `localCopy` warning rather than silently overwriting their work).
+ */
+function materializeRunbooks() {
+  const created = [];
+  const skipped = [];
+  const localCopies = [];
+  if (!existsSync(runbookTemplatesDir)) {
+    fail(`runbook templates not found at ${runbookTemplatesDir}.`);
+  }
+  const destDir = join(opts.consumer, "docs", "runbooks");
+  for (const entry of readdirSync(runbookTemplatesDir)) {
+    if (!entry.endsWith(".md")) continue;
+    if (entry.toLowerCase() === "readme.md") continue; // index, not a stub
+    const src = join(runbookTemplatesDir, entry);
+    const dest = join(destDir, entry);
+    if (existsSync(dest)) {
+      const body = readFileSync(dest, "utf8");
+      if (body.includes(STUB_MARKER)) {
+        skipped.push(rel(dest)); // already a reference stub — idempotent no-op
+      } else {
+        localCopies.push(rel(dest)); // full local copy — operator must reconcile
+      }
+      continue;
+    }
+    if (!opts.dryRun) {
+      mkdirSync(destDir, { recursive: true });
+      writeFileSync(dest, readFileSync(src, "utf8"));
+    }
+    created.push(rel(dest));
+  }
+  return { created, skipped, localCopies };
+}
+
+// ---------------------------------------------------------------------------
+// 4. Reconcile renovate / tsconfig `extends`
+// ---------------------------------------------------------------------------
+
+const RENOVATE_PRESET = `github>${"dsj1984/mandrel-platform"}`;
+const TSCONFIG_BASE = "mandrel-platform/tsconfig.base.json";
+
+/** Parse JSON tolerating `//` and block comments (jsonc), preserving nothing
+ * but the parsed value — we re-serialize with 2-space indent. */
+function parseJsonc(text) {
+  const stripped = text
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/.*$/gm, "$1");
+  return JSON.parse(stripped);
+}
+
+function reconcileRenovate() {
+  // Renovate config can live at a few canonical paths.
+  const candidates = [
+    "renovate.json",
+    "renovate.json5",
+    ".github/renovate.json",
+    ".renovaterc.json",
+  ].map((p) => join(opts.consumer, p));
+  const path = candidates.find((p) => existsSync(p));
+  if (!path) return { action: "absent", file: null };
+  let cfg;
+  try {
+    cfg = parseJsonc(readFileSync(path, "utf8"));
+  } catch (err) {
+    fail(`could not parse Renovate config at ${rel(path)}: ${err.message}`);
+  }
+  const extendsArr = Array.isArray(cfg.extends) ? [...cfg.extends] : [];
+  if (extendsArr.includes(RENOVATE_PRESET)) {
+    return { action: "unchanged", file: rel(path) };
+  }
+  // Prepend the SSOT preset so consumer overrides (later entries) still win.
+  cfg.extends = [RENOVATE_PRESET, ...extendsArr];
+  if (!opts.dryRun) writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`);
+  return { action: "reconciled", file: rel(path), added: RENOVATE_PRESET };
+}
+
+function reconcileTsconfig() {
+  const path = join(opts.consumer, "tsconfig.json");
+  if (!existsSync(path)) return { action: "absent", file: null };
+  let cfg;
+  try {
+    cfg = parseJsonc(readFileSync(path, "utf8"));
+  } catch (err) {
+    fail(`could not parse tsconfig at ${rel(path)}: ${err.message}`);
+  }
+  // `extends` may be a string or (TS 5.0+) an array.
+  const current = cfg.extends;
+  const hasBase = Array.isArray(current)
+    ? current.includes(TSCONFIG_BASE)
+    : current === TSCONFIG_BASE;
+  if (hasBase) return { action: "unchanged", file: rel(path) };
+  if (current === undefined) {
+    cfg.extends = TSCONFIG_BASE;
+  } else if (Array.isArray(current)) {
+    // Base first so the consumer's own extends override it.
+    cfg.extends = [TSCONFIG_BASE, ...current];
+  } else {
+    cfg.extends = [TSCONFIG_BASE, current];
+  }
+  if (!opts.dryRun) writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`);
+  return { action: "reconciled", file: rel(path), added: TSCONFIG_BASE };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rel(p) {
+  return relative(opts.consumer, p) || p;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  if (!existsSync(opts.consumer)) {
+    fail(`consumer dir not found: ${opts.consumer}`);
+  }
+
+  const targetSha = resolveSha();
+  log(`▶ platform-sync — ref '${opts.ref}' → ${targetSha.slice(0, 7)} (${opts.repo})`);
+  if (opts.dryRun) log("  (dry-run: no files will be written)");
+
+  const pins = pinWorkflows(targetSha);
+  const runbooks = materializeRunbooks();
+  const renovate = reconcileRenovate();
+  const tsconfig = reconcileTsconfig();
+
+  const changed =
+    pins.length > 0 ||
+    runbooks.created.length > 0 ||
+    renovate.action === "reconciled" ||
+    tsconfig.action === "reconciled";
+
+  // Human-readable summary
+  log("");
+  log(`  pins:      ${pins.length} workflow pin(s) ${opts.dryRun ? "would be " : ""}updated`);
+  for (const c of pins) log(`             - ${c.file}: ${c.from} → ${c.to}`);
+  log(
+    `  runbooks:  ${runbooks.created.length} stub(s) ${
+      opts.dryRun ? "would be " : ""
+    }materialized, ${runbooks.skipped.length} already present`
+  );
+  for (const f of runbooks.created) log(`             + ${f}`);
+  for (const f of runbooks.localCopies) {
+    log(`             ⚠ ${f}: full local copy detected — reconcile to a reference stub by hand (§2.2)`);
+  }
+  log(`  renovate:  ${renovate.action}${renovate.file ? ` (${renovate.file})` : ""}`);
+  log(`  tsconfig:  ${tsconfig.action}${tsconfig.file ? ` (${tsconfig.file})` : ""}`);
+  log("");
+  log(
+    changed
+      ? opts.dryRun
+        ? "✅ dry-run: changes planned (see above). Re-run without --dry-run to apply."
+        : "✅ sync applied."
+      : "✅ already in sync — no changes."
+  );
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ref: opts.ref,
+          sha: targetSha,
+          repo: opts.repo,
+          consumer: opts.consumer,
+          dryRun: opts.dryRun,
+          changed,
+          pins,
+          runbooks,
+          renovate,
+          tsconfig,
+        },
+        null,
+        2
+      )}\n`
+    );
+  }
+}
+
+main();

package/scripts/platform-sync.test.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * platform-sync.test.mjs — node:test suite for the MP-14 adoption CLI.
+ *
+ * Exercises the four acceptance behaviours against a synthetic consumer dir
+ * built under a temp root, in offline mode (`--sha` skips the network):
+ *
+ *   1. workflow SHA pinning (first-party rewritten, external untouched, the
+ *      `# <ref>` annotation refreshed),
+ *   2. runbook reference-stub materialization (link-only, local-copy warning),
+ *   3. renovate / tsconfig `extends` reconciliation (SSOT prepended, consumer
+ *      overrides preserved),
+ *   4. idempotency + `--dry-run` non-mutation.
+ *
+ * Run: node scripts/platform-sync.test.mjs   (or `node --test scripts/`)
+ */
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, test } from "node:test";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI = join(__dirname, "platform-sync.mjs");
+const SHA = "a".repeat(40);
+const REF = "mandrel-platform-v9.9.9";
+
+let consumer;
+
+function run(extraArgs) {
+  return execFileSync(
+    "node",
+    [CLI, "--ref", REF, "--sha", SHA, "--consumer", consumer, "--json", ...extraArgs],
+    { encoding: "utf8" }
+  );
+}
+
+function seedConsumer() {
+  mkdirSync(join(consumer, ".github", "workflows"), { recursive: true });
+  writeFileSync(
+    join(consumer, ".github", "workflows", "ci.yml"),
+    [
+      "name: CI",
+      "jobs:",
+      "  q:",
+      "    steps:",
+      `      - uses: dsj1984/mandrel-platform/.github/actions/setup-toolchain@${"1".repeat(40)} # stale`,
+      `      - uses: actions/checkout@${"2".repeat(40)} # external`,
+      "",
+    ].join("\n")
+  );
+  writeFileSync(join(consumer, "renovate.json"), JSON.stringify({ extends: ["config:base"] }, null, 2));
+  writeFileSync(
+    join(consumer, "tsconfig.json"),
+    JSON.stringify({ compilerOptions: { outDir: "dist" } }, null, 2)
+  );
+}
+
+beforeEach(() => {
+  consumer = mkdtempSync(join(tmpdir(), "platform-sync-test-"));
+  seedConsumer();
+});
+
+afterEach(() => {
+  rmSync(consumer, { recursive: true, force: true });
+});
+
+test("--dry-run does not mutate any file", () => {
+  const before = readFileSync(join(consumer, ".github", "workflows", "ci.yml"), "utf8");
+  const out = JSON.parse(run(["--dry-run"]));
+  assert.equal(out.dryRun, true);
+  assert.equal(out.changed, true);
+  const after = readFileSync(join(consumer, ".github", "workflows", "ci.yml"), "utf8");
+  assert.equal(after, before, "ci.yml must be untouched in dry-run");
+  assert.ok(!existsSync(join(consumer, "docs", "runbooks", "observability.md")));
+});
+
+test("apply pins first-party SHAs, leaves external actions untouched", () => {
+  const out = JSON.parse(run([]));
+  assert.equal(out.changed, true);
+  assert.equal(out.pins.length, 1);
+  const ci = readFileSync(join(consumer, ".github", "workflows", "ci.yml"), "utf8");
+  assert.ok(ci.includes(`setup-toolchain@${SHA} # ${REF}`), "first-party pin rewritten + annotated");
+  assert.ok(ci.includes(`actions/checkout@${"2".repeat(40)} # external`), "external action untouched");
+});
+
+test("apply materializes runbook reference stubs (link, don't copy)", () => {
+  run([]);
+  const stub = join(consumer, "docs", "runbooks", "deploy-promotion.md");
+  assert.ok(existsSync(stub));
+  const body = readFileSync(stub, "utf8");
+  assert.ok(body.includes("Thin local stub"), "materialized stub is a reference, not a copy");
+  assert.ok(
+    body.includes("github.com/dsj1984/mandrel-platform"),
+    "stub links back to the canonical runbook"
+  );
+});
+
+test("apply reconciles renovate + tsconfig extends, preserving consumer entries", () => {
+  run([]);
+  const renovate = JSON.parse(readFileSync(join(consumer, "renovate.json"), "utf8"));
+  assert.deepEqual(renovate.extends, ["github>dsj1984/mandrel-platform", "config:base"]);
+  const tsconfig = JSON.parse(readFileSync(join(consumer, "tsconfig.json"), "utf8"));
+  assert.equal(tsconfig.extends, "mandrel-platform/tsconfig.base.json");
+  assert.equal(tsconfig.compilerOptions.outDir, "dist", "consumer overrides preserved");
+});
+
+test("re-running is idempotent (changed: false on the second pass)", () => {
+  run([]);
+  const second = JSON.parse(run([]));
+  assert.equal(second.changed, false, "second sync reports no changes");
+  assert.equal(second.pins.length, 0);
+});
+
+test("a full local-copy runbook is flagged, not overwritten", () => {
+  const dest = join(consumer, "docs", "runbooks");
+  mkdirSync(dest, { recursive: true });
+  const localCopy = "# Local copy, no stub marker\n\nfull process re-authored here\n";
+  writeFileSync(join(dest, "observability.md"), localCopy);
+  const out = JSON.parse(run([]));
+  assert.ok(
+    out.runbooks.localCopies.some((f) => f.endsWith("observability.md")),
+    "local copy surfaced as a warning"
+  );
+  assert.equal(
+    readFileSync(join(dest, "observability.md"), "utf8"),
+    localCopy,
+    "operator's local copy is never clobbered"
+  );
+});
+
+test("an existing reference stub is skipped idempotently", () => {
+  run([]); // materialize stubs
+  const out = JSON.parse(run([])); // second pass
+  assert.ok(out.runbooks.skipped.length >= 8, "already-present stubs are skipped, not re-created");
+  assert.equal(out.runbooks.created.length, 0);
+});

package/templates/runbooks/README.md

@@ -15,6 +15,16 @@ Each stub:
 
 ## How to adopt (downstream repo)
 
+**Automated path (recommended).** The adoption CLI materializes every stub for
+you (link-only, never clobbering a stub you've already filled in) as part of a
+full sync — see [`scripts/platform-sync.mjs`](../../README.md#adoption-cli-platform-sync):
+
+```bash
+node node_modules/mandrel-platform/scripts/platform-sync.mjs --ref mandrel-platform-v0.10.0
+```
+
+**Manual path.**
+
 1. Copy the stub(s) you need into your project's `docs/runbooks/`:
    ```bash
    cp node_modules/mandrel-platform/templates/runbooks/deploy-promotion.md \