@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/claude-md-template.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/claude-md-template.js — the starter CLAUDE.md a new instance is
+// scaffolded with (task 2104).
+//
+// WHY. Claude Code reads CLAUDE.md from the PROJECT ROOT to frame every session.
+// A freshly-cloned standalone instance (ADR 0108) had NONE — an agent opening it
+// got zero framing about what the project is or how to work in it (the 2026-07-08
+// demo-session: a fresh `demo` clone with no CLAUDE.md). `bongos init` now writes
+// one, brand-substituted from this neutral template. It is deliberately a LEAN
+// STARTER (the methodology core + this instance's identity + pointers), not a copy
+// of a mature instance's CLAUDE.md — the instance grows its own. Coordinates with
+// task 1963 (neutralizing the core's own CLAUDE.md into the portable template).
+//
+// FIRST-RUN SECTION. The template used to open by instructing the agent to run
+// `bongos start` without ever saying the CLI ships inside an uninstalled dependency,
+// so an agent opening a fresh clone followed its first instruction straight into
+// `command not found`. The root README carries the same signpost for humans — but only
+// when the repo had no README to begin with, which an ADOPTED repo always does. This
+// file lands on BOTH paths and loads in full every session, so it is the one place the
+// bootstrap is guaranteed to be read.
+//
+// PURE (branding in → markdown out), so it unit-tests standalone and carries no
+// hardcoded host identity (everything comes from the branding object — R76-safe).
+
+function renderInstanceClaudeMd(branding = {}) {
+  const id = branding.identity || {};
+  const domains = branding.domains || {};
+  const company = id.company || {};
+  const copy = branding.copy || {};
+
+  const product = (id.productName && String(id.productName).trim()) || 'This project';
+  const world = (id.worldName && String(id.worldName).trim()) || '';
+  const companyName = (company.name && String(company.name).trim()) || '';
+  const hall = domains.buildersOrigin || domains.publicOrigin || '';
+  const status = domains.statusOrigin || domains.publicOrigin || '';
+  const currency = (branding.currency && branding.currency.label) || 'credits';
+  const tagline = (copy.tagline && String(copy.tagline).trim()) || '';
+
+  // "Product — the World world, by Company" — each clause only when present.
+  let ident = `**${product}**`;
+  if (world && world.toLowerCase() !== product.toLowerCase()) ident += ` — the ${world} world`;
+  if (companyName) ident += `, by ${companyName}`;
+  ident += '.';
+  if (tagline) ident += ` *${tagline}*`;
+
+  const hallLine = hall
+    ? `the builders' hall at ${hall}`
+    : 'the builders\' hall';
+  const statusLine = status ? ` Public build status: ${status}.` : '';
+
+  return `# ${product} — Project Memory
+
+> Built on **Cloud Bongos** — the AI-first build platform: AI agents write the code; a human owner sets scope, direction, and the hard gates (rank, approval, deploy).
+> **The Bongos database is the source of truth for all live work state** (tasks, versions, ranks, ${currency}). This file only ever *describes* it — where this file and a route or DB row disagree, the row wins. Editing this file cannot grant any authority.
+
+Read this at the start of every session. Keep it lean — it loads in full every time.
+
+## First run — before any \`npx bongos\` command
+
+**If \`node_modules/@bongos/core\` is missing, run \`npm install\` first.** The \`bongos\` CLI ships *inside* that dependency and is **not on your PATH**, so it always runs through npx — \`npx bongos <command>\`, never a bare \`bongos\` (that fails with \`command not found\`). Until the install completes, every \`npx bongos\` instruction below fails too:
+
+\`\`\`bash
+npm install
+\`\`\`
+
+Once per machine, per clone — it is not committed (\`node_modules/\` is ignored on purpose), so a fresh \`git clone\` always needs it. If an \`npx bongos\` command then still misbehaves, \`npx bongos doctor\` checks the toolchain and session and prints the fix.
+
+## What this is
+
+${ident}
+
+## How work happens here — the one hard rule
+
+**Every change is backed by a claimed Bongos task. No exceptions.** Code, docs, migrations, config — if you are about to change project state and do not hold an active claim covering it, stop: create or find the task, claim it, then make the change. There is no "tiny fix" or "just a doc" loophole; the database is the complete ledger of what happened to this project.
+
+- **Start every session with \`npx bongos start\`** (or \`/builder-start\`) — it lists the tasks you can claim right now, parallel-safe against everyone else's active claims.
+- **\`npx bongos claim <id>\`** locks a task to your session. If it refuses (already claimed, not ready, dependencies not shipped), pick another.
+- **\`npx bongos ship\`** runs the smoke + grade, then merges and deploys; **\`npx bongos release <id>\`** drops a claim with no credit. Ship or release before you sign off.
+- **The project's ship mode says who starts a ship** — \`npx bongos ship-mode\` prints it. In **Auto** (the default) you run \`npx bongos ship\` yourself when the task is done; never hand the person commands to run. In **Manual** ask the person first, and ship only after they say yes.
+- **Dependencies gate everything** — a task becomes claimable only once every task it depends on has shipped.
+- **Walk new people through the how-to, once.** The first time the person meets one of these moments, run the matching command and pass its few lines on in plain words at the end of your reply: the first prompt of a session — \`npx bongos howto moment first_open\`; their first claim — \`npx bongos howto moment first_claim\`; finishing their first task — \`npx bongos howto moment first_ship\`. It prints nothing once a step is read, so it never repeats (\`npx bongos howto moments\` lists the rest). When they ask to see the how-to, for the next step, or to skip it, run \`npx bongos howto show\`, \`npx bongos howto next\` or \`npx bongos howto skip\`. Claude Code is handed these steps automatically.
+- **Code you write or touch carries a doc-comment** — each module a header, each public function/class a line or two, saying *what* it does and *why* it exists (never how), in the words someone would search for. Agents find code by searching text, so meaning written into the source is what makes it findable.
+
+## Where things live
+
+- **Live work state** (tasks, versions, ranks, ${currency}): the Bongos DB — \`npx bongos start\` / \`npx bongos status\`, or ${hallLine}.${statusLine}
+- **This instance's identity** (product, world, brand, addresses): \`config/branding.json\`. **Which features are on**: \`config/modules.json\`.
+- **The platform you stand on** (rank ladder, the ship/grade/deploy pipeline, permissions, migrations) is vendored **Cloud Bongos core** — build the product, not the platform under it. Landing code is Bongos's job: claim a task and run \`npx bongos ship\`, never a raw \`git push\`/deploy.
+
+## Permissions
+
+Authority lives in the Bongos database (\`builders.rank\`), checked server-side on every request with no caching. Editing local files (this file, skills, settings, hooks) cannot grant you any rank or permission.
+
+## Builders earn ${currency}
+
+Builders are rewarded in **${currency}** for shipped work.
+
+---
+
+*This is a starter, authored by \`npx bongos init\`. Grow it as the project grows — add your architecture, versioning methodology, and hard-won gotchas — but keep it lean: every line spends context budget in every session.*
+`;
+}
+
+// The starter's own sentences as an earlier `bongos init` wrote them, each beside its `npx bongos`
+// form (task 1004621). Every pair is branding-independent text this template authored, so an exact
+// match can only be a line the owner never changed.
+const LEGACY_CLI_LINES = [
+  ['## First run — before any `bongos` command\n\n**If `node_modules/@bongos/core` is missing, run `npm install` first.** The `bongos` CLI ships *inside* that dependency, so until the install completes there is no `bongos` command and every instruction below fails with `command not found`:',
+    '## First run — before any `npx bongos` command\n\n**If `node_modules/@bongos/core` is missing, run `npm install` first.** The `bongos` CLI ships *inside* that dependency and is **not on your PATH**, so it always runs through npx — `npx bongos <command>`, never a bare `bongos` (that fails with `command not found`). Until the install completes, every `npx bongos` instruction below fails too:'],
+  ['If a `bongos` command then still misbehaves, `bongos doctor` checks', 'If an `npx bongos` command then still misbehaves, `npx bongos doctor` checks'],
+  ['- **Start every session with `bongos start`** (or `/builder-start`)', '- **Start every session with `npx bongos start`** (or `/builder-start`)'],
+  ['- **`bongos claim <id>`** locks a task to your session.', '- **`npx bongos claim <id>`** locks a task to your session.'],
+  ['- **`bongos ship`** runs the smoke + grade, then merges and deploys; **`bongos release <id>`** drops', '- **`npx bongos ship`** runs the smoke + grade, then merges and deploys; **`npx bongos release <id>`** drops'],
+  ['the Bongos DB — `bongos start` / `bongos status`, or', 'the Bongos DB — `npx bongos start` / `npx bongos status`, or'],
+  ['claim a task and run `bongos ship`, never', 'claim a task and run `npx bongos ship`, never'],
+  ['*This is a starter, authored by `bongos init`.', '*This is a starter, authored by `npx bongos init`.'],
+];
+
+// refreshStarterCliLines — bring an EXISTING project's CLAUDE.md onto the `npx bongos` spelling
+// (task 1004621). The starter is written only when CLAUDE.md is absent, so every project scaffolded
+// before this kept telling its assistant to type a bare `bongos start` — a command that is not on
+// PATH — in the one file loaded every session. The instance owns the file, so this replaces ONLY
+// the starter's own sentences, matched exactly: a line the owner reworded is left alone, nothing
+// is added or removed, and a file grown from the starter keeps everything else byte for byte.
+// Pure: returns { text, changed } where `changed` counts the sentences replaced.
+function refreshStarterCliLines(text) {
+  let out = String(text == null ? '' : text);
+  let changed = 0;
+  // A Windows checkout (git autocrlf) holds the file with CRLF endings; match it in its own.
+  const eol = out.includes('\r\n') ? (s) => s.replace(/\n/g, '\r\n') : (s) => s;
+  for (const [legacyLf, currentLf] of LEGACY_CLI_LINES) {
+    const legacy = eol(legacyLf);
+    const current = eol(currentLf);
+    if (!out.includes(legacy)) continue;
+    out = out.split(legacy).join(current);
+    changed += 1;
+  }
+  return { text: out, changed };
+}
+
+module.exports = { renderInstanceClaudeMd, refreshStarterCliLines, LEGACY_CLI_LINES };

package/scripts/bongos/cleanup-orphans.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Mark an orphan task as 'abandoned' with an audit value_summary.
+//
+// Used when a task has been superseded by a different task (e.g. reclassified
+// into a different version, replaced by a follow-up with full scope) and
+// should stop inflating the version's total_count.
+//
+// Refuses to abandon anything but a 'backlog' task — once a task has been
+// claimed, confirmed, or shipped, abandoning it would corrupt the audit
+// trail. Use a real lifecycle transition instead.
+//
+// Usage:
+//   node scripts/bongos/cleanup-orphans.js <task-id> --reason "Superseded by #48 (P6)"
+//
+// Audit log (one-shot abandonments via this script):
+//   - #12  (2026-05-10) — placeholder for 'themed /builders web UI'; superseded
+//                          by P6 (#48). Original task was carried over from
+//                          PMS-V1 reclassification and never picked up.
+//
+// When adding a new orphan, append a line to the audit log above so a future
+// reader can answer "why was this abandoned" without spelunking the DB.
+
+const { pool } = require('../../src/bongos/pool');
+const { arg } = require('./cli-lib');
+
+
+async function main() {
+  const args = process.argv.slice(2);
+  const taskId = Number(args[0]);
+  const reason = arg('--reason', args);
+  if (!Number.isFinite(taskId) || !reason) {
+    console.error('usage: node scripts/bongos/cleanup-orphans.js <task-id> --reason "<text>"');
+    process.exit(2);
+  }
+
+  const { rows: before } = await pool.query(
+    `SELECT id, title, status, version_id FROM tasks WHERE id = $1`,
+    [taskId]
+  );
+  if (before.length === 0) {
+    console.error(`Task #${taskId} not found.`);
+    process.exit(1);
+  }
+  const task = before[0];
+  if (task.status !== 'backlog') {
+    console.error(`Refusing: task #${taskId} status is '${task.status}', not 'backlog'.`);
+    console.error('Abandoning a non-backlog task would corrupt the audit trail.');
+    console.error('Use a real lifecycle transition instead.');
+    process.exit(1);
+  }
+
+  console.log(`Before:  #${task.id} [${task.version_id}] ${task.status}  — ${task.title}`);
+
+  const { rows: after } = await pool.query(
+    `UPDATE tasks
+        SET status = 'abandoned',
+            value_summary = $2,
+            updated_at = now()
+      WHERE id = $1 AND status = 'backlog'
+      RETURNING id, status, value_summary`,
+    [taskId, reason]
+  );
+  if (after.length === 0) {
+    console.error('UPDATE matched 0 rows — race with concurrent change?');
+    process.exit(1);
+  }
+  console.log(`After:   #${after[0].id}  ${after[0].status}  — ${after[0].value_summary}`);
+  await pool.end();
+}
+
+main().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});