@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/goal-names.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// scripts/bongos/goal-names.js — give every open goal a NAME, and move its
+// explanation into `subtitle` (task 1003225, goal 1000072, criterion
+// legibility-goal-names-and-claude-text).
+//
+// Owner directive: a goal's subtitle should not sit on its title. 28 open goals
+// carried theirs after a dash and 3 more after a colon — the punctuation is not
+// the point, the jamming is. Task 1003224 gave `goals` a `subtitle` column and
+// taught the hall to render name / subtitle / Claude's prose at three weights;
+// this moves the existing text into that shape.
+//
+// WHY A MAPPING FILE AND NOT 31 AD-HOC PATCHES. A rename is a judgment call, and
+// judgment that lives only in a shell history cannot be reviewed, re-run, or
+// argued with. The table below IS the decision: it can be read in a diff, its
+// invariants are unit-tested (no duplicate names, no name still carrying its own
+// explanation, nothing dropped), and re-running is a no-op.
+//
+// IT IS NOT A MECHANICAL SPLIT, which is the whole reason this is its own task.
+// Splitting on the separator works where the head already names the thing
+// ("Findability — the grep path"). It FAILS where the head is not distinctive:
+// goals 1000038/1000039/1000040 all head "Agents module" and differ ONLY in the
+// tail, so a split would leave three identically-named goals — strictly worse
+// than today. Those three, the version catch-all, and three wordy heads get
+// written names; the rest keep theirs verbatim.
+//
+// SAFETY. Dry-run by DEFAULT (`--apply` to write). Every write goes through
+// PATCH /goals/:id, which is authorized (owner|manager|Archon) and records
+// prose-edit deltas — so the rename is audit-trailed, unlike the prod SQL UPDATE
+// that would otherwise be the only channel. It REFUSES to run at all if the
+// server does not yet return `subtitle`, because renaming titles against a
+// server that cannot store the subtitle would DELETE the explanations.
+
+'use strict';
+
+// id → { title, subtitle, why? }. `why` is recorded only where the name is
+// NEW rather than the existing head — i.e. where judgment was applied.
+const GOAL_NAMES = Object.freeze({
+  // ── names written, because the head was not usable ───────────────────────
+  1000003: { title: 'Work with no goal yet',
+    subtitle: 'The version catch-all. Tasks land here when nothing else fits — and nothing here can satisfy a criterion (ADR 0183), so it is a holding pen, not a home.',
+    why: 'was "BONGOS-V1 — general": a version id and the word general name nothing. Named for what it actually is.' },
+  1000038: { title: 'Agent framework & registry',
+    subtitle: 'The foundation — the plugin surface an agent is written against, and the registry that holds the roster.',
+    why: 'one of THREE goals heading "Agents module"; a mechanical split would have left three identically-named goals. Written without a colon on purpose: "Agents: framework" is the same name-plus-qualifier shape this task exists to remove, and the test flagged it.' },
+  1000039: { title: 'Agent authoring & first roster',
+    subtitle: 'Owner and builder authoring, plus the first real roster — event-driven and on-demand agents.',
+    why: 'second of the three "Agents module" goals. Named for what it adds — authoring and the first roster — rather than by a tail no list ever showed.' },
+  1000040: { title: 'Agent scheduling & spend limits',
+    subtitle: 'Scheduled agents, and the guardrails on what they are allowed to spend.',
+    why: 'third of the three "Agents module" goals. Scheduling and spend are what separate it from the framework and authoring goals.' },
+  1000053: { title: 'Sessions start knowing',
+    subtitle: 'Front-load auth, environment and instance facts so a session does not spend its first minutes rediscovering them.',
+    why: 'was "Session efficiency: sessions start knowing" — the head restated the tail. Kept the half that is a name.' },
+  1000064: { title: 'The hall as the room',
+    subtitle: 'Agora, Monitor & Contribute, and chat that does not care which channel it came from.',
+    why: 'colon-separated rather than dashed; same jamming, so treated identically.' },
+  1000075: { title: 'Collaboration & the social hall',
+    subtitle: 'Ask for help by craft, and let the hall become a mode rather than a page.',
+    why: 'was "Collab, then the social hall" — an ordering, not a name.' },
+  1000077: { title: 'Guards, not notes',
+    subtitle: 'The four failure modes that prose already documented and nothing refused.',
+    why: 'colon-separated; the head is already a good name, the tail is the explanation.' },
+  1000078: { title: 'Project money out',
+    subtitle: 'A funded balance, real builder payouts, visible outflows, and work that cannot outrun the money.',
+    why: 'colon-separated rather than dashed. The head is already the name; the tail is a four-part explanation that belongs underneath it.' },
+
+  // ── heads kept verbatim; only the tail moves ─────────────────────────────
+  1000025: { title: 'Builder experience', subtitle: 'Hall, dev box, and skills.' },
+  1000027: { title: 'Findability', subtitle: 'The grep path (ADR 0095).' },
+  1000029: { title: 'Module upstreaming & catalog', subtitle: 'Instances contribute modules back into core.' },
+  1000032: { title: 'Instance hosting + domains', subtitle: 'The `provisioning` module.' },
+  1000044: { title: 'Living project sky', subtitle: 'A shared, persistent, data-driven orb gate.' },
+  1000045: { title: 'Public builder profiles', subtitle: 'Track record, apply-to-project, and owner recruiting.' },
+  1000046: { title: 'Project creation', subtitle: 'Visibility and customization.' },
+  1000048: { title: 'SEO & public discoverability', subtitle: 'Rankable per-project profiles.' },
+  1000049: { title: 'Orb Physics', subtitle: 'Orb motion and space-whale flight.' },
+  1000052: { title: 'First-run onboarding', subtitle: 'From a bare machine to a first ship.' },
+  1000054: { title: 'Public distribution', subtitle: 'CLI installer and Claude plugin.' },
+  1000057: { title: 'Rank blocker matrix', subtitle: 'Empirically verify intended vs unintended blockers across xenos, thetes and metic.' },
+  1000058: { title: 'Non-cloudbongos project lifecycle', subtitle: 'Creation, governance, planning, building — the whole flow works and feels right.' },
+  1000063: { title: 'The front door', subtitle: 'Enter the Future: hero-only landing, wormhole transit, About on the map.' },
+  1000065: { title: 'Community surface', subtitle: 'Builder discovery on the hub.' },
+  1000067: { title: 'Ideator compensation', subtitle: 'The idea credit stream, separate from cost-plus.' },
+  1000068: { title: 'Government, not governance', subtitle: 'Ranks are ranks, and "role" belongs to the crafts.' },
+  1000070: { title: 'Scan-before-install', subtitle: 'First-real-run hardening.' },
+  1000071: { title: 'Idea routing', subtitle: 'Work that has a home lands in it.' },
+  1000072: { title: 'Human legibility', subtitle: 'Seeing, sorting and steering an AI-run project.' },
+  1000073: { title: 'Finish the GDS→Bongos rename', subtitle: 'Retire a legacy Primea term without rewriting history.' },
+  1000074: { title: "The artist's loop", subtitle: 'Review authority, copy an artist can change, and a place to do it.' },
+  // 1000080 already carried a subtitle, so the tail is PREPENDED to it rather than
+  // replacing it — overwriting would delete text, the exact loss this task guards.
+  1000080: { title: 'Apex UI pass 2', subtitle: 'One top bar, two dropdowns, and a project card worth opening — the chrome and the card on cloudbongos.com and /projects.' },
+});
+
+// A name must not carry its own explanation — that is the whole point.
+const SEPARATOR = / [—-] |: /;
+
+// Goals deliberately untouched: their titles are already names. Listed so the
+// coverage test can tell "already fine" from "forgotten".
+const ALREADY_NAMES = Object.freeze([1000009, 1000024, 1000028, 1000037, 1000047, 1000050]);
+
+module.exports = { GOAL_NAMES, ALREADY_NAMES, SEPARATOR };

package/scripts/bongos/goal.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+// Goal board CLI — list goals, or show one goal's criteria + tasks + what to claim next.
+//
+// Usage:
+//   node scripts/bongos/goal.js list [--version V] [--status open|achieved|archived|all]
+//   node scripts/bongos/goal.js show <id>
+//   node scripts/bongos/goal.js move <id> --to <version> [--admit-reason "..."]
+//
+// list/show are read-only; default list filter is --status open. `move` re-homes an
+// open goal — its criteria and every task in it — on another version (Archon;
+// POST /goals/:id/move, task 1004485).
+
+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/bongos/goal.js list [--version V] [--status open|achieved|archived|all]');
+  console.error('       node scripts/bongos/goal.js show <id>');
+  console.error('       node scripts/bongos/goal.js move <id> --to <version> [--admit-reason "..."]');
+  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/bongos/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/bongos/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.');
+  }
+}
+
+// parseMoveArgs — the argv after `move`: `<id> --to <version> [--admit-reason "..."]`.
+// Returns { id, body } or null (usage error). Pure, so the CLI's own validation
+// is tested rather than trusted (task 1004485).
+function parseMoveArgs(args) {
+  const id = args[0];
+  if (!/^\d+$/.test(id || '')) return null;
+  const rest = args.slice(1);
+  const to = arg('--to', rest);
+  if (!to || !/^[\w.-]+$/.test(to)) return null;
+  const body = { version_id: to };
+  const reason = arg('--admit-reason', rest);
+  if (reason) body.admit_reason = reason;
+  return { id: Number(id), body };
+}
+
+async function move(api, args) {
+  const parsed = parseMoveArgs(args);
+  if (!parsed) usageExit();
+  const { id, body } = parsed;
+  const r = await api.goals.postGoalsIdMove({ id, body });
+  if (!r.ok) {
+    console.error(`move refused (${r.status}):`, (r.data && (r.data.message || r.data.error)) || JSON.stringify(r.data));
+    if (r.data && r.data.details && r.data.details.links) console.error('  crossing links:', JSON.stringify(r.data.details.links));
+    process.exitCode = 1;
+    return;
+  }
+  const d = r.data;
+  console.log(`Goal #${d.goal.id} "${d.goal.title}" moved ${d.from_version_id} → ${d.to_version_id}${d.admitted ? ' (admitted into a building version)' : ''}.`);
+  console.log(`  tasks moved: ${d.moved_task_ids.length}${d.moved_task_ids.length ? ' (' + d.moved_task_ids.join(', ') + ')' : ''}`);
+  console.log(`  criteria moved: ${d.moved_criterion_ids.length}`);
+}
+
+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 if (cmd === 'move') {
+    await move(api, args.slice(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, parseMoveArgs };