mandrel-platform 0.17.2 → 0.19.0

package/scripts/platform-sync.mjs

@@ -28,6 +28,29 @@
  *      the SSOT (`github>dsj1984/mandrel-platform` for Renovate,
  *      `mandrel-platform/tsconfig.base.json` for TypeScript).
  *
+ * It also runs a fourth, **advisory-only** check (Story #173): whether the
+ * consumer's `.github/workflows/ci.yml` matches the canonical CI-caller
+ * naming triplet (file `ci.yml`, display name `CI`, caller job id `ci` →
+ * required context `ci / ci-required`; see
+ * `docs/reusable-workflows.md` § "Canonical caller naming"). This never
+ * renames or rewrites anything — renaming an existing caller must land
+ * atomically with its own branch-protection ruleset context update, which is
+ * a deliberate per-consumer Story, not an automatic sync side-effect.
+ *
+ * It also materializes canonical workflow **caller templates** from
+ * `templates/workflows/` into the consumer's `.github/workflows/` (Story
+ * #175) — e.g. `deploy-staging.yml`, the one-paved-road `workflow_run` caller
+ * for the shared `deploy-cloudflare.yml`'s CI-green guard. Same link-don't-
+ * copy semantics as the runbook stubs: never overwrites an existing file.
+ *
+ * A fifth, **report-only** GitHub-side mode (Story #178, `--check-ruleset`)
+ * reads a consumer's LIVE branch ruleset over the GitHub Rulesets API and
+ * reports drift against `docs/runbooks/main-protection.json` — the same
+ * non-blocking posture as `--check-settings`, but deliberately with no
+ * `--apply-ruleset` counterpart: a ruleset gates merge eligibility for every
+ * in-flight PR, so an automated PATCH here has a materially different blast
+ * radius than the same-repo settings toggles `--apply-settings` patches.
+ *
  * 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.
@@ -82,6 +105,20 @@ const opts = {
   templates: null,
   repo: "dsj1984/mandrel-platform",
   json: false,
+  // GitHub-side repo-settings check/apply mode (Story #171). This is a
+  // distinct mode from the local-checkout file sync above — it operates over
+  // the GitHub API against a `--consumer-repo owner/repo` slug rather than a
+  // local `--consumer <dir>` checkout, so it short-circuits main() below
+  // rather than composing with the pin/runbook/extends reconciliation.
+  checkSettings: false,
+  applySettings: false,
+  consumerRepo: null,
+  baseline: null,
+  // GitHub-side branch-ruleset drift check (Story #178). Report-only by
+  // design — see the SETTINGS_PATCHABLE_FIELDS comment below for why
+  // rulesets deliberately have no --apply-ruleset counterpart.
+  checkRuleset: false,
+  contract: null,
 };
 
 for (let i = 0; i < args.length; i++) {
@@ -93,6 +130,12 @@ for (let i = 0; i < args.length; 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 === "--check-settings") opts.checkSettings = true;
+  else if (a === "--apply-settings") opts.applySettings = true;
+  else if (a === "--consumer-repo" && args[i + 1]) opts.consumerRepo = args[++i];
+  else if (a === "--baseline" && args[i + 1]) opts.baseline = resolve(args[++i]);
+  else if (a === "--check-ruleset") opts.checkRuleset = true;
+  else if (a === "--contract" && args[i + 1]) opts.contract = resolve(args[++i]);
   else if (a === "--help" || a === "-h") {
     printHelp();
     process.exit(0);
@@ -111,14 +154,32 @@ function printHelp() {
       "  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.",
+      "  --ref <ref>          (required unless --check-settings/--apply-settings) release",
+      "                        tag / branch / floating tag to pin to.",
+      "  --dry-run            plan only; no disk writes / no GitHub-side mutation.",
       "  --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.",
       "",
+      "GitHub-side repo-settings check/apply (Story #171):",
+      "  --check-settings          read a consumer's LIVE repo settings via `gh api` and",
+      "                            report drift against the baseline (never blocks; report only).",
+      "  --apply-settings          same read, then PATCH the drifted fields to match the",
+      "                            baseline (safe subset only — see README). Implies --check-settings.",
+      "  --consumer-repo <owner/repo>  (required with --check-settings/--apply-settings) the",
+      "                            consumer repo to read/patch over the GitHub API.",
+      "  --baseline <path>         path to the repo-settings baseline JSON",
+      "                            (default: docs/runbooks/repo-settings.json next to this script's package).",
+      "",
+      "GitHub-side branch-ruleset drift check (Story #178, report-only — no --apply-ruleset):",
+      "  --check-ruleset           read a consumer's LIVE branch ruleset via `gh api` and report",
+      "                            drift against the main-protection contract (never blocks; never mutates).",
+      "  --consumer-repo <owner/repo>  (required with --check-ruleset) the consumer repo to read.",
+      "  --contract <path>         path to the main-protection contract JSON",
+      "                            (default: docs/runbooks/main-protection.json next to this script's package).",
+      "",
     ].join("\n")
   );
 }
@@ -140,9 +201,28 @@ function log(msg) {
 // 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}).`);
+const settingsMode = opts.checkSettings || opts.applySettings;
+const rulesetMode = opts.checkRuleset;
+
+if (settingsMode) {
+  if (!opts.consumerRepo) {
+    fail("--consumer-repo <owner/repo> is required with --check-settings/--apply-settings.");
+  }
+  if (!opts.baseline) {
+    opts.baseline = resolve(__dirname, "..", "docs", "runbooks", "repo-settings.json");
+  }
+} else if (rulesetMode) {
+  if (!opts.consumerRepo) {
+    fail("--consumer-repo <owner/repo> is required with --check-ruleset.");
+  }
+  if (!opts.contract) {
+    opts.contract = resolve(__dirname, "..", "docs", "runbooks", "main-protection.json");
+  }
+} else {
+  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.
@@ -152,6 +232,7 @@ if (!opts.templates) {
   opts.templates = resolve(__dirname, "..", "templates");
 }
 const runbookTemplatesDir = join(opts.templates, "runbooks");
+const workflowTemplatesDir = join(opts.templates, "workflows");
 
 // ---------------------------------------------------------------------------
 // 1. Resolve the chosen ref → commit SHA
@@ -254,6 +335,53 @@ function pinWorkflows(targetSha) {
   return changes;
 }
 
+// ---------------------------------------------------------------------------
+// 2a. Canonical CI-caller-naming advisory (Story #173)
+// ---------------------------------------------------------------------------
+
+/**
+ * Non-blocking advisory: does the consumer's `.github/workflows/` carry the
+ * canonical `ci.yml` / `CI` / `ci` caller triplet documented in
+ * docs/reusable-workflows.md § "Canonical caller naming"? This never mutates
+ * anything — renaming an existing caller file/job id is a deliberate,
+ * atomic per-consumer migration (rename + branch-protection ruleset context
+ * update together), never an automatic sync side-effect. Mirrors the
+ * warn-only posture of `check-required-contexts.mjs`'s naming lint.
+ */
+function checkCiCallerNaming() {
+  const workflowsDir = join(opts.consumer, ".github", "workflows");
+  const files = collectYaml(workflowsDir).map((f) => rel(f));
+  const canonicalPath = files.find((f) => f === ".github/workflows/ci.yml");
+
+  if (!canonicalPath) {
+    return {
+      status: "no-canonical-file",
+      message:
+        `no ".github/workflows/ci.yml" found — the canonical CI caller naming is ` +
+        `file "ci.yml", display name "CI", caller job id "ci" (required context ` +
+        `"ci / ci-required"). See docs/reusable-workflows.md § "Canonical caller naming".`,
+    };
+  }
+
+  const content = readFileSync(join(opts.consumer, canonicalPath), "utf8");
+  const nameMatch = content.match(/^name:\s*(.+?)\s*$/m);
+  const displayName = nameMatch ? nameMatch[1].replace(/^["']|["']$/g, "") : null;
+  const hasCiJob = /^\s{2}ci:\s*$/m.test(content);
+
+  if (displayName === "CI" && hasCiJob) {
+    return { status: "canonical", message: null };
+  }
+
+  const gaps = [];
+  if (displayName !== "CI") gaps.push(`display name is "${displayName ?? "(none)"}" (canonical: "CI")`);
+  if (!hasCiJob) gaps.push(`no "ci" job id found (canonical required context: "ci / ci-required")`);
+
+  return {
+    status: "non-canonical",
+    message: `ci.yml found, but ${gaps.join(" and ")}. See docs/reusable-workflows.md § "Canonical caller naming".`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // 3. Materialize runbook reference stubs (link, don't copy)
 // ---------------------------------------------------------------------------
@@ -300,6 +428,55 @@ function materializeRunbooks() {
   return { created, skipped, localCopies };
 }
 
+// ---------------------------------------------------------------------------
+// 3a. Materialize workflow caller templates (link, don't copy) — Story #175
+// ---------------------------------------------------------------------------
+
+// Every materialized workflow template names itself as a "canonical staging-
+// deploy caller template" in its header comment — used the same way
+// STUB_MARKER is used for runbooks: detect an already-materialized (or
+// operator-filled-in) file so re-runs are idempotent and an operator's own
+// customized caller is never clobbered.
+const WORKFLOW_TEMPLATE_MARKER = "Canonical staging-deploy caller template";
+
+/**
+ * Copy each `templates/workflows/*.yml` into the consumer's
+ * `.github/workflows/`, but only when the destination is ABSENT — mirrors
+ * `materializeRunbooks`'s link-don't-copy / never-clobber semantics. An
+ * existing destination is left untouched; if it doesn't carry the template
+ * marker, it's surfaced as a `localCopy` warning so the operator can
+ * reconcile a hand-authored caller against the canonical template by hand.
+ */
+function materializeWorkflowStubs() {
+  const created = [];
+  const skipped = [];
+  const localCopies = [];
+  if (!existsSync(workflowTemplatesDir)) {
+    return { created, skipped, localCopies };
+  }
+  const destDir = join(opts.consumer, ".github", "workflows");
+  for (const entry of readdirSync(workflowTemplatesDir)) {
+    if (!/\.ya?ml$/.test(entry)) continue;
+    const src = join(workflowTemplatesDir, entry);
+    const dest = join(destDir, entry);
+    if (existsSync(dest)) {
+      const body = readFileSync(dest, "utf8");
+      if (body.includes(WORKFLOW_TEMPLATE_MARKER)) {
+        skipped.push(rel(dest)); // already materialized — idempotent no-op
+      } else {
+        localCopies.push(rel(dest)); // hand-authored caller — 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`
 // ---------------------------------------------------------------------------
@@ -369,6 +546,331 @@ function reconcileTsconfig() {
   return { action: "reconciled", file: rel(path), added: TSCONFIG_BASE };
 }
 
+// ---------------------------------------------------------------------------
+// 5. GitHub-side repo-settings check/apply (Story #171)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fields safe to PATCH automatically. Deliberately excludes nothing today —
+ * every dimension the baseline governs (merge methods, squash source,
+ * auto-merge, delete-branch-on-merge, Actions default token permissions,
+ * Actions PR-approval) is a same-repo settings toggle with no destructive
+ * blast radius, unlike e.g. branch-protection rulesets (out of scope — see
+ * the companion check-ruleset.mjs story) or anything that could strand
+ * in-flight PRs. Kept as an explicit allow-list (not "patch every mismatch")
+ * so a future baseline addition must be deliberately added here before
+ * --apply-settings will touch it.
+ */
+const SETTINGS_PATCHABLE_FIELDS = new Set([
+  "allowSquashMerge",
+  "allowMergeCommit",
+  "allowRebaseMerge",
+  "squashMergeCommitTitle",
+  "squashMergeCommitMessage",
+  "deleteBranchOnMerge",
+  "allowAutoMerge",
+]);
+const SETTINGS_ACTIONS_FIELDS = new Set([
+  "actionsDefaultWorkflowPermissions",
+  "actionsCanApprovePullRequestReviews",
+]);
+
+const REPO_FIELD_TO_API_KEY = {
+  allowSquashMerge: "allow_squash_merge",
+  allowMergeCommit: "allow_merge_commit",
+  allowRebaseMerge: "allow_rebase_merge",
+  squashMergeCommitTitle: "squash_merge_commit_title",
+  squashMergeCommitMessage: "squash_merge_commit_message",
+  deleteBranchOnMerge: "delete_branch_on_merge",
+  allowAutoMerge: "allow_auto_merge",
+};
+const ACTIONS_FIELD_TO_API_KEY = {
+  actionsDefaultWorkflowPermissions: "default_workflow_permissions",
+  actionsCanApprovePullRequestReviews: "can_approve_pull_request_reviews",
+};
+
+function ghApiJson(apiPath) {
+  const raw = execFileSync("gh", ["api", apiPath, "-H", "Accept: application/vnd.github+json"], {
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  return JSON.parse(raw);
+}
+
+function ghApiPatch(apiPath, fields) {
+  const args = ["api", "-X", "PATCH", apiPath, "-H", "Accept: application/vnd.github+json"];
+  for (const [key, value] of Object.entries(fields)) {
+    // -f serializes as a string field; -F lets gh infer type (bool/number)
+    // from the literal, which is what PATCH /repos and the Actions
+    // permissions endpoint both expect for boolean fields.
+    args.push("-F", `${key}=${value}`);
+  }
+  execFileSync("gh", args, { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+}
+
+/** Read a consumer's live settings across both endpoints, mapped to the baseline's camelCase field shape. */
+function fetchLiveSettings(repo) {
+  const repoPayload = ghApiJson(`repos/${repo}`);
+  const actionsPayload = ghApiJson(`repos/${repo}/actions/permissions/workflow`);
+  const live = {};
+  for (const field of SETTINGS_PATCHABLE_FIELDS) live[field] = repoPayload[REPO_FIELD_TO_API_KEY[field]];
+  for (const field of SETTINGS_ACTIONS_FIELDS) live[field] = actionsPayload[ACTIONS_FIELD_TO_API_KEY[field]];
+  return live;
+}
+
+/** Diff `live` against `baseline` for every baseline-declared field. Unknown/extra baseline keys are ignored. */
+function diffSettings(live, baseline) {
+  const mismatches = [];
+  for (const field of [...SETTINGS_PATCHABLE_FIELDS, ...SETTINGS_ACTIONS_FIELDS]) {
+    if (!(field in baseline)) continue;
+    if (live[field] !== baseline[field]) {
+      mismatches.push({ field, expected: baseline[field], actual: live[field] });
+    }
+  }
+  return mismatches;
+}
+
+/**
+ * Apply the drifted fields to the consumer repo via two PATCH calls (one per
+ * endpoint — GitHub does not expose a combined settings write surface).
+ * Never touches a field absent from `mismatches`.
+ */
+function applySettings(repo, mismatches) {
+  const repoPatch = {};
+  const actionsPatch = {};
+  for (const { field, expected } of mismatches) {
+    if (SETTINGS_PATCHABLE_FIELDS.has(field)) repoPatch[REPO_FIELD_TO_API_KEY[field]] = expected;
+    else if (SETTINGS_ACTIONS_FIELDS.has(field)) actionsPatch[ACTIONS_FIELD_TO_API_KEY[field]] = expected;
+  }
+  if (Object.keys(repoPatch).length > 0) ghApiPatch(`repos/${repo}`, repoPatch);
+  if (Object.keys(actionsPatch).length > 0) ghApiPatch(`repos/${repo}/actions/permissions/workflow`, actionsPatch);
+}
+
+function runSettingsMode() {
+  let baseline;
+  try {
+    baseline = JSON.parse(readFileSync(opts.baseline, "utf8"));
+  } catch (err) {
+    fail(`could not read baseline at ${opts.baseline}: ${err.message}`);
+  }
+
+  log(`▶ platform-sync — repo-settings ${opts.applySettings ? "check+apply" : "check"} for ${opts.consumerRepo}`);
+  log("  (non-blocking: drift is reported, never a hard gate — standing decision #10)");
+
+  let live;
+  let mismatches;
+  let error = null;
+  try {
+    live = fetchLiveSettings(opts.consumerRepo);
+    mismatches = diffSettings(live, baseline);
+  } catch (err) {
+    error = err.message;
+    live = null;
+    mismatches = [];
+  }
+
+  let applied = false;
+  if (opts.applySettings && mismatches.length > 0 && !error) {
+    if (opts.dryRun) {
+      log(`  (dry-run: would PATCH ${mismatches.length} field(s) on ${opts.consumerRepo})`);
+    } else {
+      applySettings(opts.consumerRepo, mismatches);
+      applied = true;
+    }
+  }
+
+  log("");
+  if (error) {
+    log(`  ⚠️ error reading ${opts.consumerRepo}: ${error}`);
+  } else if (mismatches.length === 0) {
+    log(`  ✅ ${opts.consumerRepo} matches the repo-settings baseline — no drift.`);
+  } else {
+    log(`  ❌ drift on ${opts.consumerRepo}:`);
+    for (const m of mismatches) {
+      log(`     - ${m.field}: expected ${JSON.stringify(m.expected)}, got ${JSON.stringify(m.actual)}`);
+    }
+    if (applied) log(`  ✅ applied: ${mismatches.length} field(s) patched to match the baseline.`);
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          mode: opts.applySettings ? "apply-settings" : "check-settings",
+          consumerRepo: opts.consumerRepo,
+          baseline,
+          live,
+          drift: mismatches.length > 0,
+          mismatches,
+          applied,
+          dryRun: opts.dryRun,
+          error,
+        },
+        null,
+        2
+      )}\n`
+    );
+  }
+
+  // Report-only by design (standing decision #10): drift never fails this
+  // command's exit code. A hard error reading the consumer IS fatal.
+  if (error) process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// 6. GitHub-side branch-ruleset drift check (Story #178)
+// ---------------------------------------------------------------------------
+//
+// Report-only — deliberately no --apply-ruleset. Unlike the repo-settings
+// toggles above (same-repo settings PATCHes with no destructive blast
+// radius), a branch ruleset governs merge eligibility for every in-flight
+// PR; an automated PATCH here could strand a PR mid-review. This mode only
+// reads and reports (see the companion scripts/check-ruleset.mjs, which
+// this composes with — same contract, same consumer-registry shape, same
+// non-blocking posture).
+
+/** Find the ruleset (from a full per-ruleset detail fetch) targeting refs/heads/<branch>. */
+function findRuleset(rulesets, branch) {
+  const targetRef = `refs/heads/${branch}`;
+  return (
+    rulesets.find((rs) => {
+      if (rs.enforcement !== "active") return false;
+      const include = rs.conditions?.ref_name?.include ?? [];
+      return include.includes(targetRef) || include.includes("~DEFAULT_BRANCH");
+    }) ?? null
+  );
+}
+
+/** Map a full ruleset object's rules[] into the main-protection contract's field shape. */
+function mapRuleset(ruleset) {
+  const rules = Array.isArray(ruleset.rules) ? ruleset.rules : [];
+  const byType = Object.fromEntries(rules.map((r) => [r.type, r]));
+  const statusCheckRule = byType.required_status_checks;
+  const statusChecks = (statusCheckRule?.parameters?.required_status_checks ?? []).map((c) => c.context);
+  const bypassActors = Array.isArray(ruleset.bypass_actors) ? ruleset.bypass_actors : [];
+  return {
+    pullRequestRequired: Boolean(byType.pull_request),
+    bypassActorsEmpty: bypassActors.length === 0,
+    requiredStatusChecks: statusChecks,
+    strictRequiredStatusChecksPolicy: Boolean(statusCheckRule?.parameters?.strict_required_status_checks_policy),
+    allowForcePushes: !byType.non_fast_forward,
+    allowDeletions: !byType.deletion,
+    requireLinearHistory: Boolean(byType.required_linear_history),
+  };
+}
+
+/** Diff a mapped live ruleset against the main-protection contract. */
+function diffRuleset(live, contract) {
+  const mismatches = [];
+  if (contract.requiredStatusChecks !== undefined) {
+    const expected = [...contract.requiredStatusChecks].sort();
+    const actual = [...(live.requiredStatusChecks ?? [])].sort();
+    if (JSON.stringify(expected) !== JSON.stringify(actual)) {
+      mismatches.push({
+        field: "requiredStatusChecks",
+        expected: contract.requiredStatusChecks,
+        actual: live.requiredStatusChecks,
+      });
+    }
+  }
+  if (live.pullRequestRequired !== true) {
+    mismatches.push({ field: "pullRequestRequired", expected: true, actual: live.pullRequestRequired });
+  }
+  if (live.bypassActorsEmpty !== true) {
+    mismatches.push({ field: "bypassActorsEmpty", expected: true, actual: live.bypassActorsEmpty });
+  }
+  if (live.strictRequiredStatusChecksPolicy !== true) {
+    mismatches.push({
+      field: "strictRequiredStatusChecksPolicy",
+      expected: true,
+      actual: live.strictRequiredStatusChecksPolicy,
+    });
+  }
+  for (const [field, expected] of [
+    ["requireLinearHistory", contract.requireLinearHistory],
+    ["allowForcePushes", contract.allowForcePushes],
+    ["allowDeletions", contract.allowDeletions],
+  ]) {
+    if (expected === undefined) continue;
+    if (live[field] !== expected) mismatches.push({ field, expected, actual: live[field] });
+  }
+  return mismatches;
+}
+
+function runRulesetMode() {
+  let contract;
+  try {
+    contract = JSON.parse(readFileSync(opts.contract, "utf8"));
+  } catch (err) {
+    fail(`could not read contract at ${opts.contract}: ${err.message}`);
+  }
+
+  log(`▶ platform-sync — branch-ruleset check for ${opts.consumerRepo}`);
+  log("  (non-blocking: drift is reported, never a hard gate — standing decision #10)");
+  log("  (report-only: this mode never mutates a live ruleset)");
+
+  const branch = contract.branch ?? "main";
+  let live = null;
+  let mismatches = [];
+  let error = null;
+  let status = "current";
+  try {
+    const list = ghApiJson(`repos/${opts.consumerRepo}/rulesets`);
+    const detailed = (Array.isArray(list) ? list : []).map((rs) =>
+      ghApiJson(`repos/${opts.consumerRepo}/rulesets/${rs.id}`)
+    );
+    const ruleset = findRuleset(detailed, branch);
+    if (!ruleset) {
+      status = "missing";
+      error = `no active ruleset targets refs/heads/${branch}`;
+    } else {
+      live = mapRuleset(ruleset);
+      mismatches = diffRuleset(live, contract);
+      status = mismatches.length > 0 ? "drift" : "current";
+    }
+  } catch (err) {
+    error = err.message;
+    status = "error";
+  }
+
+  log("");
+  if (status === "error") {
+    log(`  ⚠️ error reading ${opts.consumerRepo}: ${error}`);
+  } else if (status === "missing") {
+    log(`  ⚠️ ${opts.consumerRepo}: ${error}`);
+  } else if (status === "current") {
+    log(`  ✅ ${opts.consumerRepo} matches the main-protection contract — no drift.`);
+  } else {
+    log(`  ❌ drift on ${opts.consumerRepo}:`);
+    for (const m of mismatches) {
+      log(`     - ${m.field}: expected ${JSON.stringify(m.expected)}, got ${JSON.stringify(m.actual)}`);
+    }
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          mode: "check-ruleset",
+          consumerRepo: opts.consumerRepo,
+          contract,
+          live,
+          drift: status === "drift" || status === "missing",
+          mismatches,
+          status,
+          error,
+        },
+        null,
+        2
+      )}\n`
+    );
+  }
+
+  // Report-only by design (standing decision #10): drift never fails this
+  // command's exit code. A hard error reading the consumer IS fatal.
+  if (status === "error") process.exit(1);
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -382,6 +884,15 @@ function rel(p) {
 // ---------------------------------------------------------------------------
 
 function main() {
+  if (settingsMode) {
+    runSettingsMode();
+    return;
+  }
+  if (rulesetMode) {
+    runRulesetMode();
+    return;
+  }
+
   if (!existsSync(opts.consumer)) {
     fail(`consumer dir not found: ${opts.consumer}`);
   }
@@ -391,13 +902,16 @@ function main() {
   if (opts.dryRun) log("  (dry-run: no files will be written)");
 
   const pins = pinWorkflows(targetSha);
+  const ciNaming = checkCiCallerNaming();
   const runbooks = materializeRunbooks();
+  const workflowStubs = materializeWorkflowStubs();
   const renovate = reconcileRenovate();
   const tsconfig = reconcileTsconfig();
 
   const changed =
     pins.length > 0 ||
     runbooks.created.length > 0 ||
+    workflowStubs.created.length > 0 ||
     renovate.action === "reconciled" ||
     tsconfig.action === "reconciled";
 
@@ -405,6 +919,9 @@ function main() {
   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}`);
+  if (ciNaming.status !== "canonical") {
+    log(`             ⚠ CI caller naming: ${ciNaming.message}`);
+  }
   log(
     `  runbooks:  ${runbooks.created.length} stub(s) ${
       opts.dryRun ? "would be " : ""
@@ -414,6 +931,15 @@ function main() {
   for (const f of runbooks.localCopies) {
     log(`             ⚠ ${f}: full local copy detected — reconcile to a reference stub by hand (§2.2)`);
   }
+  log(
+    `  workflows: ${workflowStubs.created.length} caller template(s) ${
+      opts.dryRun ? "would be " : ""
+    }materialized, ${workflowStubs.skipped.length} already present`
+  );
+  for (const f of workflowStubs.created) log(`             + ${f}`);
+  for (const f of workflowStubs.localCopies) {
+    log(`             ⚠ ${f}: hand-authored caller detected — reconcile against the canonical template by hand`);
+  }
   log(`  renovate:  ${renovate.action}${renovate.file ? ` (${renovate.file})` : ""}`);
   log(`  tsconfig:  ${tsconfig.action}${tsconfig.file ? ` (${tsconfig.file})` : ""}`);
   log("");
@@ -436,7 +962,9 @@ function main() {
           dryRun: opts.dryRun,
           changed,
           pins,
+          ciNaming,
           runbooks,
+          workflowStubs,
           renovate,
           tsconfig,
         },