@bongos/core 1.17.0

package/scripts/gds/gate-review.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/gate-review.js — the automatic gate-surface gatekeeper (ADR 0058).
+//
+// WHY. In deploy mode 'ci' (config/deploy.json) PRs auto-merge on green checks and
+// main auto-deploys to prod. CODEOWNERS (owner review on gate surfaces) was the ONLY
+// human in that loop — and the bottleneck. The owner chose a RANK-BASED trust model
+// (2026-06-15): trust senior builders to auto-merge routine sensitive work, but keep a
+// HARD, rank-independent floor for the gate's own machinery + deploy switch.
+//
+// WHAT. This is a PURE, deterministic classifier over the PR diff-as-DATA. It runs in
+// CI (.github/workflows/gate-review.yml) from the TRUSTED BASE copy (the workflow
+// overlays scripts/+src/ from origin/main before running, so a PR cannot edit the
+// analyzer to pass itself). It emits one of three verdicts:
+//
+//   PASS         — no gate surface touched, OR only AUTO pure-removal surfaces
+//                  (un-mute a test, narrow the secret-scanner allowlist). Auto-merge.
+//   NEEDS_TRUST  — a sensitive-but-routine gate surface (migrations, deps, routes,
+//                  server, ship plumbing, boxes, auth-adjacent, doctrine docs). The
+//                  workflow auto-merges this IFF the author is Metic+ (rank trust) or
+//                  the owner approved; otherwise it escalates.
+//   ESCALATE     — the HARD FLOOR: the gate's own machinery, the deploy switch, branch
+//                  protection, CI workflows, the rank/permission enforcement, the
+//                  grader, the deploy-time audit, or the hooks the gate ships through.
+//                  Rank-trust does NOT apply — this ALWAYS pings the owner. Also any
+//                  pre-flight rejection (symlink / non-ASCII path / oversize / analyzer
+//                  error) → ESCALATE, fail-closed.
+//
+// The gate-surface SET is the authoritative src/bongos/permission-path-check.PROTECTED_GLOBS
+// (imported, NEVER hand-retyped — the red-team's #1 finding). The classifier only
+// decides, per touched surface, whether it is HARD-FLOOR, NEEDS_TRUST, or AUTO. Anything
+// matched-protected-but-unclassified defaults to ESCALATE (no allow-by-omission).
+//
+// The pure core (classifyChanges) takes diff data as arguments and is exhaustively
+// unit-tested (tests/gate_review.mjs) with the red-team evasion matrix. The CLI wrapper
+// (main) gathers the real diff via git and applies GATE_REPORT_ONLY / exit codes.
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const permPath = require('../../src/bongos/permission-path-check');
+const { PROTECTED_GLOBS, globToRegExp } = permPath;
+
+// --- HARD FLOOR (rank-independent ESCALATE) -------------------------------------------
+// A subset of PROTECTED_GLOBS: the surfaces that, if a compromised/injected senior
+// session auto-merged them, would DISABLE the safety system itself or the deploy gate.
+// Kept as globs so the matcher is identical to permission-path-check (trailing '/' =
+// subtree). The owner can promote a NEEDS_TRUST surface here with a one-line edit (which
+// is itself a hard-floor change to this file → escalates — correct).
+const HARD_FLOOR_GLOBS = [
+  'scripts/gds/gate-review.js', // self
+  'src/bongos/permission-path-check.js', // defines the protected set this gate reads
+  'src/bongos/route-rank-check.js', // the route-gate auditor
+  'src/bongos/auth.js', // requireRank / requireBuilder — the enforcement point
+  'modules/grading/grader.js',       // BV1.R73: grading carved to modules/grading/
+  'modules/grading/grader-workers/',
+  'modules/grading/grader-rubric.json',
+  'scripts/gds/ci-grade.js', // CI grade-gate driver (task 1143 — red-team #3)
+  'scripts/gds/grade-smoke.js', // grade-smoke driver
+  'scripts/gds/conductor-dispatch.js', // mid-flight grader dispatch
+  'scripts/gds/main-audit.js', // the authoritative deploy-time audit (the backstop)
+  'scripts/gds/push-main.js', // the sanctioned main-push carrying the override
+  'scripts/gds/run-unit-tests.js', // the test selector (AUTO pure-removal handled first)
+  'scripts/gds/install-git-hooks.js',
+  'scripts/gds/hooks/',
+  'scripts/migrate.sh',
+  'scripts/deploy/',
+  'config/deploy.json', // the laptop/ci/bypass deploy switch
+  'infra/', // branch-protection.json + deploy substrate
+  '.github/', // CI gates: gate-review.yml, deploy-prod.yml, secret scan, grade gate
+  'CODEOWNERS',
+  '.husky/', // pre-push/pre-commit gate delivery (secrets-allowlist.txt is AUTO, checked first)
+  '.claude/hooks/',
+  '.claude/settings.json',
+];
+
+// db.js is HARD-FLOOR only for the rank-tier brain (REQUIRES_RANK_TIER); every other
+// db.js change is NEEDS_TRUST (it is a huge, routinely-edited module — file-level
+// hard-flooring it would ping the owner for ordinary query work). This is the one
+// content-level rule; everything else is path-level.
+const DB_JS = 'src/bongos/db.js';
+const RANK_TIER_RE = /REQUIRES_RANK_TIER\s*=\s*\{[\s\S]*?\}/;
+
+// AUTO pure-removal surfaces — a NARROWING-only edit can only STRENGTHEN the gate, so
+// it may auto-pass for ANY author. Any non-narrowing edit falls through to its glob
+// classification (run-unit-tests.js → HARD FLOOR; secrets-allowlist.txt → .husky/ HARD FLOOR).
+const AUTO_NARROWING = {
+  'scripts/gds/run-unit-tests.js': certifyRunUnitTestsNarrowing,
+  '.husky/secrets-allowlist.txt': certifyAllowlistNarrowing,
+};
+
+const COMPILED_HARD = HARD_FLOOR_GLOBS.map((g) => ({ glob: g, re: globToRegExp(g) }));
+const matchesHardFloor = (f) => COMPILED_HARD.some((c) => c.re.test(f));
+
+// A path is "protected" per the authoritative module.
+const protectedRe = PROTECTED_GLOBS.map((g) => ({ glob: g, re: globToRegExp(g) }));
+const matchesProtected = (f) => protectedRe.some((c) => c.re.test(f));
+
+// Only [\x20-\x7e] path chars, NFC-stable, no leading/trailing whitespace. Defeats the
+// unicode-homoglyph + whitespace-alias evasions (red-team Holes 6/8).
+function isCanonicalPath(p) {
+  return typeof p === 'string' && p.length > 0 && /^[\x20-\x7e]+$/.test(p)
+    && p === p.normalize('NFC') && p === p.trim();
+}
+
+// AUTO certifier: run-unit-tests.js may auto-pass ONLY if its sole semantic change is
+// REMOVING entries from INTEGRATION/KNOWN_FAILING (un-muting tests) — never adding, and
+// the rest of the file byte-identical modulo those two set literals.
+function certifyRunUnitTestsNarrowing(base, head) {
+  if (base == null || head == null) return { pass: false, reason: 'added/removed wholesale — not a narrowing edit' };
+  const setOf = (t, name) => {
+    const m = new RegExp(`const ${name} = new Set\\(\\[([\\s\\S]*?)\\]\\)`).exec(t);
+    if (!m) return null;
+    return new Set([...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]));
+  };
+  const strip = (t) => t.replace(/const (INTEGRATION|KNOWN_FAILING) = new Set\(\[[\s\S]*?\]\)/g, 'SET');
+  if (strip(base) !== strip(head)) return { pass: false, reason: 'non-set code changed in run-unit-tests.js' };
+  for (const name of ['INTEGRATION', 'KNOWN_FAILING']) {
+    const b = setOf(base, name), h = setOf(head, name);
+    if (!b || !h) return { pass: false, reason: `cannot parse ${name} set — fail-closed` };
+    for (const x of h) if (!b.has(x)) return { pass: false, reason: `${name} ADDED '${x}' (muting a test)` };
+  }
+  return { pass: true };
+}
+
+// AUTO certifier: secrets-allowlist.txt may auto-pass ONLY if its head line set is a
+// subset of the base (removing/narrowing allowlist entries) — never adding a new exclude.
+function certifyAllowlistNarrowing(base, head) {
+  if (base == null || head == null) return { pass: false, reason: 'added/removed wholesale — not a narrowing edit' };
+  const norm = (t) => new Set(t.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#')));
+  const b = norm(base), h = norm(head);
+  for (const line of h) if (!b.has(line)) return { pass: false, reason: `allowlist ADDED/BROADENED: ${line}` };
+  return { pass: true };
+}
+
+// ----------------------------------------------------------------------------------------
+// PURE CORE. Inputs are diff DATA (no git, no fs) so the whole policy is unit-tested:
+//   files:  [{ path, mode, deleted }]  — changed paths + git new-mode + delete flag
+//   blobAt: (which:'base'|'head', path) => string|null   — file content at base/head
+//   diffBytes: number                                    — total textual diff size
+// Returns { verdict:'pass'|'needs_trust'|'escalate', escalations:[{path,reason}],
+//           needsTrust:[{path,reason}], autoPassed:[path], surfaces:[path] }.
+// ----------------------------------------------------------------------------------------
+const MAX_DIFF_BYTES = Number(process.env.GATE_MAX_DIFF_BYTES || 2 * 1024 * 1024);
+
+function classifyChanges({ files, blobAt, diffBytes = 0 } = {}) {
+  const escalations = [];
+  const needsTrust = [];
+  const autoPassed = [];
+  const surfaces = [];
+
+  // --- Pre-flight, fail-closed (whole changed set) ---
+  for (const f of files || []) {
+    if (f.mode === '120000') escalations.push({ path: f.path, reason: 'symlink in diff — refused (alias evasion)' });
+    if (!isCanonicalPath(f.path)) escalations.push({ path: String(f.path), reason: 'non-ASCII/whitespace path — refused' });
+  }
+  if (diffBytes > MAX_DIFF_BYTES) {
+    escalations.push({ path: '<diff>', reason: `diff ${diffBytes}B exceeds ${MAX_DIFF_BYTES}B — too large to certify` });
+  }
+
+  for (const f of files || []) {
+    const p = f.path;
+    if (!isCanonicalPath(p)) continue; // already escalated above
+    // A gate surface = the authoritative PROTECTED_GLOBS, OR a hard-floor glob (some
+    // floor paths — gate-review.js itself, config/deploy.json, CODEOWNERS — are also
+    // added to PROTECTED_GLOBS, but OR-ing keeps the gatekeeper correct even if a
+    // future hard-floor entry isn't yet in the shared list), OR a tests/*.mjs file.
+    const isProtected = matchesProtected(p) || matchesHardFloor(p);
+    const isTest = /^tests\/.+\.mjs$/.test(p);
+    if (!isProtected && !isTest) continue; // not a gate surface
+
+    surfaces.push(p);
+
+    // tests/*.mjs: deleting or shrinking a test silently weakens the suite → NEEDS_TRUST
+    // (rank-trustable per the owner's model); adding/expanding is fine → PASS.
+    if (isTest && !isProtected) {
+      if (f.deleted) { needsTrust.push({ path: p, reason: 'test file DELETED — suite shrink' }); continue; }
+      const base = blobAt('base', p), head = blobAt('head', p);
+      if (base != null && head != null && head.length < base.length) {
+        needsTrust.push({ path: p, reason: 'test file SHRANK — possible muting' });
+      }
+      continue;
+    }
+
+    // AUTO pure-removal surfaces: certify a narrowing-only edit (any author).
+    if (Object.prototype.hasOwnProperty.call(AUTO_NARROWING, p)) {
+      const cert = AUTO_NARROWING[p](blobAt('base', p), blobAt('head', p));
+      if (cert.pass) { autoPassed.push(p); continue; }
+      // not a narrowing edit → fall through to HARD FLOOR (both AUTO files are floor globs)
+      escalations.push({ path: p, reason: `AUTO surface failed narrowing cert (${cert.reason}) — root-of-trust` });
+      continue;
+    }
+
+    // db.js: HARD FLOOR only when the rank-tier brain changed; else NEEDS_TRUST.
+    if (p === DB_JS) {
+      const base = blobAt('base', p), head = blobAt('head', p);
+      const region = (t) => { const m = t == null ? null : RANK_TIER_RE.exec(t); return m ? m[0] : (t == null ? '<absent>' : '<no-region>'); };
+      if (base == null || head == null) { needsTrust.push({ path: p, reason: 'db.js added/removed' }); continue; }
+      if (region(base) !== region(head)) {
+        escalations.push({ path: p, reason: 'db.js REQUIRES_RANK_TIER (rank brain) changed — root-of-trust' });
+      } else {
+        needsTrust.push({ path: p, reason: 'db.js change outside the rank-tier region' });
+      }
+      continue;
+    }
+
+    // HARD FLOOR globs → ESCALATE regardless of rank.
+    if (matchesHardFloor(p)) { escalations.push({ path: p, reason: 'gate machinery / deploy switch (hard floor) — owner review required' }); continue; }
+
+    // Any other protected surface → NEEDS_TRUST (rank-trustable).
+    needsTrust.push({ path: p, reason: 'sensitive gate surface — auto-merges for Metic+ (rank trust)' });
+  }
+
+  const verdict = escalations.length ? 'escalate' : (needsTrust.length ? 'needs_trust' : 'pass');
+  return { verdict, escalations, needsTrust, autoPassed, surfaces };
+}
+
+// Resolve the merge action from the verdict + the two trust signals (both injected by
+// the workflow, never read by the pure classifier). RANK trust (server-attested Metic+)
+// clears NEEDS_TRUST only; the HARD FLOOR (escalate) is cleared ONLY by an explicit
+// owner review — rank never bypasses it. An owner approval clears anything.
+//   pass        → 'pass'
+//   needs_trust → 'pass' iff (rank-trusted OR owner-approved)
+//   escalate    → 'pass' iff owner-approved
+function resolveAction({ verdict, trusted, ownerApproved }) {
+  if (verdict === 'pass') return 'pass';
+  if (verdict === 'escalate') return ownerApproved ? 'pass' : 'block';
+  return trusted || ownerApproved ? 'pass' : 'block';
+}
+
+// ----------------------------------------------------------------------------------------
+// CLI wrapper — gather the real diff and apply report-only / exit codes. Never returns 0
+// on an analyzer error (fail-closed). The rank/owner-approval resolution for NEEDS_TRUST
+// is provided by the workflow via GATE_AUTHOR_TRUSTED (set from the server-resolved rank /
+// owner approval); the pure core never reads rank.
+// ----------------------------------------------------------------------------------------
+function git(args) { return execFileSync('git', args, { encoding: 'utf8', maxBuffer: 128 * 1024 * 1024 }); }
+
+function gatherDiff(baseRef) {
+  const mb = git(['merge-base', baseRef, 'HEAD']).trim();
+  const raw = git(['diff', '--raw', `${mb}...HEAD`]).split('\n').filter(Boolean);
+  const files = [];
+  for (const line of raw) {
+    // ":100644 100644 sha sha M\tpath"  (status D = delete; mode 120000 = symlink)
+    const m = /^:(\d{6}) (\d{6}) \S+ \S+ (\S+)\t(.+)$/.exec(line);
+    if (!m) { files.push({ path: '<unparseable>', mode: '000000', deleted: false, parseError: true }); continue; }
+    const [, , newMode, status, rawPath] = m;
+    files.push({ path: rawPath, mode: newMode, deleted: status.startsWith('D') });
+  }
+  const diffBytes = Buffer.byteLength(git(['diff', `${mb}...HEAD`]), 'utf8');
+  const blobAt = (which, p) => {
+    const ref = which === 'base' ? mb : 'HEAD';
+    try { return git(['show', `${ref}:${p}`]); } catch { return null; }
+  };
+  return { files, blobAt, diffBytes };
+}
+
+async function main() {
+  const baseRef = process.env.GATE_BASE_REF || 'origin/main';
+  const reportOnly = process.env.GATE_REPORT_ONLY === '1';
+  const trusted = process.env.GATE_AUTHOR_TRUSTED === '1'; // set by the workflow from server-resolved rank / owner approval
+
+  let result;
+  try {
+    if ((process.env.GATE_FILES_JSON || '').trim()) {
+      // test/dry-run injection: {files, blobs:{ 'base:path':..., 'head:path':... }, diffBytes}
+      const inj = JSON.parse(process.env.GATE_FILES_JSON);
+      const blobAt = (which, p) => (inj.blobs && Object.prototype.hasOwnProperty.call(inj.blobs, `${which}:${p}`)) ? inj.blobs[`${which}:${p}`] : null;
+      result = classifyChanges({ files: inj.files, blobAt, diffBytes: inj.diffBytes || 0 });
+    } else {
+      const { files, blobAt, diffBytes } = gatherDiff(baseRef);
+      if (files.some((f) => f.parseError)) throw new Error('unparseable --raw diff line (fail-closed)');
+      result = classifyChanges({ files, blobAt, diffBytes });
+    }
+  } catch (e) {
+    console.error(`gate-review: analyzer error (fail-closed): ${e && e.stack ? e.stack : e}`);
+    process.exit(reportOnly ? 0 : 1);
+    return;
+  }
+
+  // Resolve the final action.
+  const ownerApproved = process.env.GATE_OWNER_APPROVED === '1';
+  const action = resolveAction({ verdict: result.verdict, trusted, ownerApproved });
+
+  const lines = [`## gate-review: ${result.verdict.toUpperCase()}${reportOnly ? ' (report-only)' : ''} → would ${action === 'pass' ? 'PASS' : 'BLOCK + ping owner'}`, ''];
+  if (result.surfaces.length) lines.push(`Gate surfaces touched: ${result.surfaces.length}`);
+  for (const e of result.escalations) lines.push(`- ESCALATE \`${e.path}\` — ${e.reason}`);
+  for (const n of result.needsTrust) lines.push(`- NEEDS-TRUST \`${n.path}\` — ${n.reason} → ${action === 'pass' ? 'PASS' : 'BLOCK (needs Metic+ attestation or owner approval)'}`);
+  for (const a of result.autoPassed) lines.push(`- AUTO-PASS \`${a}\` — pure narrowing (strengthens the gate)`);
+  if (!result.surfaces.length) lines.push('No gate surface touched — auto-merge.');
+
+  const out = lines.join('\n');
+  console.log(out);
+  if (process.env.GITHUB_STEP_SUMMARY) { try { fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, out + '\n'); } catch (_) { /* best-effort */ } }
+
+  if (action === 'block' && !reportOnly) {
+    await pingOwner(result).catch(() => {});
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+async function pingOwner(result) {
+  const url = process.env.DISCORD_GATE_APPROVALS_WEBHOOK;
+  const pr = process.env.GATE_PR_NUMBER;
+  if (!url || !pr) return;
+  const surfaces = [...new Set([...result.escalations, ...result.needsTrust].map((x) => x.path))].slice(0, 10).join(', ');
+  const body = { content: `gate-pr #${pr} — gate-surface change needs your review: ${surfaces}\nReview + approve the PR to land it.`, allowed_mentions: { parse: [] } };
+  await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+}
+
+module.exports = {
+  classifyChanges,
+  resolveAction,
+  certifyRunUnitTestsNarrowing,
+  certifyAllowlistNarrowing,
+  isCanonicalPath,
+  matchesHardFloor,
+  HARD_FLOOR_GLOBS,
+};
+
+if (require.main === module) main();

package/scripts/gds/gating.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+// scripts/gds/gating.js — owner kill-switch for main-branch merge gating.
+//
+// What "gating" means here — TWO independent levers, both toggled together:
+//   1. GitHub branch protection on `main`: required status checks (unit,
+//      trufflehog, gate-review) + required code-owner review (CODEOWNERS).
+//   2. The application-layer trust gates that run on every PR — the gate-review
+//      and grade-gate CI workflows. These post their own status checks and the
+//      ship / auto-merge pipeline refuses to land a PR while gate-review is red
+//      (it escalates gate-surface changes — infra/, migrations/, CODEOWNERS,
+//      scripts/gds plumbing — to owner approval). Branch protection alone does
+//      NOT neutralize these, which is why `off` also `gh workflow disable`s them.
+// With gating ON, a gate-surface PR needs owner approval / --admin to merge.
+// With gating OFF, ordinary `gh pr merge N` (and every builder / autonomous
+// session) merges with no checks and no approval. `unit` + `trufflehog` keep
+// running either way — real safety nets that force no approval.
+//
+// It is REVERSIBLE by construction: `off` snapshots the live protection to a
+// replay-ready file, then deletes protection; `on` PUTs the snapshot back,
+// byte-for-byte. If the snapshot is missing, `on` falls back to a baked-in
+// known-good config (printed loudly) so you can never get permanently stuck.
+//
+// ⚠ While OFF, ANY merge to `main` reaches prod with no checks and no review —
+//   yours, any builder's, any autonomous session's. This is a deliberate,
+//   owner-only, temporary posture. Flip it back with `on` when done.
+//
+// Usage:
+//   node scripts/gds/gating.js status     # show current protection + snapshot state
+//   node scripts/gds/gating.js off         # snapshot, then remove all protection
+//   node scripts/gds/gating.js on          # restore protection from the snapshot
+//
+// Auth: uses the `gh` CLI, which must be authenticated as a repo admin (the
+// owner). This is a trust-boundary surface (ADR 0016/0043) — owner-gated in
+// CODEOWNERS so a builder cannot weaken the gate by editing this file.
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const BRANCH = 'main';
+const SNAPSHOT = require('../../src/instance-config').configPath('gating-snapshot.json');
+
+// The application-layer trust gates that run on every PR and force owner
+// approval / --admin on gate-surface changes. Branch protection alone does NOT
+// neutralize these — they post their own status checks and the auto-merge /
+// ship pipeline refuses to land a PR while gate-review is red. So the kill-switch
+// also disables/enables these workflows. `unit` + `trufflehog` (secret scan) are
+// deliberately left running — they are real safety nets and force no approval.
+const GATE_WORKFLOWS = ['gate-review.yml', 'grade-gate.yml'];
+
+// Baked-in known-good config (the live state captured 2026-06-19). Used only as
+// a restore fallback when no snapshot exists, so `on` can never be stuck.
+const DEFAULT_PROTECTION = {
+  required_status_checks: {
+    strict: false,
+    checks: [
+      { context: 'unit', app_id: 15368 },
+      { context: 'trufflehog', app_id: 15368 },
+      { context: 'gate-review', app_id: 15368 },
+    ],
+  },
+  enforce_admins: false,
+  required_pull_request_reviews: {
+    dismiss_stale_reviews: false,
+    require_code_owner_reviews: true,
+    required_approving_review_count: 0,
+    require_last_push_approval: false,
+  },
+  restrictions: null,
+};
+
+function gh(args, opts = {}) {
+  return execFileSync('gh', args, {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    ...opts,
+  });
+}
+
+function repoSlug() {
+  try {
+    return gh(['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner']).trim();
+  } catch (e) {
+    fail('could not resolve the repo via `gh repo view` — is gh installed and run inside the repo?', e);
+  }
+}
+
+// GET protection. Returns the parsed object, or null if protection is OFF
+// (GitHub returns 404 "Branch not protected").
+function getProtection(repo) {
+  try {
+    const out = gh(['api', `repos/${repo}/branches/${BRANCH}/protection`]);
+    return JSON.parse(out);
+  } catch (e) {
+    const msg = `${e.stderr || ''}${e.stdout || ''}`;
+    if (/Branch not protected|Not Found|HTTP 404/i.test(msg)) return null;
+    fail('failed to read branch protection', e);
+  }
+}
+
+// Transform a GET-protection response into a valid PUT body (the two shapes
+// differ — GET nests booleans under {enabled}, PUT wants flat values).
+function toPutBody(p) {
+  const body = {
+    required_status_checks: null,
+    enforce_admins: !!(p.enforce_admins && p.enforce_admins.enabled),
+    required_pull_request_reviews: null,
+    restrictions: null,
+  };
+  if (p.required_status_checks) {
+    const rsc = p.required_status_checks;
+    body.required_status_checks = { strict: !!rsc.strict };
+    if (Array.isArray(rsc.checks) && rsc.checks.length) {
+      body.required_status_checks.checks = rsc.checks.map((c) => ({
+        context: c.context,
+        app_id: c.app_id ?? null,
+      }));
+    } else {
+      body.required_status_checks.contexts = rsc.contexts || [];
+    }
+  }
+  if (p.required_pull_request_reviews) {
+    const r = p.required_pull_request_reviews;
+    const rb = {
+      dismiss_stale_reviews: !!r.dismiss_stale_reviews,
+      require_code_owner_reviews: !!r.require_code_owner_reviews,
+      required_approving_review_count: r.required_approving_review_count ?? 0,
+    };
+    if (typeof r.require_last_push_approval === 'boolean') {
+      rb.require_last_push_approval = r.require_last_push_approval;
+    }
+    body.required_pull_request_reviews = rb;
+  }
+  if (p.restrictions) {
+    body.restrictions = {
+      users: (p.restrictions.users || []).map((u) => u.login),
+      teams: (p.restrictions.teams || []).map((t) => t.slug),
+      apps: (p.restrictions.apps || []).map((a) => a.slug),
+    };
+  }
+  for (const key of [
+    'required_linear_history',
+    'allow_force_pushes',
+    'allow_deletions',
+    'block_creations',
+    'required_conversation_resolution',
+    'lock_branch',
+    'allow_fork_syncing',
+  ]) {
+    if (p[key] && typeof p[key].enabled === 'boolean') body[key] = p[key].enabled;
+  }
+  return body;
+}
+
+function putProtection(repo, putBody) {
+  gh(['api', '-X', 'PUT', `repos/${repo}/branches/${BRANCH}/protection`, '--input', '-'], {
+    input: JSON.stringify(putBody),
+  });
+}
+
+function deleteProtection(repo) {
+  gh(['api', '-X', 'DELETE', `repos/${repo}/branches/${BRANCH}/protection`]);
+}
+
+// --- gate CI workflows ('active' | 'disabled_manually' | 'disabled_inactivity') ---
+function workflowState(repo, wf) {
+  try {
+    return gh(['api', `repos/${repo}/actions/workflows/${wf}`, '-q', '.state']).trim();
+  } catch {
+    return 'absent'; // not on the default branch / never registered
+  }
+}
+
+function setWorkflow(repo, wf, enable) {
+  // `gh workflow enable/disable` resolves the workflow from the repo context.
+  gh(['workflow', enable ? 'enable' : 'disable', wf]);
+}
+
+function readSnapshot() {
+  try {
+    return JSON.parse(fs.readFileSync(SNAPSHOT, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeSnapshot(obj) {
+  fs.mkdirSync(path.dirname(SNAPSHOT), { recursive: true });
+  fs.writeFileSync(SNAPSHOT, JSON.stringify(obj, null, 2));
+}
+
+function fail(msg, err) {
+  console.error(`\n✗ gating: ${msg}`);
+  if (err && (err.stderr || err.message)) console.error(`  ${(err.stderr || err.message).trim()}`);
+  process.exit(1);
+}
+
+function summarize(putBody) {
+  const checks =
+    putBody.required_status_checks
+      ? (putBody.required_status_checks.checks || putBody.required_status_checks.contexts || [])
+          .map((c) => c.context || c)
+          .join(', ') || '(none)'
+      : '(none)';
+  const review =
+    putBody.required_pull_request_reviews?.require_code_owner_reviews
+      ? 'code-owner review required'
+      : putBody.required_pull_request_reviews
+        ? `${putBody.required_pull_request_reviews.required_approving_review_count || 0} approving review(s)`
+        : 'no PR review required';
+  return { checks, review };
+}
+
+function cmdStatus(repo) {
+  const live = getProtection(repo);
+  const snap = readSnapshot();
+  const wf = GATE_WORKFLOWS.map((w) => ({ w, state: workflowState(repo, w) }));
+  const wfActive = wf.filter((x) => x.state === 'active');
+  console.log(`repo: ${repo}   branch: ${BRANCH}\n`);
+
+  // Lever 1 — branch protection.
+  if (live) {
+    const { checks, review } = summarize(toPutBody(live));
+    console.log('branch protection : 🟢 ON');
+    console.log(`  required checks : ${checks}`);
+    console.log(`  pr review       : ${review}`);
+    console.log(`  enforce_admins  : ${!!(live.enforce_admins && live.enforce_admins.enabled)} (owner can --admin merge when false)`);
+  } else {
+    console.log('branch protection : 🔴 OFF — `main` is UNPROTECTED.');
+  }
+
+  // Lever 2 — gate CI workflows.
+  console.log(`\ngate CI workflows : ${wfActive.length ? '🟢 ON' : '🔴 OFF'}`);
+  for (const x of wf) console.log(`  ${x.w.padEnd(16)}: ${x.state}`);
+
+  const fullyOff = !live && wfActive.length === 0;
+  const fullyOn = !!live && wfActive.length === GATE_WORKFLOWS.length;
+  console.log(`\ngating: ${fullyOff ? '🔴 fully OFF — merges sail through, no checks/approval' : fullyOn ? '🟢 fully ON' : '🟡 PARTIAL — run `off` or `on` to make it consistent'}`);
+  console.log(`snapshot: ${snap ? SNAPSHOT : '(none yet — `off` will create it; `on` would use the baked-in default)'}`);
+}
+
+function cmdOff(repo) {
+  // Lever 1 — branch protection (idempotent).
+  const live = getProtection(repo);
+  if (live) {
+    const putBody = toPutBody(live);
+    writeSnapshot({ saved_at_branch: BRANCH, repo, raw: live, put_body: putBody });
+    const { checks, review } = summarize(putBody);
+    console.log('branch protection: removing.');
+    console.log(`  was: checks [${checks}] + ${review}`);
+    console.log(`  snapshot saved: ${SNAPSHOT}`);
+    deleteProtection(repo);
+  } else {
+    console.log('branch protection: already off.');
+  }
+
+  // Lever 2 — gate CI workflows (idempotent).
+  for (const w of GATE_WORKFLOWS) {
+    const state = workflowState(repo, w);
+    if (state === 'active') {
+      setWorkflow(repo, w, false);
+      console.log(`gate workflow ${w}: disabled.`);
+    } else {
+      console.log(`gate workflow ${w}: already ${state}.`);
+    }
+  }
+
+  console.log('\n🔴 gating OFF. `main` is UNPROTECTED and the gate-review/grade CI gates no longer');
+  console.log('   run — ordinary `gh pr merge N` (and every builder / autonomous session) merges');
+  console.log('   with no checks and no approval. (unit + secret-scan still run.)');
+  console.log('   ↩  restore everything: node scripts/gds/gating.js on');
+}
+
+function cmdOn(repo) {
+  // Lever 1 — branch protection (idempotent).
+  const live = getProtection(repo);
+  if (!live) {
+    const snap = readSnapshot();
+    let putBody;
+    if (snap?.put_body) {
+      putBody = snap.put_body;
+      console.log(`branch protection: restoring from snapshot ${SNAPSHOT}`);
+    } else {
+      putBody = DEFAULT_PROTECTION;
+      console.log('⚠ branch protection: no snapshot — restoring the baked-in known-good default.');
+    }
+    putProtection(repo, putBody);
+    const after = getProtection(repo);
+    if (!after) fail('PUT returned but protection still reads as OFF — check `gh` auth / admin rights');
+    const { checks, review } = summarize(toPutBody(after));
+    console.log(`  restored: checks [${checks}] + ${review}`);
+  } else {
+    console.log('branch protection: already on.');
+  }
+
+  // Lever 2 — gate CI workflows (idempotent).
+  for (const w of GATE_WORKFLOWS) {
+    const state = workflowState(repo, w);
+    if (state !== 'active' && state !== 'absent') {
+      setWorkflow(repo, w, true);
+      console.log(`gate workflow ${w}: re-enabled.`);
+    } else {
+      console.log(`gate workflow ${w}: already ${state}.`);
+    }
+  }
+
+  console.log('\n🟢 gating ON. Branch protection + the gate-review/grade CI gates are back.');
+}
+
+function main() {
+  const cmd = (process.argv[2] || 'status').toLowerCase();
+  if (!['status', 'off', 'on'].includes(cmd)) {
+    console.error('usage: node scripts/gds/gating.js <status|off|on>');
+    process.exit(2);
+  }
+  const repo = repoSlug();
+  if (cmd === 'status') cmdStatus(repo);
+  else if (cmd === 'off') cmdOff(repo);
+  else if (cmd === 'on') cmdOn(repo);
+}
+
+main();

package/scripts/gds/gds-db-backup.service

@@ -0,0 +1,24 @@
+[Unit]
+Description=Nightly pg_dump of GDS Postgres DB (filed by #412)
+Documentation=file:///home/lars/amazonprimea/docs/recipes/gds-db-backup.md
+After=postgresql.service
+Requires=postgresql.service
+
+[Service]
+Type=oneshot
+User=lars
+Group=lars
+# Run the canonical script from the deployed repo. Keep this path stable;
+# the recipe doc points at it for restore + manual-one-shot use cases.
+ExecStart=/home/lars/amazonprimea/scripts/gds/db-backup-nightly.sh
+# Modest hardening — the script only needs read on the socket + write on
+# /var/backups/gds. Anything else is gravy for forensics.
+NoNewPrivileges=true
+ProtectSystem=strict
+ReadWritePaths=/var/backups/gds
+ProtectHome=read-only
+PrivateTmp=true
+
+[Install]
+# Not socket-activated; timer drives this. No [Install] WantedBy needed —
+# the timer's WantedBy is what gets enabled.