@bongos/core 1.21.175 → 1.21.176

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

@@ -1,142 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/claude-md-template.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/claude-md-template.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-// scripts/gds/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 };
+require('../bongos/forwarder.js').forward(module, 'claude-md-template.js');

package/scripts/gds/cleanup-orphans.js

@@ -1,74 +1,7 @@
 #!/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/gds/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/gds/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);
-});
+// scripts/gds/cleanup-orphans.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/cleanup-orphans.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'cleanup-orphans.js');