@bongos/core 1.18.19 → 1.19.3

package/scripts/gds/gating.js

@@ -2,18 +2,25 @@
 // 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).
+//   1. GitHub branch protection on `main`: required status checks + required
+//      code-owner review (CODEOWNERS). The required contexts are ONLY checks
+//      that exist and can pass today — currently `unit` (the suite + fitness
+//      lane, task 1002610). The planned `secret-scan` and `gate-review`
+//      contexts (ADR 0058 phase 3; CORE_EXPECTED_CHECKS in adopt-preflight.js)
+//      join DEFAULT_PROTECTION when their workflows ship — requiring a context
+//      nothing reports blocks every merge indefinitely (D-12, ADR 0159).
 //   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
+//      and grade-gate CI workflows (ADR 0058 phases 1-3; NOT YET IN THE TREE —
+//      workflowState() reports them 'absent' and the toggles below no-op until
+//      they ship). Once live they 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.
+// session) merges with no checks and no approval. `unit` keeps running either
+// way — a real safety net that forces 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,
@@ -47,19 +54,27 @@ const SNAPSHOT = require('../../src/instance-config').configPath('gating-snapsho
 // 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.
+// also disables/enables these workflows. PLANNED, not yet in the tree (ADR 0058
+// phases 1-3): while absent, workflowState() reports 'absent' and both toggles
+// no-op — the names stay here so the switch covers them the moment they ship.
+// `unit` is deliberately left running — a real safety net that forces 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.
+// Baked-in known-good config. Used only as a restore fallback when no snapshot
+// exists, so `on` can never be stuck. Requires ONLY contexts that exist and can
+// pass today (ADR 0159 — D-12: a required context nothing reports blocks every
+// merge indefinitely, and a required context that is red on every PR does the
+// same). When the secret-scan / gate-review workflows ship (ADR 0058), add
+// their contexts back here — those names are the contract (adopt-preflight.js
+// CORE_EXPECTED_CHECKS, init.js), tool-agnostic on purpose.
 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 },
+      // Stated intent, not yet requirable — uncomment as each workflow ships:
+      // { context: 'secret-scan', app_id: 15368 },  // secret scanning (ADR 0058)
+      // { context: 'gate-review', app_id: 15368 },  // gate-surface review (ADR 0058 phase 3)
     ],
   },
   enforce_admins: false,
@@ -270,7 +285,7 @@ function cmdOff(repo) {
 
   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('   with no checks and no approval. (unit still runs.)');
   console.log('   ↩  restore everything: node scripts/gds/gating.js on');
 }
 

package/scripts/gds/gen-api-docs.js

@@ -81,7 +81,7 @@ const RANK_BLURB = {
   public: 'No authentication — any caller.',
   'any-builder': 'Any authenticated builder (row-level ownership enforced in-handler).',
   'metic+archon': 'Metic or Archon rank (review/triage powers).',
-  archon: 'Archon only (the single owner — ratification, infra, rank changes).',
+  archon: 'Archon only (rank and identity management + the escalation keys — the trust boundary).',
   'bfg-principal': 'The BFG cross-builder memory service principal (not a human rank).',
   unknown: 'Gate could not be classified from source — treat as privileged.',
 };

package/scripts/gds/goal.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+// Goal board CLI — list goals, or show one goal's criteria + tasks + what to claim next.
+//
+// Usage:
+//   node scripts/gds/goal.js list [--version V] [--status open|achieved|archived|all]
+//   node scripts/gds/goal.js show <id>
+//
+// Read-only. Default list filter is --status open.
+
+const { cliClient, requireSession, arg } = require('./cli-lib');
+
+const GOAL_GLYPH = { open: '○', achieved: '✓', archived: '·' };
+const IN_FLIGHT = new Set(['active', 'completed', 'confirmed']);
+const LIST_STATUSES = ['open', 'achieved', 'archived', 'all'];
+
+function usageExit() {
+  console.error('usage: node scripts/gds/goal.js list [--version V] [--status open|achieved|archived|all]');
+  console.error('       node scripts/gds/goal.js show <id>');
+  process.exit(2);
+}
+
+// abandoned is a terminal state (deliberately cut), not pending work — excluded
+// from every denominator, the same rule migration 017 applies to version_progress.
+function liveTasks(tasks) {
+  return tasks.filter((t) => t.status !== 'abandoned');
+}
+
+function rollup(tasks) {
+  const live = liveTasks(tasks);
+  const shipped = live.filter((t) => t.status === 'shipped').length;
+  const ready = live.filter((t) => t.status === 'ready').length;
+  const inFlight = live.filter((t) => IN_FLIGHT.has(t.status)).length;
+  const parts = [`${shipped}/${live.length} shipped`];
+  if (inFlight) parts.push(`${inFlight} in flight`);
+  if (ready) parts.push(`${ready} ready`);
+  return parts.join(' · ');
+}
+
+async function list(api, args) {
+  const version = arg('--version', args) || null;
+  if (args.includes('--version') && (!version || !/^[\w.-]+$/.test(version))) usageExit();
+  const status = arg('--status', args) || 'open';
+  if (!LIST_STATUSES.includes(status)) usageExit();
+  const query = {};
+  if (version) query.version = version;
+  if (status !== 'all') query.status = status;
+
+  const g = await api.goals.getGoals({ query });
+  if (!g.ok) {
+    console.error('goals list failed:', JSON.stringify(g.data));
+    // process.exitCode (not process.exit): hard-exit while undici keep-alive
+    // sockets tear down trips a libuv assertion on Windows.
+    process.exitCode = 1;
+    return;
+  }
+  const goals = g.data.goals || [];
+  if (goals.length === 0) {
+    console.log('No goals match.');
+    return;
+  }
+
+  // One goal_id-filtered fetch per listed goal, in parallel — returns exactly
+  // the rows the rollups need, never a version-wide or table-wide over-fetch.
+  const results = await Promise.all(goals.map((goal) => api.tasks.getTasks({ query: { goal_id: goal.id } })));
+  const failed = results.find((r) => !r.ok);
+  if (failed) {
+    console.error('tasks fetch failed (rollups would be wrong):', JSON.stringify(failed.data));
+    process.exitCode = 1;
+    return;
+  }
+  const byGoal = new Map(goals.map((goal, i) => [String(goal.id), results[i].data.tasks || []]));
+
+  for (const goal of goals) {
+    const glyph = GOAL_GLYPH[goal.status] || '?';
+    const tasks = byGoal.get(String(goal.id)) || [];
+    const tail = liveTasks(tasks).length ? `  [${rollup(tasks)}]` : '';
+    console.log(`${glyph} #${goal.id}  ${goal.version_id}  ${goal.title}${tail}`);
+  }
+  console.log('');
+  console.log(`${goals.length} goal${goals.length === 1 ? '' : 's'} · node scripts/gds/goal.js show <id> for detail`);
+}
+
+function criterionGlyph(c) {
+  if (c.satisfied) return '✓';
+  if (c.pending_review) return '◇';
+  return '○';
+}
+
+function criterionState(c) {
+  if (c.satisfied) return 'satisfied';
+  if (c.pending_review) return 'met — pending review (/goal-review)';
+  const linked = Number(c.linked_tasks) || 0;
+  if (linked === 0) return 'no linked tasks yet';
+  const n = Number(c.unshipped_tasks) || 0;
+  return `${n} of ${linked} linked task${linked === 1 ? '' : 's'} unshipped`;
+}
+
+async function show(api, id) {
+  const [g, t] = await Promise.all([
+    api.goals.getGoalsId({ id }),
+    api.tasks.getTasks({ query: { goal_id: id } }),
+  ]);
+  if (!g.ok) {
+    console.error(`goal ${id} fetch failed:`, JSON.stringify(g.data));
+    process.exitCode = 1;
+    return;
+  }
+  if (!t.ok) {
+    console.error(`tasks fetch for goal ${id} failed:`, JSON.stringify(t.data));
+    process.exitCode = 1;
+    return;
+  }
+  const { goal, members, criteria, dependencies } = g.data;
+  const tasks = t.data.tasks || [];
+
+  console.log(`#${goal.id}  ${goal.title}`);
+  console.log(`${goal.version_id} · ${goal.status} · modules: ${(goal.scope_modules || []).join(', ') || '—'}`);
+  const allMembers = members || [];
+  const lead = allMembers.filter((m) => m.role === 'lead').map((m) => `@${m.github_login}`);
+  if (lead.length) {
+    console.log(`lead: ${lead.join(', ')}${allMembers.length > lead.length ? ` (+${allMembers.length - lead.length} members)` : ''}`);
+  } else if (allMembers.length) {
+    console.log(`members: ${allMembers.length} (no lead)`);
+  }
+  for (const d of dependencies || []) {
+    console.log(`prerequisite goal: #${d.id ?? d.goal_id} ${d.title || ''} ${d.satisfied ? '(satisfied)' : '(NOT satisfied)'}`);
+  }
+  if (goal.description) {
+    console.log('');
+    console.log(goal.description);
+  }
+
+  if ((criteria || []).length) {
+    console.log('');
+    console.log('Done-when criteria:');
+    for (const c of criteria) {
+      console.log(`  ${criterionGlyph(c)} ${c.criterion_id} — ${criterionState(c)}`);
+    }
+  }
+
+  if (tasks.length === 0) {
+    console.log('');
+    console.log('No tasks filed under this goal yet.');
+    return;
+  }
+  await printTaskBuckets(api, tasks);
+}
+
+// Pure bucketing, split from printing so it unit-tests without a live API.
+function bucketTasks(tasks) {
+  return {
+    shipped: tasks.filter((x) => x.status === 'shipped'),
+    inFlight: tasks.filter((x) => IN_FLIGHT.has(x.status)),
+    ready: tasks.filter((x) => x.status === 'ready'),
+    gated: tasks.filter((x) => x.status === 'backlog' || x.status === 'blocked'),
+    abandoned: tasks.filter((x) => x.status === 'abandoned'),
+  };
+}
+
+async function printTaskBuckets(api, tasks) {
+  const buckets = bucketTasks(tasks);
+  const live = liveTasks(tasks);
+
+  // Explain WHY each gated task waits — parallel, with per-task catch: one
+  // failed dependency fetch degrades to "dependencies unknown" for that task
+  // instead of aborting the listing.
+  const waits = new Map();
+  const waitsUnknown = new Set();
+  await Promise.all(buckets.gated.map(async (task) => {
+    try {
+      const d = await api.tasks.getTasksIdDependencies({ id: task.id });
+      if (!d.ok) { waitsUnknown.add(String(task.id)); return; }
+      const unshipped = (d.data.dependencies || []).filter((dep) => dep.status !== 'shipped');
+      if (unshipped.length) waits.set(String(task.id), unshipped.map((dep) => `task ${dep.id} (${dep.status})`).join(', '));
+    } catch {
+      waitsUnknown.add(String(task.id));
+    }
+  }));
+
+  console.log('');
+  const abandonedNote = buckets.abandoned.length ? `, ${buckets.abandoned.length} abandoned` : '';
+  console.log(`Tasks (${buckets.shipped.length}/${live.length} shipped${abandonedNote}):`);
+  for (const x of buckets.shipped) console.log(`  ✓ ${x.id}  ${x.title}`);
+  for (const x of buckets.inFlight) console.log(`  ▶ ${x.id}  ${x.title}  [${x.status}]`);
+  for (const x of buckets.ready) console.log(`  ● ${x.id}  ${x.title}  [ready — claimable now]`);
+  for (const x of buckets.gated) {
+    const key = String(x.id);
+    const why = waits.has(key) ? ` — waits on ${waits.get(key)}`
+      : waitsUnknown.has(key) ? ' — dependencies unknown (fetch failed)' : '';
+    console.log(`  ○ ${x.id}  ${x.title}  [${x.status}${why}]`);
+  }
+  for (const x of buckets.abandoned) console.log(`  ✕ ${x.id}  ${x.title}  [abandoned — excluded from progress]`);
+
+  console.log('');
+  if (buckets.ready.length) {
+    console.log(`Next: node scripts/gds/claim.js ${buckets.ready[0].id}`);
+  } else if (buckets.inFlight.length) {
+    console.log('Nothing claimable — work in flight must land first.');
+  } else if (buckets.gated.length) {
+    const allWait = buckets.gated.every((x) => waits.has(String(x.id)));
+    console.log(allWait
+      ? 'Nothing claimable — every remaining task waits on an unshipped dependency.'
+      : 'Nothing claimable — remaining tasks are backlog/blocked and not yet promoted to ready.');
+  } else if (live.length === 0) {
+    console.log('No live tasks — everything filed here was abandoned.');
+  } else {
+    console.log('All tasks shipped — run /goal-review to confirm criteria.');
+  }
+}
+
+async function main() {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  const api = await cliClient();
+
+  if (cmd === 'list') {
+    await list(api, args.slice(1));
+  } else if (cmd === 'show') {
+    if (!/^\d+$/.test(args[1] || '')) usageExit();
+    await show(api, Number(args[1]));
+  } else {
+    usageExit();
+  }
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('goal.js failed:', err && err.message ? err.message : err);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { rollup, criterionGlyph, criterionState, bucketTasks, liveTasks };

package/scripts/gds/init.js

@@ -258,6 +258,13 @@ function buildBrandingConfig(spec) {
     firstAdmin: spec.firstAdmin,
     currency: { label: (spec.currency && spec.currency.label) || 'credits', symbol: (spec.currency && spec.currency.symbol) || '' },
     envPrefix: spec.envPrefix || 'CLOUDBONGOS',
+    // Every instance gets its OWN session/config dir (task 1002626). Without
+    // this, instance-config.js falls back to the shared 'cloudbongos' dir, so
+    // every un-branded instance on a machine reads/writes the SAME
+    // ~/.config/cloudbongos/gds-session.json — signing in to one silently
+    // evicts the CLI session of every other, including the hub. Same slug
+    // family as the package name + provisioning slug.
+    configDir: spec.configDir ? String(spec.configDir).trim() : slugify(productName, 'instance'),
   };
   if (spec.tagline) branding.copy = { tagline: spec.tagline };
   return branding;
@@ -364,7 +371,11 @@ function kickoffTasks(spec) {
   if (!provisioningRequest(spec)) tasks.push(productionTopologyKickoff());
   tasks.push({
     title: 'Fill the instance look with your own LLM',
-    kind: 'ideator',
+    // 'ideator' is a DISCIPLINE, not a kind — tasks_kind_check rejects it as a
+    // kind and the task silently vanished from the checklist (the one non-infra
+    // kickoff step). Deciding the instance look is a decision by an ideator.
+    kind: 'decision',
+    discipline: 'ideator',
     description: 'init wrote a lean config/branding.json and left the LOOK to you (a locked project rule: brand with your ' +
       'own LLM, not a generator). Hand docs/branding-fill-prompt.md to your AI to design a palette/fonts/wordmark, or keep the vanilla look.',
   });
@@ -451,6 +462,9 @@ function versionPayload(spec) {
     id: v.id,
     name: v.name,
     status: v.status || 'building',
+    // versions.track is NOT NULL (no DB default) — always send it explicitly.
+    // An instance's first version is its product track unless the spec says otherwise.
+    track: v.track === 'internal' ? 'internal' : 'product',
     done_when: v.done_when,
     criteria: [{ criterion_id: v.criterion_id ? slugify(v.criterion_id) : 'first-goal', criterion_md: v.done_when }],
   };
@@ -728,12 +742,19 @@ async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {
   else log(`  ✓ created version ${vp.id} + 1 done-when goal`);
   const criterionId = vp.criteria[0].criterion_id;
 
-  // A tracked kickoff/starter task (status ready, engineer discipline). Returns true on success.
+  // A tracked kickoff/starter task (status ready). Returns true on success.
+  // The whole point of filing these is "nothing is silently skipped" — so a
+  // rejected POST must be LOUD: every failure is collected with its reason and
+  // reported against the expected count, never absorbed into a smaller total.
+  let attempted = 0;
+  const failures = [];
   const postTask = async (t, extra = {}) => {
+    attempted++;
     const res = await api('POST', '/api/gds/tasks', {
       version_id: vp.id, title: t.title, description: t.description || '', status: 'ready',
-      kind: t.kind || 'infra', discipline: 'engineer', source: 'bongos-init', ...extra,
+      kind: t.kind || 'infra', discipline: t.discipline || 'engineer', source: 'bongos-init', ...extra,
     });
+    if (!res.ok) failures.push({ title: t.title, status: res.status, detail: JSON.stringify(res.data) });
     return res.ok;
   };
 
@@ -771,8 +792,12 @@ async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {
   }
 
   const kickoffLabel = provisioned ? `${kickoff.length} kickoff + provisioning request` : `${kickoff.length} kickoff`;
-  log(`  ✓ filed ${created} task(s) (${starters.length} starter + ${kickoffLabel})`);
-  return { seeded: true, created, provisioned };
+  if (failures.length) {
+    log(`  ✗ ${failures.length} of ${attempted} task(s) FAILED to file — the checklist below is INCOMPLETE:`);
+    for (const f of failures) log(`      ✗ "${f.title}" (${f.status}): ${f.detail}`);
+  }
+  log(`  ${failures.length ? '⚠' : '✓'} filed ${created} of ${attempted} task(s) (${starters.length} starter + ${kickoffLabel})`);
+  return { seeded: true, created, attempted, failures, provisioned };
 }
 
 // ---------------------------------------------------------------------------
@@ -795,7 +820,12 @@ function confirmProceed({ input = process.stdin, output = process.stdout } = {})
 // seeds the repo's REAL version/goal + IMPORTS its existing backlog (task 2044), NOT a
 // synthetic "V1 — Prove the loop". `--dry-run` previews everything and writes nothing;
 // `--no-seed` layers without seeding. Returns a process exit code.
-async function runAdopt(spec, { dir, dryRun, noSeed = false, accept = false, log = console.log }) {
+// `coreDep`/`vendorPlan` (task 1002562): adopt used to ALWAYS write the caret range,
+// which resolves NOWHERE on npm — so an adopted repo could not `npm ci --omit=dev`, the
+// exact command the provisioner runs on the box. Greenfield already had --vendor-core for
+// this; passing the same resolved pin through here makes an adopted repo equally
+// installable. Omitted (a plain `bongos init --adopt` on a laptop) → the caret, unchanged.
+async function runAdopt(spec, { dir, dryRun, noSeed = false, accept = false, coreDep = null, vendorPlan = null, log = console.log }) {
   log(`\nAdopting Cloud Bongos onto the existing repo at "${dir}"${dryRun ? '  (dry run — nothing will be written or created)' : ''}:`);
   log('  Layering — pre-existing files are left untouched; nothing is overwritten.');
 
@@ -827,7 +857,30 @@ async function runAdopt(spec, { dir, dryRun, noSeed = false, accept = false, log
   }
 
   const cfg = layerConfigs(spec, { dir, dryRun, log });
-  const pkg = layerPackageJson(spec, { dir, dryRun, log });
+  const pkg = layerPackageJson(spec, { dir, dryRun, log, ...(coreDep ? { coreRange: coreDep } : {}) });
+
+  // Vendor the pinned core tarball + generate the lockfile, mirroring the greenfield
+  // --vendor-core steps, so the adopted repo is `npm ci --omit=dev`-installable (ADR 0108).
+  // Skipped when layerPackageJson found the dep ALREADY present — re-pinning someone's
+  // existing declaration is an overwrite, and adopt never overwrites.
+  if (vendorPlan && pkg.action !== 'present' && pkg.action !== 'unparseable') {
+    const upgrade = require('./upgrade');
+    if (dryRun) {
+      log(`\n  [dry-run] would vendor ${vendorPlan.tgz} → ${vendorPlan.vendorRel} and run \`npm install\` to generate package-lock.json`);
+    } else {
+      log('\nVendoring the pinned @bongos/core + generating the lockfile:');
+      upgrade.vendorTarball({ instanceDir: dir, fromTgz: vendorPlan.tgz, targetVersion: vendorPlan.version });
+      log(`  ✓ vendored ${vendorPlan.vendorRel}`);
+      const inst = upgrade.npmInstall(dir);
+      if (!inst.ok) {
+        log(`  ! npm install failed (${inst.reason || 'exit ' + inst.code}) — package-lock.json not generated; run \`npm install\` in ${dir} by hand before provisioning.`);
+      } else {
+        log('  ✓ npm install → package-lock.json generated (node_modules/@bongos/core installed)');
+      }
+    }
+  } else if (vendorPlan && pkg.action === 'present') {
+    log(`  • ${CORE_PKG} was already declared — left as-is; the vendored tarball was NOT pinned over it.`);
+  }
 
   log('\nMaterializing the .claude/ methodology surface (additive — existing files left untouched):');
   const claude = materializeClaude({ coreRoot: resolveCoreRoot(), instanceDir: dir, dryRun, overwrite: false, log });
@@ -846,7 +899,10 @@ async function runAdopt(spec, { dir, dryRun, noSeed = false, accept = false, log
       ? `${backlog.tasks.length} imported task(s) from ${backlog.source}${backlog.truncated ? ` (capped at ${BACKLOG_MAX})` : ''}`
       : 'no backlog found (capture tasks later)';
     log(`\nReflecting real state — seeding version "${spec.version && spec.version.id}" + goal + ${importNote}:`);
-    await seedViaApi(spec, { dryRun, log });
+    const seedResult = (await seedViaApi(spec, { dryRun, log })) || {};
+    if (Array.isArray(seedResult.failures) && seedResult.failures.length) {
+      log(`\n  ⚠ ${seedResult.failures.length} seed task(s) failed to file (details above) — re-file them by hand or re-run the seed; the tracked checklist is incomplete until they exist.`);
+    }
   } else {
     log('\n  (--no-seed: layered config only; skipped real-state seeding)');
   }
@@ -907,17 +963,16 @@ async function main(argv) {
     return 1;
   }
 
-  // Brownfield (ADR 0121): a distinct LAYER + real-state path — never the greenfield
-  // scaffold/overwrite below. Its own report + next-steps live in runAdopt.
-  if (adopt) return await runAdopt(spec, { dir, dryRun, noSeed, accept });
-
-  // Greenfield core-dep resolution (ADR 0108 gap 1/4, task 2053). With --vendor-core, pin
+  // Core-dep resolution (ADR 0108 gap 1/4, task 2053). With --vendor-core, pin
   // package.json to the vendored `file:` tarball (the caret range resolves NOWHERE on npm,
   // so a caret-only scaffold can't `npm ci`); the tarball is copied + the lockfile generated
-  // just below. Without it, the scaffold carries the declared caret (a local/dev scaffold the
+  // below. Without it, the scaffold carries the declared caret (a local/dev scaffold the
   // owner resolves another way). Reuses the bongos-upgrade vendoring + install steps.
+  //
+  // Resolved BEFORE the adopt branch (task 1002562) because BOTH paths need it: an adopted
+  // repo has to be `npm ci`-installable by the provisioner exactly like a scaffolded one.
   const upgrade = require('./upgrade');
-  let coreDep = null; // null → writeConfigs writes the caret range
+  let coreDep = null; // null → writeConfigs/layerPackageJson write the caret range
   let vendorPlan = null;
   if (vendorCore) {
     const tgz = path.resolve(vendorCore);
@@ -935,6 +990,10 @@ async function main(argv) {
     vendorPlan = { tgz, version, vendorRel };
   }
 
+  // Brownfield (ADR 0121): a distinct LAYER + real-state path — never the greenfield
+  // scaffold/overwrite below. Its own report + next-steps live in runAdopt.
+  if (adopt) return await runAdopt(spec, { dir, dryRun, noSeed, accept, coreDep, vendorPlan });
+
   console.log(`\nScaffolding "${spec.identity.productName}"${dryRun ? '  (dry run — nothing will be written or created)' : ''}:`);
   writeConfigs(spec, { dir, force, dryRun, coreDep });
 
@@ -1024,6 +1083,9 @@ async function main(argv) {
   else console.log('  (--no-seed: skipped version/task seeding)');
 
   console.log(`\n${dryRun ? 'Dry run complete.' : 'Done.'} Next:`);
+  if (Array.isArray(seedResult.failures) && seedResult.failures.length) {
+    console.log(`  ⚠ ${seedResult.failures.length} seed task(s) failed to file (details above) — re-file them by hand or re-run the seed; the tracked checklist is incomplete until they exist.`);
+  }
   console.log('  • fill the look: hand docs/branding-fill-prompt.md to your own LLM');
   console.log(`  • sign in as ${spec.firstAdmin} to become the owner, then run \`bongos start\` to see the kickoff tasks`);
   console.log('  • work through the kickoff tasks the way you would any task: claim → ship');

package/scripts/gds/main-audit.js

@@ -34,12 +34,13 @@
 //   node scripts/gds/main-audit.js --revert              # also print `git revert` plan
 //   node scripts/gds/main-audit.js --strict              # also block on unresolved authors
 //   node scripts/gds/main-audit.js --db                  # resolve ranks from Postgres instead of the API
+//   node scripts/gds/main-audit.js --require-roster      # CI: an empty roster is a loud DID-NOT-RUN, not a vacuous green
 
 'use strict';
 
 const { execSync } = require('node:child_process');
 const ppc = require(require('node:path').join(__dirname, '..', '..', 'src', 'bongos', 'permission-path-check.js'));
-const { cliClient } = require('./cli-lib');
+const { cliClient, API_BASE } = require('./cli-lib');
 
 // ---------- pure analyzer (tested in tests/main_audit.mjs) ----------
 
@@ -87,7 +88,7 @@ function analyzeCommits(commits, rankByIdentity, { strict = false } = {}) {
         author: c.authorName,
         rank,
         files: hits.map((h) => h.file),
-        summary: `commit ${short(c.sha)} by '${c.authorName}' (rank '${rank}', below Metic) modified permission-sensitive path(s) [${fileList}] — this is the SEC #863 violation class. It must be reverted and re-landed by an Archon if genuinely needed.`,
+        summary: `commit ${short(c.sha)} by '${c.authorName}' (rank '${rank}', below Metic) modified permission-sensitive path(s) [${fileList}] — this is the SEC #863 violation class. It must be reverted and re-landed by a Metic+ builder if genuinely needed.`,
       });
     }
   }
@@ -120,6 +121,34 @@ function git(args) {
   return execSync(`git ${args}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
 }
 
+// How far back the default scan reaches, in first-parent steps.
+const DEFAULT_WINDOW = 200;
+
+// First-parent depth of a ref. `<ref>~N` walks FIRST parents N times, so this —
+// not the total commit count — is what bounds the window. On a repo where every
+// land is a --no-ff merge the two diverge sharply: this one has 526 commits
+// reachable from origin/main but a first-parent chain only 186 deep.
+function firstParentDepth(ref) {
+  try {
+    return Number(git(`rev-list --count --first-parent ${ref}`).trim());
+  } catch (_) {
+    return NaN;
+  }
+}
+
+// Clamp the window to what the history actually holds. Returns null when there
+// is nothing to audit, so the caller reports that plainly instead of emitting a
+// `<ref>~200..<ref>` that git rejects as an unknown revision (task 1002566).
+function clampWindow(depth, want = DEFAULT_WINDOW) {
+  if (typeof depth !== 'number' || !Number.isFinite(depth) || depth < 2) return null;
+  return Math.min(want, depth - 1);
+}
+
+function defaultRange(ref, depth, want = DEFAULT_WINDOW) {
+  const n = clampWindow(depth, want);
+  return n === null ? null : `${ref}~${n}..${ref}`;
+}
+
 // Parse `git log --name-only` with a NUL-delimited custom format into commits.
 function parseCommits(range) {
   // %x00 = NUL. Format: NUL sha NUL parents NUL authorName NUL authorEmail NUL subject \n files...
@@ -128,7 +157,9 @@ function parseCommits(range) {
   try {
     out = git(`log ${range} --name-only --format=${JSON.stringify(fmt)}`);
   } catch (e) {
-    return { error: `git log failed for range ${range}: ${e.message}` };
+    // Say plainly that nothing was audited. A bare git error here used to read
+    // as a transient glitch, which is how a dead check passed for a clean one.
+    return { error: `DID NOT RUN — git log could not resolve range ${range}, so no commits were audited: ${e.message}` };
   }
   const records = out.split('\x00').slice(1); // first chunk is empty / pre-first-NUL
   const commits = [];
@@ -194,8 +225,25 @@ async function fetchRankMap({ useDb = false } = {}) {
   try {
     const api = await cliClient({ allowUnauthenticated: true });
     const res = await api.builders.getBuildersRoster();
-    if (res && res.ok) return rowsToMap(res.data?.builders || []);
-  } catch (_) { /* offline / not archon — map stays empty → unresolved authors */ }
+    if (res && res.ok) {
+      const map = rowsToMap(res.data?.builders || []);
+      if (Object.keys(map).length) return map;
+    }
+  } catch (_) { /* offline / no session — fall through to the public surface */ }
+  // Public fallback (task 1002612): CI has no GDS session, and with an empty
+  // rank map every author resolves to null so a blocker can NEVER fire — a
+  // vacuous green. github_login + rank are public facts on this platform (the
+  // status dashboard serves them), and the public leaderboard is server-
+  // authoritative, so resolving from it is as trustworthy as the roster route.
+  // Caveat: a zero-activity builder may be absent → resolves as UNRESOLVED
+  // ('review' finding), never as falsely-trusted.
+  try {
+    const res = await fetch(`${API_BASE}/api/gds/public/leaderboard`);
+    if (res.ok) {
+      const data = await res.json();
+      return rowsToMap(data?.leaderboard || []);
+    }
+  } catch (_) { /* offline — map stays empty → unresolved authors */ }
   return {};
 }
 
@@ -221,12 +269,22 @@ async function main() {
     range = process.env.OTB_AUDIT_RANGE;
   }
   if (!range || range === true) {
-    if (verifyHead) {
-      range = 'HEAD~200..HEAD';
-    } else {
+    const ref = verifyHead ? 'HEAD' : 'origin/main';
+    if (!verifyHead) {
       // Default: recent origin/main. Fetch first so we're auditing the truth.
       try { git('fetch origin main'); } catch (_) { /* offline — audit local */ }
-      range = 'origin/main~200..origin/main';
+    }
+    // Clamp to the ref's real first-parent depth. A fixed ~200 silently made
+    // this audit unrunnable on any repo with a shorter chain (task 1002566).
+    const depth = firstParentDepth(ref);
+    range = defaultRange(ref, depth);
+    if (!range) {
+      console.error(
+        `main-audit: DID NOT RUN — cannot build a default range for ${ref}: its first-parent history is `
+        + `${Number.isFinite(depth) ? `${depth} commit(s)` : 'unreadable'} deep. `
+        + 'Pass --range <A..B> or set OTB_AUDIT_RANGE. This is a check that did not execute, not a clean audit.'
+      );
+      process.exit(2);
     }
   }
 
@@ -237,7 +295,15 @@ async function main() {
   }
   const rankMap = await fetchRankMap({ useDb });
   if (Object.keys(rankMap).length === 0) {
-    console.error('main-audit: WARNING — could not load the GDS roster (offline / not Archon / no DB). Authors will be unresolved; run as an Archon or with --db (on the droplet) for a definitive audit.');
+    // --require-roster (task 1002612): the CI caller refuses to "pass" an audit
+    // that could not have failed. With no ranks, every author is unresolved and
+    // a blocker can never fire — that is a check that did not execute, not a
+    // clean audit (the same false-green shape parseCommits guards against).
+    if (process.argv.includes('--require-roster')) {
+      console.error('main-audit: DID NOT RUN — the roster is unavailable (offline / no session / public leaderboard unreachable). An empty rank map can never produce a blocker, so exiting green would be a vacuous pass. Fix connectivity or drop --require-roster for a best-effort local read.');
+      process.exit(2);
+    }
+    console.error('main-audit: WARNING — could not load the GDS roster (offline / insufficient rank / no DB). Authors will be unresolved; run as a Metic+ builder or with --db (on the droplet) for a definitive audit.');
   }
 
   const result = analyzeCommits(parsed.commits, rankMap, { strict });
@@ -276,4 +342,7 @@ if (require.main === module) {
   });
 }
 
-module.exports = { analyzeCommits, resolveRank, parseCommits };
+module.exports = {
+  analyzeCommits, resolveRank, parseCommits, rowsToMap,
+  clampWindow, defaultRange, firstParentDepth, DEFAULT_WINDOW,
+};