@bongos/core 1.17.0

package/scripts/gds/newcomer-floor.test.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// Pure-helper tests for the deterministic newcomer floor replenisher
+// (task 1158; multi-chore-per-discipline since task 1488).
+//
+// Co-located with the script rather than in tests/*.mjs. The repo's
+// run-unit-tests.js gate only scans tests/, so tests/newcomer_floor.mjs is a thin
+// shim that require()s THIS file so it runs in the gate. Covers the pure logic
+// (per-chore deficit math, per-template floor resolution, monotonic per-instance
+// source_ref seq, ref decomposition, template->copy building + scope-clamp,
+// description assembly) and the integrity of the real templates.json. Runnable:
+//
+//   node scripts/gds/newcomer-floor.test.js
+//
+// Exits non-zero on first failure.
+
+const assert = require('node:assert');
+const path = require('node:path');
+const nf = require('./newcomer-floor');
+
+let passed = 0;
+function test(name, fn) {
+  try { fn(); passed += 1; }
+  catch (err) { console.error(`✗ ${name}\n  ${err.message}`); process.exit(1); }
+}
+
+// per-discipline DEFAULT floors (the fallback when a template omits its own).
+const FLOOR_DEFAULTS = { engineer: 2, artist: 3, ideator: 2 };
+
+// templates-by-discipline fixture (each discipline -> LIST of chores).
+const TEMPLATES = {
+  engineer: [
+    { template_id: 'unit-test-pass', version_id: 'GDS-V4', discipline: 'engineer', floor: 2, title: 'Add a unit test', done_when: ['a', 'b'], est_minutes: 45 },
+    { template_id: 'docs-hygiene-pass', version_id: 'GDS-V4', discipline: 'engineer', floor: 1, title: 'Docs sweep', done_when: ['a', 'b'], est_minutes: 40 },
+  ],
+  artist: [
+    { template_id: 'asset-generate-pass', version_id: 'V2', discipline: 'artist', title: 'Asset', done_when: ['a', 'b'], est_minutes: 55 }, // no own floor -> default
+  ],
+};
+
+// ---- templateFloor ----
+
+test('templateFloor: own floor wins over the discipline default', () => {
+  assert.strictEqual(nf.templateFloor({ floor: 5 }, 'engineer', FLOOR_DEFAULTS), 5);
+});
+
+test('templateFloor: falls back to the discipline default when omitted', () => {
+  assert.strictEqual(nf.templateFloor({}, 'artist', FLOOR_DEFAULTS), 3);
+});
+
+test('templateFloor: 0 is a valid explicit floor (not treated as missing)', () => {
+  assert.strictEqual(nf.templateFloor({ floor: 0 }, 'engineer', FLOOR_DEFAULTS), 0);
+});
+
+test('templateFloor: unknown discipline with no default -> 0', () => {
+  assert.strictEqual(nf.templateFloor({}, 'nope', FLOOR_DEFAULTS), 0);
+});
+
+// ---- computeTemplateDeficits ----
+
+function deficitFor(rows, templateId) {
+  return rows.find((r) => r.template_id === templateId);
+}
+
+test('computeTemplateDeficits: empty supply -> each chore needs its full floor', () => {
+  const rows = nf.computeTemplateDeficits({}, TEMPLATES, FLOOR_DEFAULTS);
+  assert.strictEqual(deficitFor(rows, 'unit-test-pass').needed, 2);
+  assert.strictEqual(deficitFor(rows, 'docs-hygiene-pass').needed, 1);
+  assert.strictEqual(deficitFor(rows, 'asset-generate-pass').needed, 3, 'artist uses the default floor');
+});
+
+test('computeTemplateDeficits: ready + backlog both count as supply (idempotency)', () => {
+  const supply = { 'engineer:unit-test-pass': { ready: 1, backlog: 1 } }; // fills floor 2
+  const rows = nf.computeTemplateDeficits(supply, TEMPLATES, FLOOR_DEFAULTS);
+  assert.strictEqual(deficitFor(rows, 'unit-test-pass').needed, 0);
+  assert.strictEqual(deficitFor(rows, 'docs-hygiene-pass').needed, 1, 'sibling chore is independent');
+});
+
+test('computeTemplateDeficits: supply is per-template, not shared across a discipline', () => {
+  // over-supplying one engineer chore must NOT satisfy the other.
+  const supply = { 'engineer:unit-test-pass': { ready: 9, backlog: 0 } };
+  const rows = nf.computeTemplateDeficits(supply, TEMPLATES, FLOOR_DEFAULTS);
+  assert.strictEqual(deficitFor(rows, 'unit-test-pass').needed, 0);
+  assert.strictEqual(deficitFor(rows, 'docs-hygiene-pass').needed, 1);
+});
+
+test('computeTemplateDeficits: over-supply never goes negative', () => {
+  const supply = { 'artist:asset-generate-pass': { ready: 10, backlog: 0 } };
+  const rows = nf.computeTemplateDeficits(supply, TEMPLATES, FLOOR_DEFAULTS);
+  assert.strictEqual(deficitFor(rows, 'asset-generate-pass').needed, 0);
+});
+
+test('computeTemplateDeficits: only-filter narrows to one discipline', () => {
+  const rows = nf.computeTemplateDeficits({}, TEMPLATES, FLOOR_DEFAULTS, { only: 'artist' });
+  assert.deepStrictEqual([...new Set(rows.map((r) => r.discipline))], ['artist']);
+});
+
+test('computeTemplateDeficits: ignores non-floor disciplines', () => {
+  const rows = nf.computeTemplateDeficits({}, { unclassified: [{ template_id: 'x', floor: 9 }] }, { unclassified: 9 });
+  assert.deepStrictEqual(rows, []);
+});
+
+// ---- instanceSourceRef + parseSeq + parseRef ----
+
+test('instanceSourceRef: tmpl:<disc>:<template_id>:<seq>', () => {
+  assert.strictEqual(nf.instanceSourceRef('engineer', 'unit-test-pass', 7), 'tmpl:engineer:unit-test-pass:7');
+});
+
+test('parseSeq: returns seq only for the matching discipline+template', () => {
+  assert.strictEqual(nf.parseSeq('tmpl:engineer:unit-test-pass:4', 'engineer', 'unit-test-pass'), 4);
+  assert.strictEqual(nf.parseSeq('tmpl:engineer:unit-test-pass:4', 'artist', 'unit-test-pass'), null, 'wrong discipline');
+  assert.strictEqual(nf.parseSeq('tmpl:engineer:other:4', 'engineer', 'unit-test-pass'), null, 'wrong template');
+  assert.strictEqual(nf.parseSeq('manual:engineer:some-title', 'engineer', 'unit-test-pass'), null, 'foreign ref');
+  assert.strictEqual(nf.parseSeq('tmpl:engineer:unit-test-pass:abc', 'engineer', 'unit-test-pass'), null, 'malformed seq');
+});
+
+test('parseRef: decomposes a chore ref into discipline/template/seq', () => {
+  assert.deepStrictEqual(nf.parseRef('tmpl:engineer:unit-test-pass:7'), { discipline: 'engineer', templateId: 'unit-test-pass', seq: 7 });
+  assert.strictEqual(nf.parseRef('manual:engineer:x'), null, 'not a chore ref');
+  assert.strictEqual(nf.parseRef('tmpl:engineer:unit-test-pass:0'), null, 'seq must be positive');
+  assert.strictEqual(nf.parseRef('tmpl:engineer:unit-test-pass'), null, 'too few parts');
+  assert.strictEqual(nf.parseRef('tmpl:a:b:c:d'), null, 'too many parts');
+});
+
+// ---- nextSeq (monotonic across all refs) ----
+
+test('nextSeq: empty set -> 1', () => {
+  assert.strictEqual(nf.nextSeq(new Set(), 'engineer', 'unit-test-pass'), 1);
+});
+
+test('nextSeq: 1 + max matching seq, ignoring other templates/disciplines', () => {
+  const refs = new Set([
+    'tmpl:engineer:unit-test-pass:1',
+    'tmpl:engineer:unit-test-pass:3', // gap is fine; max is 3
+    'tmpl:engineer:unit-test-pass:2',
+    'tmpl:engineer:docs-hygiene-pass:9', // sibling chore — ignored
+    'tmpl:artist:asset-generate-pass:5', // different discipline — ignored
+    'manual:engineer:something',         // foreign — ignored
+  ]);
+  assert.strictEqual(nf.nextSeq(refs, 'engineer', 'unit-test-pass'), 4);
+  assert.strictEqual(nf.nextSeq(refs, 'engineer', 'docs-hygiene-pass'), 10, 'sibling seq is independent');
+  assert.strictEqual(nf.nextSeq(refs, 'ideator', 'idea-seed-pass'), 1);
+});
+
+test('nextSeq: never recycles a shipped/abandoned seq (max over ALL statuses)', () => {
+  const refs = new Set(['tmpl:ideator:idea-seed-pass:1', 'tmpl:ideator:idea-seed-pass:2']);
+  assert.strictEqual(nf.nextSeq(refs, 'ideator', 'idea-seed-pass'), 3);
+});
+
+// ---- buildProposalFromTemplate ----
+
+const SAMPLE_TEMPLATE = {
+  template_id: 'docs-hygiene-pass',
+  version_id: 'GDS-V4',
+  discipline: 'engineer',
+  kind: 'cleanup',
+  est_minutes: 40,
+  credits_reward: 15,
+  floor: 1,
+  title: '  Docs-hygiene sweep  ',
+  description: 'Body.',
+  done_when: ['a', 'b'],
+  touches: ['docs/', 42, ''],
+};
+
+test('buildProposalFromTemplate: carries fields, normalizes touches, sets seq ref', () => {
+  const p = nf.buildProposalFromTemplate(SAMPLE_TEMPLATE, 5, { discipline: 'engineer' });
+  assert.strictEqual(p.title, 'Docs-hygiene sweep', 'trimmed');
+  assert.strictEqual(p.version_id, 'GDS-V4');
+  assert.strictEqual(p.kind, 'cleanup');
+  assert.strictEqual(p.credits_reward, 15);
+  assert.strictEqual(p.est_minutes, 40);
+  assert.deepStrictEqual(p.touches, ['docs/', '42'], 'empties dropped, coerced to strings');
+  assert.strictEqual(p.source_ref, 'tmpl:engineer:docs-hygiene-pass:5');
+  assert.deepStrictEqual(p.done_when, ['a', 'b']);
+});
+
+test('buildProposalFromTemplate: clamps est_minutes to the 60-min hard cap', () => {
+  const over = nf.buildProposalFromTemplate({ ...SAMPLE_TEMPLATE, est_minutes: 120 }, 1);
+  assert.strictEqual(over.est_minutes, nf.HARD_MAX_MINUTES, '120 clamps to 60');
+  const bad = nf.buildProposalFromTemplate({ ...SAMPLE_TEMPLATE, est_minutes: -3 }, 1);
+  assert.strictEqual(bad.est_minutes, nf.HARD_MAX_MINUTES, 'non-positive -> ceiling');
+});
+
+test('buildProposalFromTemplate: null on a titleless template', () => {
+  assert.strictEqual(nf.buildProposalFromTemplate({ ...SAMPLE_TEMPLATE, title: '   ' }, 1), null);
+  assert.strictEqual(nf.buildProposalFromTemplate(null, 1), null);
+});
+
+// ---- buildDescription ----
+
+test('buildDescription: folds done-when + evergreen footer', () => {
+  const desc = nf.buildDescription(
+    { title: 't', description: 'Body text.', done_when: ['x', 'y'], est_minutes: 30 },
+    'engineer'
+  );
+  assert.ok(desc.includes('Body text.'));
+  assert.ok(desc.includes('**Done when:**'));
+  assert.ok(desc.includes('- x') && desc.includes('- y'));
+  assert.ok(desc.includes('Evergreen newcomer chore'), 'footer present');
+  assert.ok(desc.includes('engineer'), 'discipline in footer');
+});
+
+// ---- loadTemplates: the REAL templates.json is well-formed (multi-chore shape) ----
+
+test('loadTemplates: real templates.json is a valid per-discipline list', () => {
+  const templates = nf.loadTemplates(path.join(__dirname, 'newcomer-floor.templates.json'));
+  for (const disc of ['engineer', 'artist', 'ideator']) {
+    const list = templates[disc];
+    assert.ok(Array.isArray(list) && list.length >= 1, `${disc} is a non-empty list`);
+    for (const t of list) {
+      assert.strictEqual(t.discipline, disc, `${disc} chore discipline matches its key`);
+      assert.ok(t.template_id && t.title && t.version_id, `${disc} chore has template_id/title/version_id`);
+      assert.ok(Array.isArray(t.done_when) && t.done_when.length >= 2, `${disc}/${t.template_id} has done-when bullets`);
+      assert.ok(t.est_minutes <= nf.HARD_MAX_MINUTES, `${disc}/${t.template_id} within the 60-min cap`);
+      assert.ok(Number.isFinite(Number(t.floor)) && t.floor >= 0, `${disc}/${t.template_id} has a numeric floor`);
+      const p = nf.buildProposalFromTemplate(t, 1, { discipline: disc });
+      assert.ok(p && p.source_ref === `tmpl:${disc}:${t.template_id}:1`, `${disc}/${t.template_id} stamps a clean copy`);
+    }
+  }
+});
+
+test('loadTemplates: engineer now offers BOTH the unit-test chore and the docs sweep', () => {
+  const templates = nf.loadTemplates(path.join(__dirname, 'newcomer-floor.templates.json'));
+  const ids = templates.engineer.map((t) => t.template_id);
+  assert.ok(ids.includes('unit-test-pass'), 'the safe coding chore is present');
+  assert.ok(ids.includes('docs-hygiene-pass'), 'the docs sweep is retained');
+  // every engineer chore touches only safe (non-protected) surfaces by design:
+  // touches[] is empty (git-merge is the collision detector), so this asserts the
+  // contract that engineer chores carry no protected-path touches.
+  for (const t of templates.engineer) {
+    assert.deepStrictEqual(t.touches || [], [], `${t.template_id} declares no touches[]`);
+  }
+});
+
+console.log(`✓ all ${passed} newcomer-floor pure-helper tests passed`);

package/scripts/gds/next-number.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// next-number.js — deterministic next-free ADR + migration numbers (V4.R26 / #964).
+//
+// WHY: ADR + migration numbers collided across parallel sessions. ADRs collided
+// because each session scanned its OWN (possibly stale) local tree and picked the
+// same "next" — the triple ADR-0044 collision (sessions 1660/1629) and the
+// ADR-0024 collision (idea 122). Migrations collided/drifted because the
+// claim-time DB counter is not reconciled against reality — it once handed out
+// 079 when 079 was already applied on prod, and today it sits ahead of the
+// committed files (counter ~099 while migrations/ tops out at 093), so the
+// "reserved" number is neither the next free one nor collision-proof.
+//
+// This helper computes the next free number from the AUTHORITATIVE union of:
+//   - files committed on origin/main  (git — the real "taken" set, shared by all
+//     parallel sessions, so everyone agrees on the baseline)
+//   - the local working tree          (so a file you added THIS session counts,
+//     even before it is committed)
+// next = max(union) + 1.
+//
+// FAIL-OPEN (V4 ethos: sessions stop fighting the machine room): if origin/main
+// is unreachable (offline, fresh clone, credential-less box) it falls back to the
+// local HEAD tree + working tree and flags the result `degraded` — it never throws
+// and never blocks a claim.
+//
+// Usage:
+//   node scripts/gds/next-number.js           # human-readable
+//   node scripts/gds/next-number.js --json     # {"adr":58,"migration":94,...}
+//
+// Pure helpers (parseNumbers, nextFree, computeNextNumbers) + the sync facade
+// (nextNumbers) are exported for unit tests (tests/next_number.mjs).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { migrationNumberOf, CORE_NS } = require('./migration-namespace');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const ADR_DIR = 'docs/adr';
+const MIGRATIONS_DIR = 'migrations';
+
+// ADRs are NNNN-slug.md (4-digit). Migration numbers are parsed via migration-namespace's
+// migrationNumberOf so BOTH the legacy bare form (NNN_slug.sql) AND the namespaced form
+// (core_NNN_slug.sql / <key>_NNN_slug.sql, ADR 0108 §5) count toward the next-free number —
+// otherwise the first core_-prefixed file would be undercounted and its number reused.
+const ADR_RE = /^(\d{4})-.*\.md$/;
+
+// Extract the numeric prefixes matching `re` from a list of basenames → Set<int>.
+function parseNumbers(basenames, re) {
+  const out = new Set();
+  for (const name of basenames || []) {
+    const m = re.exec(name);
+    if (m) out.add(parseInt(m[1], 10));
+  }
+  return out;
+}
+
+// next free = max + 1; an empty set starts the sequence at `start`.
+function nextFree(numberSet, start = 1) {
+  let max = -Infinity;
+  for (const n of numberSet) if (n > max) max = n;
+  return max === -Infinity ? start : max + 1;
+}
+
+// PURE core: given two lists of repo-relative paths (committed + local), compute
+// the next free ADR + migration number. `start*` let callers pin the sequence
+// floor; defaults match the real repo (ADRs from 1, migrations from 1).
+function computeNextNumbers({ committedPaths = [], localPaths = [], startAdr = 1, startMigration = 1 } = {}) {
+  const baseName = (p) => p.split('/').pop();
+  const inDir = (p, dir) => p.startsWith(dir + '/');
+  const allPaths = [...committedPaths, ...localPaths];
+
+  const adrNames = allPaths.filter((p) => inDir(p, ADR_DIR)).map(baseName);
+  const migNames = allPaths.filter((p) => inDir(p, MIGRATIONS_DIR)).map(baseName);
+
+  const adrSet = parseNumbers(adrNames, ADR_RE);
+  // Count bare AND namespaced migration files (ADR 0108 §5): migrationNumberOf(...) parses
+  // both `NNN_x.sql` and `core_NNN_x.sql`/`<key>_NNN_x.sql`, so a prefixed file is never
+  // undercounted (which would hand its number out again).
+  const migSet = new Set(migNames.map(migrationNumberOf).filter((n) => n != null));
+
+  return {
+    adr: nextFree(adrSet, startAdr),
+    migration: nextFree(migSet, startMigration),
+    highestAdr: adrSet.size ? Math.max(...adrSet) : null,
+    highestMigration: migSet.size ? Math.max(...migSet) : null,
+  };
+}
+
+// ---- I/O facade (injectable for tests) -------------------------------------
+
+// List repo-relative paths under `dirs` committed on `ref`, via git. Returns []
+// (not throw) if the ref/repo is unavailable — the caller decides degraded-ness.
+function gitTreePaths(ref, dirs, runGit) {
+  try {
+    const out = runGit(['ls-tree', '-r', '--name-only', ref, '--', ...dirs]);
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return null; // signal: ref unreachable
+  }
+}
+
+// List repo-relative paths under `dir` in the local working tree.
+function localDirPaths(dir, readDir) {
+  try {
+    return readDir(path.join(REPO_ROOT, dir)).map((name) => `${dir}/${name}`);
+  } catch {
+    return [];
+  }
+}
+
+const defaultRunGit = (args) =>
+  execFileSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+const defaultReadDir = (p) => fs.readdirSync(p);
+
+// SYNC facade used by claim.js + the CLI. Pulls the committed set from
+// origin/main (fail-open to HEAD, then to local-only) and unions the working
+// tree. Returns the numbers plus which source answered (for an honest print).
+function nextNumbers({ runGit = defaultRunGit, readDir = defaultReadDir } = {}) {
+  const dirs = [ADR_DIR, MIGRATIONS_DIR];
+  let committedPaths = gitTreePaths('origin/main', dirs, runGit);
+  let source = 'origin/main';
+  let degraded = false;
+  if (committedPaths === null) {
+    committedPaths = gitTreePaths('HEAD', dirs, runGit);
+    source = 'HEAD';
+    degraded = true;
+  }
+  if (committedPaths === null) {
+    committedPaths = [];
+    source = 'local-only';
+    degraded = true;
+  }
+  const localPaths = [...localDirPaths(ADR_DIR, readDir), ...localDirPaths(MIGRATIONS_DIR, readDir)];
+  const nums = computeNextNumbers({ committedPaths, localPaths });
+  return { ...nums, source, degraded };
+}
+
+const padAdr = (n) => String(n).padStart(4, '0');
+const padMig = (n) => String(n).padStart(3, '0');
+
+function main() {
+  const json = process.argv.includes('--json');
+  const r = nextNumbers();
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      adr: r.adr, migration: r.migration,
+      adr_padded: padAdr(r.adr), migration_padded: padMig(r.migration),
+      source: r.source, degraded: r.degraded,
+    }) + '\n');
+    return;
+  }
+  console.log(`Next free ADR:        ${padAdr(r.adr)}   →  docs/adr/${padAdr(r.adr)}-<slug>.md`);
+  // New CORE migrations are namespaced ${CORE_NS}_ (ADR 0108 §5) so their stem can't collide
+  // with an instance/module migration across repos. Instance seeds stay bare in
+  // migrations/instance/; a module migration is <key>_${padMig(r.migration)}_… in its own dir.
+  console.log(`Next free migration:  ${padMig(r.migration)}   →  migrations/${CORE_NS}_${padMig(r.migration)}_<slug>.sql   (core; instance seeds stay bare → migrations/instance/${padMig(r.migration)}_<slug>.sql)`);
+  console.log(`(from ${r.source} ∪ local working tree)${r.degraded ? '  ⚠ origin/main unreachable — verify before committing' : ''}`);
+}
+
+if (require.main === module) main();
+
+module.exports = { parseNumbers, nextFree, computeNextNumbers, nextNumbers, gitTreePaths, padAdr, padMig };

package/scripts/gds/oauth-secret.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/oauth-secret.js — SHELL-INDEPENDENT, VERIFIED placement of a
+// provisioned instance's GitHub OAuth App credentials (BONGOS-V1 goal 35, task 1979).
+//
+// WHY. During the Emersonian standup the manual hidden-input shell command used to
+// place the GitHub OAuth client secret failed SILENTLY on the server shell, leaving a
+// 26-char truncated value in web.env that broke sign-in with no obvious cause. The
+// onboarding flow needs a secret-placement step that is:
+//   (1) SHELL-INDEPENDENT — a Node rewrite of the specific env line, never a fragile
+//       `read -s`/`sed -i` that can truncate or silently no-op;
+//   (2) VALIDATED before it is written — length + charset checks that CATCH the 26-char
+//       truncation the runtime auth_configured probe MISSES (authConfigured() only
+//       checks PRESENCE, not validity — a truncated-but-present secret passes it);
+//   (3) VERIFIED after the service restarts — probe GET /healthz and assert
+//       auth_configured:true, so onboarding never "proceeds" past broken auth.
+// It APPLIES TO EVERY FORM of the flow — the /new-project skill (task 1981), the
+// `bongos onboard` CLI (task 1982), and the hall wizard (task 1983) drive it.
+//
+// Control-plane tool (like provision.js): it rewrites /etc/<slug>/web.env (chmod 600)
+// and restarts the instance's systemd unit, so it runs on the box, never the web tier.
+// DRY-RUN by DEFAULT: without --apply it validates + prints the plan and mutates nothing.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const cp = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+// Mirrors provision.js conventions (kept in lockstep — ADR 0111 / provision.js).
+const ETC_BASE = process.env.PROVISION_ETC_BASE || '/etc';
+const PROVISIONED_BRANDING_FILE = 'config/branding.neutral.json';
+
+// A GitHub OAuth App client SECRET is a 40-char hex string (classic); GitHub may issue
+// longer. Require a sane MINIMUM (catches the 26-char truncation) + a charset no real
+// secret violates; do NOT hard-cap length.
+const SECRET_MIN_LEN = 40;
+// A client ID: classic 20 hex chars, or an 'Iv1.'/'Iv23'/'Ov23' App prefix.
+const CLIENT_ID_MIN_LEN = 20;
+const PLACEHOLDER_RE = /^(x{3,}|placeholder|change[-_]?me|todo|your[-_]?(client[-_]?)?(id|secret))$/i;
+
+function validateClientSecret(secret) {
+  const s = String(secret == null ? '' : secret).trim();
+  if (!s) return { ok: false, reason: 'empty — no client secret provided' };
+  if (PLACEHOLDER_RE.test(s)) return { ok: false, reason: `looks like a placeholder ("${s.slice(0, 16)}")` };
+  if (s.length < SECRET_MIN_LEN) return { ok: false, reason: `too short (${s.length} chars; a GitHub OAuth client secret is ≥ ${SECRET_MIN_LEN}) — likely truncated by a silent shell failure (the task-1979 bug)` };
+  if (!/^[A-Za-z0-9._-]+$/.test(s)) return { ok: false, reason: 'contains characters no GitHub client secret uses (whitespace/quotes?) — likely a bad paste' };
+  return { ok: true };
+}
+
+function validateClientId(id) {
+  const s = String(id == null ? '' : id).trim();
+  if (!s) return { ok: false, reason: 'empty — no client id provided' };
+  if (PLACEHOLDER_RE.test(s)) return { ok: false, reason: `looks like a placeholder ("${s.slice(0, 16)}")` };
+  if (s.length < CLIENT_ID_MIN_LEN) return { ok: false, reason: `too short (${s.length} chars; a GitHub OAuth client id is ≥ ${CLIENT_ID_MIN_LEN})` };
+  if (!/^[A-Za-z0-9._]+$/.test(s)) return { ok: false, reason: 'contains unexpected characters — likely a bad paste' };
+  return { ok: true };
+}
+
+// The env-var prefix the provisioned instance resolves (the neutral pack's envPrefix,
+// mirroring provision.js provisionedEnvPrefix — the creds MUST be written under this
+// prefix or src/branding + auth never read them, task 1972). Fail-soft to CLOUDBONGOS.
+function provisionedEnvPrefix() {
+  try {
+    const pack = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, PROVISIONED_BRANDING_FILE), 'utf8'));
+    return pack.envPrefix || 'CLOUDBONGOS';
+  } catch { return 'CLOUDBONGOS'; }
+}
+
+function webEnvPath(slug, { etcBase = ETC_BASE } = {}) {
+  return path.posix.join(etcBase, slug, 'web.env');
+}
+
+// Rewrite the CLIENT_ID / CLIENT_SECRET lines of a web.env body IN PLACE, matching the
+// pack's env prefix. PURE string transform — this IS the shell-independent placement
+// (no `read -s`, no `sed -i`). THROWS if a target key line is absent, so a
+// mismatched-prefix web.env can never silently no-op (the failure mode task 1979 hits).
+function fillOAuthEnv(body, { prefix, clientId, clientSecret }) {
+  const esc = (k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const setKey = (text, key, value) => {
+    const re = new RegExp(`^(${esc(key)})=.*$`, 'm');
+    if (!re.test(text)) throw new Error(`web.env has no "${key}=" line to fill (env-prefix mismatch?)`);
+    return text.replace(re, `$1=${value}`);
+  };
+  let out = body;
+  if (clientId != null) out = setKey(out, `${prefix}_GITHUB_CLIENT_ID`, clientId);
+  if (clientSecret != null) out = setKey(out, `${prefix}_GITHUB_CLIENT_SECRET`, clientSecret);
+  return out;
+}
+
+// The PORT= line a web.env carries (provision.js writes it) — the healthz probe target.
+function portFromEnv(body) {
+  const m = /^PORT=(\d+)$/m.exec(String(body || ''));
+  return m ? Number(m[1]) : null;
+}
+
+// Parse the /healthz JSON the post-restart probe returns → { ok, authConfigured }.
+function parseHealthzAuth(stdout) {
+  try {
+    const j = JSON.parse(String(stdout || '').trim());
+    return { ok: j.ok !== false, authConfigured: j.auth_configured === true };
+  } catch { return { ok: false, authConfigured: false, parseError: true }; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI: place <slug> --client-id ID --client-secret SECRET [--apply] [--port N]
+// ---------------------------------------------------------------------------
+function argVal(args, name) { const i = args.indexOf(name); return i >= 0 && i + 1 < args.length ? args[i + 1] : null; }
+
+function usage() {
+  console.log(`oauth-secret.js — verified, shell-independent OAuth-secret placement (ADR 0111, task 1979)
+
+Usage:
+  node scripts/gds/oauth-secret.js place <slug> --client-id <id> --client-secret <secret> [--apply] [--port <n>]
+
+Validates the creds (length/format — CATCHES the silent-truncation bug), rewrites the
+CLIENT_ID/CLIENT_SECRET lines of /etc/<slug>/web.env via Node (no fragile shell input),
+restarts the instance's systemd unit, then PROBES /healthz to confirm auth_configured.
+DRY-RUN by default; --apply performs the write + restart + probe on the control plane.`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { usage(); process.exit(0); }
+  if (cmd !== 'place') { console.error(`unknown command: ${cmd}\n`); usage(); process.exit(2); }
+  const slug = args[1] && !args[1].startsWith('--') ? args[1] : null;
+  if (!slug) { console.error('place needs a <slug>'); process.exit(2); }
+  const apply = args.includes('--apply');
+  const clientId = argVal(args, '--client-id');
+  const clientSecret = argVal(args, '--client-secret');
+
+  // (1) VALIDATE before touching anything — the truncation guard.
+  const idV = validateClientId(clientId);
+  const secV = validateClientSecret(clientSecret);
+  const problems = [];
+  if (!idV.ok) problems.push(`client id: ${idV.reason}`);
+  if (!secV.ok) problems.push(`client secret: ${secV.reason}`);
+  if (problems.length) {
+    console.error('✖ OAuth creds rejected before placement (nothing written):');
+    for (const p of problems) console.error(`   - ${p}`);
+    process.exit(2);
+  }
+  console.log('✓ creds validated (length + charset)');
+
+  const prefix = provisionedEnvPrefix();
+  const envPath = webEnvPath(slug);
+  let body;
+  try { body = fs.readFileSync(envPath, 'utf8'); }
+  catch (e) { console.error(`cannot read ${envPath}: ${e.message} — is ${slug} provisioned on this control plane?`); process.exit(1); }
+
+  // (2) SHELL-INDEPENDENT placement — rewrite the specific env lines via Node.
+  let next;
+  try { next = fillOAuthEnv(body, { prefix, clientId, clientSecret }); }
+  catch (e) { console.error(`✖ ${e.message}`); process.exit(1); }
+
+  const port = argVal(args, '--port') ? Number(argVal(args, '--port')) : portFromEnv(next);
+
+  if (!apply) {
+    console.log(`[dry-run] would rewrite ${envPath} (${prefix}_GITHUB_CLIENT_ID/_SECRET), chmod 600`);
+    console.log(`[dry-run] would restart systemd unit ${slug}, then probe http://127.0.0.1:${port || '<port>'}/healthz for auth_configured`);
+    console.log('re-run with --apply to place + verify.');
+    process.exit(0);
+  }
+
+  fs.writeFileSync(envPath, next, { mode: 0o600 });
+  fs.chmodSync(envPath, 0o600);
+  console.log(`✓ wrote ${envPath} (chmod 600)`);
+  cp.execSync(`systemctl restart ${slug}`, { stdio: 'inherit' });
+  console.log(`✓ restarted ${slug}`);
+
+  // (3) VERIFY — probe /healthz for auth_configured (retry briefly for restart).
+  if (!port) { console.error('✖ no PORT in web.env and no --port given — cannot probe /healthz'); process.exit(1); }
+  let probe = { authConfigured: false };
+  for (let i = 0; i < 10; i++) {
+    try {
+      const out = cp.execSync(`curl -sS --max-time 5 http://127.0.0.1:${port}/healthz`, { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+      probe = parseHealthzAuth(out);
+      if (probe.ok || probe.authConfigured) break;
+    } catch { /* not up yet */ }
+    cp.execSync('sleep 1');
+  }
+  if (!probe.authConfigured) {
+    console.error(`✖ post-restart probe: /healthz reports auth_configured=false — the instance still cannot authenticate. Do NOT proceed; recheck the OAuth app creds.`);
+    process.exit(1);
+  }
+  console.log('✓ verified: /healthz reports auth_configured=true — sign-in is live');
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  SECRET_MIN_LEN, CLIENT_ID_MIN_LEN,
+  validateClientSecret, validateClientId,
+  provisionedEnvPrefix, webEnvPath, fillOAuthEnv, portFromEnv, parseHealthzAuth,
+};