@bongos/core 1.17.0

package/scripts/gds/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/gds/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/gds/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 @cloudbongos/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/gds/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/gds/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/gds/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/gds/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/gds/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)));

package/scripts/gds/seed-bongos-app-tasks.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// Seed the 17 net-new BONGOS-V1 tasks — the Cloud Bongos desktop "Feedback
+// Capture" app (a Zoom-style floating toolbar: record + markup over any target
+// -> one model-agnostic prompt -> Claude Desktop/Code). The Dev Box app is
+// absorbed as a module of this app. Visual element-select is deferred to V2.
+// Design home: the "Bongos App — V1" plan artifact (favicon 🥁).
+//
+// Shape mirrors seed-bongos-tasks.js exactly:
+//   - POST /api/gds/tasks   { version_id:'BONGOS-V1', criterion_ids:['C1'], ... }
+//   - POST /api/gds/tasks/:id/dependencies   { depends_on_task_ids:[...] }
+//   - idempotent on source_ref (skips already-created); deps idempotent server-side.
+// Run migration 120_bongos_v1_planning_seed.sql FIRST so the version + C1..C4 exist.
+// After this runs, promote the zero-dependency tasks (R01/R02/R03) to 'ready'
+// (planning-session Phase 5 step 6) — they never auto-promote.
+//
+// Usage:  node scripts/gds/seed-bongos-app-tasks.js [--dry-run]
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+const DRY = process.argv.includes('--dry-run');
+
+// key = symbolic intra-version ref used in deps[]. Display R## assigned dynamically.
+const TASKS = [
+  {
+    key: 'R01',
+    title: 'Resolve Windows code-signing cert (reuse existing Apple Developer ID for Mac)',
+    description: `Part of Bongos App V1 / C1. The launch gate for a mic+screen app: an unsigned app that asks for Screen Recording + Microphone is treated as hostile (macOS grants may not persist; Windows SmartScreen blocks first launch). The macOS half is settled — reuse the Apple Developer ID already in hand for the Dev Box app. This task resolves the Windows code-signing path (cert acquisition + electron-builder wiring decision) so packaging (R15/R16) is unblocked on both OSes.
+
+**Done when:** the Windows signing approach is decided + the cert/identity is available (or an explicit interim "ship Mac-signed only" decision is recorded), and the Mac path is confirmed to reuse the existing Apple Developer ID.`,
+    kind: 'decision', discipline: 'engineer', priority: 3,
+    est_minutes: 30, manual_degree: 4, credits_reward: 10,
+    touches: ['bongos-app/'], criteria: ['C1'], deps: [],
+  },
+  {
+    key: 'R02',
+    title: 'Spike — transparent always-on-top click-through overlay on Mac + Windows',
+    description: `Part of Bongos App V1 / C2. De-risk the load-bearing UX primitive before building on it: an Electron transparent, frameless, always-on-top BrowserWindow with setIgnoreMouseEvents(true,{forward:true}) that lets the user draw over any other app (the Zoom annotation model). Prove the macOS type:'panel' / setVisibleOnAllWorkspaces({visibleOnFullScreen:true}) approach survives fullscreen apps + Spaces, and Windows multi-monitor / per-monitor DPI coordinate mapping.
+
+**Done when:** a throwaway build draws a click-through overlay over a fullscreen app on macOS and over a second monitor on Windows, with the cursor passing through to the app underneath; findings (gotchas, the chosen window flags) are captured for R04.`,
+    kind: 'spike', discipline: 'engineer', priority: 4,
+    est_minutes: 180, manual_degree: 3, credits_reward: 30,
+    touches: ['bongos-app/'], criteria: ['C2'], deps: [],
+  },
+  {
+    key: 'R03',
+    title: 'Stand up the bongos-app umbrella Electron app; absorb the Dev Box app as a module',
+    description: `Part of Bongos App V1 / C1. Establish bongos-app/ as the umbrella Cloud Bongos desktop app, and bring the existing Dev Box app (devbox-app/, ADR 0045) INTO it as a module rather than a sibling install. Reuse the Dev Box app's Electron shell + app-pairing auth (writes the same ~/.config/otb/gds-session.json), branded /downloads redirect distribution, in-app updater, brand discipline (ADR 0004), and the existing Apple Developer ID. The result is one signed app that offers both the Dev Box switch and (new) the feedback toolbar.
+
+**Done when:** bongos-app/ builds + launches as one Electron app containing the prior Dev Box functionality as a module; auth + branded distribution + updater are reused (not reimplemented); and the migration path for existing Dev Box app users is recorded.`,
+    kind: 'infra', discipline: 'engineer', priority: 5,
+    est_minutes: 360, manual_degree: 3, credits_reward: 60,
+    touches: ['bongos-app/', 'devbox-app/'], criteria: ['C1'], deps: [],
+  },
+  {
+    key: 'R04',
+    title: 'Floating toolbar + global hotkey + click-through overlay',
+    description: `Part of Bongos App V1 / C2. Cross-ref: R02 (spike), R03 (shell). Build the production floating toolbar: a small always-on-top bar summoned/dismissed by a global hotkey, plus the transparent click-through overlay window proven in R02, with macOS panel/fullscreen/Spaces handling and Windows per-monitor-DPI coordinate handling.
+
+**Done when:** the toolbar appears over any app via a global hotkey; the overlay draws over arbitrary windows including fullscreen apps; coordinates are correct across multiple monitors / DPI scales on both OSes.`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 300, manual_degree: 2, credits_reward: 55,
+    touches: ['bongos-app/'], criteria: ['C2'], deps: ['R02', 'R03'],
+  },
+  {
+    key: 'R05',
+    title: 'First-run macOS permission wizard (Screen Recording + Microphone)',
+    description: `Part of Bongos App V1 / C1. Cross-ref: R03. A one-screen guided wizard that detects each TCC grant state (systemPreferences.getMediaAccessStatus), deep-links straight to the exact System Settings pane, and shows a live green check as each is granted. Screen Recording + Microphone are mandatory; Accessibility is requested lazily (only when rung-2 element reads land in V2), never up front. Frame the recurring (~monthly) macOS Screen-Recording re-prompt as normal.
+
+**Done when:** on a fresh macOS install the wizard walks the user to grant Screen Recording + Microphone with live state + deep-links, and capture works immediately after; Windows (lighter: no TCC) is handled gracefully.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 180, manual_degree: 2, credits_reward: 35,
+    touches: ['bongos-app/'], criteria: ['C1'], deps: ['R03'],
+  },
+  {
+    key: 'R06',
+    title: 'Screen/window + microphone capture + target picker',
+    description: `Part of Bongos App V1 / C2. Cross-ref: R04, R05. Use getDisplayMedia/desktopCapturer to capture a chosen window or the full screen, plus the microphone. A target picker lets the user choose WHAT to capture (and excludes the toolbar/overlay itself from the capture).
+
+**Done when:** the user picks a target window or screen, capture streams video + mic, and the toolbar/overlay are excluded from the captured frames; works on macOS + Windows after the R05 grants.`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 240, manual_degree: 2, credits_reward: 50,
+    touches: ['bongos-app/'], criteria: ['C2'], deps: ['R04', 'R05'],
+  },
+  {
+    key: 'R07',
+    title: '~1/sec snapshot grabber + snapshot-on-change + perceptual dedup + cap',
+    description: `Part of Bongos App V1 / C2. Cross-ref: R06. Grab ~1 frame/sec off the capture stream as the token-discipline core: snapshot-on-meaningful-change rather than fixed 1/sec, perceptual-hash dedup of near-identical frames, and a hard frame cap (~60) per session. This is what keeps a session ~90x cheaper than naive full-res 1/sec.
+
+**Done when:** frames are grabbed at ~1/sec, near-duplicate frames are dropped, a session cannot exceed the frame cap, and each kept frame carries a timestamp for later alignment.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 180, manual_degree: 2, credits_reward: 35,
+    touches: ['bongos-app/'], criteria: ['C2'], deps: ['R06'],
+  },
+  {
+    key: 'R08',
+    title: 'Markup canvas (box/arrow/freehand/text) + freeze-frame over any window',
+    description: `Part of Bongos App V1 / C2. Cross-ref: R04. A drawing layer on the overlay: freehand, box, arrow, and text annotation over any window's pixels, plus a "freeze" that snapshots the current frame so the user can mark up a still. Markup events are timestamped (for alignment in R10) and serialized as part of the bundle.
+
+**Done when:** the user can freeze the target and draw box/arrow/freehand/text over it; annotations export as an image + structured strokes with timestamps.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 180, manual_degree: 2, credits_reward: 35,
+    touches: ['bongos-app/'], criteria: ['C2'], deps: ['R04'],
+  },
+  {
+    key: 'R09',
+    title: 'On-device transcription (whisper.cpp) with word timestamps',
+    description: `Part of Bongos App V1 / C3. Cross-ref: R06. Bundle whisper.cpp (small/q5 default, base fallback, large-v3-turbo opt-in) to transcribe the recorded mic audio fully on-device — privacy-respecting and effectively free, removing ~99% of the audio token cost (audio -> text). Decide lazy-download of model weights on first use vs bundling (~250-300MB).
+
+**Done when:** recorded audio is transcribed locally to text with per-word timestamps on macOS + Windows; no audio leaves the machine; the model-weights delivery (bundle vs lazy-download) is decided + implemented.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 240, manual_degree: 2, credits_reward: 45,
+    touches: ['bongos-app/'], criteria: ['C3'], deps: ['R06'],
+  },
+  {
+    key: 'R10',
+    title: 'Transcript <-> frame time-alignment + salience frame-escalation',
+    description: `Part of Bongos App V1 / C3. Cross-ref: R07, R08, R09. Join the word-timestamped transcript with the timestamped frame stream and the markup events, then decide which frames escalate to full resolution: the ones the speech points at (deictic words like "this/here/that"), the ones with markup, and element/freeze moments. Everything else stays a cheap thumbnail.
+
+**Done when:** transcript segments, frames, and markup are aligned on one clock; a salience pass selects which frames escalate to full-res (capped); the output is an ordered, aligned timeline ready for prompt assembly.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 240, manual_degree: 3, credits_reward: 50,
+    touches: ['bongos-app/'], criteria: ['C3'], deps: ['R07', 'R08', 'R09'],
+  },
+  {
+    key: 'R11',
+    title: 'Deterministic prompt.md template + bundle writer (model-agnostic)',
+    description: `Part of Bongos App V1 / C3. Cross-ref: R10. Assemble the aligned timeline into one deterministic, model-agnostic prompt.md (no LLM call by default): target context, the transcript with timestamps, attached images with captions + inlined ABSOLUTE file paths, and the ask. Write the bundle (prompt.md + frame PNGs) to a stable dir e.g. ~/CloudBongos/feedback/<id>/. Keep it agent-neutral so it feeds Claude, Cursor, Codex, etc.
+
+**Done when:** a session produces a self-contained prompt.md + image files at a stable path, a typical session lands at the disciplined token envelope (~5-11k), and the format is documented enough for any agent to consume.`,
+    kind: 'feature', discipline: 'engineer', priority: 5,
+    est_minutes: 180, manual_degree: 2, credits_reward: 45,
+    touches: ['bongos-app/'], criteria: ['C3'], deps: ['R10'],
+  },
+  {
+    key: 'R12',
+    title: 'File-bundle + clipboard handoff for Claude Desktop',
+    description: `Part of Bongos App V1 / C4. Cross-ref: R11. The universal handoff for Claude Desktop: copy the prompt.md text to the clipboard and open the bundle folder so the user drags the images into the composer (Desktop accepts mixed text + images). Print the one-liner that tells the user exactly what to do.
+
+**Done when:** one click puts the prompt on the clipboard + opens the folder; pasting into Claude Desktop + dragging the images produces a complete, actionable message.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 150, manual_degree: 2, credits_reward: 30,
+    touches: ['bongos-app/'], criteria: ['C4'], deps: ['R11'],
+  },
+  {
+    key: 'R13',
+    title: '/feedback Claude Code slash command',
+    description: `Part of Bongos App V1 / C4. Cross-ref: R11. A shipped /feedback slash command that injects the latest prompt.md into a Claude Code session (cat ~/CloudBongos/feedback/latest/prompt.md) so the inlined absolute image paths let Claude's Read tool load the frames — sidestepping the unreliable CLI clipboard-image paste.
+
+**Done when:** running /feedback in a Claude Code session pulls in the latest bundle (text + image paths Claude can Read), with no manual file wrangling.`,
+    kind: 'feature', discipline: 'engineer', priority: 4,
+    est_minutes: 120, manual_degree: 2, credits_reward: 25,
+    touches: ['.claude/skills/', 'scripts/gds/'], criteria: ['C4'], deps: ['R11'],
+  },
+  {
+    key: 'R14',
+    title: 'Local stdio MCP server — get_latest_feedback (optional "direct" path)',
+    description: `Part of Bongos App V1 / C4. Cross-ref: R11. A local stdio MCP server (bundled with the app) exposing get_latest_feedback so both Claude Desktop and Claude Code can PULL the latest bundle hands-free. CRITICAL: return image FILE PATHS, not inline base64 (inline blows the MCP tool-result size cap). Optional/stretch for V1 — the file-bundle + /feedback paths already complete the loop.
+
+**Done when:** a connected Claude session can call get_latest_feedback and receive the prompt text + image file paths; documented as the optional "direct" handoff.`,
+    kind: 'feature', discipline: 'engineer', priority: 2,
+    est_minutes: 180, manual_degree: 2, credits_reward: 35,
+    touches: ['bongos-app/', 'scripts/'], criteria: ['C4'], deps: ['R11'],
+  },
+  {
+    key: 'R15',
+    title: 'Code-signing + notarization config (electron-builder)',
+    description: `Part of Bongos App V1 / C1. Cross-ref: R01, R03. Wire electron-builder to sign + notarize the macOS build (reusing the existing Apple Developer ID) and sign the Windows build (per the R01 decision), including the hardened-runtime entitlements and the Info.plist usage keys (NSMicrophoneUsageDescription, screen capture) a mic+screen app needs.
+
+**Done when:** CI produces a signed + notarized macOS build and a signed Windows build that launch without Gatekeeper/SmartScreen blocks and whose TCC grants persist across relaunches.`,
+    kind: 'infra', discipline: 'engineer', priority: 3,
+    est_minutes: 180, manual_degree: 3, credits_reward: 35,
+    touches: ['bongos-app/', '.github/'], criteria: ['C1'], deps: ['R01', 'R03'],
+  },
+  {
+    key: 'R16',
+    title: 'Branded download + auto-update wiring',
+    description: `Part of Bongos App V1 / C1. Cross-ref: R15. Reuse the Dev Box app's distribution pattern: per-platform binaries published to the public releases repo, the branded server-side /downloads/* 302-redirect, and the in-app semver updater — now serving the unified bongos app.
+
+**Done when:** users install the bongos app from the branded /downloads link on Mac + Windows and receive in-app auto-updates; the Dev Box app's old download path redirects/upgrades to the unified app.`,
+    kind: 'infra', discipline: 'engineer', priority: 3,
+    est_minutes: 150, manual_degree: 2, credits_reward: 30,
+    touches: ['bongos-app/', '.github/'], criteria: ['C1'], deps: ['R15'],
+  },
+  {
+    key: 'R17',
+    title: 'ADR + README — architecture + model-agnostic handoff contract',
+    description: `Part of Bongos App V1 / C4. Cross-ref: R11. Write the ADR recording the bongos app architecture (umbrella app absorbing Dev Box, the capture->synthesize->handoff pipeline, the Rung-3 capture floor with element-select deferred to V2) and a README documenting the bundle format + the model-agnostic prompt/handoff contract so any agent can consume it.
+
+**Done when:** an ADR under docs/adr/ records the architecture + the bongos-as-GDS-successor intent, and a bongos-app/README.md documents the prompt.md/bundle contract + the three handoff paths.`,
+    kind: 'infra', discipline: 'engineer', priority: 3,
+    est_minutes: 120, manual_degree: 2, credits_reward: 25,
+    touches: ['docs/adr/', 'bongos-app/'], criteria: ['C4'], deps: ['R11'],
+  },
+];
+
+async function main() {
+  await requireSession();
+  const api = await cliClient();
+
+  // Pull the current BONGOS-V1 task list once: idempotency (skip existing
+  // source_ref) and the next free decorative R## (fresh version -> starts at R1).
+  const list = await api.tasks.getTasks({ query: { version: 'BONGOS-V1' } });
+  const existing = list.data?.tasks || [];
+  const bySourceRef = {};
+  let maxR = 0;
+  for (const t of existing) {
+    if (t.source_ref) bySourceRef[t.source_ref] = t;
+    const m = /BV1\.R(\d+)\b/.exec(t.title || '');
+    if (m) { const n = Number(m[1]); if (n > maxR) maxR = n; }
+  }
+  console.log(`context: ${existing.length} BONGOS-V1 tasks, maxR=R${maxR}`);
+
+  // Assign display R## numbers sequentially after the current max.
+  const refByKey = {};
+  TASKS.forEach((def, i) => { refByKey[def.key] = `R${String(maxR + 1 + i).padStart(2, '0')}`; });
+
+  const idByKey = {};
+  let created = 0, skipped = 0, errors = 0;
+
+  for (const def of TASKS) {
+    const r = refByKey[def.key];
+    const source_ref = `bongos-v1-${def.key.toLowerCase()}`;
+    if (bySourceRef[source_ref]) {
+      idByKey[def.key] = Number(bySourceRef[source_ref].id);
+      console.log(`SKIP  ${def.key} (${r}) already exists: id=${bySourceRef[source_ref].id}`);
+      skipped++;
+      continue;
+    }
+    const body = {
+      version_id: 'BONGOS-V1',
+      title: `BV1.${r} — ${def.title}`,
+      description: def.description,
+      kind: def.kind,
+      discipline: def.discipline,
+      status: 'backlog',
+      priority: def.priority,
+      est_minutes: def.est_minutes,
+      manual_degree: def.manual_degree,
+      credits_reward: def.credits_reward,
+      touches: def.touches || [],
+      criterion_ids: def.criteria || [],
+      source: 'planning-session',
+      source_ref,
+    };
+    if (DRY) {
+      const deps = (def.deps || []).map((d) => (refByKey[d] ? `${d}=${refByKey[d]}` : d)).join(',');
+      console.log(`DRY   ${def.key} -> ${r}  P${def.priority} ${def.kind}  crit=${(def.criteria || []).join('/')}  deps=[${deps}]  ${def.title.slice(0, 52)}`);
+      continue;
+    }
+    const res = await api.tasks.postTasks({ body });
+    if (res.status !== 201) {
+      console.error(`FAIL  ${def.key}: status=${res.status} ${JSON.stringify(res.data).slice(0, 220)}`);
+      errors++;
+      continue;
+    }
+    idByKey[def.key] = Number(res.data.task.id);
+    console.log(`OK    ${def.key} -> BV1.${r}  task id=${idByKey[def.key]}  (crit ${(def.criteria || []).join('/')})`);
+    created++;
+  }
+
+  const resolveDep = (ref) => idByKey[ref] ?? null;
+
+  let depsWired = 0, depErrors = 0;
+  if (!DRY) {
+    for (const def of TASKS) {
+      const deps = def.deps || [];
+      if (deps.length === 0) continue;
+      const taskId = idByKey[def.key];
+      if (!taskId) { console.error(`DEPS  ${def.key}: no task id (create failed?), skipping`); depErrors++; continue; }
+      const depIds = deps.map(resolveDep).filter((n) => Number.isFinite(n));
+      if (depIds.length !== deps.length) {
+        const missing = deps.filter((d) => !Number.isFinite(resolveDep(d)));
+        console.error(`DEPS  ${def.key}: unresolved deps [${missing.join(',')}] — wiring the resolvable ones only`);
+        depErrors++;
+        if (depIds.length === 0) continue;
+      }
+      const res = await api.tasks.postTasksIdDependencies({ id: taskId, body: { depends_on_task_ids: depIds } });
+      if (res.status === 200) {
+        console.log(`DEPS  ${def.key} <- [${deps.join(',')}] (ids ${depIds.join(',')})`);
+        depsWired++;
+      } else {
+        console.error(`DEPS FAIL ${def.key}: ${res.status} ${JSON.stringify(res.data).slice(0, 220)}`);
+        depErrors++;
+      }
+    }
+  }
+
+  const zeroDep = TASKS.filter((d) => (d.deps || []).length === 0).map((d) => `${d.key}=${idByKey[d.key] || '?'}`);
+  console.log(`\nDONE  created=${created} skipped=${skipped} errors=${errors} deps_wired=${depsWired} dep_errors=${depErrors}  (manifest: ${TASKS.length})`);
+  console.log(`NEXT  promote zero-dependency tasks to 'ready' (they never auto-promote): ${zeroDep.join(', ')}`);
+  process.exit(errors === 0 && depErrors === 0 ? 0 : 1);
+}
+
+main().catch((err) => { console.error('FATAL', err); process.exit(1); });

package/scripts/gds/seed-bongos-coreB-tranche1-tasks.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// seed-bongos-coreB-tranche1-tasks.js
+// Seeds BONGOS-V1 criterion C7 (gds-core-modularized) — the "Config B" core
+// decomposition wave, tranche 1: kernel boundary + db.js per-domain carve +
+// proving carve (memory, grading). Planning session 2026-06-26 (task 1567).
+// Idempotent on source_ref; criterion links + dependency edges idempotent too.
+// Run: node scripts/gds/seed-bongos-coreB-tranche1-tasks.js
+const os = require('os');
+const TOKEN = require(os.homedir() + '/.config/otb/gds-session.json').token;
+const BASE = process.env.GDS_BASE || 'https://amazonprimea.com';
+const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };
+
+// ref → task spec. depends_on_refs are local R## refs resolved after create.
+const TASKS = [
+  { ref: 'R67', kind: 'spike', priority: 5, title: 'BV1.R67 — Define + bound the kernel (ADR amending 0083)',
+    description: 'Spike → ADR amending 0083: fix the KERNEL file roster (auth · rank · pool · audit · permission-path-check · route-rank-check · config/identity · loader · seams), decide the db.js per-domain carve strategy, and the fix for the doorway leaking domain queries (getBuilderById/createTask/insertAuditLog re-exported from module-api.js). Output: ADR + a sub-task shape for the carve. GATES the whole C7 tranche. The audit found the "kernel" is currently only the 6 loader-machinery files; this defines the real ~3.5k-LOC trust kernel. deps: none.',
+    deps: [] },
+  { ref: 'R68', kind: 'feature', priority: 5, title: 'BV1.R68 — Doorway surface for core domains (withTx + stop leaking db.js)',
+    description: 'Add `withTx` (BEGIN/COMMIT wrapper) + any shared primitives a core-domain module needs to module-api.js; minor CORE_VERSION bump. Stop re-exporting domain-specific queries through the doorway (relocate/deprecate getBuilderById, createTask, insertAuditLog, getBuilderGeminiKeyRow — these belong to their domains, not the kernel). deps: R67.',
+    deps: ['R67'] },
+  { ref: 'R69', kind: 'refactor', priority: 5, title: 'BV1.R69 — Per-domain db.js access pattern + carve the reference slice',
+    description: 'Establish HOW a carved core domain owns its SQL (module gets pool+withTx via the doorway and owns its queries; db.js shrinks per-domain). Prove the pattern on one reference slice. This is the mechanism every later carve copies. deps: R67, R68.',
+    deps: ['R67', 'R68'] },
+  { ref: 'R70', kind: 'infra', priority: 4, title: 'BV1.R70 — Fitness: real KERNEL_FILES roster + kernel-imports-no-domain',
+    description: 'Replace fitness.js KERNEL_FILES (currently just the 6 loader-machinery files) with the true kernel roster from R67; add a check that the kernel imports no soon-to-be-module domain. Ratchets the boundary so core-carve regressions are a red build. deps: R67.',
+    deps: ['R67'] },
+  { ref: 'R71', kind: 'infra', priority: 4, title: 'BV1.R71 — Register new core module keys in module-scope-map.js',
+    description: 'Add the new core module keys (memory, grading, and the tranche-2 domains as they are scoped) to src/bongos/module-scope-map.js so goals (scope walls), task→module affinity, and ship-time diff⊆module drift detection work for them. Then widen goal 10 (GDS core modularization) scope to include them via POST /goals/10/scope. deps: R67.',
+    deps: ['R67'] },
+  { ref: 'R72', kind: 'refactor', priority: 4, title: 'BV1.R72 — Carve memory → modules/memory/',
+    description: 'Move memory/recall/search/learnings (~2.2k LOC: memory.js, search.js, search-chunker.js, learnings.js + routes) into modules/memory/ with its tables + db.js slice (per the R69 pattern). Cleanest db.js-split proof — the design scan shows memory slices cleanly. OTB byte-identical. deps: R69, R71.',
+    deps: ['R69', 'R71'] },
+  { ref: 'R73', kind: 'refactor', priority: 4, title: 'BV1.R73 — Carve grading → modules/grading/, lifecycle resolves grade via a kernel PORT',
+    description: 'Move the grader + worker panel (~3.1k LOC) into modules/grading/. The lifecycle (tasks.js ship path) stops importing the grader directly and instead resolves a `grade` capability via a kernel PORT (registerProvider/resolve). Proves the design\'s "keep the state machine whole, extract the capability behind a seam" pattern AND closes the audit\'s unimplemented-port gap (reward/grade were illustrative-only). deps: R68, R69, R71.',
+    deps: ['R68', 'R69', 'R71'] },
+  { ref: 'R74', kind: 'verify', priority: 3, title: 'BV1.R74 — Proof: the core-carve pattern holds (memory + grading as modules)',
+    description: 'Prove C7\'s tranche-1: memory + grading live as modules/, db.js shrank by their slices, the kernel is bounded + fitness green (R70), a capability resolves via a kernel port (R73), and OTB behaves byte-identically. The single live demonstration the criterion hinges on for tranche 1. deps: R72, R73.',
+    deps: ['R72', 'R73'] },
+];
+
+async function post(path, body) {
+  const r = await fetch(BASE + path, { method: 'POST', headers: H, body: JSON.stringify(body) });
+  return { status: r.status, json: await r.json().catch(() => ({})) };
+}
+
+(async () => {
+  const idByRef = {};
+  // Phase 1: create tasks (idempotent on source_ref), link C7 at create.
+  for (const t of TASKS) {
+    const body = {
+      version_id: 'BONGOS-V1', title: t.title, description: t.description,
+      kind: t.kind, discipline: 'engineer', priority: t.priority,
+      criterion_ids: ['C7'],
+      source: 'planning', source_ref: `BONGOS-V1-coreB-${t.ref}`,
+    };
+    let { status, json } = await post('/api/gds/tasks', body);
+    let id = json.id || (json.task && json.task.id);
+    if (!id && t.kind === 'verify') {
+      // memory: kind=verify has 500'd before (idea #357). Fall back, keep going.
+      console.log(`  ${t.ref}: kind=verify failed (${json.error || status}); retrying as kind=feature`);
+      ({ status, json } = await post('/api/gds/tasks', { ...body, kind: 'feature' }));
+      id = json.id || (json.task && json.task.id);
+    }
+    if (!id) { console.log(`  ${t.ref}: CREATE FAILED — ${status} ${JSON.stringify(json).slice(0, 160)}`); continue; }
+    idByRef[t.ref] = id;
+    console.log(`  ${t.ref} -> task ${id} (${t.kind}, P${t.priority})`);
+  }
+  // Phase 2: wire dependencies (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 { status, json } = await post(`/api/gds/tasks/${id}/dependencies`, { depends_on_task_id: depId });
+      console.log(`  ${t.ref}(${id}) depends on ${dep}(${depId}) -> ${status === 200 || status === 201 ? 'ok' : (json.error || status)}`);
+    }
+  }
+  console.log('refs:', JSON.stringify(idByRef));
+})();