mandrel-platform 0.17.2 → 0.18.0

package/README.md

@@ -1,7 +1,34 @@
 # mandrel-platform
 
-Shared CI/deploy workflows, composite toolchain action, npm config package,
-Renovate preset, and operator runbook templates for the Mandrel platform.
+The **single source of truth (SSOT)** for CI/CD, security, and configuration
+across the Mandrel fleet. A consumer repo adopts this platform once and inherits
+a converged, hardened baseline — reusable GitHub Actions workflows, a composite
+toolchain action, importable config bases, guardrail scripts, edge-security
+middleware, a Renovate preset, and operator runbook templates — instead of
+hand-maintaining its own copies and drifting apart over time.
+
+## What's in scope
+
+| Pillar | What it provides |
+| ------ | ---------------- |
+| **Reusable workflows** | `workflow_call` CI, deploy, secret-scan, release, and CodeQL pipelines, consumed by tag/SHA pin. |
+| **Composite action** | `setup-toolchain` — pnpm + Node + frozen install in one step. |
+| **Config bases (npm)** | `extends`-able baselines: TypeScript, Biome, Knip, Stryker, commitlint, dependency-cruiser, size-limit, Lighthouse. |
+| **Edge-security middleware (npm)** | Per-env closed-allowlist CORS, security headers, and app-layer rate limiting for Astro + Hono. |
+| **Guardrail scripts (npm)** | Dependency-free policy checks: CVE gate, action-pin ratchet, coverage floor, destructive-migration guard, workflow-portability, required-contexts, docs-staleness. |
+| **Renovate preset** | Shared dependency-update policy, including auto-bumping this repo's own `uses:` pins. |
+| **Supply-chain config** | pnpm-native hardening fragment (`blockExoticSubdeps`, `trustPolicy`, 7-day `minimumReleaseAge`). |
+| **Adoption & drift control** | `platform-sync` (adopt/repair) plus a scheduled cross-consumer pin-drift dashboard and auto-repair-PR loop. |
+| **Runbook templates** | Copyable thin-stub operator runbooks that link back to the canonical process docs. |
+
+**Out of scope.** mandrel-platform is not an application and ships no runtime
+service — it deploys nothing of its own beyond its release train. Consumers keep
+every project-specific knob (entrypoints, budgets, score floors, deploy targets)
+local: the platform sets the floor, the consumer sets the ceiling. The `.agents/`
+tree in this repo is the Mandrel agent framework used to *develop* the platform
+(sourced from the separate `mandrel` CLI) — it is dev-time only and is **not**
+part of the published npm package, whose `files` allowlist ships only `config/`,
+`default.json`, `scripts/`, and `templates/`.
 
 **Docs:** [reusable-workflows.md](docs/reusable-workflows.md) (the `workflow_call`
 contract) · [decisions.md](docs/decisions.md) (decision log). Status, the
@@ -11,15 +38,24 @@ consumer convergence matrix, and the forward roadmap are tracked privately.
 
 ## Reusable workflows
 
-The shared `workflow_call` workflows — `pr-quality.yml` and
-`deploy-cloudflare.yml` (plus `secret-scan-push.yml`, `release-automation.yml`,
-`codeql.yml`, and `smoke-dispatch.yml`) — and their public input/secret
-contract are documented in
-**[docs/reusable-workflows.md](docs/reusable-workflows.md)**. Consumers should
-configure their callers from that reference (input types, defaults,
-when-to-override, the frozen `{CLOUDFLARE_*, TURSO_*}` deploy secret allowlist,
-the single `ci-required` aggregator context, and the pin-by-tag/SHA versioning
-model).
+Five workflows expose a stable `workflow_call` contract and are consumed by
+tag/SHA pin. Configure your callers from
+**[docs/reusable-workflows.md](docs/reusable-workflows.md)** — the authoritative
+reference for input types, defaults, when-to-override, the frozen
+`{CLOUDFLARE_*, TURSO_*}` deploy-secret allowlist, the single `ci-required`
+aggregator context, and the pin-by-tag/SHA versioning model.
+
+| Workflow | Purpose |
+| -------- | ------- |
+| [`pr-quality.yml`](docs/reusable-workflows.md#pr-qualityyml) | Tiered PR gate — lint/format → typecheck → unit → contract → e2e/smoke → migration-guard → security → osv-scan, each tier independently toggled, behind one `ci-required` aggregator. |
+| [`deploy-cloudflare.yml`](docs/reusable-workflows.md#deploy-cloudflareyml) | Defence-in-depth Cloudflare deploy with a frozen deploy-secret allowlist. |
+| [`secret-scan-push.yml`](docs/reusable-workflows.md#secret-scan-pushyml) | Full-history gitleaks secret scan on push to the default branch. |
+| [`release-automation.yml`](docs/reusable-workflows.md#release-automationyml) | Conventional-commit release lifecycle (version bump + `CHANGELOG.md` + tag) via release-please. |
+| [`codeql.yml`](docs/reusable-workflows.md#codeqlyml) | CodeQL SAST analysis — dual-mode: runs on this repo's push/PR/schedule **and** is `workflow_call`-consumable. |
+
+> `smoke-dispatch.yml` is a **platform-internal** cross-repo smoke trigger
+> (`push` / `workflow_dispatch`, not `workflow_call`). It appears in the
+> reference for completeness but is not part of the consumer caller surface.
 
 `release-automation.yml` extends the platform from CI/deploy into the **full
 release lifecycle**: a thin caller gets conventional-commit-driven version
@@ -147,6 +183,30 @@ mutate set (`stryker.config.json`):
 }
 ```
 
+#### `commitlint.base.mjs`
+
+Single-sources the conventional-commit **type-enum** — the eleven types
+(`feat`, `fix`, `perf`, `refactor`, `revert`, `docs`, `style`, `chore`,
+`test`, `build`, `ci`) documented in
+[`.agents/rules/git-conventions.md`](.agents/rules/git-conventions.md) — so
+consumers stop hand-copying the list into their own
+`commitlint.config.js`. Extends `@commitlint/config-conventional` for
+everything else (header casing/length, body/footer blank-line rules) and
+narrows `type-enum` to the fleet list. commitlint supports a native
+`extends`, so a consumer's local config reduces to the extend plus any
+repo-specific scope enforcement (`commitlint.config.js`):
+
+```js
+export default {
+  extends: ["mandrel-platform/commitlint.base.mjs"],
+  // repo-specific scope-enum, etc. — optional
+};
+```
+
+Keep this base's `type-enum`, the git-conventions.md prose list, and
+`release-please-config.json`'s `changelog-sections` in sync when adding a
+type — all three must agree.
+
 #### `dependency-cruiser.base.json`
 
 Shared dependency-cruiser rule set (no-circular, no-orphans,
@@ -362,6 +422,78 @@ is detected by Renovate).
 
 ---
 
+### Guardrail & policy-check scripts
+
+Beyond the CVE gate, the package ships a set of **dependency-free guardrail
+lints** (`node`-only, nothing to install) that enforce cross-repo CI and
+security invariants. Several are already wired into the reusable workflows, so a
+consumer that adopts those inherits the check for free; each is also runnable
+standalone (`node node_modules/mandrel-platform/scripts/<name>.mjs`) or copyable
+into a repo's own `scripts/`.
+
+| Script | Enforces | Wired into |
+| ------ | -------- | ---------- |
+| `check-coverage-threshold.mjs` | Coverage floor (lines/statements/functions/branches) read from `coverage-summary.json`; threshold `0` disables the gate. | `pr-quality.yml` (unit tier) |
+| `check-destructive-migration.mjs` | Blocks `DROP` / `TRUNCATE` / `ALTER … DROP` (and Drizzle `.dropTable()`) in migration files unless a reviewer applies the override label. | `pr-quality.yml` (migration-guard tier, opt-in) |
+| `check-workflow-portability.mjs` | Catches cross-repo footguns in reusable workflows / composite actions: relative `uses:` paths, `${{ }}` in `workflow_call` input metadata, and lagging first-party pins. | `pr-quality.yml` + `ci.yml` |
+| `check-action-pins.mjs` | Ratchet requiring every third-party Action to be pinned to a full 40-char commit SHA (tag-swap defence); local and first-party refs are exempt. | `ci.yml` |
+| `check-required-contexts.mjs` | Validates that every branch-protection required check in `main-protection.json` maps to a real CI job — no phantom required checks. Also **warns** (never blocks) when the caller file / display `name:` / caller job id diverge from the canonical `ci.yml` / `CI` / `ci` triplet ([details](docs/reusable-workflows.md#canonical-caller-naming-the-ciyml--ci--ci-triplet)). | `ci.yml` |
+| `check-docs-staleness.mjs` | Lints markdown/JSON docs for known staleness patterns (stale URLs, expired dates, dead runbook paths); suppressible per-rule. | standalone |
+| `check-repo-settings.mjs` | Cross-consumer dashboard for the GitHub-side repo-settings baseline (merge methods, squash source, auto-merge, Actions default token permissions, PR-approval-by-Actions) — see below. | standalone / `platform-sync --check-settings` |
+
+> **`config/main-protection.schema.json`** is the JSON Schema for the
+> branch-protection contract (`docs/runbooks/main-protection.json`) — required
+> status checks, the aggregator job, upstream jobs, and enforcement flags.
+> `check-required-contexts.mjs` validates the contract against the actual
+> workflow job graph; see the
+> [branch-protection runbook](docs/runbooks/branch-protection-setup.md).
+
+> **`config/repo-settings.schema.json`** is the JSON Schema for the
+> repo-settings baseline contract (`docs/runbooks/repo-settings.json`),
+> sibling to `main-protection.schema.json` — merge methods, squash-commit
+> source, auto-merge/delete-branch-on-merge, Actions default workflow token
+> permissions, and whether Actions can approve pull requests. Fleet baseline
+> decided 2026-07-01 (see `docs/decisions.md`): squash-only merges, squash
+> source `PR_TITLE`/`PR_BODY`, auto-merge + delete-branch-on-merge on, Actions
+> default token permissions `read`, `can_approve_pull_request_reviews` off.
+>
+> **Because `squashMergeCommitMessage` is `PR_BODY`, PR templates must stay
+> commit-body-safe.** The PR description becomes the literal squash-commit
+> body on `main`, which `release-please` and `commitlint` then parse — a
+> template that injects checklist boilerplate, HTML comments, or
+> non-conventional-commit prose into that body will land in commit history and
+> can break changelog generation or commitlint's body rules. Keep PR templates
+> to short, commit-message-safe prose, or put checklists in sections authors
+> delete before merge.
+>
+> **Check + apply.** `scripts/check-repo-settings.mjs` is the GitHub-side
+> drift dashboard (mirrors `check-pin-drift.mjs`'s shape: data-driven consumer
+> registry — reuses `scripts/pin-drift-consumers.json` — injectable `gh`
+> runner, `--json`/`--strict`). `scripts/platform-sync.mjs` gained a
+> settings mode for the per-consumer check/apply flow:
+>
+> ```bash
+> # Report drift for one consumer against the baseline — never mutates, never
+> # fails the exit code unless the read itself errors (standing decision #10).
+> node scripts/platform-sync.mjs --check-settings --consumer-repo dsj1984/domio
+>
+> # Same read, then PATCH the drifted fields to match the baseline.
+> node scripts/platform-sync.mjs --apply-settings --consumer-repo dsj1984/domio
+>
+> # Preview what --apply-settings would PATCH without mutating anything.
+> node scripts/platform-sync.mjs --apply-settings --dry-run --consumer-repo dsj1984/domio
+> ```
+>
+> Both commands accept `--baseline <path>` (default:
+> `docs/runbooks/repo-settings.json`) and `--json` for a machine-readable
+> envelope. **Non-blocking by design** (standing decision #10, same posture as
+> the pin-drift dashboard and `check-ruleset.mjs`): drift is reported, not a
+> hard gate — it never fails CI on a consumer's `main`. Branch-protection
+> ruleset drift is out of scope here (see the companion `check-ruleset.mjs`
+> story); this contract covers repo-settings only.
+
+---
+
 ## Renovate preset
 
 The shared Renovate preset (`default.json`, also exposed at
@@ -464,12 +596,27 @@ reports `already in sync`):
    actions (`actions/checkout`, …) are left untouched. The trailing
    `# <ref>` comment is refreshed so the pin stays human-auditable and the
    Renovate auto-bump rule above can track it.
-2. **Materializes runbook reference stubs** (§2.2 *link, don't copy*). Copies
+2. **Checks CI-caller naming** (advisory only, Story #173). Reports whether
+   `.github/workflows/ci.yml` matches the canonical caller triplet — file
+   `ci.yml`, display name `CI`, caller job id `ci` (required context
+   `ci / ci-required`; see
+   [reusable-workflows.md § "Canonical caller naming"](docs/reusable-workflows.md#canonical-caller-naming-the-ciyml--ci--ci-triplet)).
+   Never renames or rewrites anything — a caller rename must land atomically
+   with its own branch-protection ruleset context update, which is a
+   deliberate per-consumer Story, not an automatic sync side-effect.
+3. **Materializes runbook reference stubs** (§2.2 *link, don't copy*). Copies
    the thin stubs from `templates/runbooks/` into the consumer's
    `docs/runbooks/` **only when absent** — an already-adopted stub is skipped,
    and a full local copy (no stub marker) is surfaced as a warning to
    reconcile by hand, never silently overwritten.
-3. **Reconciles `extends`.** Prepends `github>dsj1984/mandrel-platform` to the
+4. **Materializes workflow caller templates.** Copies canonical callers from
+   `templates/workflows/` (e.g. `deploy-staging.yml`, the one-paved-road
+   `workflow_run` caller for `deploy-cloudflare.yml`'s CI-green guard — see
+   [`docs/reusable-workflows.md`](docs/reusable-workflows.md#deploy-cloudflareyml))
+   into the consumer's `.github/workflows/` — same link-don't-copy semantics:
+   only when absent, and a hand-authored file without the template marker is
+   surfaced as a warning rather than overwritten.
+5. **Reconciles `extends`.** Prepends `github>dsj1984/mandrel-platform` to the
    consumer's Renovate `extends` and `mandrel-platform/tsconfig.base.json` to
    its `tsconfig.json` `extends`. The SSOT goes first so the consumer's own
    later entries continue to override it.
@@ -481,16 +628,74 @@ result envelope on stdout).
 
 ---
 
+## Drift control & auto-repair
+
+The platform actively keeps consumers converged rather than trusting them to
+stay in sync by hand. Two scheduled workflows run this loop against the consumer
+registry in
+[`scripts/pin-drift-consumers.json`](scripts/pin-drift-consumers.json):
+
+- **Detect** — [`pin-drift.yml`](.github/workflows/pin-drift.yml) (weekly +
+  `workflow_dispatch`) runs `check-pin-drift.mjs`, a cross-consumer dashboard
+  that flags split pins (multiple mandrel-platform SHAs in one repo), release
+  lag, npm lag, and npm-vs-workflow surface skew. Advisory by default; `--strict`
+  turns drift into a failure. See the
+  [pin-drift dashboard runbook](docs/runbooks/pin-drift-dashboard.md).
+- **Repair** — [`platform-sync-repair.yml`](.github/workflows/platform-sync-repair.yml)
+  runs `platform-repair.mjs`, which clones each drifting consumer, runs
+  `platform-sync`, and opens (or updates) an **idempotent** repair PR on a stable
+  head branch. Requires a fine-grained `PIN_REPAIR_TOKEN` scoped to the consumer
+  repos' contents + pull-requests.
+
+`update-semgrep-rules.mjs` is a related maintenance script that vendors Semgrep's
+`p/default` ruleset — filtered to the languages actually in-repo — into
+`.semgrep/rules.json` against a pinned Semgrep version, so the SAST step in
+`pr-quality.yml` scans deterministically. Run it deliberately when bumping the
+ruleset, not on every CI run.
+
+---
+
+## Runbook templates
+
+`templates/runbooks/` ships **copyable thin-stub** operator runbooks — one per
+canonical runbook in [`docs/runbooks/`](docs/runbooks). The adoption model is
+*link, don't copy*: each stub links to the canonical process doc (the source of
+truth) and carries only `<PLACEHOLDER>` slots for project-specific values, so an
+upstream process change is picked up by re-reading the link rather than
+re-authoring the stub. `platform-sync` materializes them for you — link-only, and
+never clobbering a stub you have already filled in.
+
+| 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 |
+
+---
+
 ## Development
 
 ```bash
-# Install dependencies
+# Install dependencies (packageManager: pnpm@11.5.2)
 pnpm install
 
 # Bootstrap agent scaffolding
 pnpm run bootstrap
+
+# Run the guardrail-script test suite (node:test)
+pnpm test
 ```
 
+Every script under `scripts/` (the guardrail lints, `platform-sync`,
+`platform-repair`, `update-semgrep-rules`) carries a colocated `*.test.mjs`
+suite run by `pnpm test`. The `.agents/` tree is the Mandrel agent framework this
+repo is developed with — dev-time only, and not shipped in the npm package.
+
 ---
 
 ## Package exports
@@ -501,6 +706,7 @@ pnpm run bootstrap
 | `mandrel-platform/biome.base.json`              | `config/biome.base.json`              |
 | `mandrel-platform/knip.base.json`               | `config/knip.base.json`               |
 | `mandrel-platform/stryker.base.json`            | `config/stryker.base.json`            |
+| `mandrel-platform/commitlint.base.mjs`          | `config/commitlint.base.mjs`          |
 | `mandrel-platform/dependency-cruiser.base.json` | `config/dependency-cruiser.base.json` |
 | `mandrel-platform/size-limit.base.json`         | `config/size-limit.base.json`         |
 | `mandrel-platform/lighthouse.base.json`         | `config/lighthouse.base.json`         |

package/config/commitlint.base.mjs

@@ -0,0 +1,36 @@
+/**
+ * commitlint.base.mjs — shared commitlint config for mandrel-platform
+ * consumers.
+ *
+ * Single-sources the conventional-commit type-enum from
+ * `.agents/rules/git-conventions.md` (§ Conventional Commits) so the eleven
+ * allowed types live in exactly one place instead of being hand-copied into
+ * each consumer's own `commitlint.config.js`. Keep this list, the
+ * git-conventions.md prose list, and `release-please-config.json`'s
+ * `changelog-sections` in sync when adding a type — all three must agree.
+ *
+ * Extends `@commitlint/config-conventional` for everything else (header
+ * casing/length, body/footer leading-blank-line, etc.) and narrows
+ * `type-enum` to the fleet's eleven types.
+ */
+
+const TYPE_ENUM = [
+  "feat",
+  "fix",
+  "perf",
+  "refactor",
+  "revert",
+  "docs",
+  "style",
+  "chore",
+  "test",
+  "build",
+  "ci",
+];
+
+export default {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "type-enum": [2, "always", TYPE_ENUM],
+  },
+};

package/config/repo-settings.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dsj1984/mandrel-platform/blob/main/config/repo-settings.schema.json",
+  "title": "Repository Settings Baseline Contract",
+  "description": "Defines the GitHub-side repository settings baseline (merge methods, squash-commit source, auto-merge, Actions default token permissions, PR-approval-by-Actions) the fleet must converge on. Validated by scripts/check-repo-settings.mjs against each consumer's live settings (gh api repos/{owner}/{repo}); applied where safe by scripts/platform-sync.mjs --apply-settings. Non-blocking by design (standing decision #10) — drift is reported, never a hard gate on a consumer's main.",
+  "type": "object",
+  "required": [
+    "allowSquashMerge",
+    "allowMergeCommit",
+    "allowRebaseMerge",
+    "squashMergeCommitTitle",
+    "squashMergeCommitMessage",
+    "deleteBranchOnMerge",
+    "allowAutoMerge",
+    "actionsDefaultWorkflowPermissions",
+    "actionsCanApprovePullRequestReviews"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference."
+    },
+    "allowSquashMerge": {
+      "type": "boolean",
+      "description": "Whether squash merging is allowed. The fleet baseline requires this true (squash-only).",
+      "default": true
+    },
+    "allowMergeCommit": {
+      "type": "boolean",
+      "description": "Whether merge commits are allowed. The fleet baseline requires this false (squash-only).",
+      "default": false
+    },
+    "allowRebaseMerge": {
+      "type": "boolean",
+      "description": "Whether rebase merging is allowed. The fleet baseline requires this false (squash-only).",
+      "default": false
+    },
+    "squashMergeCommitTitle": {
+      "type": "string",
+      "description": "Source of the squash-commit title.",
+      "enum": ["PR_TITLE", "COMMIT_OR_PR_TITLE"],
+      "default": "PR_TITLE"
+    },
+    "squashMergeCommitMessage": {
+      "type": "string",
+      "description": "Source of the squash-commit message body. The fleet baseline requires PR_BODY — commits landing on main feed release-please + commitlint, so the PR body becomes the literal commit body and must stay commit-body-safe (see the _note below).",
+      "enum": ["PR_BODY", "COMMIT_MESSAGES", "BLANK"],
+      "default": "PR_BODY"
+    },
+    "deleteBranchOnMerge": {
+      "type": "boolean",
+      "description": "Whether head branches are auto-deleted after a merge.",
+      "default": true
+    },
+    "allowAutoMerge": {
+      "type": "boolean",
+      "description": "Whether GitHub's native auto-merge feature is enabled for the repo.",
+      "default": true
+    },
+    "actionsDefaultWorkflowPermissions": {
+      "type": "string",
+      "description": "Default GITHUB_TOKEN permissions granted to Actions workflows. The fleet baseline requires 'read' (least-privilege) — a workflow that needs write scopes requests it explicitly via a `permissions:` block.",
+      "enum": ["read", "write"],
+      "default": "read"
+    },
+    "actionsCanApprovePullRequestReviews": {
+      "type": "boolean",
+      "description": "Whether GitHub Actions workflows are permitted to approve pull requests. The fleet baseline requires this false — an automated actor approving its own (or any) PR is a bypass of human review, not a feature.",
+      "default": false
+    },
+    "_note": {
+      "type": "string",
+      "description": "Human-readable note for maintainers."
+    }
+  },
+  "_note": "PR templates must stay commit-body-safe: with squashMergeCommitMessage=PR_BODY, the full PR description becomes the literal squash-commit body on main, which release-please and commitlint then parse. A PR template that injects checklist boilerplate, HTML comments, or non-conventional-commit prose into that body will land in the commit history and can break release-please's changelog generation or commitlint's body-line rules. Keep PR templates short, commit-message-safe prose, or move checklists into template sections that authors delete before merge."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,7 @@
     "./biome.base.json": "./config/biome.base.json",
     "./knip.base.json": "./config/knip.base.json",
     "./stryker.base.json": "./config/stryker.base.json",
+    "./commitlint.base.mjs": "./config/commitlint.base.mjs",
     "./dependency-cruiser.base.json": "./config/dependency-cruiser.base.json",
     "./size-limit.base.json": "./config/size-limit.base.json",
     "./lighthouse.base.json": "./config/lighthouse.base.json",