@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/search-ingest-md.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+// scripts/bongos/search-ingest-md.js — repo-markdown ingester for the GDS recall
+// layer (task 947, V4.R09 / ADR 0060 §4). Walks the repo's markdown, chunks each
+// file (src/bongos/search-chunker.js), and upserts into search_chunks — DELTA-DRIVEN
+// by content_hash so an unchanged chunk is never rewritten. Vanished sources are
+// deleted, so the index tracks the tree.
+//
+// DEPLOY HOOK: a step in the prod deploy (scripts/deploy/deploy-prod.sh, mirrored
+// in the droplet's ~/deploy.sh) runs this AFTER the code update + migrate, where
+// the new markdown + the DB are both on disk. Best-effort there: an ingest hiccup
+// must never fail a deploy (the next deploy / a manual run catches up).
+//
+// SCOPING (ADR 0060 §6): a doc that documents a permission-core surface is tagged
+// min_rank='metic' so a sub-Metic search can never surface it (the search route's
+// SQL filter, #949/#950, enforces it). Everything else is 'xenos' (shared). Docs
+// are never owner-scoped (owner_builder_id stays NULL) — that's for DB-prose
+// memory (#948).
+//
+// Usage:
+//   node scripts/bongos/search-ingest-md.js            # ingest (writes)
+//   node scripts/bongos/search-ingest-md.js --dry-run  # report what WOULD change, no writes
+//   node scripts/bongos/search-ingest-md.js --root DIR # override the repo root (tests)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { chunkMarkdown } = require('../../modules/memory/search-chunker'); // carved in BV1.R72 (ADR 0091 §2)
+const { matchProtected } = require('../../src/bongos/permission-path-check');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+// Directories we never index: deps, git internals, parallel worktrees, and the
+// web front-ends (assets, not project knowledge). Both web surfaces now live under
+// modules/<key>/public/ — the status surface at modules/status-ui/public/ (BV1.R84)
+// and the hall at modules/hall-ui/public/ (BV1.R85) — so both are already covered
+// by the `public` basename below.
+const EXCLUDE_DIRS = new Set(['node_modules', '.git', 'public']);
+// .claude/worktrees holds throwaway parallel checkouts — skip by path fragment.
+const EXCLUDE_PATH_RE = /(^|\/)\.claude\/worktrees\//;
+
+// Permission-core / read-sensitive DOCUMENTATION surfaces → min_rank='metic'
+// (ADR 0060 §6 / ADR 0043 "sub-Metic must not read deeply into … trust-boundary
+// docs"). The PROTECTED_GLOBS in permission-path-check are WRITE-protection over
+// CODE paths; READ-gating in the index is a DIFFERENT axis, so we curate the doc
+// surfaces a sub-Metic search must not surface: the security/audit corpus, the
+// permissions authority doc, and the two trust-boundary ADRs. A trailing '/' is
+// a subtree. (CLAUDE.md is write-protected but READ-PUBLIC — see minRankForDoc.)
+const SENSITIVE_DOC_GLOBS = [
+  'docs/canonical-permissions.md',  // the rank-ladder / authority reference
+  'docs/security/',                 // threat models + red-team reports
+  'docs/audits/',                   // security + architecture audit findings
+  'docs/governance/',               // the gate ENUMERATION + choke-point map
+  'docs/adr/0016-trust-boundary-server-enforced-permissions.md',
+  'docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md',
+];
+
+function relPath(abs) {
+  return path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+}
+
+function minRankForDoc(rel) {
+  // CLAUDE.md is in permission-path-check's PROTECTED_GLOBS, but that's
+  // WRITE-protection (sub-Metic can't EDIT it). For RECALL it's the universal
+  // onboarding index every rank reads at session start — read-public. Carve it
+  // out so a Xenos search still surfaces it (it links to the gated detail docs,
+  // which stay metic via the curated list below).
+  if (rel === 'CLAUDE.md') return 'xenos';
+  // Curated read-sensitive documentation surfaces → metic.
+  for (const g of SENSITIVE_DOC_GLOBS) {
+    if (g.endsWith('/') ? rel.startsWith(g) : rel === g) return 'metic';
+  }
+  // Defensive: any OTHER markdown that physically lives under a protected CODE
+  // surface (e.g. a future README inside src/bongos/) → metic. matchProtected over
+  // an md path only ever matches CLAUDE.md today (carved out above) or such a
+  // nested doc, so this is a forward-looking guard, not a second CLAUDE.md hit.
+  if (matchProtected([rel]).length > 0) return 'metic';
+  return 'xenos';
+}
+
+// Recursively collect *.md files under root, honoring the exclusions.
+function collectMarkdown(dir, root, out = []) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (EXCLUDE_DIRS.has(e.name)) continue;
+      const rel = relPath(abs);
+      if (EXCLUDE_PATH_RE.test(rel + '/')) continue;
+      collectMarkdown(abs, root, out);
+    } else if (e.isFile() && e.name.toLowerCase().endsWith('.md')) {
+      const rel = relPath(abs);
+      if (EXCLUDE_PATH_RE.test(rel)) continue;
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+function sha256(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+// The pg Pool lives in the ROOT src/db.js — src/bongos/db.js USES it but does NOT
+// re-export it (src/bongos/search.js requires '../db' for the same reason). Pulled
+// into an exported helper so a unit test pins the path: the original
+// require('../../src/bongos/db') returned no `pool`, crashing only on the DB path
+// (which the pure tests + --dry-run never exercised). task 1156.
+function requirePool() {
+  const { pool } = require('../../src/bongos/pool');
+  return pool;
+}
+
+// Build the per-file chunk rows (pure — no DB). Exported for the dry-run report
+// + tests.
+function chunkFile(abs) {
+  const rel = relPath(abs);
+  const content = fs.readFileSync(abs, 'utf8');
+  const { title, chunks } = chunkMarkdown({ path: rel, content });
+  const min_rank = minRankForDoc(rel);
+  return chunks.map((c) => ({
+    source_kind: 'doc',
+    source_ref: rel,
+    chunk_index: c.chunk_index,
+    heading_path: c.heading_path,
+    title: title || rel,
+    body: c.body,
+    min_rank,
+    content_hash: sha256(c.body),
+  }));
+}
+
+// Upsert one file's chunks in a transaction: delta-update changed chunks, prune
+// any trailing chunks (file shrank). Returns { inserted, updated, unchanged, pruned }.
+async function ingestFile(client, rows, sourceRef) {
+  const stats = { inserted: 0, updated: 0, unchanged: 0, pruned: 0 };
+  for (const r of rows) {
+    const res = await client.query(
+      `INSERT INTO search_chunks
+         (source_kind, source_ref, chunk_index, heading_path, title, body, min_rank, owner_builder_id, content_hash, updated_at)
+       VALUES ('doc', $1, $2, $3, $4, $5, $6, NULL, $7, now())
+       ON CONFLICT (source_kind, source_ref, chunk_index) DO UPDATE
+         SET heading_path = EXCLUDED.heading_path,
+             title        = EXCLUDED.title,
+             body         = EXCLUDED.body,
+             min_rank     = EXCLUDED.min_rank,
+             content_hash = EXCLUDED.content_hash,
+             updated_at   = now()
+         WHERE search_chunks.content_hash IS DISTINCT FROM EXCLUDED.content_hash
+            OR search_chunks.min_rank    IS DISTINCT FROM EXCLUDED.min_rank
+       RETURNING (xmax = 0) AS inserted`,
+      [sourceRef, r.chunk_index, r.heading_path, r.title, r.body, r.min_rank, r.content_hash]
+    );
+    if (res.rowCount === 0) stats.unchanged += 1;        // WHERE skipped the update (no change)
+    else if (res.rows[0].inserted) stats.inserted += 1;  // fresh row
+    else stats.updated += 1;                             // changed row rewritten
+  }
+  // Prune chunks beyond the new count (file shrank / sections removed).
+  const pruneRes = await client.query(
+    `DELETE FROM search_chunks WHERE source_kind='doc' AND source_ref=$1 AND chunk_index >= $2`,
+    [sourceRef, rows.length]
+  );
+  stats.pruned = pruneRes.rowCount || 0;
+  return stats;
+}
+
+// task 1002859 (panel finding): bound the driver's error text before it reaches a
+// log. A Postgres error message is unbounded upstream text and CAN embed row
+// content (a constraint violation quotes the offending key), and these logs are
+// deploy/cron sinks that get shipped around. One line, capped, is enough to
+// identify the fault; the source_ref beside it is what actually locates it. The
+// DB corpus makes this matter more than it looks — its prose is session-log and
+// memory-derived text the file elsewhere treats as scrub-sensitive.
+const ERR_LOG_MAX = 300;
+function errLine(e) {
+  const raw = e && e.message ? String(e.message) : String(e);
+  const flat = raw.replace(/\s+/g, ' ').trim();
+  return flat.length > ERR_LOG_MAX ? `${flat.slice(0, ERR_LOG_MAX)}… (truncated)` : flat;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes('--dry-run');
+  const rootIdx = args.indexOf('--root');
+  const root = rootIdx >= 0 ? path.resolve(args[rootIdx + 1]) : REPO_ROOT;
+
+  const files = collectMarkdown(root, root).sort();
+  const allRows = [];
+  let metic = 0;
+  for (const abs of files) {
+    const rows = chunkFile(abs);
+    if (rows.some((r) => r.min_rank === 'metic')) metic += 1;
+    allRows.push({ sourceRef: relPath(abs), rows });
+  }
+  const totalChunks = allRows.reduce((n, f) => n + f.rows.length, 0);
+  console.log(`search-ingest-md: ${files.length} markdown file(s), ${totalChunks} chunk(s), ${metic} file(s) tagged min_rank=metic`);
+
+  if (dryRun) {
+    console.log('--dry-run: no writes. Sample of metic-tagged sources:');
+    for (const f of allRows.filter((f) => f.rows[0] && f.rows[0].min_rank === 'metic').slice(0, 10)) {
+      console.log(`  metic  ${f.sourceRef} (${f.rows.length} chunk(s))`);
+    }
+    return;
+  }
+
+  const pool = requirePool();
+  const client = await pool.connect();
+  const totals = { inserted: 0, updated: 0, unchanged: 0, pruned: 0, deleted: 0 };
+  // task 1002859: ONE TRANSACTION PER FILE, not one for the whole run. The old
+  // shape opened a single BEGIN before this loop, so ANY failure on ANY file
+  // rolled back the ENTIRE index update — that is the "rolls back the entire
+  // re-index" in this task's title, and it is what turned a one-character data
+  // problem into a total, permanent recall outage. Per-file scope makes the
+  // blast radius one file: the other ~900 still land, and the failure is
+  // reported by name instead of vanishing.
+  const failures = [];
+  for (const f of allRows) {
+    try {
+      await client.query('BEGIN');
+      const s = await ingestFile(client, f.rows, f.sourceRef);
+      await client.query('COMMIT');
+      totals.inserted += s.inserted; totals.updated += s.updated;
+      totals.unchanged += s.unchanged; totals.pruned += s.pruned;
+    } catch (e) {
+      await client.query('ROLLBACK').catch(() => {});
+      failures.push({ sourceRef: f.sourceRef, message: errLine(e) });
+      console.error(`search-ingest-md: SKIPPED ${f.sourceRef} — ${errLine(e)}`);
+    }
+  }
+  // Delete chunks for doc sources that no longer exist in the tree. Its own
+  // transaction, and deliberately SKIPPED when any file failed: `present` is the
+  // list of sources we intended to write, so pruning against it after a partial
+  // run could delete chunks for a file that only failed transiently.
+  try {
+    if (failures.length === 0) {
+      await client.query('BEGIN');
+      const present = allRows.map((f) => f.sourceRef);
+      const del = await client.query(
+        `DELETE FROM search_chunks WHERE source_kind='doc' AND NOT (source_ref = ANY($1::text[]))`,
+        [present]
+      );
+      totals.deleted = del.rowCount || 0;
+      await client.query('COMMIT');
+    } else {
+      console.error(`search-ingest-md: vanished-source prune SKIPPED — ${failures.length} file(s) failed, so the present-sources list is incomplete`);
+    }
+  } catch (e) {
+    await client.query('ROLLBACK').catch(() => {});
+    failures.push({ sourceRef: '(vanished-source prune)', message: errLine(e) });
+    console.error('search-ingest-md: vanished-source prune FAILED:', errLine(e));
+  }
+  client.release();
+  await pool.end().catch(() => {});
+  console.log(`search-ingest-md: inserted=${totals.inserted} updated=${totals.updated} unchanged=${totals.unchanged} pruned=${totals.pruned} deleted_sources_chunks=${totals.deleted}`);
+  if (failures.length > 0) {
+    // NON-SILENT (task 1003097's sibling half): the deploy step runs this
+    // best-effort, so a non-zero exit is the only signal that reaches a log a
+    // human reads. Name every casualty — "some files were skipped" is what let
+    // this hide.
+    console.error(`search-ingest-md: ${failures.length} file(s) FAILED and were skipped:`);
+    for (const f of failures) console.error(`  ${f.sourceRef}: ${f.message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('search-ingest-md: error', e); process.exit(1); });
+}
+
+module.exports = { chunkFile, minRankForDoc, collectMarkdown, ingestFile, requirePool, SENSITIVE_DOC_GLOBS };

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// seed-adopt-tasks.js
+// Seeds the brownfield adopt-mode task breakdown for BONGOS-V1 goal 35
+// ("Project creation flow"), criterion `adopt-existing-repo`, per ADR 0121
+// (task 1986). Scope-only deliverable: these are the BUILD tasks for
+// `bongos init --adopt`; they are seeded as `backlog` (NOT promoted) so the
+// owner schedules the adopt build deliberately. See ADR 0121 §Consequences.
+//
+// Idempotent: task create on source_ref (`BONGOS-V1-adopt-A0N`), criterion
+// links on (task_id, criterion_id), dependency edges on (task_id,
+// depends_on_task_id). Safe to re-run. Run: node scripts/bongos/seed-adopt-tasks.js
+const { apiCall } = require('./cli-lib.js');
+
+const GOAL_ID = 35;
+const CRIT = 'adopt-existing-repo';
+const RUNBOOK_TASK = 1981; // goal-35 canonical runbook; A05 depends on it (external edge)
+
+// ref → task spec. `deps` are local A0N refs; `extDeps` are literal task ids.
+const TASKS = [
+  { ref: 'A01', kind: 'feature', priority: 4, est: 180, crit: [CRIT], deps: [], extDeps: [],
+    title: 'bongos init --adopt: mode skeleton + additive config layering (no clobber)',
+    description: 'Add an `--adopt` mode to `scripts/bongos/init.js` (ADR 0121 §Decision 1-2). Instead of the greenfield "stand up a NEW instance" path (which refuses where config/branding.json exists and whose --force OVERWRITES), --adopt LAYERS onto the existing tree: add the pinned @bongos/core dependency + the lean config/ overrides + .claude/ ADDITIVELY. For any pre-existing file (package.json, an existing .claude/, a CI workflow) it MERGES or LEAVES-AND-REPORTS — it never overwrites, and it must NOT reuse the --force code path. Writes only the lean branding.json overrides (rest resolves from *.neutral.json). Serves criterion adopt-existing-repo. deps: none (the ADR-0108 configurable-root substrate is shipped).' },
+  { ref: 'A02', kind: 'feature', priority: 4, est: 150, crit: [CRIT], deps: [], extDeps: [],
+    title: 'bongos init --adopt: detect the existing stack + layout',
+    description: 'Before writing anything, --adopt inspects the existing tree — language/runtime, package manager, test + CI setup, directory layout — so the enabled modules, the generated repo-map, and the core<->host fitness boundary (ADR 0062 §1) fit what is already there instead of assuming the reference layout (ADR 0121 §Decision 4). Output: a detected-stack summary consumed by A03 (real-state capture) and A04 (pre-flight). Serves criterion adopt-existing-repo. deps: none.' },
+  { ref: 'A03', kind: 'feature', priority: 3, est: 180, crit: [CRIT], deps: ['A01'], extDeps: [],
+    title: 'bongos init --adopt: reflect REAL state — capture version/goal + import backlog',
+    description: 'Replace the synthetic "V1 — Prove the loop" seed with the repo\'s ACTUAL current version/milestone + open goal (by interview + detection), and IMPORT the existing backlog into GDS tasks — GitHub issues (via the auth the flow already establishes), a TODO/ROADMAP/BACKLOG.md, or an interview fallback — so the ledger starts truthful rather than empty (ADR 0121 §Decision 3). Serves criterion adopt-existing-repo. deps: A01.' },
+  { ref: 'A04', kind: 'feature', priority: 3, est: 150, crit: [CRIT], deps: ['A01', 'A02'], extDeps: [],
+    title: 'bongos init --adopt: conflict pre-flight report (--dry-run default, accept-gated)',
+    description: 'Produce the pre-flight report the owner must ACCEPT before anything is written (ADR 0121 §Decision 5): migration-namespace collisions (ADR 0108 §5), core<->host fitness-boundary violations in existing imports (ADR 0062 §1), incoming files that land on protected paths (ADR 0043), and CI collisions between core\'s expected unit/gate check and the repo\'s own workflows. --dry-run is the default first pass; nothing is written until accepted. Serves criterion adopt-existing-repo. deps: A01, A02.' },
+  { ref: 'A05', kind: 'feature', priority: 3, est: 120, crit: [CRIT], deps: ['A01', 'A03', 'A04'], extDeps: [RUNBOOK_TASK],
+    title: 'bongos init --adopt: wire greenfield-vs-adopt into the runbook + both forms',
+    description: 'Offer the greenfield-vs-adopt choice at the SCAFFOLD leg of goal 35\'s canonical step sequence, across all three forms: the /new-project skill (task 1981), the `bongos onboard` CLI (task 1982), and the hall "start a project" wizard (task 1983). Since --adopt is a branch of the same init, the forms inherit it (ADR 0121 §Decision 1). Serves criterion adopt-existing-repo. deps: A01, A03, A04, and the runbook task 1981.' },
+];
+
+(async () => {
+  const idByRef = {};
+  // Phase 1: create tasks (idempotent on source_ref) + link the criterion.
+  for (const t of TASKS) {
+    const create = await apiCall('POST', '/api/bongos/tasks', {
+      version_id: 'BONGOS-V1',
+      goal_id: GOAL_ID,
+      title: t.title,
+      description: t.description,
+      kind: t.kind,
+      discipline: 'engineer',
+      priority: t.priority,
+      est_minutes: t.est,
+      source: 'planning',
+      source_ref: `BONGOS-V1-adopt-${t.ref}`,
+    });
+    const task = create.data && (create.data.task || create.data);
+    const id = task && task.id;
+    if (!id) { console.log(`  ${t.ref}: CREATE FAILED — ${create.status} ${JSON.stringify(create.data).slice(0, 160)}`); continue; }
+    idByRef[t.ref] = id;
+    const link = await apiCall('POST', `/api/bongos/tasks/${id}/criteria`, { criterion_ids: t.crit });
+    console.log(`  ${t.ref} -> task ${id} (${t.kind}, P${t.priority}, goal ${task.goal_id}) · criterion ${link.status === 200 ? 'ok' : (JSON.stringify(link.data).slice(0, 120))}`);
+  }
+  // Phase 2: dependency edges (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 localDepIds = t.deps.map((d) => idByRef[d]).filter(Boolean);
+    const allDeps = [...localDepIds, ...t.extDeps];
+    for (const depId of allDeps) {
+      const r = await apiCall('POST', `/api/bongos/tasks/${id}/dependencies`, { depends_on_task_id: depId });
+      console.log(`  ${t.ref}(${id}) -> ${depId} ${r.status === 200 || r.status === 201 ? 'ok' : (JSON.stringify(r.data).slice(0, 120))}`);
+    }
+  }
+  // NOTE: intentionally NO promote step — these are backlog until the owner
+  // schedules the adopt build (ADR 0121; task 1986 is scope-only).
+  console.log('refs:', JSON.stringify(idByRef));
+})().catch((e) => console.log('ERR ' + (e && e.message)));

package/scripts/bongos/seed-api-contract-goal-tasks.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// seed-api-contract-goal-tasks.js
+// Seeds BONGOS-V1 goal 36 — "Robust, versioned, easy-to-call public API" — from
+// the 2026-07-04 Archon planning session (task 1987). Five done-when criteria
+// (slugs api-error-envelope · api-versioning · api-client-sdk · api-validation ·
+// api-pagination) were created via POST /versions/BONGOS-V1/done-when before this
+// runs; this seeds the 14 tasks (refs R01-R14) + their criterion links + the
+// dependency edges. Entry point is CONTRACT-FIRST, so only the zero-dep,
+// non-spike Phase-A tasks (R01 envelope contract, R05 versioning policy) plus the
+// independent R13 pagination decision are promoted to `ready`; R07 (the
+// source-of-truth spike) stays backlog by convention and is opened manually when
+// Phase B starts; everything else auto-promotes as its predecessor ships.
+//
+// Idempotent: task create on source_ref, criterion links on (task_id,
+// criterion_id), dependency edges on (task_id, depends_on_task_id). Safe to re-run.
+// Run: node scripts/bongos/seed-api-contract-goal-tasks.js
+const { cliClient } = require('./cli-lib.js');
+
+const GOAL_ID = 36;
+const C = {
+  envelope: 'api-error-envelope',
+  versioning: 'api-versioning',
+  sdk: 'api-client-sdk',
+  validation: 'api-validation',
+  pagination: 'api-pagination',
+};
+
+// ref → task spec. `deps` are local R## refs, resolved to ids after create.
+const TASKS = [
+  // ---- Criterion 1: error envelope (Phase A) ----
+  { ref: 'R01', kind: 'decision', priority: 5, est: 90, crit: [C.envelope],
+    title: 'API error envelope + code taxonomy (contract + ADR)',
+    description: 'Define the single error response envelope `{error:{code,message,details}}` and the taxonomy that collapses today\'s ~339 ad-hoc error strings into a documented registry. Deliverable: an ADR + a shared registry module of canonical codes. No behaviour change — this is the contract R02 implements. Serves C1 (api-error-envelope). deps: none.',
+    deps: [] },
+  { ref: 'R02', kind: 'infra', priority: 5, est: 120, crit: [C.envelope],
+    title: 'Central error-handling middleware + envelope helper',
+    description: 'Add a central Express error-handling middleware + an `ApiError`/`res.fail(code,status,details)` helper (kernel route layer) emitting the R01 envelope; wire the handler last so any thrown/unhandled error returns the envelope. Backward-compatible — existing ad-hoc responses keep working until the R04 sweep. Serves C1. deps: R01.',
+    deps: ['R01'] },
+  { ref: 'R03', kind: 'infra', priority: 4, est: 90, crit: [C.envelope],
+    title: 'Build check: fail on a route emitting a non-envelope error',
+    description: 'Add a fitness/lint check (into fitness.js / the unit gate) that fails the build when a route hand-rolls a flat `res.status(NNN).json({error:\'...\'})` instead of the R02 helper. Holds the line as the sweep progresses. Serves C1. deps: R02.',
+    deps: ['R02'] },
+  { ref: 'R04', kind: 'refactor', priority: 4, est: 240, crit: [C.envelope],
+    title: 'Sweep existing routes onto the error envelope',
+    description: 'Convert the ~219 handlers across core + modules from ad-hoc flat errors to the R02 envelope (the audit found 168 open-coded 500s + 615 flat-error sites). Mechanical but wide — touches every module\'s routes. Serves C1. deps: R02.',
+    deps: ['R02'] },
+  // ---- Criterion 2: versioning (Phase A) ----
+  { ref: 'R05', kind: 'decision', priority: 5, est: 90, crit: [C.versioning],
+    title: 'API versioning + deprecation policy (ADR)',
+    description: 'ADR defining the versioning scheme (a `/v1/` path marker), what counts as a breaking change, the deprecation window, and how the currently-un-updatable consumers (shipped Dev Box binaries, live boxes, status dashboard) are handled. Serves C2 (api-versioning). deps: none.',
+    deps: [] },
+  { ref: 'R06', kind: 'infra', priority: 5, est: 150, crit: [C.versioning],
+    title: 'Serve the API under /v1/ with legacy aliasing',
+    description: 'Mount the current surface under `/v1/` and alias today\'s unversioned paths (`/api/bongos`, `/api/gds`) into it so no consumer breaks on day one. Stamp the version into the OpenAPI spec + `/docs`. Serves C2. deps: R05.',
+    deps: ['R05'] },
+  // ---- Criterion 3: client SDK (Phase B) ----
+  { ref: 'R07', kind: 'spike', priority: 4, est: 120, crit: [C.sdk],
+    title: 'Spike: pick the API contract source-of-truth (schema-first vs code-first)',
+    description: 'Decide whether the OpenAPI spec becomes the SOURCE (schema-first: define request/response schemas -> generate spec + validation + client) or stays GENERATED from code with codegen layered on. This one decision shapes the SDK (C3) and validation (C4). Output: an ADR + a sub-task list refining R08-R12. kind=spike (stays backlog; opened manually when Phase B starts). Serves C3, informs C4. deps: none (do after Phase A).',
+    deps: [] },
+  { ref: 'R08', kind: 'feature', priority: 3, est: 180, crit: [C.sdk],
+    title: 'Generate + publish the typed API client',
+    description: 'Per the R07 decision, generate a typed client from the OpenAPI spec and publish it for install (internal package first). Serves C3. deps: R07.',
+    deps: ['R07'] },
+  { ref: 'R09', kind: 'refactor', priority: 3, est: 240, crit: [C.sdk],
+    title: 'Migrate internal callers onto the client; delete duplicates',
+    description: 'Move the CLI (cli-lib apiCall), the devbox Electron app (its own gds-client), and the web UIs (per-page fetch helpers) onto the generated client; delete the 3 duplicate implementations. Cuts per-call boilerplate from ~15 lines to 1. Touches hall-ui/status-ui/dev-box. Serves C3. deps: R08.',
+    deps: ['R08'] },
+  { ref: 'R10', kind: 'feature', priority: 3, est: 120, crit: [C.sdk],
+    title: 'External-consumer on-ramp + hello-world (proof)',
+    description: 'Document how an outside program authenticates (token acquisition beyond the interactive Device Flow) and makes its first call, with a runnable hello-world using the published client. The PROOF an external self-hoster can actually use the API. Serves C3. deps: R08.',
+    deps: ['R08'] },
+  // ---- Criterion 4: validation (Phase C) ----
+  { ref: 'R11', kind: 'feature', priority: 3, est: 240, crit: [C.validation],
+    title: 'Spec-driven request validation: 100% writes + query params',
+    description: 'Per the R07 decision, drive validation from the spec so every write route AND its query parameters are validated, and unknown/typo\'d fields are rejected with the R02 envelope (today ~55% coverage, extras silently dropped). Serves C4 (api-validation). deps: R07.',
+    deps: ['R07'] },
+  { ref: 'R12', kind: 'infra', priority: 3, est: 90, crit: [C.validation],
+    title: 'Build check: fail on an unvalidated write route',
+    description: 'Add a fitness check that fails the build when a write route (POST/PUT/PATCH/DELETE) has no spec-bound validation. Locks in C4\'s 100% coverage. Serves C4. deps: R11.',
+    deps: ['R11'] },
+  // ---- Criterion 5: pagination (Phase C) ----
+  { ref: 'R13', kind: 'decision', priority: 2, est: 90, crit: [C.pagination],
+    title: 'Pagination contract + shared helper (decision)',
+    description: 'Decide one pagination convention (cursor vs limit/offset) and build the shared helper. Today three styles coexist (limit-only, limit+offset, none) with per-endpoint clamps. Serves C5 (api-pagination). deps: none (independent).',
+    deps: [] },
+  { ref: 'R14', kind: 'refactor', priority: 2, est: 180, crit: [C.pagination],
+    title: 'Adopt the pagination contract across list endpoints; cap unbounded lists',
+    description: 'Apply the R13 helper across all list endpoints and cap the currently-unbounded public lists (leaderboard, blockers, versions). Serves C5. deps: R13.',
+    deps: ['R13'] },
+];
+
+(async () => {
+  const api = await cliClient();
+  const idByRef = {};
+  // Phase 1: create tasks (idempotent on source_ref) + link criteria explicitly
+  // (criterion_ids at create is not honored on this build; /criteria is idempotent).
+  for (const t of TASKS) {
+    const create = await api.tasks.postTasks({ body: {
+      version_id: 'BONGOS-V1',
+      goal_id: GOAL_ID,
+      title: t.title,
+      description: t.description,
+      kind: t.kind,
+      discipline: 'engineer',
+      priority: t.priority,
+      est_minutes: t.est,
+      source: 'planning',
+      source_ref: `BONGOS-V1-api-contract-${t.ref}`,
+    } });
+    const task = create.data && (create.data.task || create.data);
+    const id = task && task.id;
+    if (!id) { console.log(`  ${t.ref}: CREATE FAILED — ${create.status} ${JSON.stringify(create.data).slice(0, 160)}`); continue; }
+    idByRef[t.ref] = id;
+    const link = await api.tasks.postTasksIdCriteria({ id, body: { criterion_ids: t.crit } });
+    console.log(`  ${t.ref} -> task ${id} (${t.kind}, P${t.priority}, goal ${task.goal_id}) · criteria ${link.status === 200 ? 'ok' : (JSON.stringify(link.data).slice(0, 120))}`);
+  }
+  // Phase 2: dependency edges (idempotent on (task_id, depends_on_task_id)).
+  console.log('--- dependencies ---');
+  for (const t of TASKS) {
+    const id = idByRef[t.ref];
+    if (!id || !t.deps.length) continue;
+    for (const dep of t.deps) {
+      const depId = idByRef[dep];
+      if (!depId) { console.log(`  ${t.ref}: dep ${dep} not created — skip`); continue; }
+      const r = await api.tasks.postTasksIdDependencies({ id, body: { depends_on_task_id: depId } });
+      console.log(`  ${t.ref}(${id}) -> ${dep}(${depId}) ${r.status === 200 || r.status === 201 ? 'ok' : (JSON.stringify(r.data).slice(0, 120))}`);
+    }
+  }
+  // Phase 3: promote the zero-dep, non-spike tasks to `ready` (contract-first:
+  // R01 + R05 open Phase A now; R13 is independent). R07 (spike) stays backlog.
+  console.log('--- promote (zero-dep, non-spike) ---');
+  for (const t of TASKS) {
+    if (t.deps.length || t.kind === 'spike') continue;
+    const id = idByRef[t.ref];
+    if (!id) continue;
+    const p = await api.tasks.postTasksIdPromote({ id, body: {} });
+    console.log(`  ${t.ref}(${id}) promote -> ${p.status} ${p.ok ? 'ready' : JSON.stringify(p.data).slice(0, 120)}`);
+  }
+  console.log('refs:', JSON.stringify(idByRef));
+})().catch((e) => console.log('ERR ' + (e && e.message)));