mandrel-platform 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "engines": {

package/scripts/check-workflow-portability.mjs

@@ -4,15 +4,15 @@
  *
  * Cross-repo portability lint for reusable workflows and composite actions.
  *
- * GitHub validates a reusable workflow's `workflow_call` interface (and a
- * composite action's interface) only when it is *called from another repo* —
- * never when its own repo runs CI on it. That blind spot has shipped four
- * consecutive consumer-facing breakages from this repo (see the #24 → #29 →
- * #30 → #32 chain on the athportal Story #2006 worktree), each a silent
- * "workflow file issue / 0 jobs started" that no in-repo check could catch.
+ * GitHub validates a reusable workflow's / composite action's interface only
+ * when it is *called from another repo* — never when its own repo runs CI on
+ * it. That blind spot has shipped five consecutive consumer-facing breakages
+ * from this repo (the #24 → #29 → #30 → #32 → #35 chain on the athportal /
+ * domio Story worktrees), each a silent "workflow file issue / 0 jobs" or a
+ * "Set up job" load failure that no in-repo check could catch.
  *
- * This lint closes the blind spot by statically asserting the two invariants
- * that GitHub only enforces at cross-repo call time:
+ * This lint closes the blind spot by statically asserting the invariants that
+ * GitHub only enforces at cross-repo call / action-load time:
  *
  *   1. RELATIVE `uses:` PATHS (e.g. `uses: ./.github/actions/foo`) are
  *      PROHIBITED inside a reusable workflow. A cross-repo caller checks out
@@ -24,9 +24,20 @@
  *      input `default:` fields are PROHIBITED. GitHub evaluates these during
  *      interface validation, where contexts like `runner.*` do not yet exist,
  *      so the call fails silently. The SAME footgun applies to composite
- *      `action.yml` input `default:` values — a composite default is never
- *      expression-evaluated, so `${{ }}` is passed through as a literal string.
- *      (Caused #32 / v0.2.4 and #30's setup-toolchain default regression.)
+ *      `action.yml` input `default:` and `description:` values — a composite
+ *      default is never expression-evaluated (passed through as a literal),
+ *      and a `${{ }}` in a composite description throws "Unrecognized
+ *      named-value" at action-load time ("Set up job"). (Caused #32 / #35.)
+ *
+ *   3. INTERNAL SHA PINS must point to a CLEAN manifest. A reusable workflow
+ *      that pins a first-party action by `owner/repo/path@<sha>` is validated
+ *      here against the manifest AT THAT SHA — not just the working-tree copy.
+ *      A pin left lagging on a pre-fix commit re-introduces a footgun the
+ *      working tree already fixed: this is exactly #35, where pr-quality.yml
+ *      kept pinning setup-toolchain@<pre-fix-sha> after the description was
+ *      cleaned in the working tree, so every consumer job died at "Set up
+ *      job". Requires git history (run CI checkout with fetch-depth: 0); the
+ *      check degrades to a skipped NOTE when the pinned blob is unreachable.
  *
  * What this lint deliberately does NOT flag: `${{ }}` in `runs.steps[].with`
  * (e.g. `dest: ${{ inputs['pnpm-dest'] || format('{0}/pnpm', runner.temp) }}`)
@@ -38,6 +49,7 @@
  *   node scripts/check-workflow-portability.mjs
  *   node scripts/check-workflow-portability.mjs --workflows-dir .github/workflows
  *   node scripts/check-workflow-portability.mjs --actions-dir .github/actions
+ *   node scripts/check-workflow-portability.mjs --no-pin-check   # skip Rule 3
  *
  * Exit codes:
  *   0 — every reusable workflow and composite action is cross-repo portable
@@ -45,15 +57,19 @@
  *
  * Consumer adoption:
  *   Copy this script into your project's `scripts/` directory, then wire it
- *   into your CI alongside check-required-contexts.mjs:
+ *   into your CI alongside check-required-contexts.mjs. Use fetch-depth: 0 on
+ *   the checkout so Rule 3 can resolve pinned blobs:
  *
+ *   - uses: actions/checkout@<sha>
+ *     with: { fetch-depth: 0 }
  *   - name: Lint workflow portability
  *     run: node scripts/check-workflow-portability.mjs
  *
  *   It is dependency-free (no YAML parser) so it copies cleanly into any repo.
  */
 
-import { readFileSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { resolve, join, relative, basename } from "node:path";
 
 // ---------------------------------------------------------------------------
@@ -63,15 +79,18 @@ import { resolve, join, relative, basename } from "node:path";
 const args = process.argv.slice(2);
 let workflowsDir = null;
 let actionsDir = null;
+let pinCheck = true;
 
 for (let i = 0; i < args.length; i++) {
   if ((args[i] === "--workflows-dir" || args[i] === "-w") && args[i + 1]) {
     workflowsDir = args[++i];
   } else if ((args[i] === "--actions-dir" || args[i] === "-a") && args[i + 1]) {
     actionsDir = args[++i];
+  } else if (args[i] === "--no-pin-check") {
+    pinCheck = false;
   } else if (args[i] === "--help" || args[i] === "-h") {
     process.stdout.write(
-      "Usage: node scripts/check-workflow-portability.mjs [--workflows-dir <dir>] [--actions-dir <dir>]\n"
+      "Usage: node scripts/check-workflow-portability.mjs [--workflows-dir <dir>] [--actions-dir <dir>] [--no-pin-check]\n"
     );
     process.exit(0);
   }
@@ -170,6 +189,159 @@ function walkYaml(content) {
 
 const EXPR = /\$\{\{/;
 
+// ---------------------------------------------------------------------------
+// Content checks (reused for both working-tree files and pinned blobs)
+// ---------------------------------------------------------------------------
+
+/** Reusable-workflow checks (Rules 1 & 2). Returns [{line, message}]. */
+function checkWorkflowContent(content) {
+  const violations = [];
+  const records = walkYaml(content);
+
+  const isReusable = records.some(
+    (r) => r.path.join(".") === "on.workflow_call" || r.path.join(".").startsWith("on.workflow_call.")
+  );
+  if (!isReusable) return violations;
+
+  // Rule 1: no relative `uses:` anywhere in a reusable workflow.
+  content.split("\n").forEach((raw, idx) => {
+    if (/^\s*uses:\s*['"]?\.\//.test(raw)) {
+      violations.push({
+        line: idx + 1,
+        message:
+          `relative \`uses: ./\` path in a reusable workflow — a cross-repo ` +
+          `caller resolves \`./\` against its own checkout. Use absolute ` +
+          `\`owner/repo/path@ref\` form.`,
+      });
+    }
+  });
+
+  // Rule 2: no `${{ }}` in workflow_call input/secret description or default.
+  for (const r of records) {
+    const p = r.path.join(".");
+    const isInputMeta = /^on\.workflow_call\.inputs\.[^.]+\.(description|default)$/.test(p);
+    const isSecretMeta = /^on\.workflow_call\.secrets\.[^.]+\.description$/.test(p);
+    if ((isInputMeta || isSecretMeta) && EXPR.test(r.value)) {
+      const field = r.path[r.path.length - 1];
+      const name = r.path[r.path.length - 2];
+      violations.push({
+        line: r.lineNo,
+        message:
+          `\`\${{ }}\` expression in workflow_call \`${name}.${field}\` — ` +
+          `GitHub evaluates this during interface validation (where ` +
+          `runner.*/secrets.* do not exist), failing every cross-repo call. ` +
+          `Write it as plain text.`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+/** Composite-action checks (Rules 3/4 of the original; manifest cleanliness). */
+function checkActionContent(content) {
+  const violations = [];
+  const records = walkYaml(content);
+
+  for (const r of records) {
+    const p = r.path.join(".");
+    if (/^inputs\.[^.]+\.(default|description)$/.test(p) && EXPR.test(r.value)) {
+      const field = r.path[r.path.length - 1];
+      const name = r.path[r.path.length - 2];
+      violations.push({
+        line: r.lineNo,
+        message:
+          `\`\${{ }}\` expression in action input \`${name}.${field}\` — ` +
+          `composite ${field}s are not expression-evaluated; \`${field}\` ` +
+          `throws "Unrecognized named-value" at action-load time. Move ` +
+          `runtime expressions into \`runs.steps[].with\`, or write it as ` +
+          `plain text.`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+// ---------------------------------------------------------------------------
+// Internal SHA-pin guard (Rule 3) — validate the PINNED manifest, not just
+// the working tree. Catches a self-reference that lags a fix (e.g. #35).
+// ---------------------------------------------------------------------------
+
+let gitAvailable = null;
+function isGitRepo() {
+  if (gitAvailable !== null) return gitAvailable;
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd: repoRoot,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    gitAvailable = true;
+  } catch {
+    gitAvailable = false;
+  }
+  return gitAvailable;
+}
+
+/** `git show <sha>:<path>` → file content, or null if unreachable. */
+function gitShow(sha, path) {
+  try {
+    return execFileSync("git", ["show", `${sha}:${path}`], {
+      cwd: repoRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 8 * 1024 * 1024,
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collect internal (same-repo, full-SHA-pinned) `uses:` references from a
+ * workflow/action file. "Internal" is detected structurally: the sub-path
+ * after `owner/repo/` exists in the local working tree. External refs
+ * (actions/checkout, pnpm/action-setup, …) resolve to no local path and are
+ * skipped — so the heuristic needs no knowledge of this repo's own slug.
+ */
+function collectInternalPins(content) {
+  const pins = [];
+  content.split("\n").forEach((raw, idx) => {
+    const m = raw.match(
+      /uses:\s*['"]?[\w.-]+\/[\w.-]+\/([^@\s'"]+)@([0-9a-fA-F]{40})/
+    );
+    if (!m) return;
+    const subpath = m[1];
+    const sha = m[2];
+    const local = join(repoRoot, subpath);
+    if (!existsSync(local)) return; // external ref → skip
+    pins.push({ subpath, sha, line: idx + 1 });
+  });
+  return pins;
+}
+
+/** Resolve a pinned ref's manifest path + kind ('action' | 'workflow'). */
+function resolvePinnedManifest(subpath) {
+  const local = join(repoRoot, subpath);
+  let st;
+  try {
+    st = statSync(local);
+  } catch {
+    return null;
+  }
+  if (st.isDirectory()) {
+    for (const name of ["action.yml", "action.yaml"]) {
+      if (existsSync(join(local, name))) return { path: `${subpath}/${name}`, kind: "action" };
+    }
+    return null;
+  }
+  if (/\.ya?ml$/.test(subpath)) {
+    const kind = basename(subpath).startsWith("action.") ? "action" : "workflow";
+    return { path: subpath, kind };
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // File discovery
 // ---------------------------------------------------------------------------
@@ -212,10 +384,11 @@ function listActionFiles(dir) {
 }
 
 // ---------------------------------------------------------------------------
-// Lint rules
+// Per-file lint
 // ---------------------------------------------------------------------------
 
-/** Collect violations for a single file. Returns an array of {line, message}. */
+const pinSkips = [];
+
 function lintFile(filePath) {
   const violations = [];
   let content;
@@ -225,68 +398,38 @@ function lintFile(filePath) {
     return [{ line: 0, message: `cannot read file: ${err.message}` }];
   }
 
-  const records = walkYaml(content);
   const isWorkflow = filePath.startsWith(resolvedWorkflowsDir);
   const isAction =
     basename(filePath) === "action.yml" || basename(filePath) === "action.yaml";
 
-  if (isWorkflow) {
-    const isReusable = records.some(
-      (r) => r.path.join(".") === "on.workflow_call" || r.path.join(".").startsWith("on.workflow_call.")
-    );
-    if (!isReusable) return violations; // ordinary workflow — nothing to enforce
-
-    // Rule 1: no relative `uses:` anywhere in a reusable workflow.
-    content.split("\n").forEach((raw, idx) => {
-      if (/^\s*uses:\s*['"]?\.\//.test(raw)) {
-        violations.push({
-          line: idx + 1,
-          message:
-            `relative \`uses: ./\` path in a reusable workflow — a cross-repo ` +
-            `caller resolves \`./\` against its own checkout. Use absolute ` +
-            `\`owner/repo/path@ref\` form.`,
-        });
-      }
-    });
-
-    // Rule 2: no `${{ }}` in workflow_call input/secret description or default.
-    for (const r of records) {
-      const p = r.path.join(".");
-      const isInputMeta =
-        /^on\.workflow_call\.inputs\.[^.]+\.(description|default)$/.test(p);
-      const isSecretMeta =
-        /^on\.workflow_call\.secrets\.[^.]+\.description$/.test(p);
-      if ((isInputMeta || isSecretMeta) && EXPR.test(r.value)) {
-        const field = r.path[r.path.length - 1];
-        const name = r.path[r.path.length - 2];
-        violations.push({
-          line: r.lineNo,
-          message:
-            `\`\${{ }}\` expression in workflow_call \`${name}.${field}\` — ` +
-            `GitHub evaluates this during interface validation (where ` +
-            `runner.*/secrets.* do not exist), failing every cross-repo call. ` +
-            `Write it as plain text.`,
-        });
+  // Rules 1 & 2 (workflows) and the manifest checks (actions) on the live file.
+  if (isWorkflow) violations.push(...checkWorkflowContent(content));
+  if (isAction) violations.push(...checkActionContent(content));
+
+  // Rule 3: validate internal SHA-pinned references against their pinned blob.
+  if (pinCheck && isGitRepo()) {
+    for (const pin of collectInternalPins(content)) {
+      const manifest = resolvePinnedManifest(pin.subpath);
+      if (!manifest) continue;
+      const pinned = gitShow(pin.sha, manifest.path);
+      if (pinned === null) {
+        pinSkips.push(
+          `${relative(repoRoot, filePath)}:${pin.line} — pinned ${pin.subpath}@${pin.sha.slice(0, 7)} ` +
+          `(blob unreachable; run checkout with fetch-depth: 0 to enable Rule 3)`
+        );
+        continue;
       }
-    }
-  }
-
-  if (isAction) {
-    // Rule 3/4: no `${{ }}` in composite-action input default or description.
-    // A composite default is never expression-evaluated (the literal string is
-    // passed through); a description expression is misleading and needless.
-    for (const r of records) {
-      const p = r.path.join(".");
-      if (/^inputs\.[^.]+\.(default|description)$/.test(p) && EXPR.test(r.value)) {
-        const field = r.path[r.path.length - 1];
-        const name = r.path[r.path.length - 2];
+      const pinnedViolations =
+        manifest.kind === "action"
+          ? checkActionContent(pinned)
+          : checkWorkflowContent(pinned);
+      for (const v of pinnedViolations) {
         violations.push({
-          line: r.lineNo,
+          line: pin.line,
           message:
-            `\`\${{ }}\` expression in action input \`${name}.${field}\` — ` +
-            `composite ${field}s are not expression-evaluated; the literal ` +
-            `string is used as-is. Move runtime expressions into ` +
-            `\`runs.steps[].with\`, or write the ${field} as plain text.`,
+            `internal pin \`${pin.subpath}@${pin.sha.slice(0, 7)}\` points to a ` +
+            `manifest with a portability defect (${manifest.path}:${v.line}) — ` +
+            `${v.message} Bump the pin to a commit whose manifest is clean.`,
         });
       }
     }
@@ -305,7 +448,8 @@ const allFiles = [...workflowFiles, ...actionFiles];
 
 process.stdout.write(
   `[check-workflow-portability] Workflows: ${relative(repoRoot, resolvedWorkflowsDir)}/ (${workflowFiles.length})\n` +
-  `[check-workflow-portability] Actions  : ${relative(repoRoot, resolvedActionsDir)}/ (${actionFiles.length})\n`
+  `[check-workflow-portability] Actions  : ${relative(repoRoot, resolvedActionsDir)}/ (${actionFiles.length})\n` +
+  `[check-workflow-portability] Pin check: ${pinCheck ? (isGitRepo() ? "on" : "on (git unavailable — skipped)") : "off"}\n`
 );
 
 if (allFiles.length === 0) {
@@ -327,6 +471,13 @@ for (const file of allFiles) {
   }
 }
 
+if (pinSkips.length > 0) {
+  process.stdout.write(
+    `\n[check-workflow-portability] ⚠️  ${pinSkips.length} internal pin(s) could not be verified (Rule 3 skipped):\n`
+  );
+  for (const s of pinSkips) process.stdout.write(`     ${s}\n`);
+}
+
 if (total > 0) {
   process.stderr.write(
     `\n[check-workflow-portability] ${total} portability violation${total === 1 ? "" : "s"} detected.\n` +

package/templates/runbooks/README.md

@@ -0,0 +1,42 @@
+# Runbook Templates (copyable thin stubs)
+
+These are **copyable thin-stub templates** — one per canonical mandrel-platform
+runbook in [`docs/runbooks/`](https://github.com/dsj1984/mandrel-platform/tree/main/docs/runbooks).
+They implement the MP-9 adoption model (§7.7 / F1): *replace each duplicated
+process runbook with a thin local doc that holds project-specific values plus a
+link to the canonical runbook.*
+
+Each stub:
+
+- **Links** to its canonical mandrel-platform runbook (the process source of
+  truth — do not re-author the process here).
+- Carries **placeholders** for project-specific values in `<ANGLE_BRACKET>`
+  form (hosts, env names, dashboards, DB engine, worker names, …).
+
+## How to adopt (downstream repo)
+
+1. Copy the stub(s) you need into your project's `docs/runbooks/`:
+   ```bash
+   cp node_modules/mandrel-platform/templates/runbooks/deploy-promotion.md \
+      docs/runbooks/deploy-promotion.md
+   ```
+2. Replace every `<PLACEHOLDER>` with your project's real values.
+3. Fill in the **Project-Specific Notes** section.
+4. Leave the canonical link intact — when the upstream process changes, you only
+   re-read the link, not rewrite the stub.
+
+## Stubs
+
+| Stub | Canonical runbook |
+|------|-------------------|
+| `deploy-promotion.md` | staging → production promotion |
+| `incident-response.md` | severity, escalation, postmortem |
+| `database-backup-restore.md` | backup, PITR, restore/rollback |
+| `observability.md` | logs, Sentry, uptime, metrics |
+| `post-deploy-smoke.md` | boot-smoke gate + diagnosis |
+| `environments-provisioning.md` | env model + provisioning steps |
+| `dependency-update.md` | Renovate, CVE gate, catalog |
+| `branch-protection-setup.md` | aggregator required-check model |
+
+> Placeholder convention: `<UPPER_SNAKE>` between angle brackets. Search for
+> `<` after copying to find everything that still needs a value.

package/templates/runbooks/branch-protection-setup.md

@@ -0,0 +1,45 @@
+# Branch Protection Setup — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical single-aggregator protection model and the
+> `main-protection.json` contract live in the mandrel-platform repo:
+> [`docs/runbooks/branch-protection-setup.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/branch-protection-setup.md).
+> This file only holds **<PROJECT_NAME>-specific check names and reviewers**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Repo (`owner/repo`) | `<OWNER>/<REPO>` |
+| Protected branch | `<PROTECTED_BRANCH>` (e.g. `main`) |
+| Required aggregator check | `<AGGREGATOR_CHECK>` (e.g. `ci-required`) |
+| Protection contract file | `<MAIN_PROTECTION_JSON>` (e.g. `docs/runbooks/main-protection.json`) |
+| Reviewer group(s) | `<REVIEWER_GROUPS>` |
+| GitHub plan | `<GITHUB_PLAN>` (free / pro / team) |
+
+## Apply & Verify
+
+```bash
+# Preview / apply
+node scripts/apply-branch-protection.mjs --dry-run
+node scripts/apply-branch-protection.mjs --apply
+
+# Verify
+gh api repos/<OWNER>/<REPO>/branches/<PROTECTED_BRANCH>/protection \
+  --jq '.required_status_checks.contexts'
+# Expected: ["<AGGREGATOR_CHECK>"]
+```
+
+> **Do not add individual job names as required checks** — only the aggregator.
+
+## Project-Specific Notes
+
+<!-- Ruleset IDs, enforceAdmins rationale, plan-specific constraints. -->
+
+- _TODO: fill in._
+
+---
+
+See also the project's `<MAIN_PROTECTION_JSON>` and the local stubs:
+`dependency-update.md`, `environments-provisioning.md`.

package/templates/runbooks/database-backup-restore.md

@@ -0,0 +1,49 @@
+# Database Backup & Restore — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical backup strategy, PITR procedure, and
+> restore steps live in the mandrel-platform repo:
+> [`docs/runbooks/database-backup-restore.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/database-backup-restore.md).
+> This file only holds **<PROJECT_NAME>-specific database values**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| DB engine | `<DB_ENGINE>` (e.g. Turso/libSQL) |
+| Staging DB name | `<STAGING_DB_NAME>` |
+| Production DB name | `<PRODUCTION_DB_NAME>` |
+| Org / account | `<DB_ORG>` |
+| PITR retention window | `<PITR_WINDOW>` (e.g. 7 days) |
+| Critical tables (integrity check) | `<CRITICAL_TABLE>` |
+| Worker secret for DB URL | `<DATABASE_URL_SECRET>` |
+| Backup verification log | `<BACKUP_VERIFY_LOG_LOCATION>` |
+
+## Restore from Pre-Deploy Snapshot (primary path)
+
+```bash
+SNAPSHOT_BRANCH="<SNAPSHOT_BRANCH>"   # from the deploy workflow run output
+turso db create <PRODUCTION_DB_NAME>-restored \
+  --from-db <PRODUCTION_DB_NAME> --from-branch "$SNAPSHOT_BRANCH"
+turso db shell <PRODUCTION_DB_NAME>-restored "SELECT COUNT(*) FROM <CRITICAL_TABLE>;"
+# Repoint the worker secret and redeploy — see canonical Section 5.
+```
+
+## Manual Backup
+
+```bash
+turso db branch create <PRODUCTION_DB_NAME> backup-$(date +%Y%m%d)
+turso db shell <PRODUCTION_DB_NAME> ".dump" > backup-$(date +%Y%m%d).sql  # store securely
+```
+
+## Project-Specific Notes
+
+<!-- Snapshot cadence, who owns restores, where dumps are archived. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `rollback.md`, `deploy-promotion.md`,
+`incident-response.md`, and the project's `docs/environments.md`.

package/templates/runbooks/dependency-update.md

@@ -0,0 +1,40 @@
+# Dependency Update — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical Renovate model, CVE gate, catalog, and
+> override conventions live in the mandrel-platform repo:
+> [`docs/runbooks/dependency-update.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/dependency-update.md).
+> This file only holds **<PROJECT_NAME>-specific configuration pointers**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Package manager | `<PACKAGE_MANAGER>` (e.g. pnpm) |
+| Renovate config | `<RENOVATE_CONFIG_PATH>` |
+| CVE allowlist location | `<CVE_ALLOWLIST_PATH>` |
+| Audit command | `<AUDIT_COMMAND>` (e.g. `pnpm run audit:check`) |
+| Renovate Dependency Dashboard | `<DASHBOARD_ISSUE_URL>` |
+| Node version pin | `<NODE_VERSION>` (`.nvmrc`) |
+
+## Common Commands
+
+```bash
+# Run the CVE gate locally (what CI sees)
+<AUDIT_COMMAND>
+
+# Out-of-band update
+<PACKAGE_MANAGER> update <package-name>
+```
+
+## Project-Specific Notes
+
+<!-- Renovate preset overrides, grouped packages, manual-merge policies. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `secret-rotation.md`, `incident-response.md`, and
+the project's `docs/environments.md`.

package/templates/runbooks/deploy-promotion.md

@@ -0,0 +1,47 @@
+# Deploy Promotion — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical, process-level procedure lives in the
+> mandrel-platform repo:
+> [`docs/runbooks/deploy-promotion.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/deploy-promotion.md).
+> This file only holds **<PROJECT_NAME>-specific values**. When the process
+> changes, update the canonical runbook upstream — not this stub.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Staging worker name | `<STAGING_WORKER_NAME>` |
+| Production worker name | `<PRODUCTION_WORKER_NAME>` |
+| Staging deploy workflow | `<STAGING_DEPLOY_WORKFLOW>` (e.g. `deploy-staging.yml`) |
+| Production deploy workflow | `<PRODUCTION_DEPLOY_WORKFLOW>` (e.g. `deploy-production.yml`) |
+| Production health URL | `<PRODUCTION_HEALTH_URL>` |
+| Staging health URL | `<STAGING_HEALTH_URL>` |
+| Promotion approvers | `<APPROVER_HANDLES>` |
+| Deploy-window channel | `<DEPLOY_CHANNEL>` |
+
+## Trigger a Production Promotion
+
+```bash
+gh workflow run <PRODUCTION_DEPLOY_WORKFLOW> --ref main --field confirm=true
+```
+
+## Verify
+
+```bash
+curl -sf <PRODUCTION_HEALTH_URL> && echo OK || echo FAIL
+wrangler deployments list --name <PRODUCTION_WORKER_NAME> | head -3
+```
+
+## Project-Specific Notes
+
+<!-- Record any promotion quirks for this project: extra pre-checks, manual
+     migration steps, stakeholder sign-off requirements, etc. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `rollback.md`, `post-deploy-smoke.md`,
+`incident-response.md`, and the project's `docs/environments.md`.

package/templates/runbooks/environments-provisioning.md

@@ -0,0 +1,42 @@
+# Environments Provisioning — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical environment model and step-by-step
+> provisioning procedure live in the mandrel-platform repo:
+> [`docs/runbooks/environments-provisioning.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/environments-provisioning.md).
+> This file only holds **<PROJECT_NAME>-specific IDs and names**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Repo (`owner/repo`) | `<OWNER>/<REPO>` |
+| Cloudflare account ID | `<CF_ACCOUNT_ID>` |
+| Zone / domain | `<ZONE>` |
+| Worker base name | `<WORKER_NAME>` |
+| Staging domain | `<STAGING_DOMAIN>` |
+| Production domain | `<PRODUCTION_DOMAIN>` |
+| Secrets manager project | `<SECRETS_PROJECT_ID>` (e.g. Infisical) |
+| Staging DB name | `<STAGING_DB_NAME>` |
+| Production DB name | `<PRODUCTION_DB_NAME>` |
+
+## Environment Map
+
+| Environment | Branch | Deployed by |
+|-------------|--------|-------------|
+| `local` | any | developer (`wrangler dev`) |
+| `staging` | `main` (auto) | CI/CD after CI-green |
+| `production` | `main` (manual) | `workflow_dispatch` |
+
+## Project-Specific Notes
+
+<!-- Custom domains, reviewer requirements, secret-sync specifics. -->
+
+- _TODO: fill in._
+
+---
+
+The authoritative environment inventory (URLs, secret names, DB names) is the
+project's own `docs/environments.md`. See also the local stubs:
+`branch-protection-setup.md`, `secret-rotation.md`, `deploy-promotion.md`.

package/templates/runbooks/incident-response.md

@@ -0,0 +1,52 @@
+# Incident Response — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical severity model, escalation flow, response
+> steps, and postmortem template live in the mandrel-platform repo:
+> [`docs/runbooks/incident-response.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/incident-response.md).
+> This file only holds **<PROJECT_NAME>-specific contacts and links**.
+
+---
+
+## Escalation Contacts
+
+| Role | Who | Channel |
+|------|-----|---------|
+| First responder / on-call | `<ONCALL_HANDLE>` | `<ONCALL_CHANNEL>` |
+| On-call lead (P1/P2) | `<LEAD_HANDLE>` | `<LEAD_CHANNEL>` |
+| Stakeholder notify (P1) | `<STAKEHOLDER_LIST>` | `<STAKEHOLDER_CHANNEL>` |
+
+## Tooling Links
+
+| Tool | URL |
+|------|-----|
+| Error tracking (Sentry) | `<SENTRY_PROJECT_URL>` |
+| Uptime (Better Stack) | `<BETTERSTACK_URL>` |
+| Status page | `<STATUS_PAGE_URL>` |
+| Incident issue label | `incident`, `severity::P1` … |
+
+## Severity SLAs (from canonical — confirm or override)
+
+| Severity | Target response |
+|----------|-----------------|
+| P1 — Critical | < 15 min |
+| P2 — High | < 1 hour |
+| P3 — Medium | < 4 hours |
+| P4 — Low | next business day |
+
+## First Moves
+
+1. Acknowledge the alert in `<BETTERSTACK_URL>` / `<SENTRY_PROJECT_URL>`.
+2. Open an incident issue (`incident` + `severity::*`).
+3. **Recent deploy? Rollback first** — see `rollback.md`.
+4. Follow the full response steps in the canonical runbook.
+
+## Project-Specific Notes
+
+<!-- Paging procedures, escalation timeouts, known fragile subsystems. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `rollback.md`, `observability.md`,
+`secret-rotation.md`, and the project's `docs/environments.md`.

package/templates/runbooks/observability.md

@@ -0,0 +1,49 @@
+# Observability — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical observability stack, query patterns, and
+> on-call response flow live in the mandrel-platform repo:
+> [`docs/runbooks/observability.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/observability.md).
+> This file only holds **<PROJECT_NAME>-specific endpoints and dataset names**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Worker name(s) | `<WORKER_NAME>` |
+| Cloudflare account ID | `<CF_ACCOUNT_ID>` |
+| Analytics Engine dataset | `<AE_DATASET>` |
+| Sentry dashboard | `<SENTRY_PROJECT_URL>` |
+| Sentry DSN secret | `<SENTRY_DSN_SECRET>` |
+| Better Stack dashboard | `<BETTERSTACK_URL>` |
+| Logpush destination | `<LOGPUSH_DESTINATION>` |
+
+## Quick Commands
+
+```bash
+# Live tail
+wrangler tail --name <WORKER_NAME> --format pretty
+
+# Errors only
+wrangler tail --name <WORKER_NAME> --format json | jq 'select(.outcome != "ok")'
+```
+
+## Alert Thresholds (from canonical — confirm or override)
+
+| Metric | Action threshold |
+|--------|------------------|
+| 5xx rate | > 1% sustained → consider rollback |
+| P99 response time | > 2× baseline → investigate |
+| Uptime probe failing | any failure → page on-call |
+
+## Project-Specific Notes
+
+<!-- Custom dashboards, known noisy alerts, dataset schema notes. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `incident-response.md`, `rollback.md`, `slo.md`,
+and the project's `docs/environments.md`.

package/templates/runbooks/post-deploy-smoke.md

@@ -0,0 +1,39 @@
+# Post-Deploy Smoke — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical smoke contract, failure diagnosis, and
+> auto-rollback behavior live in the mandrel-platform repo:
+> [`docs/runbooks/post-deploy-smoke.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/post-deploy-smoke.md).
+> This file only holds **<PROJECT_NAME>-specific health URLs and parameters**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Staging health URL | `<STAGING_HEALTH_URL>` |
+| Production health URL | `<PRODUCTION_HEALTH_URL>` |
+| Health route | `<HEALTH_ROUTE>` (e.g. `GET /health`) |
+| Smoke script | `<SMOKE_SCRIPT>` (e.g. `./scripts/smoke-deploy.sh`) |
+| Max attempts | `<SMOKE_MAX_ATTEMPTS>` (default 5) |
+| Delay between retries | `<SMOKE_DELAY_SECONDS>` (default 10s) |
+
+## Run the Smoke Manually
+
+```bash
+<SMOKE_SCRIPT> <PRODUCTION_HEALTH_URL> <SMOKE_MAX_ATTEMPTS> <SMOKE_DELAY_SECONDS>
+
+# One-shot check
+curl -sf <PRODUCTION_HEALTH_URL> && echo OK || echo FAIL
+```
+
+## Project-Specific Notes
+
+<!-- Cold-start tuning, non-standard health checks, auth exceptions. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `rollback.md`, `deploy-promotion.md`,
+`observability.md`, and the project's `docs/environments.md`.