@bongos/core 1.17.0

package/scripts/gds/seed-bongos-module-system-tasks.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+// Seed the BONGOS-V1 module-system child tasks — the build sequence of epic
+// #1388 (BV1.R34), turned into claimable, dependency-ordered tasks per ADR 0083
+// (task 1405 / BV1.R36). All link to criterion C5 (module-system-live), added by
+// companion migration 144_bongos_v1_module_system_criterion.sql.
+//
+// Idempotent: skips tasks whose source_ref already exists; dependency wiring is
+// idempotent on (task_id, depends_on_task_id). Display R## numbers are assigned
+// sequentially after the current max BV1.R## (so this composes with the existing
+// desktop-app R01..R36 without renumbering). Dependency edges reference the
+// logical `key`, not the R## — so re-running after a partial seed is safe.
+//
+// Mirrors scripts/gds/seed-bongos-app-tasks.js exactly (criterion_ids in the
+// POST body; engineer discipline; deps via POST /tasks/:id/dependencies).
+//
+// Usage:  node scripts/gds/seed-bongos-module-system-tasks.js [--dry-run]
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+const DRY = process.argv.includes('--dry-run');
+
+// Each entry: { key, title, description, kind, discipline, priority,
+//               est_minutes, manual_degree, credits_reward, touches,
+//               criteria: ['C5'], deps: ['<key>', ...] }
+const TASKS = [
+  // ===========================================================================
+  // PHASE 0 — The doorway (P5, roots)
+  // ===========================================================================
+  {
+    key: 'M01',
+    title: 'core/module-api.js — the published, semver’d doorway',
+    description: `Part of the module system (epic #1388, ADR 0083, design 01§3). Create \`src/module-api.js\` — the stable, semver’d import surface and the ONLY core file a module may require. Re-export the kernel capabilities a module legitimately needs: requireBuilder/requireRank (src/bongos/auth.js), a DB pool accessor (src/bongos/pool.js), the seam registry (M05), config/branding/identity (src/instance-config.js, config/branding.json), a logger. Carry a CORE_VERSION constant. Adding to it = minor bump; changing/removing = major.
+
+**Done when:** src/module-api.js exists + exports the surface + CORE_VERSION; a nested CLAUDE.md documents the contract; unit test asserts the public surface is stable; no behavior change to OTB.`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 150, manual_degree: 2, credits_reward: 25,
+    touches: ['src/module-api.js', 'tests/'], criteria: ['C5'], deps: [],
+  },
+  {
+    key: 'M03',
+    title: 'module.json manifest schema + validator',
+    description: `Part of the module system (epic #1388, ADR 0083, design 04§4). Define the \`module.json\` manifest schema — key, coreVersion, \`contributes\` (routes, rooms, pollers, migrations, uiSections, disciplines, skills), \`provides\`/\`consumes\` (seam ports), \`prerequisites.modules\` — and a pure validator the loader (M04) and fitness (M09) both call. Model the \`contributes\` shape on the existing src/modules.js entries.
+
+**Done when:** schema documented; validator rejects malformed manifests with clear errors; hermetic test suite green; no app wiring yet.`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 150, manual_degree: 2, credits_reward: 25,
+    touches: ['src/module-loader/', 'tests/'], criteria: ['C5'], deps: [],
+  },
+  {
+    key: 'M05',
+    title: 'Kernel seam registry — ports + event bus',
+    description: `Part of the module system (epic #1388, ADR 0083, design 04§1). Build the kernel switchboard: PORTS (registerProvider/resolve — a required capability, e.g. economy provides \`reward\`, lifecycle resolves it at ship) and EVENTS (emit/on — optional reaction, e.g. lifecycle emits \`task.shipped\`, discord reacts). No module ever holds a reference to another. Exposed through src/module-api.js (M01).
+
+**Done when:** register/resolve + emit/on live in the kernel and re-exported via module-api.js; hermetic tests for port resolution + event fan-out; fail-clear when a required port has no provider.`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 180, manual_degree: 2, credits_reward: 30,
+    touches: ['src/module-loader/', 'src/module-api.js', 'tests/'], criteria: ['C5'], deps: ['M01'],
+  },
+  {
+    key: 'M02',
+    title: 'Fitness: one-way boundary checks (core↔module imports)',
+    description: `Part of the module system (epic #1388, ADR 0083, design 04§3). Add two pure checks to scripts/gds/fitness.js CHECKS array (rides the \`unit\` job, no workflow change), mirroring checkCoreHostBoundary: (1) "core never imports a module" — flag any require() under the kernel resolving into modules/; (2) "modules import only the published API" — flag any module require() resolving into core internals other than src/module-api.js, or into a sibling module. Fresh GRANDFATHERED set, warn-mode; green on an empty modules/ tree. Each ships with a negative test (proves it catches a violation).
+
+**Done when:** both checks in CHECKS + exported + tested (clean-pass AND catches-violation); green on current tree.`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 150, manual_degree: 2, credits_reward: 25,
+    touches: ['scripts/gds/fitness.js', 'tests/fitness.mjs'], criteria: ['C5'], deps: ['M01'],
+  },
+
+  // ===========================================================================
+  // PHASE 1 — The loader (P5)
+  // ===========================================================================
+  {
+    key: 'M04',
+    title: 'The loader — discover/validate/mount modules/*/module.json',
+    description: `Part of the module system (epic #1388, ADR 0083, design 01§3a). Replace the closed KNOWN_MODULES registry in src/modules.js with a loader that: discovers modules/*/module.json across roots; validates each (M03); checks coreVersion compat (fail-closed); resolves→loads→mounts each enabled module’s route factory BEHIND kernel-composed auth (loader wraps audit → requireBuilder → requireRank around the module’s recipe + declared rank — the module never calls app.use); starts/stops pollers; applies migrations (enabled-gated, M10). Keep isModuleEnabled/enabledDisciplines/clientModules as a back-compat facade over the loader so nothing downstream breaks.
+
+**Done when:** loader discovers + mounts from manifests; the back-compat facade keeps all current call sites working; OTB boots byte-identically; hermetic loader tests (mount behind auth, coreVersion mismatch refused, disabled module not mounted).`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 360, manual_degree: 2, credits_reward: 70,
+    touches: ['src/modules.js', 'src/module-loader/', 'src/bongos/routes.js', 'server.js', 'tests/'],
+    criteria: ['C5'], deps: ['M01', 'M03'],
+  },
+
+  // ===========================================================================
+  // PHASE 2 — First move: dev-box (the template) (P4)
+  // ===========================================================================
+  {
+    key: 'M06',
+    title: 'Module→core contribution seam for profile + settings UI',
+    description: `Part of the module system (epic #1388, ADR 0083, design 02§cross-cutting). The recurring strangler seam: src/bongos/routes/me.js (the builder-profile route) and public-builders/settings.js embed dev-box/discord/art-key surfaces (box ~16, discord ~63, art-key ~32 line-refs). Add a module→core registration hook so a module contributes its profile fields + a settings panel via the seam (M05) instead of being hardcoded into the core route/page. This is the prerequisite that lets dev-box/discord/art leave core (game has zero such coupling).
+
+**Done when:** a module can register profile fields + a settings panel; me.js + settings.js render contributed surfaces via the hook with no behavior change; test covers a registered + an absent contribution.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 300, manual_degree: 2, credits_reward: 55,
+    touches: ['src/bongos/routes/me.js', 'public-builders/settings.js', 'src/module-loader/', 'tests/'],
+    criteria: ['C5'], deps: ['M05'],
+  },
+  {
+    key: 'M07',
+    title: 'Move dev-box → modules/dev-box/ (the template move)',
+    description: `Part of the module system (epic #1388, ADR 0083, design 03 + 01§6). The most-isolated module (0 refs in server.js/routes.js bodies; box-prefixed tables; routes already flag-gated at routes.js:122) — the template every later move copies. Move src/bongos/box*.js + routes/box.js + public-builders/box-panel.js + the manifest + a nested CLAUDE.md into modules/dev-box/; register its profile fields via M06; delete the if(isModuleEnabled('dev-box')) gate; the loader mounts it. devbox-app/ (Electron) may stay separate for now.
+
+**Done when:** dev-box runs entirely from modules/dev-box/ via the loader; the inline gate is gone; OTB behaves BYTE-IDENTICALLY (the proof); smoke green.`,
+    kind: 'refactor', discipline: 'engineer', priority: 4,
+    est_minutes: 360, manual_degree: 2, credits_reward: 70,
+    touches: ['modules/dev-box/', 'src/bongos/routes.js', 'src/bongos/routes/me.js'],
+    criteria: ['C5'], deps: ['M04', 'M06'],
+  },
+
+  // ===========================================================================
+  // PHASE 3 — Trust enforcement (P4)
+  // ===========================================================================
+  {
+    key: 'M08',
+    title: 'Fitness: every module write-route is rank-gated',
+    description: `Part of the module system (epic #1388, ADR 0083, design 01§3a). Do NOT re-implement — parameterize route-rank-check.js’s ROUTES_DIR (route-rank-check.js:26,151-159) so checkRouteRanks ALSO walks modules/**/routes/. Module write-routes then inherit the exact "unknown write = blocker" rule Check 4 already enforces; optionally pin authority module routes in EXPECTED_RANKS. Check 4 in fitness.js picks it up with no change.
+
+**Done when:** a module route with no rank gate is a red build (negative test); existing core route checks unaffected; the moved dev-box routes (M07) pass.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 150, manual_degree: 2, credits_reward: 25,
+    touches: ['src/bongos/route-rank-check.js', 'tests/'], criteria: ['C5'], deps: ['M04'],
+  },
+  {
+    key: 'M09',
+    title: 'Fitness: core-carries-no-module-code + module-migrations checks; flip warn→violation',
+    description: `Part of the module system (epic #1388, ADR 0083, design 04§3). Add two checks to fitness.js: "core carries no module-specific code" (no module key/domain term leaks into kernel files) and "module migrations are additive + namespaced" (read modules/<key>/migrations/, regex-reject DROP TABLE/DROP COLUMN/destructive ALTER, assert a <key>_ object prefix). Once the first move (M07) is clean, flip M02’s one-way checks from warn-mode to violation (the ratchet).
+
+**Done when:** both new checks in CHECKS + exported + tested (clean-pass AND catches-violation); M02 checks now hard-fail; green on the post-M07 tree.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 180, manual_degree: 2, credits_reward: 30,
+    touches: ['scripts/gds/fitness.js', 'tests/fitness.mjs'], criteria: ['C5'], deps: ['M04', 'M07'],
+  },
+
+  // ===========================================================================
+  // PHASE 4 — Module-owned migrations (P4) [migrate.sh = gate HARD-FLOOR]
+  // ===========================================================================
+  {
+    key: 'M10',
+    title: 'Module-owned migrations — generalize migrations/game/ → modules/<key>/migrations/',
+    description: `Part of the module system (epic #1388, ADR 0083, design 04§2 + ADR 0062 §5). Teach scripts/migrate.sh to discover modules/*/migrations/*.sql and apply each ONLY if its module is enabled (the MEDUSA_GDS_ONLY game-gate generalized to per-module enablement). schema_migrations stays STEM-KEYED so relocating a migration from migrations/game/ to modules/game/migrations/ does NOT re-run it on prod (the existing safety guarantee). Disable preserves data (mechanism is "don’t apply", never "drop"). Generalize scripts/verify-gds-only-schema.sh into a per-module presence/absence verifier. Add modules/<key>/migrations/ to PROTECTED_GLOBS (permission-path-check.js).
+
+**NOTE:** scripts/migrate.sh is a gate HARD-FLOOR — this PR needs owner Gate approval. **Done when:** module migrations apply enabled-gated; a relocated game migration does not re-run; the per-module verifier passes for an enabled + a disabled module.`,
+    kind: 'infra', discipline: 'engineer', priority: 4,
+    est_minutes: 240, manual_degree: 3, credits_reward: 45,
+    touches: ['scripts/migrate.sh', 'scripts/verify-gds-only-schema.sh', 'src/bongos/permission-path-check.js'],
+    criteria: ['C5'], deps: ['M04'],
+  },
+
+  // ===========================================================================
+  // PHASE 5 — More moves: discord, art-pipeline (P3)
+  // ===========================================================================
+  {
+    key: 'M11',
+    title: 'Move discord → modules/discord/',
+    description: `Part of the module system (epic #1388, ADR 0083, design 02). Move the discord bot + broadcast (src/bongos/discord-*.js, ship-card.js, ship-broadcast.js) + routes/discord.js + the link/role UI (via the M06 profile seam) + manifest + nested CLAUDE.md into modules/discord/; relocate migrations/067_discord_*.sql to modules/discord/migrations/ (M10); delete the if(isModuleEnabled('discord')) gates in server.js + routes.js. React to lifecycle events (e.g. task.shipped) through the seam (M05), not by import.
+
+**Done when:** discord runs entirely from modules/discord/ via the loader; gates gone; OTB byte-identical (ship broadcast + role sync still fire); fitness green.`,
+    kind: 'refactor', discipline: 'engineer', priority: 3,
+    est_minutes: 300, manual_degree: 2, credits_reward: 55,
+    touches: ['modules/discord/', 'server.js', 'src/bongos/routes.js', 'src/bongos/routes/me.js'],
+    criteria: ['C5'], deps: ['M07', 'M06', 'M10'],
+  },
+  {
+    key: 'M12',
+    title: 'Move art-pipeline → modules/art-pipeline/',
+    description: `Part of the module system (epic #1388, ADR 0083, design 02). The hardest clean cut: its API lives INSIDE core routes/me.js (art-key, ~32 refs) and the artist discipline threads through src/modules.js enabledDisciplines(). Carve the art-key endpoints out of me.js into a modules/art-pipeline/routes/ router; move src/bongos/art-key.js + the art/ tree (~18k LOC) + the otb-* skills + the artist-discipline contribution + manifest + nested CLAUDE.md into modules/art-pipeline/; loader mounts it; the artist discipline registers via the seam.
+
+**Done when:** art-pipeline runs entirely from modules/art-pipeline/ via the loader; art-key API + tile generation + the artist discipline work unchanged; fitness green.`,
+    kind: 'refactor', discipline: 'engineer', priority: 3,
+    est_minutes: 360, manual_degree: 2, credits_reward: 65,
+    touches: ['modules/art-pipeline/', 'src/bongos/routes/me.js', 'src/modules.js'],
+    criteria: ['C5'], deps: ['M07', 'M06'],
+  },
+
+  // ===========================================================================
+  // PHASE 6 — Move game (the hard one) (P3)
+  // ===========================================================================
+  {
+    key: 'M13',
+    title: 'Move game → modules/game/ (Colyseus realtime seam)',
+    description: `Part of the module system (epic #1388, ADR 0083, design 01§6 phase 4). Game already lives outside src/bongos/ (src/rooms/, src/world/, public/game/) with its own migrations/game/ and a game-less platform-server.js — but server.js carries its static-serve tail + the Colyseus room registration. Move rooms/world/public/game/migrations into modules/game/ (M10); express a "realtime capability" seam so the loader can register Colyseus rooms for an enabled game module without server.js hardcoding them; delete the if(isModuleEnabled('game')) gates (server.js:139-143,176-178). Keep the server/client render twins in sync.
+
+**Done when:** game runs entirely from modules/game/ via the loader; the Colyseus rooms register through the seam; OTB byte-identical (world + queue + movement); fitness green.`,
+    kind: 'refactor', discipline: 'engineer', priority: 3,
+    est_minutes: 360, manual_degree: 3, credits_reward: 70,
+    touches: ['modules/game/', 'server.js', 'src/rooms/register.js'],
+    criteria: ['C5'], deps: ['M04', 'M10'],
+  },
+
+  // ===========================================================================
+  // PHASE 7 — Developer experience (P3)
+  // ===========================================================================
+  {
+    key: 'M14',
+    title: 'bongos module new <key> scaffolder + bongos upgrade coreVersion pre-check',
+    description: `Part of the module system (epic #1388, ADR 0083, design 04§2). Add a scaffolder (bongos init / scripts/gds/init.js extension) that creates modules/<key>/ with a valid module.json (M03), the dir skeleton (routes/, migrations/, ui/), and a nested CLAUDE.md — no core edit needed. Add \`bongos upgrade\` that pre-checks every enabled module’s coreVersion against CORE_VERSION (M01) and refuses/warns on mismatch (fail-closed).
+
+**Done when:** \`module new <key>\` scaffolds a loader-discoverable module that mounts with no core edit; \`bongos upgrade\` reports/refuses on coreVersion mismatch; tests cover both.`,
+    kind: 'feature', discipline: 'engineer', priority: 3,
+    est_minutes: 240, manual_degree: 2, credits_reward: 40,
+    touches: ['scripts/gds/init.js', 'scripts/gds/', 'tests/'], criteria: ['C5'], deps: ['M03', 'M04'],
+  },
+
+  // ===========================================================================
+  // PHASE 8 — Docs + proof (P2/P1)
+  // ===========================================================================
+  {
+    key: 'M15',
+    title: 'Rewrite docs/modules-contract.md to the plugin-API contract + index sweep',
+    description: `Part of the module system (epic #1388, ADR 0083 step 7). Rewrite docs/modules-contract.md as the plugin-API contract (the doorway surface, the manifest schema, the seam ports/events, the rank-gate rule, module-owned migrations) + a module-author recipe (scaffold → write → declare → enable). Sweep the indexes: CLAUDE.md quick-nav, docs/file-map.md (the modules/ tree), docs/architecture.md (core+modules section), docs/adr/README.md.
+
+**Done when:** modules-contract.md documents the live contract + recipe; all indexes reference modules/ and ADR 0083; no stale "closed registry" claims.`,
+    kind: 'infra', discipline: 'engineer', priority: 2,
+    est_minutes: 180, manual_degree: 2, credits_reward: 30,
+    touches: ['docs/modules-contract.md', 'CLAUDE.md', 'docs/file-map.md', 'docs/architecture.md', 'docs/adr/README.md'],
+    criteria: ['C5'], deps: ['M14', 'M07', 'M11', 'M12', 'M13'],
+  },
+  {
+    key: 'M16',
+    title: 'Proof: a net-new module via the scaffolder, mounted + shipped, OTB byte-identical',
+    description: `Part of the module system (epic #1388, ADR 0083 — the criterion’s live proof). On a staged throwaway: run \`bongos module new demo\` (M14), give it one rank-gated route + one namespaced migration, enable it, prove the loader mounts it with NO core edit; prove OTB behaves byte-identically; prove fitness REJECTS a deliberate cross-module import (demo requires modules/dev-box internals) and a missing route rank gate. Capture the transcript in the task notes.
+
+**Done when:** the walkthrough is documented; the scaffolded module mounts + serves; both fitness violations are caught as red builds.`,
+    kind: 'verify', discipline: 'engineer', priority: 1,
+    est_minutes: 180, manual_degree: 3, credits_reward: 35,
+    touches: ['docs/', 'modules/'], criteria: ['C5'],
+    deps: ['M07', 'M11', 'M12', 'M13', 'M14'],
+  },
+
+  // ===========================================================================
+  // PHASE 9 — Follow-on: task→module affinity (P2)
+  // ===========================================================================
+  {
+    key: 'M17',
+    title: 'task→module affinity — the touches[] successor (may re-break-out)',
+    description: `Part of the module system (epic #1388, ADR 0083§task→module, design 00§6 + 01§4). The research centerpiece, gated on the full roster being moved. Give a task a \`module\` label; scope the agent’s context to that module + the published API (smaller context, higher quality); make parallel-safety MODULE-DISJOINTNESS (cleaner than path overlap); make drift detection semantic ("you said dev-box, you touched game" via the ship-time diff⊆module check); retire the file-path touches[] (already advisory, ADR 0049) in favor of the module label. This is itself a sizeable feature — may be re-broken into children at a planning pass.
+
+**Done when:** tasks carry a module label; claim-time context is module-scoped; ship-time diff⊆module is enforced; touches[] is retired or demoted to derived-from-module.`,
+    kind: 'feature', discipline: 'engineer', priority: 2,
+    est_minutes: 360, manual_degree: 3, credits_reward: 60,
+    touches: ['src/bongos/db.js', 'src/bongos/routes/tasks.js', 'scripts/gds/claim.js', 'scripts/gds/ship.js'],
+    criteria: ['C5'], deps: ['M07', 'M11', 'M12', 'M13'],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Main: post each task with criterion_ids; assign R## after current max; wire deps.
+// ---------------------------------------------------------------------------
+
+async function main() {
+  await requireSession();
+  const api = await cliClient();
+
+  const list = await api.tasks.getTasks({ query: { version: 'BONGOS-V1' } });
+  const existing = list.data?.tasks || [];
+  const bySourceRef = {};
+  let maxR = 0;
+  for (const t of existing) {
+    if (t.source_ref) bySourceRef[t.source_ref] = t;
+    const m = /BV1\.R(\d+)\b/.exec(t.title || '');
+    if (m) { const n = Number(m[1]); if (n > maxR) maxR = n; }
+  }
+  console.log(`context: ${existing.length} BONGOS-V1 tasks, maxR=R${maxR}`);
+
+  const refByKey = {};
+  TASKS.forEach((def, i) => { refByKey[def.key] = `R${String(maxR + 1 + i).padStart(2, '0')}`; });
+
+  const idByKey = {};
+  let created = 0, skipped = 0, errors = 0;
+
+  for (const def of TASKS) {
+    const r = refByKey[def.key];
+    const source_ref = `bongos-v1-${def.key.toLowerCase()}`;
+    if (bySourceRef[source_ref]) {
+      idByKey[def.key] = Number(bySourceRef[source_ref].id);
+      console.log(`SKIP  ${def.key} (${r}) already exists: id=${bySourceRef[source_ref].id}`);
+      skipped++;
+      continue;
+    }
+    const body = {
+      version_id: 'BONGOS-V1',
+      title: `BV1.${r} — ${def.title}`,
+      description: def.description,
+      kind: def.kind,
+      discipline: def.discipline,
+      status: 'backlog',
+      priority: def.priority,
+      est_minutes: def.est_minutes,
+      manual_degree: def.manual_degree,
+      credits_reward: def.credits_reward,
+      touches: def.touches || [],
+      criterion_ids: def.criteria || [],
+      source: 'planning-session',
+      source_ref,
+    };
+    if (DRY) {
+      const deps = (def.deps || []).map((d) => (refByKey[d] ? `${d}=${refByKey[d]}` : d)).join(',');
+      console.log(`DRY   ${def.key} -> ${r}  P${def.priority} ${def.kind}  crit=${(def.criteria || []).join('/')}  deps=[${deps}]  ${def.title.slice(0, 50)}`);
+      continue;
+    }
+    const res = await api.tasks.postTasks({ body });
+    if (res.status !== 201) {
+      console.error(`FAIL  ${def.key}: status=${res.status} ${JSON.stringify(res.data).slice(0, 220)}`);
+      errors++;
+      continue;
+    }
+    idByKey[def.key] = Number(res.data.task.id);
+    console.log(`OK    ${def.key} -> BV1.${r}  task id=${idByKey[def.key]}  (crit ${(def.criteria || []).join('/')})`);
+    created++;
+  }
+
+  const resolveDep = (ref) => idByKey[ref] ?? null;
+
+  let depsWired = 0, depErrors = 0;
+  if (!DRY) {
+    for (const def of TASKS) {
+      const deps = def.deps || [];
+      if (deps.length === 0) continue;
+      const taskId = idByKey[def.key];
+      if (!taskId) { console.error(`DEPS  ${def.key}: no task id (create failed?), skipping`); depErrors++; continue; }
+      const depIds = deps.map(resolveDep).filter((n) => Number.isFinite(n));
+      if (depIds.length !== deps.length) {
+        const missing = deps.filter((d) => !Number.isFinite(resolveDep(d)));
+        console.error(`DEPS  ${def.key}: unresolved deps [${missing.join(',')}] — wiring the resolvable ones only`);
+        depErrors++;
+        if (depIds.length === 0) continue;
+      }
+      const res = await api.tasks.postTasksIdDependencies({ id: taskId, body: { depends_on_task_ids: depIds } });
+      if (res.status === 200) {
+        console.log(`DEPS  ${def.key} <- [${deps.join(',')}] (ids ${depIds.join(',')})`);
+        depsWired++;
+      } else {
+        console.error(`DEPS FAIL ${def.key}: ${res.status} ${JSON.stringify(res.data).slice(0, 220)}`);
+        depErrors++;
+      }
+    }
+  }
+
+  const zeroDep = TASKS.filter((d) => (d.deps || []).length === 0).map((d) => `${d.key}=${idByKey[d.key] || '?'}`);
+  console.log(`\nDONE  created=${created} skipped=${skipped} errors=${errors} deps_wired=${depsWired} dep_errors=${depErrors}  (manifest: ${TASKS.length})`);
+  console.log(`NEXT  promote zero-dependency tasks to 'ready' (they never auto-promote): ${zeroDep.join(', ')}`);
+  process.exit(errors === 0 && depErrors === 0 ? 0 : 1);
+}
+
+main().catch((err) => { console.error('FATAL', err); process.exit(1); });

package/scripts/gds/seed-bongos-tasks.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// Seed the 6 net-new "Cloud Bongos CLI" tasks added to GDS-V4 (C8) — the
+// conda/Miniconda-style terminal-first onboarding toolkit. `bongos` is the CLI
+// command (Cloud Bongos = the standalone build platform; Amazonprimea =
+// instance 1). Design doc: artifact 02bcca71 (the bongos toolkit).
+//
+// Shape mirrors seed-medusa-tasks.js exactly:
+//   - POST /api/gds/tasks   { version_id:'GDS-V4', criterion_ids:['C8'], ... }
+//   - POST /api/gds/tasks/:id/dependencies   { depends_on_task_ids:[...] }
+//   - idempotent on source_ref (skips already-created); deps idempotent server-side.
+//
+// Display R## numbers are assigned dynamically from the current max V4.R## in
+// the version (decorative sort prefix; deps are the load-bearing part — ADR 0049).
+// Intra-cluster deps use the symbolic key (EPIC/P1/...); cross-cluster deps use
+// the real 'R53'/'R54' ref, resolved from the existing GDS-V4 task list.
+//
+// Usage:  node scripts/gds/seed-bongos-tasks.js [--dry-run]
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+const DRY = process.argv.includes('--dry-run');
+
+// Each entry: { key, title, description, kind, discipline, priority,
+//   est_minutes, manual_degree, credits_reward, touches, criteria, deps }
+// `key` is the symbolic intra-cluster ref; `deps` may hold keys or real 'R##'.
+const TASKS = [
+  {
+    key: 'EPIC',
+    title: 'Cloud Bongos `bongos` CLI — terminal-first onboarding toolkit (epic)',
+    description: `Part of Cloud Bongos / C8 (standalone instance). Umbrella + design home for the conda-style onboarding toolkit. Design doc: the "bongos toolkit" artifact.
+
+The thesis: what Miniconda is to Python, the \`bongos\` CLI is to a Cloud Bongos instance — one tiny installer -> one command surface -> an isolated, reproducible, Claude-wired dev environment. Three commands from a fresh laptop to a claimed task:
+  curl -fsSL https://get.bongos.dev | sh   ->   bongos login <instance>   ->   bongos code   ->   bongos start / claim / ship
+
+Conda mapping: installer->\`bongos\`; \`conda <verb>\`->\`bongos <verb>\`; \`conda create/activate\`->\`bongos up\`/\`bongos code\` (the dev box IS the environment); channels->instances (\`bongos login <url>\`); environment.yml->the instance manifest. Lives ALONGSIDE the /builder-* slash-commands and the desktop app (additive, not a replacement); same scripts/gds/* underneath.
+
+Locked decisions: full product (strangers install it, AGPL self-host is the backbone); cloud box default, \`--local\` clone = Metic+; admission is invite-only via a public access-request + an Archon 👍 in Discord (the CLI files the request + polls); admission is the only box gate (first box hands-off, ADR 0059); box cost is surfaced + billed to the builder; Node-based, compiled binary in Phase 3.
+
+**Done when:** an ADR records the bongos verb surface, the distribution model, and the instance-manifest contract; the four phase tasks below are seeded + tracked under this epic.`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 120, manual_degree: 3, credits_reward: 30,
+    touches: ['docs/adr/'], criteria: ['C8'], deps: [],
+  },
+  {
+    key: 'P1',
+    title: 'bongos dispatcher — one CLI over scripts/gds/* (npm)',
+    description: `Part of Cloud Bongos / C8. Cross-ref: EPIC. **The one genuinely missing piece** — there is no top-level CLI dispatcher today, only ~65 loose node scripts behind ~26 slash-commands.
+
+A bin/bongos.js that routes \`bongos <verb> [args]\` to the existing scripts/gds/*.js, passing args/flags straight through. A verb registry maps: start->start.js, claim->claim.js, ship->ship.js, release->release.js, cost->cost.js, status->status.js, recall->recall.js, box->the box-ensure flow, stage->sandbox-stage/local-preview, setup/login->setup.js. \`bongos\` / \`bongos help\` prints the verb list; unknown verbs error with the list. Reuses cli-lib.js (no new auth/api code). package.json gets a \`bin\` entry so \`npm i -g\` (or npx) exposes \`bongos\`. Cross-platform Node only — no bash-isms (#686).
+
+**Done when:** \`bongos start|claim|ship|box|cost|status|recall\` dispatch to the right script with args passed through and exit codes preserved; \`bongos help\` lists the verbs; a \`bin\` entry makes \`bongos\` runnable after an npm global install; a smoke test covers the dispatch table.`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 240, manual_degree: 2, credits_reward: 50,
+    touches: ['bin/', 'package.json', 'scripts/gds/'], criteria: ['C8'], deps: [],
+  },
+  {
+    key: 'P2',
+    title: 'bongos shell + bongos code — terminal & VS Code Remote-SSH into the box',
+    description: `Part of Cloud Bongos / C8. Cross-ref: P1, ADR 0045 (the desktop app already manages the box SSH key).
+
+\`bongos shell\` opens a terminal session on the builder's dev box (wakes it via POST /box/ensure if needed). \`bongos code\` writes/refreshes an SSH host alias into ~/.ssh/config (reusing the ed25519 box key the Dev Box app provisions) and launches VS Code Remote-SSH at /workspace, so the laptop is a thin client and the box is the full environment with Claude's VS Code extension already installed (baked by cloud-init). Both default to the cloud box; \`--local\` (Metic+ only) targets a local clone / devcontainer instead.
+
+Known handoff: Claude's first-time login on a box is interactive by design (device enrollment can't be scripted — the ttyd/Chromebook work proved this). \`bongos shell\` runs an interactive \`claude\` the first time so the builder completes /login once; silent thereafter.
+
+**Done when:** \`bongos code\` from a fresh laptop wakes the box and opens VS Code attached over Remote-SSH at /workspace; \`bongos shell\` opens a working terminal on the box; the first-run \`claude\` login handoff is wired; \`--local\` is gated to Metic+.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 300, manual_degree: 2, credits_reward: 50,
+    touches: ['bin/', 'scripts/gds/', 'infra/'], criteria: ['C8'], deps: ['P1'],
+  },
+  {
+    key: 'P3',
+    title: 'One-liner installer + standalone bongos binary (GitHub Releases; brew/scoop/winget)',
+    description: `Part of Cloud Bongos / C8. Cross-ref: P1, ADR 0045 (the devbox-app already ships per-platform binaries via a public GitHub Releases repo — reuse that distribution pattern).
+
+A \`curl -fsSL https://get.bongos.dev | sh\` bootstrap (detects OS/arch, downloads the right binary, puts it on PATH, prints next steps) plus a compiled standalone \`bongos\` binary (bun/deno/pkg-style) so there is NO "install Node first" prerequisite — the true Miniconda feel and the on-ramp for non-Node users + self-hosters. CI builds the per-platform binaries (mac arm64/x64, win, linux) and publishes them as GitHub Release assets; add at least one package-manager recipe (brew tap / scoop / winget). The server can serve branded /downloads redirects like it does for the devbox app.
+
+**Done when:** a single \`curl … | sh\` puts \`bongos\` on PATH on macOS/Windows/Linux with no prior Node; CI publishes per-platform binaries to a GitHub Release; at least one package-manager install path works; the installer is idempotent + re-runnable.`,
+    kind: 'infra', discipline: 'engineer', priority: 4,
+    est_minutes: 360, manual_degree: 2, credits_reward: 60,
+    touches: ['.github/', 'scripts/', 'bin/'], criteria: ['C8'], deps: ['P1'],
+  },
+  {
+    key: 'P4A',
+    title: 'Instance manifest endpoint — GET /api/gds/instance (brand + modules + repo)',
+    description: `Part of Cloud Bongos / C8. Cross-ref: R53 (branding-contract layer), R54 (feature-module selection). This is the read-API over those two configs — the conda "environment.yml" a CLI fetches to configure itself.
+
+A small public, read-only endpoint returning the instance descriptor assembled from the R53 branding contract + the R54 module flags: product/instance name + brand (identity, copy, theme — NO secrets), enabled feature-modules, the GitHub repo binding, the rank ladder, supported auth methods (device-flow / app-pair), admission policy (invite-only vs open), and whether a managed dev-box backend is available. So \`bongos login <url>\` brands itself, knows the repo for \`--local\`, and hides verbs an instance doesn't run (e.g. no \`box\` if dev-box is off). Today GET /healthz returns only { ok, auth_configured } — this is a genuine gap.
+
+**Done when:** GET /api/gds/instance returns a documented manifest assembled from the branding contract + module flags, contains no secrets/topology, is fetchable pre-auth (CORS read), and the CLI can brand + feature-gate itself from it. Depends on R53/R54 so the brand + module sources exist.`,
+    kind: 'feature', discipline: 'engineer', priority: 3,
+    est_minutes: 240, manual_degree: 2, credits_reward: 50,
+    touches: ['src/bongos/routes/', 'src/bongos/'], criteria: ['C8'], deps: ['R53', 'R54'],
+  },
+  {
+    key: 'P4B',
+    title: 'bongos login <instance> (instance-agnostic) + stranger access-request flow; folds in init/upgrade',
+    description: `Part of Cloud Bongos / C8. Cross-ref: P1, P4A (manifest), R64 (\`medusa/bongos upgrade\`), R65 (\`init\`), ADR 0050/0057/0059 (admission).
+
+\`bongos login <instance-url>\` fetches the P4A manifest, runs the GitHub device-flow (browser-click, no token paste — the UI-first rule), stores a per-instance scoped session, and brands the CLI for that instance. For someone NOT yet admitted, it files the public POST /api/gds/access-requests (their GitHub username) and polls — telling them "an Archon will approve you with a 👍 in Discord" — until admission flips, then completes sign-in. No GitHub collaborator invite is involved. Default admission is invite-only. Also folds the already-planned \`bongos init\` (scaffold a brand-new instance, R65) and \`bongos upgrade\` (R64) in as subcommands of the same CLI.
+
+**Done when:** \`bongos login <any-instance-url>\` works end-to-end including the not-yet-admitted path (files the request, polls, completes once approved); the CLI is instance-agnostic (no hard-coded amazonprimea); \`init\`/\`upgrade\` are reachable subcommands.`,
+    kind: 'feature', discipline: 'engineer', priority: 3,
+    est_minutes: 360, manual_degree: 2, credits_reward: 60,
+    touches: ['bin/', 'scripts/gds/'], criteria: ['C8'], deps: ['P1', 'P4A'],
+  },
+];
+
+async function main() {
+  await requireSession();
+  const api = await cliClient();
+
+  // Pull the current GDS-V4 task list once: idempotency (skip existing
+  // source_ref), the next free R## (decorative sort prefix), and cross-cluster
+  // dep resolution (R53/R54 -> task id).
+  const list = await api.tasks.getTasks({ query: { version: 'GDS-V4' } });
+  const existing = list.data?.tasks || [];
+  const bySourceRef = {};
+  const idByRealRef = {}; // 'R53' -> id, parsed from the V4.R## title prefix
+  let maxR = 0;
+  for (const t of existing) {
+    if (t.source_ref) bySourceRef[t.source_ref] = t;
+    const m = /V4\.R(\d+)\b/.exec(t.title || '');
+    if (m) {
+      const n = Number(m[1]);
+      idByRealRef[`R${n}`] = Number(t.id);
+      if (n > maxR) maxR = n;
+    }
+  }
+  console.log(`context: ${existing.length} GDS-V4 tasks, maxR=R${maxR}, R53=${idByRealRef.R53 || '?'}, R54=${idByRealRef.R54 || '?'}`);
+
+  // Assign display R## numbers sequentially after the current max.
+  const refByKey = {};
+  TASKS.forEach((def, i) => { refByKey[def.key] = `R${maxR + 1 + i}`; });
+
+  const idByKey = {};
+  let created = 0, skipped = 0, errors = 0;
+
+  for (const def of TASKS) {
+    const r = refByKey[def.key];
+    const source_ref = `gds-v4-bongos-${def.key.toLowerCase()}`;
+    if (bySourceRef[source_ref]) {
+      idByKey[def.key] = Number(bySourceRef[source_ref].id);
+      console.log(`SKIP  ${def.key} (${r}) already exists: id=${bySourceRef[source_ref].id}`);
+      skipped++;
+      continue;
+    }
+    const body = {
+      version_id: 'GDS-V4',
+      title: `V4.${r} — ${def.title}`,
+      description: def.description,
+      kind: def.kind,
+      discipline: def.discipline,
+      status: 'backlog',
+      priority: def.priority,
+      est_minutes: def.est_minutes,
+      manual_degree: def.manual_degree,
+      credits_reward: def.credits_reward,
+      touches: def.touches || [],
+      criterion_ids: def.criteria || [],
+      source: 'planning-session',
+      source_ref,
+    };
+    if (DRY) {
+      const deps = (def.deps || []).map((d) => (refByKey[d] ? `${d}=${refByKey[d]}` : d)).join(',');
+      console.log(`DRY   ${def.key} -> ${r}  P${def.priority} ${def.kind}  crit=${(def.criteria || []).join('/')}  deps=[${deps}]  ${def.title.slice(0, 52)}`);
+      continue;
+    }
+    const res = await api.tasks.postTasks({ body });
+    if (res.status !== 201) {
+      console.error(`FAIL  ${def.key}: status=${res.status} ${JSON.stringify(res.data).slice(0, 220)}`);
+      errors++;
+      continue;
+    }
+    idByKey[def.key] = Number(res.data.task.id);
+    console.log(`OK    ${def.key} -> V4.${r}  task id=${idByKey[def.key]}  (crit ${(def.criteria || []).join('/')})`);
+    created++;
+  }
+
+  // Resolve a dep ref (symbolic key OR real 'R##') to a task id.
+  const resolveDep = (ref) => idByKey[ref] ?? idByRealRef[ref] ?? null;
+
+  let depsWired = 0, depErrors = 0;
+  if (!DRY) {
+    for (const def of TASKS) {
+      const deps = def.deps || [];
+      if (deps.length === 0) continue;
+      const taskId = idByKey[def.key];
+      if (!taskId) { console.error(`DEPS  ${def.key}: no task id (create failed?), skipping`); depErrors++; continue; }
+      const depIds = deps.map(resolveDep).filter((n) => Number.isFinite(n));
+      if (depIds.length !== deps.length) {
+        const missing = deps.filter((d) => !Number.isFinite(resolveDep(d)));
+        console.error(`DEPS  ${def.key}: unresolved deps [${missing.join(',')}] — wiring the resolvable ones only`);
+        depErrors++;
+        if (depIds.length === 0) continue;
+      }
+      const res = await api.tasks.postTasksIdDependencies({ id: taskId, body: { depends_on_task_ids: depIds } });
+      if (res.status === 200) {
+        console.log(`DEPS  ${def.key} <- [${deps.join(',')}] (ids ${depIds.join(',')})`);
+        depsWired++;
+      } else {
+        console.error(`DEPS FAIL ${def.key}: ${res.status} ${JSON.stringify(res.data).slice(0, 220)}`);
+        depErrors++;
+      }
+    }
+  }
+
+  console.log(`\nDONE  created=${created} skipped=${skipped} errors=${errors} deps_wired=${depsWired} dep_errors=${depErrors}  (manifest: ${TASKS.length})`);
+  process.exit(errors === 0 && depErrors === 0 ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error('FATAL', err);
+  process.exit(1);
+});