@bongos/core 1.19.319 → 1.19.321

package/scripts/gds/box.js

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 // scripts/gds/box.js — per-builder cloud dev box lifecycle CLI (ADR 0031 §2/§5, #598).
 //
-// The control-plane entrypoint for the box lifecycle. Like provision-staging.sh,
-// it is meant to RUN ON A TRUSTED CONTROL PLANE (the prod droplet, or an
-// operator's machine) — NOT inside a builder box. A builder box provisioning
-// boxes would be a privilege-escalation; the builder firewall doesn't even
-// allow-list the DO API. The rank gate is enforced here against the builder's
-// LIVE DB rank (the same value requireRank reads), so it is a real ADR-0016
+// The control-plane entrypoint for the box lifecycle. Like provision-staging.sh it
+// must RUN ON A TRUSTED CONTROL PLANE (the prod droplet or an operator's machine),
+// NOT inside a builder box — a box provisioning boxes is privilege escalation, and
+// the builder firewall doesn't even allow-list the DO API. The rank gate reads the
+// builder's LIVE DB rank (what requireRank reads), so it is a real ADR-0016
 // server-side check, not local prose.
 //
 // Subcommands:
@@ -21,10 +20,9 @@
 //
 // <builder> is a GitHub login or a numeric builder id.
 //
-// SAFETY: dry-run is the DEFAULT. Nothing touches DigitalOcean or writes the DB
-// unless you pass --apply. Run any command once without --apply to see the plan,
-// exactly like `pulse.js --release-stale --dry-run`.
-//
+// SAFETY: dry-run is the DEFAULT — nothing touches DigitalOcean or writes the DB
+// without --apply, so run any command bare first to see the plan (as with
+// `pulse.js --release-stale --dry-run`):
 //   node scripts/gds/box.js sweep-idle            # plan only
 //   node scripts/gds/box.js sweep-idle --apply     # actually park idle boxes
 //
@@ -96,6 +94,9 @@ function resolveBoxInfraDir(opts = {}) {
   return null;
 }
 
+// task 1002757 — the instance's own apex; null when unconfigured (callers refuse).
+const { instanceApex } = require('./instance-apex');
+
 const CONFIG = {
   floor: process.env.BOX_PROVISION_MIN_RANK || 'xenos',
   region: process.env.BOX_REGION || 'nyc3',
@@ -108,34 +109,35 @@ const CONFIG = {
   sshKeyIds: (process.env.BOX_SSH_KEY_IDS || '').split(',').map((s) => s.trim()).filter(Boolean),
   dnsHook: process.env.BOX_DNS_HOOK || null,
   tag: process.env.BOX_TAG || 'otb-builder-box',
-  dnsZone: process.env.BOX_DNS_ZONE || 'dev.amazonprimea.com',
+  // task 1002757 settled this file's old carve-out: an operator-plane DNS zone is
+  // still a FUNCTIONAL DEFAULT, and a founder literal aimed another operator's
+  // fleet at the founder's zone. Derived from the instance apex, null when
+  // unconfigured — hostnameFor() then refuses instead of minting a dead FQDN.
+  dnsZone: process.env.BOX_DNS_ZONE || (instanceApex() ? `dev.${instanceApex()}` : null),
 };
 
 // Named-tunnel automation for the browser terminal (#771, ADR 0038 Part B).
 // OPT-IN, default OFF — an unset BOX_NAMED_TUNNEL leaves the box on the tokenless
-// quick tunnel (trycloudflare.com), the zero-secret #760 default. When the
-// operator turns it on AND supplies a Cloudflare token with Tunnel + DNS scope
-// (the same CLOUDFLARE_API_TOKEN box-dns uses, scope added) + the account id, every
-// provision creates a stable term-<login>.dev.amazonprimea.com tunnel and bakes
-// its connector token into the box; deprovision tears it down.
+// quick tunnel (trycloudflare.com), the zero-secret #760 default. When the operator
+// turns it on AND supplies a Cloudflare token with Tunnel + DNS scope (the same
+// CLOUDFLARE_API_TOKEN box-dns uses) + the account id, every provision creates a
+// stable term-<login>.<terminalZone> tunnel and bakes its connector token into the
+// box; deprovision tears it down.
 const CF = {
   enabled: /^(1|true|yes)$/i.test(process.env.BOX_NAMED_TUNNEL || ''),
   apiToken: process.env.CLOUDFLARE_API_TOKEN || null,
   accountId: process.env.CLOUDFLARE_ACCOUNT_ID || null,
-  // The Cloudflare ZONE the DNS record lives in (registrable apex), e.g.
-  // amazonprimea.com — term-<login>.dev.amazonprimea.com is a record WITHIN it,
-  // matching box-dns-cloudflare.sh. Distinct from terminalZone (the host suffix).
-  zone: process.env.CLOUDFLARE_ZONE || 'amazonprimea.com',
-  // The host suffix the terminal hostname is built on (term-<login>.<terminalZone>).
-  // DEFAULTS TO THE APEX, NOT dev.* — the terminal rides a PROXIED Cloudflare
-  // tunnel (HTTPS at the edge), and free Universal SSL covers `amazonprimea.com` +
-  // `*.amazonprimea.com` (ONE label) but NOT `term-x.dev.amazonprimea.com` (TWO
-  // labels) → a 2-level host fails TLS at the edge (verified live, #771). One
-  // level (term-<login>.amazonprimea.com) is covered with no paid cert. An
-  // operator with an Advanced Certificate for *.dev.amazonprimea.com can override
-  // via BOX_TERMINAL_ZONE. (The SSH A-record path, box-dns-cloudflare.sh, stays on
-  // dev.* — it is proxied=false / direct-IP, so it needs no edge cert.)
-  terminalZone: process.env.BOX_TERMINAL_ZONE || 'amazonprimea.com',
+  // The Cloudflare ZONE the record lives in (the registrable apex) — the terminal
+  // host is a record WITHIN it, matching box-dns-cloudflare.sh. Distinct from
+  // terminalZone (the host suffix). Both resolve from the instance (task 1002757).
+  zone: process.env.CLOUDFLARE_ZONE || instanceApex(),
+  // Host suffix for term-<login>.<terminalZone>. DEFAULTS TO THE APEX, NOT dev.*:
+  // the terminal rides a PROXIED tunnel, and free Universal SSL covers <apex> +
+  // *.<apex> (ONE label) but not a TWO-label host like term-x.dev.<apex>, which
+  // fails TLS at the edge (verified live, #771). An operator holding an Advanced
+  // Certificate for *.dev.<apex> can override via BOX_TERMINAL_ZONE. (The SSH
+  // A-record path stays on dev.* — proxied=false, so it needs no edge cert.)
+  terminalZone: process.env.BOX_TERMINAL_ZONE || instanceApex(),
 };
 
 // Named-tunnel automation is live only when the operator opted in AND the
@@ -158,10 +160,9 @@ function makeCf(apply) {
 // SECURITY PREFLIGHT (task 1002511, ADR 0053 / SR#11). The edge cookie-strip
 // Transform Rule is applied BEST-EFFORT deep inside ensureNamedTunnel, so a
 // CLOUDFLARE_API_TOKEN missing the zone "Transform Rules" edit scope fails as one
-// buried log line — and the apex session cookie keeps reaching the box subdomains.
-// This probe runs BEFORE any DigitalOcean spend (dry-run included; a read-only
-// lookup running for real in a plan is the same precedent as the drift reconcile's
-// live droplet listing) and shouts the exact fix.
+// buried log line while the apex session cookie keeps reaching box subdomains. This
+// probe runs BEFORE any DigitalOcean spend (dry-run included — a read-only lookup in
+// a plan is the drift-reconcile precedent) and shouts the exact fix.
 //
 // HONESTY: the probe is a GET, so it can only DISPROVE the scope. A readable phase
 // does NOT mean the rule can be written — only the PUT inside ensureNamedTunnel
@@ -278,18 +279,21 @@ function shortStamp() {
 }
 
 function dropletName(login) { return `otb-box-${login}`; }
-function hostnameFor(login) { return `box-${login}.${CONFIG.dnsZone}`; }
-
-// Run the optional DNS hook so the per-builder hostname tracks the new IP. When
-// no hook is configured, just print the reminder — the stable-hostname CUTOVER
-// is #599's (Desktop managed-settings); #598 only records IP + hostname + offers
-// the hook so an operator can wire DO/Cloudflare DNS without editing this file.
-// Returns { ok, error?, skipped? }. task 1180: callers MUST act on ok:false
-// (record a box_events row + flag the box) instead of silently continuing — the
-// swallow that left @kingaonline's A record pinned at a dead IP while provision
-// reported success. The hook itself now retries transient Cloudflare blips
-// (infra/box-dns-cloudflare.sh), so ok:false here is a real, exhausted failure.
-// `hook` is injectable so the contract can be unit-tested with a fake (#1034).
+// Refuses on an unresolved zone (task 1002757) — `box-x.undefined` would mint a
+// DNS record and a box that can never be reached.
+function hostnameFor(login) {
+  if (!CONFIG.dnsZone) throw new Error('box: no DNS zone configured — set BOX_DNS_ZONE, or give this instance a domains.publicOrigin in config/branding.json (task 1002757).');
+  return `box-${login}.${CONFIG.dnsZone}`;
+}
+
+// Run the optional DNS hook so the per-builder hostname tracks the new IP; with no
+// hook configured, print the reminder — the stable-hostname CUTOVER is #599's, #598
+// only records IP + hostname and offers the hook so an operator can wire DNS without
+// editing this file. → { ok, error?, skipped? }. task 1180: callers MUST act on
+// ok:false (box_events row + flag the box), never continue silently — that swallow
+// left @kingaonline's A record pinned at a dead IP while provision reported success.
+// The hook retries transient Cloudflare blips, so ok:false is a real, exhausted
+// failure. `hook` is injectable so the contract is unit-testable (#1034).
 function runDnsHook(hostname, ip, hook = CONFIG.dnsHook) {
   if (!ip) return { ok: true, skipped: true };
   if (!hook) {
@@ -316,21 +320,16 @@ function runDnsHook(hostname, ip, hook = CONFIG.dnsHook) {
 // dead end to park a record at.
 const DNS_BLACKHOLE_IP = '192.0.2.1';
 
-// Park the per-builder A record at the blackhole sentinel on deprovision (idea
-// 309, refining task 1180). 1180 DELETED the record on teardown so it couldn't
-// dangle at a recycled DO IP — but delete-then-recreate across a reap→rebuild
-// left a window where the name returned NXDOMAIN, which resolvers negative-cache
-// for the zone's SOA neg-TTL (~30 min on the Cloudflare amazonprimea.com zone,
-// not builder-editable). A client that queried during that window (e.g. an open
-// Claude Desktop) then kept getting ENOTFOUND long after the box was back and the
-// record recreated. REPOINTING to a non-routable sentinel instead keeps the name
-// always-resolving (no NXDOMAIN → nothing to negative-cache) while preserving
-// 1180's guarantee that a torn-down box's name can never dial a recycled
-// stranger's IP. The next provision/wake PUTs the record straight to the live IP
-// — a clean in-place repoint at the 60s record TTL, no gap. Best-effort (like the
-// prior delete): a failure just leaves the old IP, which the next provision
-// repoints anyway. Reuses the UPSERT path of runDnsHook; `hook` is injectable for
-// tests. Returns { ok, error?, skipped? }.
+// Park the per-builder A record at the blackhole sentinel on deprovision (idea 309,
+// refining task 1180). 1180 DELETED the record so it couldn't dangle at a recycled
+// DO IP, but delete-then-recreate across a reap→rebuild left an NXDOMAIN window that
+// resolvers negative-cache for the zone's SOA neg-TTL (~30 min, not builder-editable)
+// — a client querying then kept getting ENOTFOUND long after the box was back.
+// REPOINTING to a non-routable sentinel keeps the name always-resolving (nothing to
+// negative-cache) while preserving 1180's guarantee that a torn-down box's name can
+// never dial a stranger's recycled IP; the next provision/wake PUTs the live IP
+// in-place at the 60s TTL, no gap. Best-effort like the prior delete. Reuses
+// runDnsHook's UPSERT path; `hook` injectable for tests. → { ok, error?, skipped? }
 function runDnsHookBlackhole(hostname, hook = CONFIG.dnsHook) {
   if (!hook || !hostname) return { ok: true, skipped: true };
   return runDnsHook(hostname, DNS_BLACKHOLE_IP, hook);
@@ -510,14 +509,13 @@ async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {
   // Create (or reuse) the named tunnel BEFORE the droplet so its connector token
   // bakes into the cloud-init box.env. A failure here aborts provision — better
   // no box than a box that boots without its promised stable terminal.
-  // #774: on the named-tunnel path the control plane knows EVERYTHING the browser
-  // on-ramp needs at provision time — the stable hostname (here) + a password (we
-  // generate it). So we bake the password into box.env (the box serves ttyd with
-  // it) and, once the box is active, RECORD {url, password} into the GDS ourselves
-  // (setTerminalAccess) — the builder reads them from the hall with no token ever
-  // placed on the box and no box-side reporter (that path was the quick-tunnel
-  // fallback and the source of the #771/#774 chicken-and-egg). ADR 0016 holds: no
-  // builder/infra credential is funneled into the box.
+  // #774: on the named-tunnel path the control plane knows everything the browser
+  // on-ramp needs at provision time — the stable hostname (here) + a password we
+  // generate. So bake the password into box.env (the box serves ttyd with it) and,
+  // once the box is active, RECORD {url, password} into the GDS ourselves
+  // (setTerminalAccess): the builder reads them from the hall, with no token placed
+  // on the box and no box-side reporter (the quick-tunnel fallback that caused the
+  // #771/#774 chicken-and-egg). ADR 0016 holds — no credential funneled into a box.
   let boxEnv = '';
   let terminalHostname = null;
   let terminalCredential = null;
@@ -553,24 +551,19 @@ async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {
     }
   }
 
-  // Bootstrap the builder's GDS session onto the box (#818). box-source-fetch
-  // (#600) authenticates as the BUILDER to pull the rank-scoped repo; without a
-  // session at ~/.config/otb/gds-session.json it no-ops forever, so the repo
-  // never clones, the devcontainer never comes up, and /builder-* skills are
-  // absent. The session normally comes from /builder-setup — which lives in the
-  // un-cloned repo (the chicken-and-egg). So we mint a session here and bake it
-  // into cloud-init, exactly like the SSH keys / tunnel token / terminal credential.
+  // Bootstrap the builder's GDS session onto the box (#818). box-source-fetch (#600)
+  // authenticates as the BUILDER to pull the rank-scoped repo; with no session file
+  // it no-ops forever (repo never clones → no devcontainer, no /builder-* skills),
+  // and the session normally comes from /builder-setup, which lives in the un-cloned
+  // repo — the chicken-and-egg. So mint one here and bake it into cloud-init.
   //
-  // SECURITY (#919, SR#2): this baked session is source='box' — a SCOPED, 24h
-  // refresh-on-use credential. The token lives ON the box (readable by any on-box
-  // process + the metadata endpoint), which is OUTSIDE the ADR 0016 trust boundary,
-  // so it must NOT carry the builder's full authority. auth.requireBuilder denies a
-  // 'box' session on every route except the 4 the on-box crons need (source-access,
-  // authorized-keys, heartbeat, terminal — gated by auth.allowBoxScope). The first
-  // source-fetch clones on boot; the repo persists in the snapshot. To do real work
-  // FROM the box (claim/ship) the builder runs /builder-reauth (device flow), minting
-  // a normal cli/web session — never auto-baked. user_agent='box-provision' is the
-  // marker migration 090 keys on to retroactively scope already-baked tokens.
+  // SECURITY (#919, SR#2): this baked session is source='box' — SCOPED, 24h
+  // refresh-on-use. The token sits ON the box (any on-box process + the metadata
+  // endpoint can read it), OUTSIDE the ADR 0016 trust boundary, so it must not carry
+  // the builder's full authority: requireBuilder denies a 'box' session everywhere
+  // except the 4 on-box cron routes (source-access, authorized-keys, heartbeat,
+  // terminal — via auth.allowBoxScope). Real work FROM the box needs /builder-reauth
+  // (device flow); user_agent='box-provision' is the marker migration 090 keys on.
   const gdsDb = require(path.join(REPO_ROOT, 'src/bongos/db'));
   const sessionToken = crypto.randomBytes(32).toString('hex');
   await gdsDb.createSession({

package/scripts/gds/db-backup-nightly.sh

@@ -6,8 +6,8 @@
 # in /var/backups/gds/ as YYYY-MM-DD-HHMMSS.sql.gz (UTC timestamp), and
 # files older than 30 days are pruned.
 #
-# Authentication: peer auth via the local Unix socket. The user `lars`
-# owns the `amazonprimea` Postgres role; pg_dump finds the socket at
+# Authentication: peer auth via the local Unix socket — the invoking unix
+# user owns the instance's Postgres role; pg_dump finds the socket at
 # /var/run/postgresql with no password needed. Matches the model in
 # src/db.js.
 #
@@ -36,8 +36,21 @@ set -euo pipefail
 # Destination directory for dumps. Owned by lars:lars, mode 0750.
 BACKUP_DIR="${GDS_BACKUP_DIR:-/var/backups/gds}"
 
-# Database to dump (default: production GDS).
-DB_NAME="${GDS_BACKUP_DB:-amazonprimea}"
+# Database to dump: explicit GDS_BACKUP_DB wins, else the instance's own branding
+# pack names it — the SAME resolver as migrate.sh / pool.js, so the backup and the
+# running server can never disagree (task 1002757). Deliberately NO literal
+# fallback: this script ships to every instance, and a baked-in founder default
+# aimed another instance's nightly pg_dump at a database that is not its own.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+DB_NAME="${GDS_BACKUP_DB:-}"
+if [ -z "$DB_NAME" ]; then
+  DB_NAME="$(node -e "process.stdout.write(require(process.argv[1]).instanceDbName() || '')" "$REPO_ROOT/src/bongos/pool" 2>/dev/null || true)"
+fi
+if [ -z "$DB_NAME" ]; then
+  echo "db-backup: cannot determine which database to dump. Set GDS_BACKUP_DB, or give this instance a db.database in config/branding.json. Refusing to guess (task 1002757)." >&2
+  exit 2
+fi
 
 # Retention in days. Files older than this (by mtime) are deleted at the
 # end of each successful run. 30 days = 30 daily dumps retained.

package/scripts/gds/db-backup-offsite.sh

@@ -13,13 +13,13 @@
 # scripts/gds/gds-db-offsite.service + .timer). Weekly cadence.
 #
 # Authentication: S3-style credentials for the Space live OUTSIDE the repo
-# in /etc/amazonprimea/spaces.env (chmod 600, owned by lars), per ADR 0022.
-# The systemd unit injects them via EnvironmentFile; a manual run sources
-# the same file. Required vars:
+# in /etc/<configDir>/spaces.env (chmod 600, owned by the service user), per
+# ADR 0022. The systemd unit injects them via EnvironmentFile; a manual run
+# sources the same file. Required vars:
 #   SPACES_KEY SPACES_SECRET SPACES_BUCKET SPACES_REGION SPACES_ENDPOINT
 #
 # Manual one-shot:
-#   /home/lars/amazonprimea/scripts/gds/db-backup-offsite.sh
+#   <instance-root>/scripts/gds/db-backup-offsite.sh
 #
 # Systemd:
 #   sudo systemctl start gds-db-offsite.service   # one-shot
@@ -32,7 +32,19 @@ set -euo pipefail
 
 # Where the local nightly dumps land (must match db-backup-nightly.sh).
 BACKUP_DIR="${GDS_BACKUP_DIR:-/var/backups/gds}"
-DB_NAME="${GDS_BACKUP_DB:-amazonprimea}"
+# Database name: explicit GDS_BACKUP_DB wins, else the instance's branding pack —
+# the same resolver + no-literal-fallback posture as db-backup-nightly.sh /
+# migrate.sh (task 1002757).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+DB_NAME="${GDS_BACKUP_DB:-}"
+if [ -z "$DB_NAME" ]; then
+  DB_NAME="$(node -e "process.stdout.write(require(process.argv[1]).instanceDbName() || '')" "$REPO_ROOT/src/bongos/pool" 2>/dev/null || true)"
+fi
+if [ -z "$DB_NAME" ]; then
+  echo "db-backup-offsite: cannot determine which database's dumps to ship. Set GDS_BACKUP_DB, or give this instance a db.database in config/branding.json. Refusing to guess (task 1002757)." >&2
+  exit 2
+fi
 
 # How many weekly offsite copies to retain in the Space before pruning the
 # oldest. 4 = ~1 month of weekly snapshots (Archon decision, #415 claim 338).
@@ -45,7 +57,12 @@ PREFIX="${GDS_OFFSITE_PREFIX:-gds-offsite/}"
 
 # Credentials file. Read only if the SPACES_* vars aren't already set
 # (systemd injects them via EnvironmentFile; this covers manual runs).
-ENV_FILE="${GDS_SPACES_ENV:-/etc/amazonprimea/spaces.env}"
+# Default path derives from the instance's config dir (task 1002757 — the old
+# founder-pinned /etc/<founder>/ default could never exist on another box);
+# empty when the resolver is unavailable, in which case the SPACES_* vars (or
+# an explicit GDS_SPACES_ENV) must carry the credentials.
+CONFIG_DIR_NAME="$(node -e "process.stdout.write(require(process.argv[1]).configDirName() || '')" "$REPO_ROOT/src/instance-config" 2>/dev/null || true)"
+ENV_FILE="${GDS_SPACES_ENV:-${CONFIG_DIR_NAME:+/etc/$CONFIG_DIR_NAME/spaces.env}}"
 
 # ---- load credentials -------------------------------------------------------
 

package/scripts/gds/discipline-modes.json

@@ -14,7 +14,7 @@
     "artist": {
       "skill": "paint",
       "label": "Art session",
-      "directive": "This is an ARTIST task. To work it, invoke the /paint skill — that skill is the operating playbook for art sessions, and it is the only place the experience is defined. It is show-first / low-text: Claude communicates in pictures (display the generated tile, the /art gallery at sandbox-<login>.amazonprimea.com/art, and the in-world sandbox), not paragraphs about what the pipeline did. It drives the existing pixel-art pipeline (otb-tile-generate / otb-design-review / otb-feedback-capture / art-stage.js) and keeps the locked palette + rubric sacred. If no human is present (autonomous / bypass-permissions), /paint generates, rubric-gates hard, stages passing assets to the gallery, and parks the visuals for human review. Open /paint now rather than working this task the default way; the gallery is at sandbox-<login>.amazonprimea.com/art."
+      "directive": "This is an ARTIST task. To work it, invoke the /paint skill — that skill is the operating playbook for art sessions, and it is the only place the experience is defined. It is show-first / low-text: Claude communicates in pictures (display the generated tile, the /art gallery at sandbox-<login>.<instance-apex>/art, and the in-world sandbox), not paragraphs about what the pipeline did. It drives the existing pixel-art pipeline (otb-tile-generate / otb-design-review / otb-feedback-capture / art-stage.js) and keeps the locked palette + rubric sacred. If no human is present (autonomous / bypass-permissions), /paint generates, rubric-gates hard, stages passing assets to the gallery, and parks the visuals for human review. Open /paint now rather than working this task the default way; the gallery is at sandbox-<login>.<instance-apex>/art."
     },
     "ui": {
       "skill": "design",

package/scripts/gds/doc-cli-guard.js

@@ -15,7 +15,7 @@
 //
 // WHAT IT CHECKS, deliberately narrow: for every `node scripts/gds/<x>.js` in a
 // tracked .md, (a) the script exists, and (b) each `--flag` written next to it
-// appears in that script's source. Nothing else — this is not a prose linter.
+// appears in that script's source (or in a same-directory module it requires — a CLI may be carved into phase files). Nothing else — this is not a prose linter.
 //
 // STATIC ONLY, NEVER EXECUTED. The reason matters: running every documented CLI
 // would be slow, would need a session, and a command that blocks on a prompt
@@ -203,6 +203,38 @@ const readFileOrNull = (rel) => {
 
 const NAME = 'a doc that names a CLI matches the real CLI (G01)';
 
+// readCliSource — a CLI's source PLUS the source of the same-directory modules
+// it requires, concatenated.
+//
+// A big CLI is allowed to be more than one file: task 1003205 carved
+// scripts/gds/ship.js into ship-*.js phase modules, and the flag parsing for
+// e.g. `--no-surprise` moved with the phase that reads it. Scanning ship.js
+// alone then reports a documented, genuinely-honoured flag as a violation —
+// a false alarm that pushes the next agent toward silencing the rule via
+// DOC_CLI_ALLOW, which is exactly the outcome the rule exists to prevent.
+//
+// One level of same-directory relative requires is enough (it is where a carve
+// puts things) and keeps the read bounded. A missing sibling is skipped: the
+// point is to find the flag, not to prove the require graph.
+function readCliSource(rel) {
+  const src = readFileOrNull(rel);
+  if (src === null) return null;
+  const dir = path.dirname(rel);
+  const seen = new Set([rel]);
+  const parts = [src];
+  const RE = /require\(\s*['"](\.\/[^'"]+)['"]\s*\)/g;
+  let m;
+  while ((m = RE.exec(src))) {
+    let sib = path.join(dir, m[1]);
+    if (!sib.endsWith('.js')) sib += '.js';
+    if (seen.has(sib)) continue;
+    seen.add(sib);
+    const sibSrc = readFileOrNull(sib);
+    if (sibSrc !== null) parts.push(sibSrc);
+  }
+  return parts.join('\n');
+}
+
 function checkDocNamesRealCli({ files = null } = {}) {
   const docs = files || trackedMarkdown();
   // A lint that reports on nothing is worse than one that fails (the
@@ -217,7 +249,7 @@ function checkDocNamesRealCli({ files = null } = {}) {
   }
 
   const { violations, warnings, invocations } = scanDocs(docs, {
-    readDoc: readFileOrNull, readScript: readFileOrNull,
+    readDoc: readFileOrNull, readScript: readCliSource,
   });
 
   return {

package/scripts/gds/fitness-ratchets.js

@@ -215,12 +215,52 @@ function knipIssueCount() {
 
 // ---------- baseline + ratchet ----------
 
+// readBaselines — task 1003227. Returns { metrics, error }: `error` is a reason
+// string when the file cannot be trusted, null when it read cleanly.
+//
+// This used to `catch { return {}; }`, which made the gate FAIL OPEN. An empty
+// baseline map leaves every `floor === undefined`, and compareToBaselines classifies
+// an absent floor as a WARNING — so a checkout with no config/ reported the ratchet
+// as PASSED. Measured: with the baselines gone, a planted 5,000-line and 94-cycle
+// regression produced 0 violations. That is not a hypothetical checkout — `config/`
+// is absent from every dev box's sparse slice, so the builders who most needed the
+// gate were the ones silently exempt from it, learning from red CI instead.
+//
+// Distinguish the two absences, because they are not the same fact:
+//   - the FILE is missing/malformed  -> cannot verify anything -> hard fail (here);
+//   - a KEY is missing for one metric -> a genuinely new metric -> stays a warning
+//     in compareToBaselines, so adding a metric does not break the build.
+//
+// The file's own header says raising a baseline to pass CI is out of policy;
+// deleting the file must not be the loophole that raising it is not.
 function readBaselines() {
+  let raw;
   try {
-    return JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf8')).metrics || {};
-  } catch {
-    return {};
+    raw = fs.readFileSync(BASELINE_PATH, 'utf8');
+  } catch (e) {
+    const missing = e && e.code === 'ENOENT';
+    return {
+      metrics: {},
+      error: missing
+        ? `config/fitness-baselines.json is MISSING — the quality ratchet cannot verify anything, so it fails CLOSED rather than reporting a pass it did not check. `
+          + `If this is a dev box, config/ was historically outside the sparse checkout (task 1003227); re-sync the box (\`node scripts/gds/box-sync.js\`). `
+          + `To bootstrap a fresh baseline deliberately: node scripts/gds/fitness-ratchets.js --update-baselines`
+        : `config/fitness-baselines.json is unreadable (${e && e.message}) — failing CLOSED.`,
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return { metrics: {}, error: `config/fitness-baselines.json is not valid JSON (${e && e.message}) — failing CLOSED.` };
+  }
+  const metrics = parsed && typeof parsed.metrics === 'object' && parsed.metrics !== null
+    ? parsed.metrics
+    : null;
+  if (!metrics) {
+    return { metrics: {}, error: 'config/fitness-baselines.json has no "metrics" object — failing CLOSED.' };
   }
+  return { metrics, error: null };
 }
 
 // Pure ratchet verdict — exported for the hermetic test.
@@ -256,7 +296,11 @@ function computeMetrics({ withDocs = true } = {}) {
 // The fitness.js check (in-suite, hermetic — everything except knip).
 function checkQualityRatchets() {
   const metrics = computeMetrics();
-  const { violations, warnings } = compareToBaselines(metrics, readBaselines());
+  const { metrics: baselines, error: baselineError } = readBaselines();
+  const { violations, warnings } = compareToBaselines(metrics, baselines);
+  // task 1003227: an unreadable baseline file is a hard failure, not silence. Put it
+  // FIRST so it is the headline rather than buried under per-metric noise.
+  if (baselineError) violations.unshift(baselineError);
   return {
     name: 'quality ratchets — size, duplication, cycles, console, doc entropy only tighten (task 1003129)',
     hardFail: violations.length > 0,
@@ -274,7 +318,9 @@ function main() {
     const metrics = computeMetrics();
     const knip = knipIssueCount();
     if (knip !== null) metrics.knip_issue_count = knip;
-    const existing = readBaselines();
+    // The bootstrap path deliberately tolerates an absent file — writing it is the
+    // whole point — so it reads the metrics and ignores any error (task 1003227).
+    const { metrics: existing } = readBaselines();
     if (knip === null && existing.knip_issue_count !== undefined) metrics.knip_issue_count = existing.knip_issue_count;
     fs.writeFileSync(
       BASELINE_PATH,
@@ -290,7 +336,9 @@ function main() {
       console.warn('fitness-ratchets: WARN — knip not runnable here (no node_modules / npx failure); failing OPEN.');
       process.exit(0);
     }
-    const { violations, warnings } = compareToBaselines({ knip_issue_count: value }, readBaselines());
+    const { metrics: knipBaselines, error: knipBaselineError } = readBaselines();
+    const { violations, warnings } = compareToBaselines({ knip_issue_count: value }, knipBaselines);
+    if (knipBaselineError) violations.unshift(knipBaselineError);
     for (const w of warnings) console.warn(`fitness-ratchets: ${w}`);
     if (violations.length) {
       for (const v of violations) console.error(`fitness-ratchets: FAIL — ${v}`);

package/scripts/gds/fitness.js

@@ -1023,9 +1023,14 @@ const IDENTITY_SCAN_ALLOWED = {
   'scripts/gds/fitness.js': 2,
   'scripts/gds/package-core.js': 1,
   'scripts/gds/seed-v3-tasks.js': 14,
-  'scripts/gds/audit-replay.sh': 1,
-  'scripts/gds/db-backup-nightly.sh': 1,
-  'scripts/gds/db-backup-offsite.sh': 2,
+  // audit-replay.sh + db-backup-{nightly,offsite}.sh were carved out here as
+  // "host-pinned ops"; task 1002757 RETIRED that justification for them — each
+  // now resolves its database from the branding pack (the migrate.sh pattern) and
+  // fails loudly rather than defaulting, so their counts ratcheted to zero and the
+  // entries are gone. seed-staging.sh keeps its carve-out on the OPPOSITE
+  // rationale: its literal is a fail-CLOSED safety interlock (the script wipes
+  // STAGING_DB and refuses unless the name matches exactly), so on any other
+  // instance it declines to run instead of destroying the wrong database.
   'scripts/gds/seed-staging.sh': 4,
   'scripts/gds/backfill-sessions.js': 2,
   'scripts/gds/box.js': 3,
@@ -1649,7 +1654,6 @@ function checkWriteRoutesValidated() {
   };
 }
 
-
 // ── Check 19 — the ADR 0174 vocabulary wall (goal 1000068 R07, task 1003008) ──
 //
 // "Role" means ONE thing in this codebase: a craft — Artist, Ideator, or Builder.

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

@@ -1,13 +1,24 @@
+# TEMPLATE — not installable as-is (task 1002757). The __TOKENS__ below MUST be
+# substituted at install time; a provisioned instance gets a correct per-instance
+# unit pair generated by scripts/gds/provision.js (task 2213) and never needs this
+# file. Substitute:
+#   __SERVICE_USER__     the unix user that owns the instance + its Postgres role
+#   __INSTANCE_ROOT__    the instance checkout root (docs live under it)
+#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/gds dir:
+#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/gds
+#                          full clone: <instance-root>/scripts/gds
+#   __CONFIG_DIR__       the instance config dir name (offsite unit only)
+# One-liner: sed -e 's|__SERVICE_USER__|<user>|g' -e … gds-db-backup.service | sudo tee /etc/systemd/system/…
 [Unit]
 Description=Nightly pg_dump of GDS Postgres DB (filed by #412)
-Documentation=file:///home/lars/amazonprimea/docs/recipes/gds-db-backup.md
+Documentation=file://__INSTANCE_ROOT__/docs/recipes/gds-db-backup.md
 After=postgresql.service
 Requires=postgresql.service
 
 [Service]
 Type=oneshot
-User=lars
-Group=lars
+User=__SERVICE_USER__
+Group=__SERVICE_USER__
 # 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.
 #
@@ -25,7 +36,7 @@ Group=lars
 #   vendored/standalone: /home/<user>/<instance>/node_modules/@bongos/core/scripts/gds/db-backup-nightly.sh
 #   full clone:          /home/<user>/<repo>/scripts/gds/db-backup-nightly.sh
 # See docs/recipes/gds-db-backup.md.
-ExecStart=/usr/bin/env bash /home/lars/amazonprimea/scripts/gds/db-backup-nightly.sh
+ExecStart=/usr/bin/env bash __CORE_SCRIPTS_DIR__/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

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

@@ -1,6 +1,17 @@
+# TEMPLATE — not installable as-is (task 1002757). The __TOKENS__ below MUST be
+# substituted at install time; a provisioned instance gets a correct per-instance
+# unit pair generated by scripts/gds/provision.js (task 2213) and never needs this
+# file. Substitute:
+#   __SERVICE_USER__     the unix user that owns the instance + its Postgres role
+#   __INSTANCE_ROOT__    the instance checkout root (docs live under it)
+#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/gds dir:
+#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/gds
+#                          full clone: <instance-root>/scripts/gds
+#   __CONFIG_DIR__       the instance config dir name (offsite unit only)
+# One-liner: sed -e 's|__SERVICE_USER__|<user>|g' -e … gds-db-backup.service | sudo tee /etc/systemd/system/…
 [Unit]
 Description=Daily timer for GDS DB pg_dump (filed by #412)
-Documentation=file:///home/lars/amazonprimea/docs/recipes/gds-db-backup.md
+Documentation=file://__INSTANCE_ROOT__/docs/recipes/gds-db-backup.md
 
 [Timer]
 # Run every day at 04:00 UTC. That's a low-traffic window for a

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

@@ -1,13 +1,24 @@
+# TEMPLATE — not installable as-is (task 1002757). The __TOKENS__ below MUST be
+# substituted at install time; a provisioned instance gets a correct per-instance
+# unit pair generated by scripts/gds/provision.js (task 2213) and never needs this
+# file. Substitute:
+#   __SERVICE_USER__     the unix user that owns the instance + its Postgres role
+#   __INSTANCE_ROOT__    the instance checkout root (docs live under it)
+#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/gds dir:
+#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/gds
+#                          full clone: <instance-root>/scripts/gds
+#   __CONFIG_DIR__       the instance config dir name (offsite unit only)
+# One-liner: sed -e 's|__SERVICE_USER__|<user>|g' -e … gds-db-backup.service | sudo tee /etc/systemd/system/…
 [Unit]
 Description=Weekly offsite archive of GDS Postgres dumps to DigitalOcean Spaces (filed by #415)
-Documentation=file:///home/lars/amazonprimea/docs/recipes/gds-db-backup.md
+Documentation=file://__INSTANCE_ROOT__/docs/recipes/gds-db-backup.md
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=oneshot
-User=lars
-Group=lars
+User=__SERVICE_USER__
+Group=__SERVICE_USER__
 # 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.
 #
@@ -18,12 +29,12 @@ Group=lars
 # this unit would have hit it on its first run.
 #
 # EDIT THIS PATH when installing (layout differs — vendored vs full clone).
-ExecStart=/usr/bin/env bash /home/lars/amazonprimea/scripts/gds/db-backup-offsite.sh
+ExecStart=/usr/bin/env bash __CORE_SCRIPTS_DIR__/db-backup-offsite.sh
 # S3 credentials for the Space live outside the repo (ADR 0022). systemd
 # injects them; the file is chmod 600, owned by lars. Missing-file is
 # tolerated here (the script fails loudly if the vars are unset) so a
 # fresh install doesn't fail to load the unit before creds are dropped in.
-EnvironmentFile=-/etc/amazonprimea/spaces.env
+EnvironmentFile=-/etc/__CONFIG_DIR__/spaces.env
 # Hardening — the script reads dumps from /var/backups/gds and talks to the
 # network. It needs no write access to the local filesystem.
 NoNewPrivileges=true