@bongos/core 1.17.0

package/scripts/gds/classify-discipline.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// classify-discipline — bulk-classify tasks.discipline via the heuristic
+// classifier in src/bongos/task-classifier.js.
+//
+// Usage:
+//   node scripts/gds/classify-discipline.js [--commit] [--all] [--limit N]
+//
+// Default mode: dry-run. Walks every task whose discipline is currently
+// 'unclassified', runs classifyTaskDiscipline() over title + description +
+// touches, and prints a table of proposed classifications. Nothing is
+// written to the DB.
+//
+// With --commit: same walk, but PATCH /tasks/:id for every proposal that
+// came back as engineer, artist, or ideator. Tasks the classifier leaves as
+// 'unclassified' are skipped (left for hand-triage).
+//
+// With --all: include tasks that already have a non-unclassified
+// discipline. Useful for re-running after tweaking the classifier rules;
+// will overwrite existing classifications. NOT the default.
+//
+// Idempotent without --all: re-running after a successful --commit is a
+// no-op because every previously-classified row falls outside the filter.
+
+const { cliClient, requireSession } = require('./cli-lib');
+// task-classifier carved to modules/lifecycle/ (BV1.R86); a CLI may require a
+// module directly (outside the kernel boundary — the grading/economy precedent).
+const { classifyTaskDiscipline } = require('../../modules/lifecycle/task-classifier');
+
+function pad(s, n) {
+  s = String(s);
+  return s.length >= n ? s.slice(0, n) : s + ' '.repeat(n - s.length);
+}
+
+function emoji(d) {
+  if (d === 'artist') return '🎨';
+  if (d === 'ideator') return '💡';
+  if (d === 'engineer') return '🔧';
+  return '· ';
+}
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const commit = args.includes('--commit');
+  const all = args.includes('--all');
+  const limitIdx = args.indexOf('--limit');
+  const limit = limitIdx >= 0 ? Number(args[limitIdx + 1]) : Infinity;
+
+  // Fetch tasks. Without --all we ask the API for only unclassified rows
+  // so we don't have to pull every shipped task to triage them later.
+  const api = await cliClient();
+  const r = await api.tasks.getTasks(all ? {} : { query: { discipline: 'unclassified' } });
+  if (!r.ok) {
+    console.error(`failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+  const rawTasks = (r.data?.tasks || []).slice(0, limit);
+  // Skip __smoke__ test debris — these aren't real work, classifying them
+  // would just pollute the discipline filter. Mig 005 already filters them
+  // from claimable_tasks / version_progress on the public side.
+  const smokeFiltered = rawTasks.filter((t) => /^__smoke__/.test(t.title || ''));
+  const tasks = rawTasks.filter((t) => !/^__smoke__/.test(t.title || ''));
+  if (tasks.length === 0) {
+    console.log('nothing to classify — every task already has a discipline.');
+    if (smokeFiltered.length) {
+      console.log(`(skipped ${smokeFiltered.length} __smoke__ debris rows)`);
+    }
+    return;
+  }
+
+  // Run classifier locally — no API round-trip per task.
+  const proposals = tasks.map((t) => {
+    const result = classifyTaskDiscipline(t.title, t.description, t.touches);
+    return { task: t, ...result };
+  });
+
+  // Print summary table grouped by discipline.
+  const buckets = {
+    engineer: proposals.filter((p) => p.discipline === 'engineer'),
+    artist: proposals.filter((p) => p.discipline === 'artist'),
+    ideator: proposals.filter((p) => p.discipline === 'ideator'),
+    unclassified: proposals.filter((p) => p.discipline === 'unclassified'),
+  };
+
+  console.log('');
+  console.log(`Proposed classifications across ${proposals.length} tasks:`);
+  console.log(`  ${emoji('engineer')} engineer      ${buckets.engineer.length}`);
+  console.log(`  ${emoji('artist')} artist        ${buckets.artist.length}`);
+  console.log(`  ${emoji('ideator')} ideator       ${buckets.ideator.length}`);
+  console.log(`  ${emoji('unclassified')} unclassified  ${buckets.unclassified.length} (will be skipped)`);
+  if (smokeFiltered.length) {
+    console.log(`  🧪 __smoke__     ${smokeFiltered.length} (filtered as test debris, not classified)`);
+  }
+  console.log('');
+
+  // Detail by bucket. Within each bucket: highest-confidence first so
+  // the strong signals are at the top — easy to spot the weakest.
+  for (const bucket of ['engineer', 'artist', 'ideator']) {
+    if (!buckets[bucket].length) continue;
+    console.log(`--- ${bucket} ---`);
+    const sorted = buckets[bucket].slice().sort((a, b) => b.confidence - a.confidence);
+    for (const p of sorted) {
+      const { task: t } = p;
+      const version = pad(`[${t.version_id || '?'}]`, 10);
+      const conf = `(${p.confidence.toFixed(2)})`;
+      const title = (t.title || '').slice(0, 80);
+      console.log(`  #${pad(t.id, 4)} ${conf}  ${version} ${title}`);
+    }
+    console.log('');
+  }
+
+  if (buckets.unclassified.length) {
+    console.log('--- unclassified (signals too weak / balanced) ---');
+    for (const p of buckets.unclassified.slice(0, 20)) {
+      const { task: t } = p;
+      const version = pad(`[${t.version_id || '?'}]`, 10);
+      const title = (t.title || '').slice(0, 80);
+      console.log(`  #${pad(t.id, 4)}         ${version} ${title}`);
+    }
+    if (buckets.unclassified.length > 20) {
+      console.log(`  ... ${buckets.unclassified.length - 20} more`);
+    }
+    console.log('');
+  }
+
+  if (!commit) {
+    console.log('Dry-run only. Re-run with --commit to write classifications via PATCH.');
+    return;
+  }
+
+  // Commit: PATCH each non-unclassified proposal.
+  const toWrite = [...buckets.engineer, ...buckets.artist, ...buckets.ideator];
+  console.log(`Committing ${toWrite.length} classifications...`);
+  let ok = 0;
+  let failed = 0;
+  for (const p of toWrite) {
+    const res = await api.tasks.patchTasksId({
+      id: p.task.id,
+      body: { discipline: p.discipline },
+    });
+    if (res.ok) {
+      ok++;
+    } else {
+      failed++;
+      console.error(`  PATCH #${p.task.id} failed (${res.status}):`, res.data?.error || res.data);
+    }
+  }
+  console.log('');
+  console.log(`Done. ${ok} updated, ${failed} failed.`);
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/claude-materialize.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+'use strict';
+// claude-materialize.js — materialize the .claude/ methodology surface into an instance
+// (ADR 0108 §3, configurable-root W3 / task 1883).
+//
+// WHY. Claude Code discovers .claude/settings.json + hooks/ + skills/ from the PROJECT ROOT, never
+// from a dependency. Once the Cloud Bongos core installs as a pinned npm package (ADR 0108), the
+// ~35 skills sit in node_modules/@cloudbongos/core/.claude/skills/ where Claude Code will not look —
+// so `bongos init`/`upgrade` must COPY .claude/ into the instance repo. And a copied skill can't run
+// `node scripts/gds/<x>.js`: scripts/ lives in the package, not at the instance root. So every
+// invocation is rewritten to the `bongos` bin, which resolves the heavy CLI inside the package —
+// a dedicated verb where one exists (`bongos ship`), else the generic `bongos exec scripts/gds/<x>.js`.
+//
+// BOUNDARY (publish-manifest). skills/ ships IN the core package (isPublishable) → materialized by
+// copy+transform. hooks/ + settings.json are TOPOLOGY (PROTECTED_TOPOLOGY_EXCLUDE) → NOT in the
+// package; this module copies+transforms them when they ARE present at the core root (today's single
+// checkout, and the core repo itself), and no-ops with a note when they aren't (an installed package).
+// Rewriting hook *.js internals + shipping a topology STARTER for a package-only install is a
+// follow-up (idea captured by task 1883) — this lands the skills materialization + the transform.
+//
+// SELF-COPY GUARD. When the instance dir IS the core root (running init inside the core checkout /
+// OTB today), there is nothing to materialize — a self-copy would be a no-op at best and corrupting
+// at worst. This module detects that and skips, so it is byte-identical for the live instance.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { VERBS } = require('../../bin/bongos.js'); // side-effect-free require (guarded main)
+
+// script basename (e.g. "ship.js") → dedicated bongos verb, for verbs that map to a bare script with
+// NO prefixArgs. Verbs whose script is driven by prefixArgs (box → api.js) are EXCLUDED so a generic
+// `node scripts/gds/api.js …` never mis-maps to `bongos box`; those fall to `bongos exec`. `exec`
+// itself has no script and is skipped.
+function scriptToVerb(verbs = VERBS) {
+  const m = {};
+  for (const [verb, def] of Object.entries(verbs)) {
+    if (!def || def.prefixArgs || !def.script) continue;
+    if (!(def.script in m)) m[def.script] = verb;
+  }
+  return m;
+}
+
+// Match `node [<quote>][$CLAUDE_PROJECT_DIR/|./]scripts/gds/<name>.js[<quote>]` — the invocation form
+// skills + settings.json hooks use. The optional $CLAUDE_PROJECT_DIR/ or ./ prefix and surrounding
+// quote are consumed so the whole thing collapses to the bongos form. `.claude/hooks/<x>.js` refs are
+// deliberately NOT matched (this targets scripts/gds/) — those stay instance-local after materialize.
+const GDS_INVOCATION_RE = /node\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/gds\/([a-zA-Z0-9_-]+)\.js"?/g;
+// A non-gds core script under scripts/ (rare in skills, but keep the transform total).
+const OTHER_SCRIPT_RE = /node\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!gds\/)[a-zA-Z0-9_./-]+\.js)"?/g;
+
+// Pure: rewrite core-script invocations in a skill/settings command string to the bongos bin.
+// Idempotent (a string with no matching invocation is returned unchanged).
+function bongosify(text, verbs = VERBS) {
+  const map = scriptToVerb(verbs);
+  return String(text == null ? '' : text)
+    .replace(GDS_INVOCATION_RE, (_whole, script) => {
+      const verb = map[`${script}.js`];
+      return verb ? `bongos ${verb}` : `bongos exec scripts/gds/${script}.js`;
+    })
+    .replace(OTHER_SCRIPT_RE, (_whole, rel) => `bongos exec scripts/${rel}`);
+}
+
+// ---- I/O: copy a tree, transforming text files through bongosify ----------
+
+const TEXT_EXT = new Set(['.md', '.txt', '.sh']); // command-bearing text we rewrite (skills are SKILL.md)
+
+// `overwrite` defaults true (greenfield init / upgrade — byte-identical to before).
+// `overwrite: false` is the `bongos init --adopt` layering path (ADR 0121): a file
+// that already exists at the destination is NEVER clobbered — it is skipped and
+// recorded in the returned `skipped[]` so the caller can report it.
+function copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true } = {}) {
+  let files = 0;
+  const skipped = [];
+  const walk = (rel) => {
+    const absSrc = path.join(srcDir, rel);
+    const st = fs.statSync(absSrc);
+    if (st.isDirectory()) {
+      for (const name of fs.readdirSync(absSrc)) walk(path.join(rel, name));
+      return;
+    }
+    const absDest = path.join(destDir, rel);
+    if (!overwrite && fs.existsSync(absDest)) { // adopt: leave-and-report, never clobber
+      skipped.push(rel);
+      if (onFile) onFile(rel, { skipped: true });
+      return;
+    }
+    files += 1;
+    if (dryRun) { if (onFile) onFile(rel); return; }
+    fs.mkdirSync(path.dirname(absDest), { recursive: true });
+    if (TEXT_EXT.has(path.extname(rel))) {
+      fs.writeFileSync(absDest, bongosify(fs.readFileSync(absSrc, 'utf8')));
+    } else {
+      fs.copyFileSync(absSrc, absDest); // .js / binary / json (settings handled separately) — verbatim
+    }
+    if (onFile) onFile(rel);
+  };
+  if (!fs.existsSync(srcDir)) return { files: 0, skipped, present: false };
+  for (const name of fs.readdirSync(srcDir)) walk(name);
+  return { files, skipped, present: true };
+}
+
+// Transform settings.json: parse, rewrite every hook command through bongosify, re-serialize. Keeps
+// .claude/hooks/*.js commands (instance-local) untouched and rewrites the scripts/gds/*.js ones.
+function transformSettings(srcPath) {
+  const raw = fs.readFileSync(srcPath, 'utf8');
+  let json;
+  try { json = JSON.parse(raw); } catch { return bongosify(raw); } // malformed → best-effort text rewrite
+  const hooks = json && json.hooks;
+  if (hooks && typeof hooks === 'object') {
+    for (const event of Object.values(hooks)) {
+      for (const matcher of Array.isArray(event) ? event : []) {
+        for (const h of (matcher && Array.isArray(matcher.hooks)) ? matcher.hooks : []) {
+          if (typeof h.command === 'string') h.command = bongosify(h.command);
+        }
+      }
+    }
+  }
+  return JSON.stringify(json, null, 2) + '\n';
+}
+
+// Materialize the .claude/ surface from `coreRoot` into `instanceDir`. Returns a summary.
+// `overwrite` defaults true (greenfield init / upgrade — unchanged). `overwrite: false`
+// is the `bongos init --adopt` layering path (ADR 0121): every pre-existing .claude/
+// file is LEFT untouched and recorded in `summary.skippedFiles` (never clobbered).
+function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = () => {} }) {
+  const summary = { skipped: false, skills: 0, settings: false, hooks: 0, skippedFiles: [], notes: [] };
+  if (path.resolve(instanceDir) === path.resolve(coreRoot)) {
+    summary.skipped = true;
+    summary.notes.push('instance dir is the core root — nothing to materialize (byte-identical no-op).');
+    log('  • .claude/ materialize: instance dir == core root — skipped (nothing to copy).');
+    return summary;
+  }
+  const srcClaude = path.join(coreRoot, '.claude');
+  const destClaude = path.join(instanceDir, '.claude');
+  const left = (n) => (overwrite || n === 0 ? '' : ` (${n} left untouched)`);
+
+  // 1. skills — ship in the core package; copy + rewrite invocations.
+  const skillsSrc = path.join(srcClaude, 'skills');
+  const skillsRes = copyTreeTransformed(skillsSrc, path.join(destClaude, 'skills'), { dryRun, overwrite });
+  summary.skills = skillsRes.files;
+  for (const rel of skillsRes.skipped || []) summary.skippedFiles.push(`skills/${rel}`);
+  if (!skillsRes.present) summary.notes.push('.claude/skills not found at the core root — none materialized.');
+  log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${skillsRes.files} skill file(s) → .claude/skills/ (invocations rewritten to bongos)${left((skillsRes.skipped || []).length)}`);
+
+  // 2. settings.json — topology; present in the checkout/core repo, absent in a package-only install.
+  const settingsSrc = path.join(srcClaude, 'settings.json');
+  if (fs.existsSync(settingsSrc)) {
+    const settingsDest = path.join(destClaude, 'settings.json');
+    if (!overwrite && fs.existsSync(settingsDest)) { // adopt: never clobber an owner's settings.json
+      summary.skippedFiles.push('settings.json');
+      log('  • .claude/settings.json already present — left untouched (adopt merges nothing here yet).');
+    } else {
+      if (!dryRun) {
+        fs.mkdirSync(destClaude, { recursive: true });
+        fs.writeFileSync(settingsDest, transformSettings(settingsSrc));
+      }
+      summary.settings = true;
+      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (hook commands rewritten to bongos)`);
+    }
+  } else {
+    summary.notes.push('.claude/settings.json not present at the core root (topology, excluded from the package) — provide it from a starter.');
+  }
+
+  // 3. hooks — topology; copied verbatim when present (JS-internal script requires are a follow-up).
+  const hooksRes = copyTreeTransformed(path.join(srcClaude, 'hooks'), path.join(destClaude, 'hooks'), { dryRun, overwrite });
+  summary.hooks = hooksRes.files;
+  for (const rel of hooksRes.skipped || []) summary.skippedFiles.push(`hooks/${rel}`);
+  if (!hooksRes.present) {
+    summary.notes.push('.claude/hooks not present at the core root (topology, excluded from the package) — provide them from a starter.');
+  } else {
+    log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${hooksRes.files} hook file(s) → .claude/hooks/${left((hooksRes.skipped || []).length)}`);
+    summary.notes.push('hooks copied verbatim; their internal `require(scripts/gds/…)` paths are NOT yet rewritten to resolve inside the package (W3 follow-up).');
+  }
+  return summary;
+}
+
+module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, GDS_INVOCATION_RE };

package/scripts/gds/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/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);
+});