mandrel-platform 0.2.1

package/README.md

@@ -0,0 +1,138 @@
+# mandrel-platform
+
+Shared CI/deploy workflows, composite toolchain action, npm config package,
+Renovate preset, and operator runbook templates for the Mandrel platform.
+
+---
+
+## Shared Composite Actions
+
+### `setup-toolchain`
+
+Installs pnpm (version sourced from the consuming repo's `packageManager` field), Node.js (version sourced from `.nvmrc`), and project dependencies via `pnpm install --frozen-lockfile`.
+
+**Reference by SHA** to pin an exact version:
+
+```yaml
+- name: Setup toolchain
+  uses: dsj1984/mandrel-platform/.github/actions/setup-toolchain@<sha>
+  with:
+    cache: 'true'   # omit or pass 'false' on self-hosted runners with a warm pnpm store
+```
+
+**Inputs:**
+
+| Input   | Required | Default | Description                                                                                  |
+| ------- | -------- | ------- | -------------------------------------------------------------------------------------------- |
+| `cache` | No       | `true`  | Enable pnpm store caching via `actions/setup-node`. Pass `false` on self-hosted runners. |
+
+**When to pass `cache: 'false'`:** Self-hosted runners that maintain their own warm pnpm store do not need the `actions/setup-node` pnpm cache layer. Ubuntu runners on `ubuntu-latest` benefit from the default `cache: 'true'`.
+
+---
+
+## Published npm package
+
+The `mandrel-platform` npm package exports shared configuration baselines and
+utility scripts so all consumer repos extend the same SSOT instead of
+hand-syncing copies.
+
+### `tsconfig.base.json`
+
+A strict TypeScript base config — `strict`, `noUncheckedIndexedAccess`,
+`noImplicitOverride`, `verbatimModuleSyntax`, `isolatedModules`,
+`moduleResolution: Bundler`, `target: ES2022` — intended to be extended by
+every consumer.
+
+**Consumer usage (`tsconfig.json`):**
+
+```jsonc
+{
+  "extends": "mandrel-platform/tsconfig.base.json",
+  "compilerOptions": {
+    // repo-specific overrides only
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}
+```
+
+### `biome.base.json`
+
+A Biome base config with the recommended linter rule set, import organizer,
+and standard formatter defaults (2-space indent, 100-char line width).
+
+**Consumer usage (`biome.json`):**
+
+```jsonc
+{
+  "extends": ["mandrel-platform/biome.base.json"],
+  "files": {
+    "ignore": ["dist/", ".wrangler/"]
+  }
+}
+```
+
+### `scripts/audit-check.mjs`
+
+CVE gate script. Runs `pnpm audit --prod` and blocks on any **unsuppressed**
+High or Critical vulnerability in the production dependency graph. This is the
+stricter athportal/swarm-os policy: all unsuppressed High/Critical are
+blocking, not just fixable ones.
+
+Known/accepted CVEs are suppressed via a **dated, self-expiring allowlist**
+(`audit-allowlist.json` in the project root). Expired entries are treated as
+un-suppressed and cause the script to exit non-zero — forcing teams to
+periodically re-evaluate accepted risk.
+
+**Consumer usage (`package.json`):**
+
+```jsonc
+{
+  "scripts": {
+    "audit:check": "node node_modules/mandrel-platform/scripts/audit-check.mjs"
+  }
+}
+```
+
+Or copy the script into your repo's `scripts/` directory when you need
+local customization (and pin a semver range on `mandrel-platform` so drift
+is detected by Renovate).
+
+**Allowlist format (`audit-allowlist.json`):**
+
+```jsonc
+[
+  {
+    "id": "GHSA-xxxx-xxxx-xxxx",
+    "reason": "No fix available; mitigated by X",
+    "expires": "2026-12-31"
+  }
+]
+```
+
+- `id` — GitHub Security Advisory ID (`GHSA-*`) or CVE ID (`CVE-*`).
+- `reason` — Human-readable explanation of why this CVE is accepted.
+- `expires` — ISO 8601 date (`YYYY-MM-DD`). **Required.** Entries whose
+  expiry date is in the past cause the script to exit non-zero.
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Bootstrap agent scaffolding
+pnpm run bootstrap
+```
+
+---
+
+## Package exports
+
+| Export                                | Path                        |
+| ------------------------------------- | --------------------------- |
+| `mandrel-platform/tsconfig.base.json` | `config/tsconfig.base.json` |
+| `mandrel-platform/biome.base.json`    | `config/biome.base.json`    |
+| `mandrel-platform/scripts/*`          | `scripts/*`                 |

package/config/biome.base.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  }
+}

package/config/main-protection.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dsj1984/mandrel-platform/blob/main/config/main-protection.schema.json",
+  "title": "Main Branch Protection Contract",
+  "description": "Defines the required status checks and branch protection settings for the main branch. Validated by scripts/check-required-contexts.mjs to prevent phantom-check drift.",
+  "type": "object",
+  "required": ["branch", "requiredStatusChecks"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference."
+    },
+    "branch": {
+      "type": "string",
+      "description": "The protected branch name.",
+      "default": "main"
+    },
+    "requiredStatusChecks": {
+      "type": "array",
+      "description": "The exact check context names that must pass before a PR can merge. Keep this list as short as possible — ideally one aggregator context (e.g. ci-required).",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "aggregatorJob": {
+      "type": "string",
+      "description": "The workflow job whose result is the single required branch-protection context. Must match the first entry in requiredStatusChecks."
+    },
+    "upstreamJobs": {
+      "type": "array",
+      "description": "The workflow job names that the aggregatorJob depends on. scripts/check-required-contexts.mjs validates these names exist in the workflow files.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "enforceAdmins": {
+      "type": "boolean",
+      "description": "Whether branch protection rules apply to repository administrators.",
+      "default": false
+    },
+    "requireLinearHistory": {
+      "type": "boolean",
+      "description": "Require a linear commit history (no merge commits).",
+      "default": false
+    },
+    "allowForcePushes": {
+      "type": "boolean",
+      "description": "Allow force pushes to the protected branch.",
+      "default": false
+    },
+    "allowDeletions": {
+      "type": "boolean",
+      "description": "Allow the protected branch to be deleted.",
+      "default": false
+    },
+    "_note": {
+      "type": "string",
+      "description": "Human-readable note for maintainers."
+    }
+  }
+}

package/config/renovate.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "description": "Alias — the canonical preset lives at default.json (repo root). Consumers use: github>dsj1984/mandrel-platform.",
+  "extends": ["github>dsj1984/mandrel-platform"]
+}

package/config/tsconfig.base.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "moduleResolution": "Bundler",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true
+  }
+}

package/default.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "description": "Shared Renovate preset for mandrel-platform consumers. Consume as: github>dsj1984/mandrel-platform.",
+  "schedule": ["before 9am on Monday"],
+  "timezone": "America/New_York",
+  "minimumReleaseAge": "3 days",
+  "platformAutomerge": true,
+  "dependencyDashboard": true,
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": ["before 5am on Monday"]
+  },
+  "packageRules": [
+    {
+      "description": "Automerge patch and minor updates",
+      "matchUpdateTypes": ["patch", "minor"],
+      "automerge": true,
+      "automergeType": "pr",
+      "platformAutomerge": true
+    },
+    {
+      "description": "Gate major updates behind dependency-dashboard approval",
+      "matchUpdateTypes": ["major"],
+      "dependencyDashboardApproval": true,
+      "automerge": false
+    },
+    {
+      "description": "Group Astro packages",
+      "matchPackagePatterns": ["^astro$", "^@astrojs/"],
+      "groupName": "Astro packages",
+      "groupSlug": "astro"
+    },
+    {
+      "description": "Group Sentry packages",
+      "matchPackagePatterns": ["^@sentry/"],
+      "groupName": "Sentry packages",
+      "groupSlug": "sentry"
+    },
+    {
+      "description": "Group ESLint packages",
+      "matchPackagePatterns": [
+        "^eslint$",
+        "^@eslint/",
+        "^eslint-config-",
+        "^eslint-plugin-",
+        "^@typescript-eslint/"
+      ],
+      "groupName": "ESLint packages",
+      "groupSlug": "eslint"
+    },
+    {
+      "description": "Group Vitest packages",
+      "matchPackagePatterns": ["^vitest$", "^@vitest/"],
+      "groupName": "Vitest packages",
+      "groupSlug": "vitest"
+    },
+    {
+      "description": "Group Playwright packages",
+      "matchPackagePatterns": ["^playwright$", "^@playwright/"],
+      "groupName": "Playwright packages",
+      "groupSlug": "playwright"
+    },
+    {
+      "description": "Group Cloudflare packages",
+      "matchPackagePatterns": ["^wrangler$", "^@cloudflare/", "^miniflare$"],
+      "groupName": "Cloudflare packages",
+      "groupSlug": "cloudflare"
+    },
+    {
+      "description": "Group Clerk packages",
+      "matchPackagePatterns": ["^@clerk/"],
+      "groupName": "Clerk packages",
+      "groupSlug": "clerk"
+    },
+    {
+      "description": "Keep .nvmrc and engines.node in lockstep — bump both when Node.js advances",
+      "matchManagers": ["nvm"],
+      "matchPackageNames": ["node"],
+      "postUpdateOptions": ["nodeToolchainFile"],
+      "postUpgradeTasks": {
+        "commands": [
+          "node -e \"const fs=require('fs'),path=require('path');const ver=fs.readFileSync('.nvmrc','utf8').trim().replace(/^v/,'');function walk(d){return fs.readdirSync(d,{withFileTypes:true}).flatMap(e=>{const p=path.join(d,e.name);return e.isDirectory()&&e.name!=='node_modules'?walk(p):e.isFile()&&e.name==='package.json'?[p]:[]});}walk('.').forEach(f=>{try{const pkg=JSON.parse(fs.readFileSync(f,'utf8'));if(pkg.engines&&pkg.engines.node){pkg.engines.node=ver;fs.writeFileSync(f,JSON.stringify(pkg,null,2)+'\\n','utf8');console.log('Updated engines.node to '+ver+' in '+f);}}catch(e){}});\""
+        ],
+        "fileFilters": ["**/.nvmrc", "**/package.json"]
+      },
+      "automerge": true,
+      "automergeType": "pr",
+      "platformAutomerge": true
+    },
+    {
+      "description": "Advance wrangler compatibility_date to today when wrangler is bumped",
+      "matchManagers": ["npm"],
+      "matchPackageNames": ["wrangler"],
+      "postUpgradeTasks": {
+        "commands": [
+          "node -e \"const fs=require('fs'),path=require('path');function walk(d){return fs.readdirSync(d,{withFileTypes:true}).flatMap(e=>{const p=path.join(d,e.name);return e.isDirectory()&&e.name!=='node_modules'?walk(p):e.isFile()&&/wrangler\\.(json|jsonc|toml)$/.test(e.name)?[p]:[]});}const today=new Date().toISOString().slice(0,10);walk('.').forEach(f=>{let c=fs.readFileSync(f,'utf8');const u=c.replace(/compatibility_date\\s*=\\s*\\\"[0-9-]+\\\"/g,'compatibility_date = \\\"'+today+'\\\"').replace(/\\\"compatibility_date\\\"\\s*:\\s*\\\"[0-9-]+\\\"/g,'\\\"compatibility_date\\\": \\\"'+today+'\\\"');if(u!==c){fs.writeFileSync(f,u,'utf8');console.log('Updated compatibility_date in '+f);}});\""
+        ],
+        "fileFilters": [
+          "**/wrangler.json",
+          "**/wrangler.jsonc",
+          "**/wrangler.toml"
+        ]
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "mandrel-platform",
+  "version": "0.2.1",
+  "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
+  "license": "MIT",
+  "engines": {
+    "node": "24.16.0",
+    "pnpm": ">=11.5.2"
+  },
+  "exports": {
+    "./tsconfig.base.json": "./config/tsconfig.base.json",
+    "./biome.base.json": "./config/biome.base.json",
+    "./scripts/*": "./scripts/*"
+  },
+  "files": [
+    "config/",
+    "default.json",
+    "scripts/",
+    "templates/"
+  ],
+  "dependencies": {
+    "mandrel": "^1.78.0"
+  },
+  "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)'",
+    "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",
+    "quality:watch": "node .agents/scripts/quality-watch.js"
+  }
+}

package/scripts/audit-check.mjs

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * audit-check.mjs
+ *
+ * CVE gate for the mandrel-platform npm package.
+ *
+ * Policy (athportal/swarm-os stricter variant):
+ *   Block ALL unsuppressed High and Critical vulnerabilities in the
+ *   production dependency graph. A self-expiring allowlist lets teams
+ *   record known, accepted CVEs with a required expiry date — entries
+ *   whose expiry has passed are treated as un-suppressed and will cause
+ *   the script to exit non-zero.
+ *
+ * Usage:
+ *   node scripts/audit-check.mjs
+ *   node scripts/audit-check.mjs --allowlist path/to/allowlist.json
+ *
+ * Exit codes:
+ *   0 — no blocking vulnerabilities (all High/Critical suppressed with
+ *       valid, non-expired allowlist entries, or none found)
+ *   1 — one or more unsuppressed High/Critical CVEs, or expired allowlist
+ *       entries were encountered
+ *
+ * Allowlist format (JSON):
+ *   [
+ *     {
+ *       "id": "GHSA-xxxx-xxxx-xxxx",  // GitHub Advisory ID or CVE ID
+ *       "reason": "No fix available; mitigated by X",
+ *       "expires": "2026-12-31"        // ISO 8601 date — REQUIRED
+ *     }
+ *   ]
+ *
+ * The allowlist file path defaults to `audit-allowlist.json` in the
+ * directory from which this script is invoked (i.e. the project root).
+ * Override with `--allowlist <path>`.
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// ---------------------------------------------------------------------------
+// CLI arg parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+let allowlistPath = null;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--allowlist" && args[i + 1]) {
+    allowlistPath = resolve(process.cwd(), args[i + 1]);
+    i++;
+  }
+}
+
+if (allowlistPath === null) {
+  allowlistPath = resolve(process.cwd(), "audit-allowlist.json");
+}
+
+// ---------------------------------------------------------------------------
+// Allowlist loading and validation
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ id: string; reason: string; expires: string }} AllowlistEntry
+ */
+
+/** @type {AllowlistEntry[]} */
+let allowlist = [];
+
+if (existsSync(allowlistPath)) {
+  try {
+    const raw = readFileSync(allowlistPath, "utf8");
+    const parsed = JSON.parse(raw);
+
+    if (!Array.isArray(parsed)) {
+      console.error(
+        `[audit-check] ERROR: Allowlist at ${allowlistPath} must be a JSON array.`,
+      );
+      process.exit(1);
+    }
+
+    allowlist = parsed;
+  } catch (err) {
+    console.error(
+      `[audit-check] ERROR: Failed to parse allowlist at ${allowlistPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+}
+
+const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+
+/** @type {Set<string>} Active (non-expired) suppressed advisory IDs */
+const suppressed = new Set();
+/** @type {AllowlistEntry[]} */
+const expiredEntries = [];
+
+for (const entry of allowlist) {
+  if (!entry.id || !entry.expires) {
+    console.error(
+      `[audit-check] ERROR: Allowlist entry missing required "id" or "expires" field: ${JSON.stringify(entry)}`,
+    );
+    process.exit(1);
+  }
+
+  if (entry.expires < today) {
+    expiredEntries.push(entry);
+  } else {
+    suppressed.add(entry.id);
+  }
+}
+
+if (expiredEntries.length > 0) {
+  console.error("[audit-check] EXPIRED allowlist entries detected:");
+  for (const entry of expiredEntries) {
+    console.error(
+      `  - ${entry.id} (expired ${entry.expires}): ${entry.reason ?? "no reason recorded"}`,
+    );
+  }
+  console.error(
+    "[audit-check] Renew or remove expired entries to proceed. Exit 1.",
+  );
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Run pnpm audit (production graph only)
+// ---------------------------------------------------------------------------
+
+console.log("[audit-check] Running pnpm audit --prod --json ...");
+
+let auditOutput = "";
+let auditExitCode = 0;
+
+try {
+  auditOutput = execSync("pnpm audit --prod --json 2>/dev/null", {
+    encoding: "utf8",
+  });
+} catch (err) {
+  // pnpm audit exits non-zero when vulnerabilities are found.
+  // We want the JSON regardless of the exit code.
+  const execError = /** @type {{ stdout?: string; status?: number }} */ (err);
+  auditOutput = execError.stdout ?? "";
+  auditExitCode = execError.status ?? 1;
+}
+
+// ---------------------------------------------------------------------------
+// Parse audit JSON
+// ---------------------------------------------------------------------------
+
+/** @type {unknown} */
+let report;
+
+try {
+  report = JSON.parse(auditOutput);
+} catch {
+  if (auditExitCode === 0) {
+    // No JSON means nothing to audit — clean.
+    console.log("[audit-check] No vulnerabilities found. Exit 0.");
+    process.exit(0);
+  }
+  console.error(
+    "[audit-check] ERROR: pnpm audit produced non-JSON output (exit code " +
+      auditExitCode +
+      ").",
+  );
+  console.error(auditOutput.slice(0, 2000));
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Extract advisories
+// ---------------------------------------------------------------------------
+
+/**
+ * pnpm audit --json shape:
+ *   {
+ *     "advisories": {
+ *       "<id>": {
+ *         "ghsa_id": "GHSA-xxxx",
+ *         "cve": ["CVE-xxxx"],
+ *         "severity": "high" | "critical" | "moderate" | "low" | "info",
+ *         "title": "...",
+ *         "url": "...",
+ *         ...
+ *       }
+ *     },
+ *     "metadata": { ... }
+ *   }
+ */
+
+const BLOCKING_SEVERITIES = new Set(["high", "critical"]);
+
+/** @type {Array<{ id: string; severity: string; title: string; url: string }>} */
+const blocking = [];
+
+if (
+  report !== null &&
+  typeof report === "object" &&
+  "advisories" in report &&
+  report.advisories !== null &&
+  typeof report.advisories === "object"
+) {
+  const advisories = /** @type {Record<string, unknown>} */ (
+    report.advisories
+  );
+
+  for (const [, advisory] of Object.entries(advisories)) {
+    if (
+      advisory === null ||
+      typeof advisory !== "object" ||
+      !("severity" in advisory)
+    ) {
+      continue;
+    }
+
+    const adv = /** @type {Record<string, unknown>} */ (advisory);
+    const severity = String(adv["severity"] ?? "").toLowerCase();
+
+    if (!BLOCKING_SEVERITIES.has(severity)) {
+      continue;
+    }
+
+    // Collect all IDs this advisory is known by for allowlist matching.
+    const ghsaId = String(adv["ghsa_id"] ?? "");
+    const cveIds = Array.isArray(adv["cve"])
+      ? adv["cve"].map((c) => String(c))
+      : [];
+    const allIds = [ghsaId, ...cveIds].filter(Boolean);
+
+    const isSuppressed = allIds.some((id) => suppressed.has(id));
+
+    if (!isSuppressed) {
+      blocking.push({
+        id: ghsaId || cveIds[0] || "(unknown)",
+        severity,
+        title: String(adv["title"] ?? "(no title)"),
+        url: String(adv["url"] ?? ""),
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Report and exit
+// ---------------------------------------------------------------------------
+
+if (blocking.length === 0) {
+  console.log(
+    `[audit-check] No unsuppressed High/Critical vulnerabilities in the prod graph. Exit 0.`,
+  );
+  process.exit(0);
+}
+
+console.error(
+  `[audit-check] ${blocking.length} unsuppressed High/Critical CVE(s) found in prod dependency graph:`,
+);
+
+for (const vuln of blocking) {
+  console.error(`  [${vuln.severity.toUpperCase()}] ${vuln.id}: ${vuln.title}`);
+  if (vuln.url) {
+    console.error(`    → ${vuln.url}`);
+  }
+}
+
+console.error(
+  "\n[audit-check] To suppress a known/accepted CVE, add a dated entry to audit-allowlist.json:",
+);
+console.error(
+  JSON.stringify(
+    [
+      {
+        id: blocking[0]?.id ?? "GHSA-xxxx-xxxx-xxxx",
+        reason: "Describe why this is accepted and any mitigations in place",
+        expires: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000)
+          .toISOString()
+          .slice(0, 10),
+      },
+    ],
+    null,
+    2,
+  ),
+);
+
+console.error("\n[audit-check] Exit 1.");
+process.exit(1);

package/scripts/check-docs-staleness.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * check-docs-staleness.mjs
+ *
+ * Flags retired-product references and known staleness patterns in documentation.
+ *
+ * Designed to be run in mandrel-platform consumers as a CI lint step, or from
+ * the mandrel-platform repo itself against its own docs.
+ *
+ * Usage:
+ *   node scripts/check-docs-staleness.mjs [options]
+ *
+ * Options:
+ *   --dir <path>      Directory to scan (default: docs/)
+ *   --warn-only       Exit 0 even when issues are found (print warnings, don't fail CI)
+ *   --quiet           Suppress per-file output; only print summary
+ *   --help            Print this help and exit
+ *
+ * Examples:
+ *   node scripts/check-docs-staleness.mjs
+ *   node scripts/check-docs-staleness.mjs --dir docs/ --warn-only
+ *   node node_modules/mandrel-platform/scripts/check-docs-staleness.mjs --dir docs/
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, extname } from 'node:path';
+import { parseArgs } from 'node:util';
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const { values: argv } = parseArgs({
+  options: {
+    dir: { type: 'string', default: 'docs' },
+    'warn-only': { type: 'boolean', default: false },
+    quiet: { type: 'boolean', default: false },
+    help: { type: 'boolean', default: false },
+  },
+  strict: false,
+});
+
+if (argv.help) {
+  console.log(`
+check-docs-staleness.mjs — docs staleness lint for mandrel-platform consumers
+
+Usage:
+  node scripts/check-docs-staleness.mjs [options]
+
+Options:
+  --dir <path>      Directory to scan (default: docs/)
+  --warn-only       Exit 0 even when issues are found
+  --quiet           Suppress per-file output; only print summary
+  --help            Print this help and exit
+`);
+  process.exit(0);
+}
+
+const SCAN_DIR = argv.dir ?? 'docs';
+const WARN_ONLY = argv['warn-only'] ?? false;
+const QUIET = argv.quiet ?? false;
+
+// ---------------------------------------------------------------------------
+// Staleness patterns
+//
+// Each rule has:
+//   id          — unique identifier (used in suppression comments)
+//   description — human-readable explanation shown in lint output
+//   pattern     — regex to search for in file content
+//   severity    — 'error' | 'warning'
+//   fileGlob    — optional: only apply to files matching this regex
+//
+// Suppression: add `<!-- staleness-ignore: <id> -->` on the line above the
+// flagged text to suppress a specific rule for that occurrence.
+// ---------------------------------------------------------------------------
+
+const RULES = [
+  {
+    id: 'pages-deploy-command',
+    description: 'References `wrangler pages deploy` — may be stale if the project has migrated web to a Worker',
+    pattern: /wrangler pages deploy/g,
+    severity: 'error',
+  },
+  {
+    id: 'pages-dev-url',
+    description: 'References `*.pages.dev` URL — may be stale if the project has migrated off Cloudflare Pages',
+    pattern: /[a-z0-9-]+\.pages\.dev/g,
+    severity: 'error',
+  },
+  {
+    id: 'pages-dashboard-link',
+    description: 'References the Cloudflare Pages dashboard (`dash.cloudflare.com/pages`) — may be stale after Worker migration',
+    pattern: /dash\.cloudflare\.com\/[a-z0-9]+\/pages/g,
+    severity: 'error',
+  },
+  {
+    id: 'pages-rollback',
+    description: 'References `wrangler pages deployment rollback` — may be stale if the project has migrated web to a Worker',
+    pattern: /wrangler pages deployment rollback/g,
+    severity: 'warning',
+  },
+  {
+    id: 'hardcoded-worker-name',
+    description: 'Possible hardcoded project-specific worker name in a common runbook (expected only in project-local docs)',
+    // Detects patterns like `my-app-staging` or `my-app-production` but not generic `<worker-name>`
+    pattern: /--name\s+[a-z][a-z0-9-]+-(staging|production)\b(?!\s*>)/g,
+    severity: 'warning',
+    fileGlob: /docs\/runbooks\//,
+  },
+  {
+    id: 'hardcoded-url',
+    description: 'Possible hardcoded non-placeholder URL (use `<PLACEHOLDER>` style in common runbooks)',
+    // Detects https:// URLs that are not placeholders (< >) and not github.com/cloudflare docs links
+    pattern: /https:\/\/(?!github\.com|docs\.cloudflare\.com|api\.cloudflare\.com|uptime\.betterstack\.com)[a-z0-9][a-z0-9.-]+\.[a-z]{2,}\/[^\s)"'>]*/g,
+    severity: 'warning',
+    fileGlob: /docs\/runbooks\//,
+  },
+  {
+    id: 'stale-github-runbooks-ref',
+    description: 'References `.github/RUNBOOKS/` — this is the stale duplicate directory pattern; canonical runbooks live in `docs/runbooks/`',
+    pattern: /\.github\/RUNBOOKS\//g,
+    severity: 'error',
+  },
+  {
+    id: 'quality-yml-ref',
+    description: 'References `quality.yml` — verify this file exists in the project (swarm-os ships `ci.yml` instead)',
+    pattern: /quality\.yml/g,
+    severity: 'warning',
+  },
+  {
+    id: 'expired-placeholder',
+    description: 'Placeholder date that has passed (YYYY-MM-DD pattern in an expiry/todo context)',
+    // Matches explicit expiry dates like "expires: 2025-01-01" that are in the past
+    pattern: /expires[:\s]+202[0-4]-\d{2}-\d{2}/gi,
+    severity: 'error',
+  },
+];
+
+// ---------------------------------------------------------------------------
+// File walker
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively collect all .md and .json files under dir.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walkDir(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      if (entry === 'node_modules' || entry === '.git') continue;
+      results.push(...walkDir(fullPath));
+    } else if (['.md', '.json'].includes(extname(entry))) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Lint a single file
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ file: string, line: number, rule: typeof RULES[0], match: string }} Finding
+ */
+
+/**
+ * Lint a file against all rules.
+ * @param {string} filePath
+ * @returns {Finding[]}
+ */
+function lintFile(filePath) {
+  const findings = [];
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8');
+  } catch {
+    return findings;
+  }
+
+  const lines = content.split('\n');
+
+  for (const rule of RULES) {
+    // Skip if this rule has a fileGlob and the file doesn't match
+    if (rule.fileGlob && !rule.fileGlob.test(filePath)) continue;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const prevLine = i > 0 ? lines[i - 1] : '';
+
+      // Check for suppression comment on the preceding line
+      if (prevLine.includes(`staleness-ignore: ${rule.id}`)) continue;
+
+      // Reset regex state for global patterns
+      rule.pattern.lastIndex = 0;
+      let match;
+      while ((match = rule.pattern.exec(line)) !== null) {
+        findings.push({
+          file: filePath,
+          line: i + 1,
+          rule,
+          match: match[0],
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const files = walkDir(SCAN_DIR);
+
+if (files.length === 0) {
+  console.log(`[docs-staleness] No files found under '${SCAN_DIR}' — nothing to check.`);
+  process.exit(0);
+}
+
+/** @type {Finding[]} */
+const allFindings = [];
+
+for (const file of files) {
+  const findings = lintFile(file);
+  allFindings.push(...findings);
+}
+
+// Group findings by file for readable output
+const byFile = new Map();
+for (const finding of allFindings) {
+  const key = finding.file;
+  if (!byFile.has(key)) byFile.set(key, []);
+  byFile.get(key).push(finding);
+}
+
+const errors = allFindings.filter((f) => f.rule.severity === 'error');
+const warnings = allFindings.filter((f) => f.rule.severity === 'warning');
+
+if (!QUIET) {
+  for (const [file, findings] of byFile.entries()) {
+    const relPath = relative(process.cwd(), file);
+    for (const f of findings) {
+      const sev = f.rule.severity === 'error' ? 'ERR ' : 'WARN';
+      console.log(`[${sev}] ${relPath}:${f.line} — ${f.rule.id}: ${f.rule.description}`);
+      console.log(`       matched: ${JSON.stringify(f.match)}`);
+    }
+  }
+}
+
+console.log(
+  `\n[docs-staleness] Scanned ${files.length} file(s). ` +
+  `Found ${errors.length} error(s), ${warnings.length} warning(s).`,
+);
+
+if (allFindings.length > 0) {
+  console.log(`\nTo suppress a specific rule occurrence, add this comment on the line above:`);
+  console.log(`  <!-- staleness-ignore: <rule-id> -->`);
+  console.log(`\nAvailable rule IDs: ${RULES.map((r) => r.id).join(', ')}`);
+}
+
+if (errors.length > 0 && !WARN_ONLY) {
+  process.exit(1);
+}
+
+process.exit(0);

package/scripts/check-required-contexts.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * check-required-contexts.mjs
+ *
+ * Branch-protection context lint for mandrel-platform consumers.
+ *
+ * Reads `docs/runbooks/main-protection.json` and asserts that every context
+ * listed in `requiredStatusChecks` — and every job listed in `upstreamJobs` —
+ * is actually emitted by a job in the `.github/workflows/` directory.
+ *
+ * This prevents the "phantom required check" failure mode where a check is
+ * registered in branch protection but no CI job ever reports it, leaving
+ * every PR blocked indefinitely on a `pending` status that never resolves.
+ *
+ * Usage:
+ *   node scripts/check-required-contexts.mjs
+ *   node scripts/check-required-contexts.mjs --contract path/to/main-protection.json
+ *   node scripts/check-required-contexts.mjs --workflows-dir .github/workflows
+ *
+ * Exit codes:
+ *   0 — all required contexts are emitted by at least one workflow job
+ *   1 — one or more phantom contexts detected (named in stderr)
+ *
+ * Consumer adoption:
+ *   Copy this script into your project's `scripts/` directory, then wire it
+ *   into your PR-quality workflow:
+ *
+ *   - name: Lint branch-protection contract
+ *     run: node scripts/check-required-contexts.mjs
+ *
+ *   Keep `docs/runbooks/main-protection.json` up to date whenever you add,
+ *   rename, or remove workflow jobs so the lint stays accurate.
+ */
+
+import { readFileSync, readdirSync } from "node:fs";
+import { resolve, join, relative } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+let contractPath = null;
+let workflowsDir = null;
+
+for (let i = 0; i < args.length; i++) {
+  if ((args[i] === "--contract" || args[i] === "-c") && args[i + 1]) {
+    contractPath = args[++i];
+  } else if ((args[i] === "--workflows-dir" || args[i] === "-w") && args[i + 1]) {
+    workflowsDir = args[++i];
+  } else if (args[i] === "--help" || args[i] === "-h") {
+    process.stdout.write(
+      "Usage: node scripts/check-required-contexts.mjs [--contract <path>] [--workflows-dir <dir>]\n"
+    );
+    process.exit(0);
+  }
+}
+
+// Resolve paths relative to the repo root (cwd when invoked from CI or locally).
+const repoRoot = process.cwd();
+const resolvedContract = contractPath
+  ? resolve(contractPath)
+  : resolve(repoRoot, "docs/runbooks/main-protection.json");
+const resolvedWorkflowsDir = workflowsDir
+  ? resolve(workflowsDir)
+  : resolve(repoRoot, ".github/workflows");
+
+// ---------------------------------------------------------------------------
+// Load contract
+// ---------------------------------------------------------------------------
+
+let contract;
+try {
+  const raw = readFileSync(resolvedContract, "utf8");
+  contract = JSON.parse(raw);
+} catch (err) {
+  process.stderr.write(
+    `[check-required-contexts] ERROR: Cannot read contract at ${relative(repoRoot, resolvedContract)}: ${err.message}\n`
+  );
+  process.exit(1);
+}
+
+const requiredContexts = Array.isArray(contract.requiredStatusChecks)
+  ? contract.requiredStatusChecks
+  : [];
+const upstreamJobs = Array.isArray(contract.upstreamJobs)
+  ? contract.upstreamJobs
+  : [];
+
+if (requiredContexts.length === 0) {
+  process.stderr.write(
+    "[check-required-contexts] ERROR: contract.requiredStatusChecks is empty — at least one context is required.\n"
+  );
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Collect job names from all workflow files
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract all job IDs from a YAML workflow file using a simple line-by-line
+ * parser. We intentionally avoid a full YAML parser to keep this script
+ * dependency-free — the job ID pattern is stable enough to parse with a regex.
+ *
+ * GitHub Actions job IDs appear as top-level keys under the `jobs:` map:
+ *
+ *   jobs:
+ *     lint:         ← job ID = "lint"
+ *       name: Lint & format
+ *       ...
+ *     ci-required:  ← job ID = "ci-required"
+ *       ...
+ *
+ * The job ID line is indented by exactly 2 spaces and ends with a colon.
+ */
+function extractJobIds(yamlContent) {
+  const ids = new Set();
+  let inJobsBlock = false;
+
+  for (const line of yamlContent.split("\n")) {
+    // Detect the `jobs:` top-level key (zero indentation).
+    if (/^jobs:\s*$/.test(line)) {
+      inJobsBlock = true;
+      continue;
+    }
+
+    if (!inJobsBlock) continue;
+
+    // A top-level key at zero indentation that is NOT `jobs:` ends the block.
+    if (/^[a-zA-Z0-9_-]/.test(line) && !/^jobs:\s*$/.test(line)) {
+      inJobsBlock = false;
+      continue;
+    }
+
+    // Job ID lines: exactly 2-space indent, identifier, colon, optional spaces.
+    const jobMatch = line.match(/^  ([a-zA-Z0-9_-]+):\s*$/);
+    if (jobMatch) {
+      ids.add(jobMatch[1]);
+    }
+  }
+
+  return ids;
+}
+
+let workflowFiles;
+try {
+  workflowFiles = readdirSync(resolvedWorkflowsDir).filter(
+    (f) => f.endsWith(".yml") || f.endsWith(".yaml")
+  );
+} catch (err) {
+  process.stderr.write(
+    `[check-required-contexts] ERROR: Cannot read workflows directory at ${relative(repoRoot, resolvedWorkflowsDir)}: ${err.message}\n`
+  );
+  process.exit(1);
+}
+
+if (workflowFiles.length === 0) {
+  process.stderr.write(
+    `[check-required-contexts] ERROR: No workflow files found in ${relative(repoRoot, resolvedWorkflowsDir)}\n`
+  );
+  process.exit(1);
+}
+
+/** Map from workflow filename → Set<jobId> */
+const workflowJobMap = new Map();
+/** Flat set of all job IDs across all workflows */
+const allJobIds = new Set();
+
+for (const file of workflowFiles) {
+  const filePath = join(resolvedWorkflowsDir, file);
+  let content;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch (err) {
+    process.stderr.write(
+      `[check-required-contexts] WARN: Cannot read ${file}: ${err.message} — skipping.\n`
+    );
+    continue;
+  }
+  const ids = extractJobIds(content);
+  workflowJobMap.set(file, ids);
+  for (const id of ids) {
+    allJobIds.add(id);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Validate required contexts
+// ---------------------------------------------------------------------------
+
+const phantomContexts = requiredContexts.filter((ctx) => !allJobIds.has(ctx));
+const phantomUpstream = upstreamJobs.filter((job) => !allJobIds.has(job));
+
+// ---------------------------------------------------------------------------
+// Report
+// ---------------------------------------------------------------------------
+
+const contractRel = relative(repoRoot, resolvedContract);
+const workflowsRel = relative(repoRoot, resolvedWorkflowsDir);
+
+process.stdout.write(
+  `[check-required-contexts] Contract : ${contractRel}\n` +
+  `[check-required-contexts] Workflows: ${workflowsRel}/ (${workflowFiles.length} file${workflowFiles.length === 1 ? "" : "s"})\n` +
+  `[check-required-contexts] Emitted job IDs: ${[...allJobIds].sort().join(", ")}\n`
+);
+
+if (phantomContexts.length > 0) {
+  process.stderr.write(
+    `\n[check-required-contexts] ❌ PHANTOM required contexts detected!\n` +
+    `   These contexts are listed in requiredStatusChecks but no workflow job emits them:\n`
+  );
+  for (const ctx of phantomContexts) {
+    process.stderr.write(`     • "${ctx}"\n`);
+  }
+  process.stderr.write(
+    `\n   A phantom context will block every PR indefinitely on a "pending" status\n` +
+    `   that never resolves. Fix: either add a workflow job with this exact ID,\n` +
+    `   or remove the context from requiredStatusChecks in ${contractRel}.\n\n`
+  );
+}
+
+if (phantomUpstream.length > 0) {
+  process.stderr.write(
+    `\n[check-required-contexts] ❌ PHANTOM upstream jobs detected!\n` +
+    `   These jobs are listed in upstreamJobs but no workflow defines them:\n`
+  );
+  for (const job of phantomUpstream) {
+    process.stderr.write(`     • "${job}"\n`);
+  }
+  process.stderr.write(
+    `\n   Fix: either add the missing job to a workflow, or remove it from\n` +
+    `   upstreamJobs in ${contractRel}.\n\n`
+  );
+}
+
+const hasError = phantomContexts.length > 0 || phantomUpstream.length > 0;
+
+if (!hasError) {
+  process.stdout.write(
+    `[check-required-contexts] ✅ All required contexts and upstream jobs are emitted by CI.\n` +
+    `   requiredStatusChecks : ${requiredContexts.join(", ")}\n` +
+    `   upstreamJobs         : ${upstreamJobs.length > 0 ? upstreamJobs.join(", ") : "(none listed)"}\n`
+  );
+}
+
+process.exit(hasError ? 1 : 0);