@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/seed-module-upstreaming.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/seed-module-upstreaming.js — seed the "Module upstreaming & catalog"
+// goal + its ecosystem tasks (ADR 0107, task 1766). Idempotent on source_ref.
+//
+// WHAT THIS SEEDS (the API-doable parts): the goal (find-or-create) + the 7
+// ecosystem tasks + their dependency edges. The SQL-only finishing — attaching
+// these tasks to the goal (tasks.goal_id), creating the goal's done-when
+// criteria, and consolidating the ADR-0103 separation spine (reparent
+// 1726/1727/1728 -> G26, add the 1727->1688 dep) — is a companion guarded
+// data-migration, because the GDS HTTP API exposes none of those (see ADR 0107
+// "Tooling note").
+//
+// Usage:  node scripts/bongos/seed-module-upstreaming.js [--dry-run]
+const { cliClient, requireSession } = require('./cli-lib');
+const DRY = process.argv.includes('--dry-run');
+
+const VERSION = 'BONGOS-V1';
+const GOAL_TITLE = 'Module upstreaming & catalog — instances contribute modules into core';
+const GOAL_DESC =
+  'ADR 0107. The reverse of the ADR 0100/0103 distribution arrow: instances (Example, ' +
+  'Mercury) build feature modules and submit them for approval to be merged INTO the shared ' +
+  'Cloud Bongos core catalog, credited to author + origin project. Accepted modules land in ' +
+  'core modules/<key>/ default-off, added to the isPublishable() allowlist; every instance may ' +
+  'opt in. Reward = credit now, money later. AGPL-in with a DCO sign-off (no CLA). Security ' +
+  'review is a hard accept-gate. Prereqs (manifest fields, module-owned CI test discovery, ' +
+  'submit-time pre-check) are buildable now; the submit->review->accept->catalog pipeline ' +
+  'depends on R88 (extract core, 1727) + R85 (Mercury, 1689).';
+
+// External anchors (existing tasks the pipeline gates on).
+const R88_EXTRACT_CORE = 1727; // BV1.R88 — extract the core into its own repo
+const R85_MERCURY = 1689;      // V4.R85 — stand Mercury up as customer 2
+
+// key, title, description, kind, priority, est, credits, touches, deps
+// deps: internal keys (this batch) and/or numeric ids (existing tasks).
+const TASKS = [
+  {
+    key: 'manifest',
+    title: 'Module upstreaming: extend module.json with attribution (author, origin, license, maintainer)',
+    description:
+      'ADR 0107 §2. Add author, origin (origin instance/project), license, and maintainer fields to ' +
+      'the module manifest so credit + provenance travel WITH the module (a portable record, not a ' +
+      'cross-GDS foreign key). Extend src/module-loader/manifest-schema.js validation (unknown keys ' +
+      'still fail loud), update docs/modules-contract.md, and cover it in tests/module_manifest.mjs. ' +
+      'Buildable now (single repo); dormant until the split.\n\n' +
+      'Done when: the manifest accepts + validates the four fields, docs document them, and a fresh ' +
+      'module scaffolded by `bongos module new` carries them.',
+    kind: 'infra', priority: 4, est: 120, credits: 25,
+    touches: ['src/module-loader/', 'docs/modules-contract.md', 'tests/'], deps: [],
+  },
+  {
+    key: 'ci-tests',
+    title: 'Module upstreaming: run module-owned tests (modules/<key>/tests/) in core CI',
+    description:
+      'ADR 0107 (closes the audit CI gap). Today run-unit-tests.js globs only repo-root tests/ — a ' +
+      "contributed module's own tests would not run in core CI. Extend the runner to discover " +
+      'modules/<key>/tests/*.mjs (enabled-gated, same MODULE_DISABLED skip semantics) so a ' +
+      'contributed module is self-contained and its tests actually gate acceptance. Buildable now.\n\n' +
+      'Done when: a test placed under modules/<key>/tests/ runs in the unit gate when the module is ' +
+      'enabled and is skipped when disabled; the existing repo-root tests still run.',
+    kind: 'infra', priority: 4, est: 120, credits: 25,
+    touches: ['scripts/bongos/run-unit-tests.js', 'tests/'], deps: [],
+  },
+  {
+    key: 'precheck',
+    title: 'Module upstreaming: submit-time AGPL/publish + copyright pre-check with DCO sign-off',
+    description:
+      'ADR 0107 §4. A `bongos module check` that runs isPublishable() over a module before it can be ' +
+      'submitted upstream — rejecting anything that cannot ship under AGPL (game content, pixel art, ' +
+      'copyrighted references) — and captures a lightweight DCO-style sign-off (contributor affirms ' +
+      "it is their own work, licensed AGPL-3.0; NO copyright-assignment CLA). Reuses scripts/bongos/" +
+      'publish-manifest.js. Buildable now.\n\n' +
+      'Done when: the pre-check passes a clean platform-shaped module, fails a module containing ' +
+      'denied content with a clear reason, and records the sign-off; covered by tests.',
+    kind: 'infra', priority: 4, est: 180, credits: 35,
+    touches: ['scripts/bongos/', 'src/module-loader/', 'tests/'], deps: ['manifest'],
+  },
+  {
+    key: 'submit',
+    title: 'Module upstreaming: `bongos module submit` — package module + attribution + sign-off into the core review queue',
+    description:
+      'ADR 0107 §1. Package a module (code + manifest attribution + DCO sign-off), run the §4 ' +
+      'pre-check, and file it into a rank-gated review queue on the CORE instance — WITHOUT granting ' +
+      'the submitting instance write access to core (fork-and-PR stays a fallback). Depends on there ' +
+      'being a core repo to submit into (R88) and a producing consumer (R85).\n\n' +
+      'Done when: `bongos module submit <key>` on an instance files a review-queue entry on the core ' +
+      'with the module payload + attribution + sign-off, and refuses if the pre-check fails.',
+    kind: 'feature', priority: 3, est: 360, credits: 60,
+    touches: ['bin/', 'scripts/bongos/'], deps: ['manifest', 'precheck', R88_EXTRACT_CORE, R85_MERCURY],
+  },
+  {
+    key: 'accept',
+    title: 'Module upstreaming: core-side review & accept flow (security + license + grader gate)',
+    description:
+      'ADR 0107 §5/§6. A rank-gated (Metic+/maintainer) review queue on the core: SECURITY review ' +
+      '(a contributed module runs in-process in every enabling instance — no sandbox yet), license/' +
+      'DCO check, and a quality/grader pass. Accept = land the module in core modules/<key>/ ' +
+      'default-off + add it to the isPublishable() allowlist + record attribution. Reject with ' +
+      'reasons. Depends on the submit flow.\n\n' +
+      'Done when: a reviewer can accept a queued module (it lands default-off, allowlisted, ' +
+      'attributed) or reject it with a reason; acceptance requires the security review to pass.',
+    kind: 'feature', priority: 3, est: 420, credits: 70,
+    touches: ['src/bongos/', 'modules/', 'scripts/bongos/'], deps: ['submit'],
+  },
+  {
+    key: 'catalog',
+    title: 'Module upstreaming: browsable module catalog with author + origin credit',
+    description:
+      'ADR 0107 §2/§3 (credit now). A browsable catalog of available core modules — each shown with ' +
+      'its author + origin project credit — surfaced in the hall and via `bongos module list ' +
+      '--catalog`. This is the visible "larger repository of modules built by the sub-projects." ' +
+      'The monetary reward (drachmae/cross-instance payout) is explicitly OUT of scope here (deferred ' +
+      'economics decision). Depends on the accept flow.\n\n' +
+      'Done when: the catalog lists enabled-able core modules with author + origin credit, browsable ' +
+      'in the hall and from the CLI.',
+    kind: 'feature', priority: 2, est: 300, credits: 55,
+    touches: ['modules/hall-ui/', 'bin/', 'src/bongos/'], deps: ['accept'],
+  },
+  {
+    key: 'maintenance',
+    title: 'Module upstreaming: maintenance & deprecation policy for accepted modules',
+    description:
+      'ADR 0107 §7. A policy + the mechanics for accepted-module upkeep: a module pinned to an old ' +
+      'coreVersion rots as core advances. Define whether an accepted module becomes core-maintained ' +
+      'or carries a named maintainer + a deprecation path, and surface coreVersion incompatibility ' +
+      'via the existing `bongos upgrade` pre-check so the catalog never fills with silently-broken ' +
+      'entries. Depends on the accept flow.\n\n' +
+      'Done when: the policy is recorded (doc/ADR), and an incompatible accepted module is flagged ' +
+      '(not silently broken) at upgrade time.',
+    kind: 'infra', priority: 2, est: 180, credits: 35,
+    touches: ['docs/', 'scripts/bongos/'], deps: ['accept'],
+  },
+];
+
+async function findOrCreateGoal() {
+  const api = await cliClient();
+  const list = await api.goals.getGoals({ query: { version: VERSION } });
+  const goals = list.data?.goals || [];
+  const existing = goals.find((g) => g.title === GOAL_TITLE);
+  if (existing) {
+    console.log(`GOAL exists: id=${existing.id} "${existing.title}"`);
+    return existing.id;
+  }
+  if (DRY) { console.log(`[dry-run] would create goal "${GOAL_TITLE}"`); return null; }
+  const res = await api.goals.postGoals({ body: {
+    version_id: VERSION, title: GOAL_TITLE, description: GOAL_DESC,
+  } });
+  const id = res.data?.goal?.id;
+  console.log(`GOAL created: id=${id}`);
+  return id;
+}
+
+async function main() {
+  await requireSession();
+  const api = await cliClient();
+  const goalId = await findOrCreateGoal();
+
+  const list = await api.tasks.getTasks({ query: { version: VERSION } });
+  const existing = list.data?.tasks || [];
+  const bySourceRef = {};
+  for (const t of existing) if (t.source_ref) bySourceRef[t.source_ref] = t;
+
+  const idByKey = {};
+  let created = 0, skipped = 0;
+  for (const def of TASKS) {
+    const source_ref = `mod-upstream-${def.key}`;
+    if (bySourceRef[source_ref]) {
+      idByKey[def.key] = Number(bySourceRef[source_ref].id);
+      console.log(`SKIP  ${def.key}: exists id=${idByKey[def.key]}`);
+      skipped++;
+      continue;
+    }
+    if (DRY) { console.log(`[dry-run] would create ${def.key}: ${def.title}`); continue; }
+    const res = await api.tasks.postTasks({ body: {
+      version_id: VERSION,
+      title: def.title,
+      description: def.description,
+      kind: def.kind,
+      discipline: 'engineer',
+      priority: def.priority,
+      est_minutes: def.est,
+      credits_reward: def.credits,
+      touches: def.touches,
+      source: 'planning',
+      source_ref,
+    } });
+    const id = res.data?.task?.id;
+    idByKey[def.key] = Number(id);
+    console.log(`CREATE ${def.key}: id=${id}`);
+    created++;
+  }
+
+  // Dependencies (after all tasks exist so internal keys resolve).
+  // NOTE: PUT /dependencies is a FULL REPLACE of a task's task->task edges. This
+  // is safe because we only PUT the 7 tasks WE create (never the anchors 1727/
+  // 1689), so re-running can't clobber edges set elsewhere (e.g. the migration's
+  // 1727->1688). If a task's `deps` list here is ever hand-edited, re-running
+  // will overwrite that task's edge set to match — that's intended (this script
+  // is authoritative for its own tasks' deps), not a bug.
+  if (!DRY) {
+    for (const def of TASKS) {
+      if (!def.deps.length) continue;
+      const id = idByKey[def.key];
+      if (!id) continue;
+      const depIds = def.deps.map((d) => (typeof d === 'number' ? d : idByKey[d])).filter(Boolean);
+      if (!depIds.length) continue;
+      await api.tasks.putTasksIdDependencies({ id, body: { depends_on_task_ids: depIds } });
+      console.log(`DEPS  ${def.key} (${id}) -> [${depIds.join(', ')}]`);
+    }
+  }
+
+  console.log(`\nGOAL id=${goalId} | created=${created} skipped=${skipped}`);
+  console.log('task ids:', JSON.stringify(idByKey));
+  console.log('\nNEXT: the guarded migration attaches these to the goal (goal_id), creates the');
+  console.log('goal criteria, and reparents the ADR-0103 spine (1726/1727/1728 -> G26, dep 1727->1688).');
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

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

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// Seed the "Cloud Bongos — productization & self-host" tasks derived from the
+// 2026-07-04 guided CLAUDE.md portability review (Lars + Claude, remote-control
+// session). All land under BONGOS-V1, goal id=26 ("Cloud Bongos productization
+// and self-host"), linked through that goal's done-when criteria:
+//   C16 gcarry-prod-customer2 — a second instance runs live on pinned core
+//   C22 gcarry-prod-upgrade   — `bongos upgrade` is a real update channel
+//   C32 gcarry-prod-vanilla   — vanilla boot is clean, NO host-branding leaks
+//   C35 gcarry-prod-hosting   — instance hosting as a module
+// Most of the CLAUDE.md-portability work is "de-leak the core so vanilla boots
+// clean" -> C32.
+//
+// Shape mirrors seed-bongos-tasks.js exactly:
+//   - POST /api/bongos/tasks   { version_id:'BONGOS-V1', criterion_ids:['C32'], ... }
+//   - idempotent on source_ref (skips already-created)
+//   - display BV1.R## assigned dynamically after the current max (decorative)
+//
+// Usage:  node scripts/bongos/seed-productization-tasks.js [--dry-run]
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+const DRY = process.argv.includes('--dry-run');
+
+// Each: { key, title, description, kind, discipline, priority, est_minutes,
+//   manual_degree, credits_reward, touches, criteria, deps }
+const TASKS = [
+  {
+    key: 'NAMING',
+    title: 'GDS → Bongos naming sweep across CLAUDE.md + core docs',
+    description: `From the 2026-07-04 CLAUDE.md review (bullets 3, 21, 151, 165, 195). The API prefix already moved to \`/api/bongos\` (src/bongos/api-prefix.js) with \`/api/gds\` kept as a permanent alias — but the docs still say "GDS." Sweep the user-facing naming in CLAUDE.md + core docs: \`/api/gds/*\` → \`/api/bongos/*\` (note the permanent alias once), and "GDS database / GDS task / GDS versions table" prose → "Bongos …". Follow the established "add the new surface, keep the old alias" precedent — do NOT break \`/api/gds\`. Directory rename (src/bongos/) is a SEPARATE task (see selfhost-rename-src).
+
+**Done when:** no user-facing \`/api/gds\` or bare "GDS" naming remains in CLAUDE.md + the core nav/prose (aliases documented once); links still resolve; docs-entropy clean.`,
+    kind: 'refactor', discipline: 'engineer', priority: 4,
+    est_minutes: 90, manual_degree: 3, credits_reward: 20,
+    touches: ['CLAUDE.md', 'docs/'], criteria: ['C32'], deps: [],
+  },
+  {
+    key: 'RENAME-SRC',
+    title: 'src/bongos/ → src/bongos/ directory rename (staged, de-risked)',
+    description: `From the 2026-07-04 review (bullet 27). Owner wants the rename but is (rightly) wary of a huge, half-finished sweep. Make it deterministic, not a manual hunt. STAGED:
+1. **Spike / inventory** — enumerate EVERY reference site: JS require/import paths, docs, \`config/*\`, \`.claude/\` hooks + scheduled-tasks, migration comments, the droplet checkout path — and write a codemod (path-string rewrite is deterministic).
+2. **Execute behind green gates that PROVE completeness** — full test suite + \`node scripts/bongos/fitness.js\` (import-boundary + repo-map freshness) + boot smoke + \`knip\` + \`docs-entropy\` link check must ALL stay green.
+3. **Compat shim** only for anything genuinely external (e.g. the droplet path). Mirror the api-prefix precedent (add new, don't break old) where a shim is cheap.
+
+**Done when:** \`src/bongos/\` is \`src/bongos/\`; all gates green; nothing references the old path except an intentional shim; the codemod is committed so the approach is auditable.`,
+    kind: 'refactor', discipline: 'engineer', priority: 3,
+    est_minutes: 300, manual_degree: 2, credits_reward: 60,
+    touches: ['src/bongos/', 'scripts/', 'docs/', '.claude/'], criteria: ['C32'], deps: [],
+  },
+  {
+    key: 'DOCS-DISCOVERY',
+    title: 'ADR: instance docs-discovery contract (how an agent finds its hall/docs)',
+    description: `From the 2026-07-04 review (bullet 6). Today the only pointer to an instance's doc surface is \`domains.buildersOrigin\` in branding.json. A fresh self-hosted instance needs a DEFINED contract for how an agent reliably locates its builders' hall + rendered docs from config alone (standard docs location? discovery endpoint? manifest field?). Write an ADR that pins the contract, then CLAUDE.md's preamble references it instead of hand-waving.
+
+**Done when:** an ADR records the docs-discovery contract; branding/config carries the needed field(s); CLAUDE.md §0 points at the contract; a second instance can resolve its docs surface with no hard-coded example.`,
+    kind: 'decision', discipline: 'engineer', priority: 3,
+    est_minutes: 90, manual_degree: 3, credits_reward: 20,
+    touches: ['docs/adr/', 'config/', 'CLAUDE.md'], criteria: ['C16'], deps: [],
+  },
+  {
+    key: 'TRACKS',
+    title: 'Deprecate the two-track (product/internal) model',
+    description: `From the 2026-07-04 review (bullets 48 DECISION, 79, 148-149). Downstream instances build only THEIR product and will not contribute back to Cloud Bongos — they have a single track. Work-type differentiation is already handled by discipline/role (engineer/artist/ideator), so tracks are redundant. DEPRECATE: remove the two-track framing from CLAUDE.md (§1, §8), the nav row, \`tracks\` in branding.json, and \`docs/TRACKS.md\`; and unwind the code that derives a task's track from its version. Preserve any genuinely needed per-work-type behavior via roles.
+
+**Done when:** no track concept remains in the portable core (docs/config/code); role/discipline is the sole work-type axis; existing tasks migrate cleanly; smoke + fitness green.`,
+    kind: 'refactor', discipline: 'engineer', priority: 4,
+    est_minutes: 240, manual_degree: 2, credits_reward: 50,
+    touches: ['CLAUDE.md', 'config/branding.json', 'docs/TRACKS.md', 'src/bongos/'], criteria: ['C32'], deps: [],
+  },
+  {
+    key: 'VERSION-ARCHIVES',
+    title: 'Relocate + genericize version-scope archives out of the core',
+    description: `From the 2026-07-04 review (bullets 49, 155). The core names instance/platform-specific version archives (game V1/V2, PMS-V1/V2, GDS-V3/V4) in the nav (§ nav) and §8 durable-artifacts. Portable core should describe the MECHANISM only (\`limitations/*-shipped.md\` = per-version scope archives, written after a guided review); the specific archives are host/platform state. Split: game-version archives → instance context (project-context.md); platform-version archives → Cloud Bongos platform docs; add the missing GDS-V4/BONGOS-V1 entry where platform history is kept. Flag the deeper question: a fresh instance's core template should ship with NO version history.
+
+**Done when:** the core describes the archive mechanism generically; specific version archives live in instance/platform context; nav rows updated; GDS-V4/BONGOS-V1 no longer "missing."`,
+    kind: 'refactor', discipline: 'engineer', priority: 3,
+    est_minutes: 120, manual_degree: 3, credits_reward: 25,
+    touches: ['CLAUDE.md', 'docs/project-context.md', 'limitations/'], criteria: ['C32'], deps: [],
+  },
+  {
+    key: 'NAV-HYGIENE',
+    title: 'Nav hygiene — reference the module, split instance-specifics',
+    description: `From the 2026-07-04 review (bullets 42, 57, 64, 66, 68, 94). Several nav rows (and §2 prose) INLINE content that belongs to a module or to instance-specifics. Convert them to module references, and split anything naming the example servers/assets into project-specific detail. By module:
+- **discord** (57, 64, 94): inbound #ideas, build-broadcast, channel layout → reference the discord module; the general mechanism lives there, anything naming the example Discord server specifically → project-specific detail.
+- **art-pipeline** (66): the pixel-art design-system row → reference the art module; the pixel/greek style choice itself is instance detail.
+- **game** (68): world-cell model + paths-as-overlays rows → the game module / instance context (out of the portable core).
+
+**Done when:** those nav/§2 items are thin references to their modules; no module-owned or example-server-specific detail is inlined in the core; the game-specific rows are out of core.`,
+    kind: 'cleanup', discipline: 'engineer', priority: 3,
+    est_minutes: 120, manual_degree: 3, credits_reward: 25,
+    touches: ['CLAUDE.md'], criteria: ['C32'], deps: [],
+  },
+  {
+    key: 'ECONOMY-REWARD',
+    title: 'Economy module owns reward config (currency + formula + peg), per-project',
+    description: `From the 2026-07-04 review (bullet 42). The reward currency + formula (\`round(true_cost_usd × 1.20)\`, "1 unit = $1") currently surface in CLAUDE.md — a portability leak AND a soft-integrity risk (an editable doc shouldn't state pay math). Move the reward configuration into the economy module as per-project, customizable config: currency label (already in branding \`currency.label\`), the reward multiplier, and the USD peg. CLAUDE.md's "how builders earn" nav row becomes a pointer to the economy module.
+
+**Done when:** reward currency + formula + peg are economy-module config, customizable per instance; CLAUDE.md only references the module (no formula in the doc); existing OTB values preserved as that instance's config.`,
+    kind: 'feature', discipline: 'engineer', priority: 3,
+    est_minutes: 180, manual_degree: 2, credits_reward: 40,
+    touches: ['modules/economy/', 'CLAUDE.md', 'config/'], criteria: ['C32'], deps: [],
+  },
+  {
+    key: 'BUILDER-PROFILE',
+    title: '§2 "The Prompter" → per-builder interaction profile',
+    description: `From the 2026-07-04 review (bullets 85, 87, 92). Principle: there is NO special "owner" entity — an owner is just a builder with elevated permissions + a profile. So §2's "how to work with me" defaults should become a PER-BUILDER interaction profile (tone, technical level, local-toolchain familiarity), captured at onboarding and injected each session — extending the existing per-builder settings infra (the \`wandering\` knob already works this way). Include a layer that helps NON-TECHNICAL builders who lack their own local LLM/dev-tool config. Sound-on-turn-end (bullet 92) becomes builder-local ergonomics config too. The portable defaults stay as the fallback. §2 shrinks to a thin pointer.
+
+**Done when:** a builder's interaction profile is captured at onboarding + injected per session (builder-settings); the portable defaults are the fallback; §2 is a pointer, not a hardcoded owner section; build-broadcast/sound mentions move to their modules (see nav-hygiene / discord).`,
+    kind: 'feature', discipline: 'engineer', priority: 3,
+    est_minutes: 240, manual_degree: 2, credits_reward: 50,
+    touches: ['modules/builder-settings/', 'modules/onboarding/', 'CLAUDE.md'], criteria: ['C32'], deps: [],
+  },
+  {
+    key: 'MODEL-SETTINGS',
+    title: 'Per-builder/instance model-allocation settings (§2 routing → link)',
+    description: `From the 2026-07-04 review (bullets 96-105). The subagent model-routing policy (main = Opus, subagents = Haiku/Opus, "no Sonnet") is hardcoded in CLAUDE.md §2 — it rots as model names change and is the same class of leak as the currency. Build per-builder/instance model-allocation SETTINGS (main session tier + subagent tiers, with defaults and overrides), improve them, and make §2's routing table a LINK to the setting. The existing §2 blockquote already promised this ("configurable model allocation").
+
+**Done when:** model allocation is settings-driven (per-builder and/or instance defaults, overridable); §2 references the setting instead of hardcoding tiers; changing a default doesn't require a doc edit.`,
+    kind: 'feature', discipline: 'engineer', priority: 3,
+    est_minutes: 180, manual_degree: 2, credits_reward: 40,
+    touches: ['modules/builder-settings/', 'CLAUDE.md'], criteria: ['C32'], deps: [],
+  },
+  {
+    key: 'IDENTITY-ORG',
+    title: 'Rationalize the identity apparatus + structure project-context.md',
+    description: `From the 2026-07-04 review (bullets 109-111, 134/140, 187). Almost every identity section (§§1,3,5,6,7,9) is now a thin pointer to project-context.md, the §3 stub verbosely re-explains the core↔host split that §1 + the charter already cover, and the §6/§7 stubs still NAME the instance ("the Example world", "the \`otb-*\` art skills"). Meanwhile project-context.md is getting overloaded (bullet 187). Fix: collapse §§3/5/6/7 to a single minimal pointer (or one-liners), genericize instance names out of any surviving stub, and give project-context.md a real section structure.
+
+**Done when:** the stub scaffolding is minimal + instance-name-free in the core; project-context.md has a clear, non-overloaded structure; anchors/cross-refs still resolve.`,
+    kind: 'cleanup', discipline: 'engineer', priority: 3,
+    est_minutes: 120, manual_degree: 3, credits_reward: 25,
+    touches: ['CLAUDE.md', 'docs/project-context.md'], criteria: ['C32'], deps: [],
+  },
+  {
+    key: 'REPOMAP',
+    title: 'Generated-docs & repo-map overhaul (regen pattern + doc link-graph + staleness flags)',
+    description: `From the 2026-07-04 review (bullets 178, 193, 223/224/226). Three related moves, all applying the repo-map philosophy (generated, not committed, regenerated at deploy/box-fetch — ADR 0110) to fight doc drift:
+1. **178** — apply the repo-map generation pattern to the auto-generated diagrams (and session-index) so generated artifacts don't clutter git or drift.
+2. **193** — enhance repo-map with a DOC LINK-GRAPH (click architecture.md → see the docs it links to) + STALENESS FLAGS for docs needing touch-ups (builds on what docs-entropy.js already detects).
+3. **223/224/226** — the manual "remember to update architecture.md / file-map.md / detail files" session-end chores are drift-prone; replace with staleness-flagging + regen-where-possible so the update happens mechanically, not by memory.
+
+**Done when:** generated docs follow the gitignore+regen pattern; repo-map shows a doc link-graph + staleness flags; the manual "update detail files" chores are reduced to flagged/auto-regenerated work. (May be split into 3 child tasks at triage.)`,
+    kind: 'feature', discipline: 'engineer', priority: 2,
+    est_minutes: 480, manual_degree: 2, credits_reward: 80,
+    touches: ['scripts/bongos/', 'docs/'], criteria: ['C22'], deps: [],
+  },
+  {
+    key: 'SCHED-PORT',
+    title: 'Scheduled-routines portability to self-host + multi-builder',
+    description: `From the 2026-07-04 review (bullet 241). The ~17 autonomous cron routines under \`.claude/scheduled-tasks/\` (overnight-code-review, idea-triage-nightly, overnight-builder, bfg, security-review-weekly, …) are written for this instance. Define how they port to a self-hosted, multi-builder world: which run instance-wide vs per-builder, how a fresh instance inherits/configures them, and what a builder gets by default. Spike → a contract (and likely a config surface).
+
+**Done when:** there's a documented model for which routines are instance-wide vs per-builder, how a fresh instance inherits them, and how a builder configures their own; no routine hard-assumes the example instance.`,
+    kind: 'spike', discipline: 'engineer', priority: 2,
+    est_minutes: 120, manual_degree: 3, credits_reward: 25,
+    touches: ['.claude/scheduled-tasks/', 'docs/'], criteria: ['C16'], deps: [],
+  },
+  {
+    key: 'PROSE-POLISH',
+    title: 'CLAUDE.md prose polish (trims + two structural moves)',
+    description: `From the 2026-07-04 review (bullets 20, 77, 109-111, 134/140, 161, 170a, 170b). A batch of small doc improvements — split into safe trims and two structural moves:
+TRIMS: drop the low-value ADR 0062 link in the charter row (20); drop the Medusa→Cloud Bongos rename parenthetical in §1 (77); trim the verbose §3 stub + genericize §6/§7 stub names (109-111, 134/140 — overlaps IDENTITY-ORG); delete the resolved touches-drift history in the §8 ship bullet (170b — already done via task 879).
+STRUCTURAL: reposition the AI-first-norm paragraph out of mid-§8 to a prominent early spot + dedupe against the preamble (161); de-emphasize \`/merge-mode\` in §8 + §12 so it reads as the rare admin fallback it is, not a step people reach for while waiting on the 5-min auto-land (170a).
+
+**Done when:** the trims are applied; the AI-first norm sits early + isn't repeated; merge-mode is demoted to fallback framing; budget/line-count not worsened.`,
+    kind: 'cleanup', discipline: 'engineer', priority: 2,
+    est_minutes: 90, manual_degree: 3, credits_reward: 20,
+    touches: ['CLAUDE.md'], criteria: ['C32'], 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=BV1.R${maxR}`);
+
+  const refByKey = {};
+  TASKS.forEach((def, i) => { refByKey[def.key] = `R${maxR + 1 + i}`; });
+
+  let created = 0, skipped = 0, errors = 0;
+  for (const def of TASKS) {
+    const r = refByKey[def.key];
+    const source_ref = `selfhost-${def.key.toLowerCase()}`;
+    if (bySourceRef[source_ref]) {
+      console.log(`SKIP  ${def.key} (${r}) already exists: id=${bySourceRef[source_ref].id}`);
+      skipped++;
+      continue;
+    }
+    if (DRY) {
+      console.log(`DRY   ${def.key} -> BV1.${r}  P${def.priority} ${def.kind}/${def.discipline}  crit=${def.criteria.join('/')}  ${def.title.slice(0, 60)}`);
+      continue;
+    }
+    const body = {
+      version_id: 'BONGOS-V1',
+      // Goal 26 = "Cloud Bongos productization and self-host". POST /tasks
+      // otherwise defaults goal_id to the version's general goal (3) even when
+      // criterion_ids points at a goal-26 criterion — so set it explicitly.
+      goal_id: 26,
+      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,
+    };
+    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, 240)}`);
+      errors++;
+      continue;
+    }
+    console.log(`OK    ${def.key} -> BV1.${r}  task id=${res.data.task.id}  (crit ${def.criteria.join('/')})`);
+    created++;
+  }
+
+  console.log(`\nDONE  created=${created} skipped=${skipped} errors=${errors}  (manifest: ${TASKS.length})`);
+  process.exit(errors === 0 ? 0 : 1);
+}
+
+main().catch((err) => { console.error('FATAL', err); process.exit(1); });

package/scripts/bongos/seed-project-admin-console-tasks.js

@@ -0,0 +1,88 @@
+// Seed the build tasks for the project admin console (BONGOS-V1, internal).
+// Source of truth: docs/specs/bongos-v1-project-admin-console.md (status: draft —
+// spike task 1002786's output). Idempotent on (source, source_ref); re-running
+// resolves to the existing rows. The console wave is recommended as its OWN goal
+// (the spec's "where it lives" section): create it with /goal-create, then re-run
+// with --goal <id> to home the rows.
+//
+// Run: node scripts/bongos/seed-project-admin-console-tasks.js [--goal <id>]
+const { apiCall, requireSession, cliExit } = require('./cli-lib');
+const VER = 'BONGOS-V1';
+const gIdx = process.argv.indexOf('--goal');
+const GOAL = gIdx >= 0 ? Number(process.argv[gIdx + 1]) : null;
+const SRC = 'planning-session';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function api(method, path, body, _tries = 0) {
+  await sleep(400); // base throttle to stay under the per-IP rate limit
+  const r = await apiCall(method, `/api/bongos${path}`, body);
+  const json = r.data || {};
+  if (r.status === 429 && _tries < 8) {
+    const wait = ((json.error && json.error.details && json.error.details.retry_after_seconds) || 30) + 1;
+    console.log(`  …rate-limited, waiting ${wait}s`);
+    await sleep(wait * 1000);
+    return api(method, path, body, _tries + 1);
+  }
+  return { status: r.status, ok: r.status >= 200 && r.status < 300, json };
+}
+
+// disc: engineer (backend/API/ADR) | ui (frontend). All refs per the spec's task table.
+const TASKS = [
+  { ref: 'R1', kind: 'spike', disc: 'engineer', prio: 4, est: 120, deps: [],
+    title: 'R1 · ADR: the project admin console model (planes reconciled, authority local)',
+    desc: 'Record the spike decisions as an ADR: the instance IS the project (standalone model) so authority lives on the project instance; a recruit invite is a pre-approved access_requests row (kind=invite, status=invited — sign-in is the acceptance act, firstTimeAdmissionBlocked untouched); a new grantable project.recruit atom (floor archon) carries "which rank may recruit", with the raw admission verdict (access_request.review) staying archon; the hub role is notification/relay only, retiring the authority-less resolveInvite loop. Supersedes the ADR 0141 §5 deferred-slice note. See docs/specs/bongos-v1-project-admin-console.md.' },
+  { ref: 'R2', kind: 'feature', disc: 'engineer', prio: 4, est: 240, deps: ['R1'],
+    title: 'R2 · Instance outbound recruit: invite rows on access_requests + rescind + sender list',
+    desc: 'Additive migration: access_requests gains kind (application|invite), created_by, note-for-invites. POST /access-requests/invite (gated by the new project.recruit atom) inserts kind=invite status=invited so the login can sign straight in; a rescind route re-locks before first sign-in; the sender can list outstanding invites. Done-when: an archon invites a login that never applied, that login signs in; rescind re-locks; tests extend the access-requests suite. Spec: docs/specs/bongos-v1-project-admin-console.md D2.' },
+  { ref: 'R3', kind: 'feature', disc: 'engineer', prio: 4, est: 120, deps: ['R1'],
+    title: 'R3 · Governance: the project.recruit atom (floor archon, grantable) + route pins',
+    desc: 'catalog.js gains project.recruit (floor archon, grantable, guards naming the console routes); a governance grant migration seeds the archon role; src/bongos/route-rank-check.js gets a platform-identity/console pins block (none exists today). Done-when: granting metic via the existing /governance UI lets a metic send an invite on that instance, revoking re-locks. Spec D3.' },
+  { ref: 'R4', kind: 'feature', disc: 'ui', prio: 4, est: 300, deps: ['R2', 'R3'],
+    title: 'R4 · The console page: applications + invites + settings on the project hall',
+    desc: 'New hall page on the project instance following watch.js (page floor + per-section 403-degrade) and settings.html (section rail) patterns: the applications queue (absorbing The Watch\'s access-requests section — Watch keeps the count tile linking over), outgoing invites with rescind, the join-policy toggle, and a "who may recruit" pointer into /governance. Done-when: one page shows both queues with working act buttons. Spec §Where it lives.' },
+  { ref: 'R5', kind: 'feature', disc: 'engineer', prio: 3, est: 120, deps: ['R1'],
+    title: 'R5 · Join policy: open|closed enforced at the public application door',
+    desc: 'An instance setting join_policy (open|closed) read by the public POST /access-requests — closed refuses with honest copy; the hub join relay surfaces the same truth on the button. Flipping takes effect without deploy. Four-state visibility stays with goal 1000046 (deferred per spec). Done-when: a closed project cannot be applied to, and the UI says why, both venues.' },
+  { ref: 'R6', kind: 'feature', disc: 'engineer', prio: 3, est: 180, deps: ['R2'],
+    title: 'R6 · Hub loop repair: invites notify the hub; accept = go sign in; rescind cleans both',
+    desc: 'The instance invite (R2) seeds the hub pending-membership row as a NOTIFICATION so the invitee sees it in My Projects; accepting links to the project sign-in (admission already granted instance-side); rescind cleans both sides. Retire the dead-end resolveInvite accept semantics (today accepting a hub invite admits nobody). Done-when: no state where an accepted invite leads to a locked door. Spec D2.' },
+  { ref: 'R7', kind: 'feature', disc: 'ui', prio: 3, est: 90, deps: ['R4'],
+    title: 'R7 · Apex entry: "Manage members" on the mine-view card links to the console',
+    desc: 'public-landing/projects.html ?view=mine: each owned project card grows a "Manage members" link to that project\'s own hall console (cross-host, riding the ADR 0141 SSO path). The one goal-1000059-surface touch this wave makes. Done-when: an owner clicks from cloudbongos.com/projects into their project\'s console signed in.' },
+];
+
+(async () => {
+  await requireSession(); // friendly guidance (not a stack trace) when signed out
+  const idByRef = {};
+  let created = 0, existing = 0;
+  console.log(`Seeding ${TASKS.length} console tasks (${VER}${GOAL ? `, goal ${GOAL}` : ', no goal — re-run with --goal after /goal-create'})…`);
+  for (const t of TASKS) {
+    const body = {
+      version_id: VER, title: t.title, description: t.desc,
+      kind: t.kind, discipline: t.disc, priority: t.prio, est_minutes: t.est,
+      source: SRC, source_ref: `admin-console-${t.ref}`,
+    };
+    if (GOAL) body.goal_id = GOAL;
+    const r = await api('POST', '/tasks', body);
+    if (!r.ok) { console.log(`  ${t.ref}: FAILED ${r.status} ${JSON.stringify(r.json)}`); continue; }
+    const task = r.json.task || r.json;
+    idByRef[t.ref] = task.id;
+    if (r.json.idempotent || r.json.existing) existing++; else created++;
+    console.log(`  ${t.ref} → task ${task.id} (${t.kind}/${t.disc}, P${t.prio})`);
+  }
+
+  console.log('Wiring dependencies…');
+  let edges = 0;
+  for (const t of TASKS) {
+    if (!t.deps.length) continue;
+    const id = idByRef[t.ref];
+    const depIds = t.deps.map((d) => idByRef[d]).filter(Boolean);
+    if (!id || depIds.length !== t.deps.length) { console.log(`  ${t.ref}: dep resolve gap, skipping`); continue; }
+    const r = await api('POST', `/tasks/${id}/dependencies`, { depends_on_task_ids: depIds });
+    if (!r.ok) { console.log(`  ${t.ref}: dep FAILED ${r.status} ${JSON.stringify(r.json)}`); continue; }
+    edges += depIds.length;
+    console.log(`  ${t.ref} depends on ${t.deps.join(',')}`);
+  }
+  console.log(`Done: ${created} created, ${existing} existing, ${edges} dependency edges.`);
+  cliExit(0); // never process.exit() after a request (scripts/bongos/CLAUDE.md — the win/async.c abort)
+})();

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// seed-provisioning-tasks.js
+// Seeds the follow-up tasks for ADR 0111 — the `provisioning` module (instance
+// hosting + domains) + the self-host/managed split. Consolidates owner ideas
+// #345 + #303 (task #1485, BONGOS-V1, goal 26). Idempotent on source_ref;
+// dependency edges idempotent too. Cross-arm gating deps on R85/R86 (1689/1690).
+// Run: node scripts/bongos/seed-provisioning-tasks.js
+const os = require('os');
+const TOKEN = require(os.homedir() + '/.config/otb/gds-session.json').token;
+const BASE = require('../../src/instance-config').resolveEnv('BASE') || 'https://example.com';
+const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };
+const GOAL = 26; // Cloud Bongos productization and self-host
+
+// ref → task spec. deps are local P# refs; extDeps are already-existing task ids.
+const TASKS = [
+  { ref: 'P1', kind: 'feature', discipline: 'engineer', priority: 3, est: 300,
+    title: 'BV1 — Scaffold the `provisioning` module (web-tier request + state surface, no cloud tokens)',
+    description: 'ADR 0111 §1. `bongos module new provisioning` (default:false, coreVersion ^1.14.0). Add the namespaced tables provisioning_instances / provisioning_intents / provisioning_events (modules/provisioning/migrations/provisioning_NNN_*.sql, additive). Contribute the HTTP routes: own-scoped create-request / read-own-state / request-teardown, plus Archon-scoped fleet roster + force actions (the /boxes precedent) — every write rank-gated. Register a provisioning.instanceState port. HARD boundary: this module holds NO cloud provider tokens and calls NO cloud API — it only enqueues intents + reads state (§2). deps: none. (buildable now)',
+    deps: [], extDeps: [] },
+  { ref: 'P2', kind: 'refactor', discipline: 'engineer', priority: 3, est: 180,
+    title: 'BV1 — Extract the shared DigitalOcean + Cloudflare control-plane clients (dev-box + provisioning reuse)',
+    description: 'ADR 0111 §2. The DO v2 client (modules/dev-box/do-api.js) and the Cloudflare DNS logic (infra/box-dns-cloudflare.sh) that the new provision.js runner needs currently live inside modules/dev-box/. A module may not import another module; box.js + provision.js are control-plane CLIs that may require code directly. Extract these into a shared control-plane location (scripts/bongos/ or infra/) both CLIs use — dry-run-default preserved, dev-box behaviour byte-identical. Enables P3. deps: none. (buildable now)',
+    deps: [], extDeps: [] },
+  { ref: 'P3', kind: 'infra', discipline: 'engineer', priority: 3, est: 480,
+    title: 'BV1 — `scripts/bongos/provision.js` control-plane runner + systemd timer (automate the standup runbook)',
+    description: 'ADR 0111 §2/§3. A sibling of box.js — the SOLE holder of the DO/Cloudflare tokens (from a chmod-600 /etc/<inst>/box.env via EnvironmentFile=), drained by a systemd timer running `provision.js run-intents --apply`. Drains provisioning_intents and composes the cloudbongos-standup.md runbook into one idempotent, dry-run-default, drift-reconciling flow: server (co-tenant process OR a dedicated droplet) → createdb + GDS-only migrate (MEDUSA_GDS_ONLY=1) → write config + per-instance /etc/<inst>/web.env → install per-instance systemd unit + port → Caddy site block + reload → /healthz. Never touches the web tier. deps: P1, P2. (buildable now)',
+    deps: ['P1', 'P2'], extDeps: [] },
+  { ref: 'P4', kind: 'infra', discipline: 'engineer', priority: 2, est: 300,
+    title: 'BV1 — Automated DNS record + Caddy on-demand ACME TLS for a provisioned host',
+    description: 'ADR 0111 §4. Cloudflare A-record UPSERT via the shared client (P2), plus Caddy on-demand ACME (Let\'s Encrypt) so a NEWLY provisioned host is TLS-ready with no manual Cloudflare Origin-Cert console step (the least-automated leg today). On-demand TLS MUST be allow-listed to hostnames the module actually provisioned (no cert-minting for arbitrary names). Existing example/cloudbongos apexes keep their Origin Certs unchanged. deps: P2, P3. (buildable now)',
+    deps: ['P2', 'P3'], extDeps: [] },
+  { ref: 'P5', kind: 'feature', discipline: 'engineer', priority: 2, est: 240,
+    title: 'BV1 — Wire provisioning into `bongos init` (idea #345 — "configured via the API")',
+    description: 'ADR 0111 §3. The init.js interview\'s infra answers (bring-your-own-domain, target credential ref, hosting shape/tier) flow into a provisioning request (a provisioning_intents row) instead of only filing manual kickoff tasks. The two irreducibly-human steps stay guided/manual with exact instructions: GitHub OAuth-app creation (no clean create-API) and the first owner sign-in (seats the founding Archon). deps: P1, P3. (buildable now)',
+    deps: ['P1', 'P3'], extDeps: [] },
+  { ref: 'P6', kind: 'feature', discipline: 'ui', priority: 2, est: 240,
+    title: 'BV1 — Hall UI: "Instances" provisioning panel (own-scoped for owners, Archon fleet view)',
+    description: 'ADR 0111 §1. Surface provisioning_instances state + cost estimate: an owner sees their own instance(s) and request status; Archon sees the fleet roster + cost ledger. Reuse the dev-box "boxes" UI pattern (a uiSection gated by window.__MODULES__). deps: P1. (buildable now)',
+    deps: ['P1'], extDeps: [] },
+  { ref: 'P7', kind: 'spike', discipline: 'engineer', priority: 1, est: 240,
+    title: 'BV1 — Spec the managed fleet control plane (idea #303 — operate branded instances, push updates centrally)',
+    description: 'ADR 0111 §5/§7. Spec-first (an ADR): the central operator that sits ABOVE the locked per-repo GDS DBs (ADR 0100 §3), stands up branded instances on Cloud Bongos infra using the provisioning module pointed at Cloud-Bongos-held credentials, and drives the same `bongos upgrade` version-bump channel across the fleet. Same AGPL artifact (ADR 0065 §2 — no open-core). Genuinely greenfield (no fleet registry exists). Gated on R85 Mercury (#1689 — the first real second-repo consumer proving the two-repo path) + R86 (a real `bongos upgrade`, #1690). deps: 1689, 1690. (deferred)',
+    deps: [], extDeps: [1689, 1690] },
+  { ref: 'P8', kind: 'feature', discipline: 'engineer', priority: 1, est: 480,
+    title: 'BV1 — Managed billing / metering (meter provisioned resources → invoice → payment)',
+    description: 'ADR 0111 §6. No customer billing exists today (only a box cost LEDGER). The managed layer needs metering of provisioned resources → invoice → payment (Stripe; shares the V3 Stripe work). Reuse the SIZE_CATALOG per-size USD table for cost visibility. Self-host does not need this (the owner pays their own cloud bill). deps: P7. (deferred)',
+    deps: ['P7'], extDeps: [] },
+];
+
+async function post(path, body) {
+  const r = await fetch(BASE + path, { method: 'POST', headers: H, body: JSON.stringify(body) });
+  return { status: r.status, json: await r.json().catch(() => ({})) };
+}
+
+(async () => {
+  const idByRef = {};
+  // Phase 1: create tasks (idempotent on source_ref), link goal 26 at create.
+  for (const t of TASKS) {
+    const body = {
+      version_id: 'BONGOS-V1', title: t.title, description: t.description,
+      kind: t.kind, discipline: t.discipline, priority: t.priority,
+      est_minutes: t.est, goal_id: GOAL,
+      source: 'planning', source_ref: `BONGOS-V1-prov-${t.ref}`,
+    };
+    const { status, json } = await post('/api/bongos/tasks', body);
+    const id = json.id || (json.task && json.task.id);
+    if (!id) { console.log(`  ${t.ref}: CREATE FAILED — ${status} ${JSON.stringify(json).slice(0, 160)}`); continue; }
+    idByRef[t.ref] = id;
+    console.log(`  ${t.ref} -> task ${id} (${t.kind}, ${t.discipline}, P${t.priority})`);
+  }
+  // Phase 2: wire dependencies (idempotent on (task_id, depends_on_task_id)).
+  console.log('--- dependencies ---');
+  for (const t of TASKS) {
+    const id = idByRef[t.ref];
+    if (!id) continue;
+    const allDeps = [...t.deps.map((d) => idByRef[d]).filter(Boolean), ...t.extDeps];
+    for (const depId of allDeps) {
+      const { status, json } = await post(`/api/bongos/tasks/${id}/dependencies`, { depends_on_task_id: depId });
+      console.log(`  ${t.ref}(${id}) depends on ${depId} -> ${status === 200 || status === 201 ? 'ok' : (json.error || status)}`);
+    }
+  }
+  console.log('refs:', JSON.stringify(idByRef));
+})();