@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/claim.js

@@ -1,789 +1,7 @@
 #!/usr/bin/env node
-// Builder claim — atomically claim a task.
-//
-// Usage:
-//   node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join] [--here]
-//
-// On success: prints the claim id, the task title, and the touches[] so the
-// builder knows the parallel-safety boundary they're working within.
-
-const { execSync } = require('node:child_process');
-const path = require('node:path');
-const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote, detectWorktreeName, cliExit } = require('./cli-lib');
-const { nextNumbers, padAdr, padMig } = require('./next-number');
-const { CORE_NS } = require('./migration-namespace');
-const { contextPack, formatContextPack, resolveWorktreeRoot } = require('./context-pack');
-const { printClaimRecall } = require('./claim-recall');
-const { decideWorktreeClaim, ESCAPE_FLAG } = require('./worktree-claim-guard');
-const { plainCardLines } = require('./plain-cards');
-// task 1003153 — the DEAD dependency edge, one definition shared with the route
-// and the detector. A lifecycle CLI may require the lifecycle module directly
-// (the documented exception in modules/lifecycle/CLAUDE.md).
-const { splitDeadDeps, deadDepHint } = require('../../modules/lifecycle/dead-deps.js');
-const { visualReviewNudge } = require('./visual-review-nudge');
-
-// Fetch up to 3 learnings relevant to the task being claimed. touches[] cleanup
-// [3/8] (task 878): key off the task's discipline + title (always present) rather
-// than its predicted touches[] — touches[] is becoming an optional advisory
-// (#882) and is often empty at claim time, which silently emptied the old lookup.
-// Silent on empty result, errors, or missing endpoint — this is a UX nice-to-have
-// and must never break the claim flow.
-// Returns the dedup keys of the learnings it printed, so the claim-time recall
-// surface (#956) can drop any source it would otherwise echo. Empty array on any
-// miss — the caller treats that as "nothing to exclude".
-async function printRelevantLearnings(task) {
-  const discipline = task && task.discipline;
-  const title = task && task.title;
-  if (!discipline && !title) return [];
-  try {
-    const query = {};
-    if (discipline) query.discipline = String(discipline);
-    if (title) query.title = String(title);
-    const api = await cliClient();
-    const r = await api.learnings.getLearnings({ query });
-    if (r.status !== 200 || !r.data || !Array.isArray(r.data.learnings)) return [];
-    const rows = r.data.learnings.slice(0, 3);
-    if (rows.length === 0) return [];
-    console.log(`\n📚 Relevant learnings (${rows.length}):`);
-    const shownKeys = [];
-    for (const L of rows) {
-      const ref = L.source_ref || L.source || (Array.isArray(L.related_files) && L.related_files[0]) || `#${L.id}`;
-      console.log(`  - ${L.title} (${ref})`);
-      shownKeys.push(`ref:${String(ref).toLowerCase()}`);
-      if (L.title) shownKeys.push(`title:${String(L.title).toLowerCase()}`);
-    }
-    return shownKeys;
-  } catch (_) {
-    // swallow — never block a successful claim on a learnings lookup
-    return [];
-  }
-}
-
-// The claimed task's craft (task 1267; pack-aware since 1002990; INJECTED since
-// 1002992). The directive itself — which role pack or skill this craft works
-// from — no longer prints here: GET /me carries it on the active claim and the
-// Conductor relays it on the session's next prompt (src/bongos/craft-mode.js), so
-// it reaches the session whether or not anyone read the claim output. What stays
-// is ONE role indicator line, and the side effect that must happen where the claim
-// happens: landing the mode's module-owned skills (materializeModeSkills below).
-//
-// Reads the registry beside this CLI (the file fitness.js hard-fails on when a
-// pack is missing), through the same helper the server uses. Fail-open in every
-// branch: a missing or invalid map, or a discipline with no entry, prints nothing
-// and never breaks a successful claim.
-function printRoleLine(task) {
-  let mode = null;
-  try {
-    const discipline = task && task.discipline;
-    if (!discipline) return;
-    const { readModes, roleLine } = require('../../src/bongos/craft-mode');
-    mode = readModes(path.join(__dirname, 'discipline-modes.json'))[discipline] || null;
-    if (!mode || !mode.directive) return;
-    console.log('');
-    console.log(roleLine(mode));
-  } catch (_) {
-    // never let the role line break a successful claim
-    return;
-  }
-  materializeModeSkills(mode);
-}
-
-// A task brings its own tools (task 1003486). A mode whose entry opts in with
-// `materializeModuleSkills` lands the module-owned skills its playbook names — for
-// `ui`, the ui-design taste kit /design sends the session to use — into THIS
-// checkout's .claude/skills/, as the untracked, self-ignored copies ADR 0224 defined.
-// Without it a builder is routed to /design, reads that impeccable and minimalist-ui
-// are the tools, and finds none of them on the machine with no error saying why.
-// Carried by the claim rather than a hook or a session start because a workbench is
-// not re-provisioned every session (owner decision 2026-09-02): it runs only when
-// someone actually claims work of that discipline.
-//
-// Fail-open in every branch, like the hint above it: the server already granted the
-// claim, so nothing here may throw past this point — a failure prints the one command
-// that does it by hand. The require is lazy so a claim of any other discipline never
-// pays for loading the materialiser (and a broken materialiser cannot stop a claim).
-function materializeModeSkills(mode) {
-  if (!mode || mode.materializeModuleSkills !== true) return;
-  try {
-    const { materializeModuleSkillsIntoCore, isCoreCheckoutRoot } = require('./claude-materialize');
-    const coreRoot = path.resolve(__dirname, '..', '..');
-    if (!isCoreCheckoutRoot(coreRoot)) return; // a scaffolded instance already has them from `bongos init`
-    const s = materializeModuleSkillsIntoCore({ coreRoot });
-    const n = s.materialized.length;
-    if (n) console.log(`  ✓ ${n} module-owned skill(s) for this mode are in .claude/skills/ (untracked copies — ADR 0224).`);
-  } catch (e) {
-    console.log(`  ⚠ could not land this mode's module-owned skills — run \`node scripts/gds/claude-materialize.js --module-skills-only\` (${e && e.message}).`);
-  }
-}
-
-// task 1002579 — the I/O half of the worktree-per-claim guard. Probes the tree
-// with resolveWorktreeRoot (the same signal the context pack and skill-preflight
-// read, so there is one answer to "is this the main checkout") plus the current
-// branch, hands both to the pure decision, prints it, and exits 2 on a refusal.
-// Every probe failure degrades to isMainCheckout=null, which the decision treats
-// as allow — a guard that cannot see the tree must never block a real claim.
-function enforceWorktreeClaim(taskId, { allowMainCheckout }) {
-  let tree = { isMainCheckout: null };
-  let branch = null;
-  try {
-    const runGit = (a) => execSync(`git ${a.join(' ')}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-    tree = resolveWorktreeRoot({ runGit, cwd: process.cwd() });
-    branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD']).trim() || null;
-  } catch (_) {
-    /* fail-open: an unclassifiable tree is allowed through */
-  }
-  const d = decideWorktreeClaim({
-    isMainCheckout: tree.isMainCheckout,
-    branch,
-    allowMainCheckout,
-    taskId,
-  });
-  if (d.verdict === 'allow') return tree;
-  for (const line of d.lines) console.error(line);
-  if (d.verdict === 'refuse') {
-    for (const line of plainCardLines('main_checkout_claim')) console.error(line);
-    process.exit(2);
-  }
-  console.error('');
-  return tree;
-}
-
-// task 1002592 — a failed worktree DETECTION reaches the builder disguised as a
-// claim CONFLICT, and that disguise is the whole of the original bug report.
-// When detectWorktreeName() yields nothing the claim goes up with
-// worktree_name: null; the server's one-active-claim guard keys on the WORKING
-// TREE, so an unnamed claim falls back to the per-session compare and a
-// genuinely-parallel worktree is refused as a duplicate. The builder then hunts
-// for a claim conflict that does not exist.
-//
-// Only speak when null is WRONG. In the main checkout null is the documented
-// correct answer and the refusal is genuine, so a note there would send the next
-// reader down precisely the wrong path — that distinction is the fix, not a
-// detail of it.
-function worktreeDetectionNote(ctx, taskId) {
-  // The caller must have actually PROBED the tree. Without that this cannot tell
-  // "detection failed" from "nobody looked", and guessing would hang a worktree
-  // warning on every refusal rendered by a caller that never had tree info —
-  // including every pre-existing one. Absence of knowledge is not evidence.
-  if (!ctx || !('worktree' in ctx)) return [];
-  const { worktree, isMainCheckout } = ctx;
-  if (worktree) return [];                // named fine — the refusal is genuine
-  if (isMainCheckout === true) return [];  // null is correct here
-  const why = isMainCheckout === false
-    ? 'this IS a linked worktree, so a name was expected'
-    : 'this tree is not recognisable as the main checkout either';
-  return [
-    `  ⚠ This session could not name its worktree — auto-detect returned nothing, and ${why}.`,
-    '     An unnamed claim is compared per-SESSION instead of per-worktree, so a real parallel',
-    '     worktree is refused as a duplicate. That is very likely what you are looking at, and',
-    '     it is a path-detection problem, not a claim conflict. Name it explicitly to rule it out:',
-    `       node scripts/gds/claim.js ${taskId} --worktree <name>`,
-  ];
-}
-
-function captureHeadSha() {
-  try {
-    return execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();
-  } catch (_) {
-    return null;
-  }
-}
-
-// Auto-detect this claim's worktree name when --worktree is omitted, so the
-// server's one-active-claim guard (keyed on the WORKING TREE, not the shared auth
-// session) can tell genuinely-parallel worktrees apart. The detector moved to
-// cli-lib.js in task 1003767 — the ship path now needs the SAME answer to satisfy
-// the resolve lock, and two copies drifting apart would strand a ship.
-
-// task 1278: nudge (don't block) when this session's build scripts are behind
-// origin/main. The completion cards + skills are CLI-script features that ride
-// the LOCAL checkout, not the deployed server — a worktree branched from a stale
-// main silently lacks them (the root cause behind the missing cards in session
-// 1c1e12d7: claimed/shipped task 1274 on old scripts). Mirrors the ship's
-// TOOLING_PATHSPECS preflight (ship-preflight-steps.js), but as a NUDGE — claiming on old scripts is fine, you
-// just miss features. Strictly best-effort + fail-open (never break/slow a claim).
-const STALE_TOOLING_DIRS = ['scripts/gds', 'src/bongos', '.claude/skills'];
-function warnIfToolingStale() {
-  try {
-    // Quiet, timed, fail-open fetch so the diff reflects GitHub's main, not a
-    // stale local ref — catching a stale LOCAL main is the whole point.
-    try {
-      execSync('git fetch origin main', { stdio: 'ignore', timeout: 8000 });
-    } catch (_) {
-      return; // offline / no remote / detached — skip the nudge silently
-    }
-    // `...` (symmetric, merge-base) so the builder's OWN edits to these files
-    // don't trip it — only files where origin/main has moved ahead (same as ship.js).
-    const out = execSync(
-      `git diff --name-only HEAD...origin/main -- ${STALE_TOOLING_DIRS.join(' ')}`,
-      { encoding: 'utf8', timeout: 8000 }
-    );
-    const stale = out.trim().split('\n').filter(Boolean);
-    if (stale.length === 0) return;
-    console.log('');
-    console.log(`⚠ Your build scripts are behind origin/main (${stale.length} file${stale.length === 1 ? '' : 's'} in ${STALE_TOOLING_DIRS.join(', ')}).`);
-    console.log('  Run `git merge origin/main` to pick up the latest — newer skills, fixes, and the in-feed completion cards.');
-  } catch (_) {
-    /* a freshness nudge must never break or slow a claim */
-  }
-}
-
-// task 1275: the CLAIMED stage of the deterministic lifecycle card — the SAME
-// card the ship surfaces, here showing the scope (priority / estimate / touches /
-// version) with the brief in the dropdown and the discipline session as the
-// action. Best-effort: a claim card must never break a successful claim.
-function printClaimCard(task, widgetsEnabled = true) {
-  try {
-    const shipCard = require('../../modules/lifecycle/ship-card');
-    const model = shipCard.buildCardModel({
-      stage: 'claimed',
-      taskId: task.id,
-      title: task.title,
-      description: task.description || '',
-      estMinutes: task.est_minutes != null ? Number(task.est_minutes) : null,
-      touchesCount: Array.isArray(task.touches) ? task.touches.length : null,
-      version: task.version_id,
-      kind: task.kind,
-      priority: task.priority,
-      discipline: task.discipline,
-    });
-    // task 1279: when the builder has widgets off, emitCard prints only the
-    // monospace card (no HTML written or relayed).
-    shipCard.emitCard(model, task.id, { widgetsEnabled });
-  } catch (_) { /* never block a claim on the card */ }
-}
-
-// task 1003138: the envelope/flat normalization from formatClaimFailure, pulled
-// out so the goal-join flow reads the same { code, message, d } regardless of
-// response shape. Pure + exported (tested through both consumers).
-function claimErrorInfo(r) {
-  const errRaw = r && r.data ? r.data.error : undefined;
-  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
-  return {
-    code: isEnvelope ? errRaw.code : errRaw,
-    message: isEnvelope ? errRaw.message : undefined,
-    // Structured fields live under .details in the envelope; fall back to the
-    // top-level body for the legacy flat shape (so both keep working).
-    d: { ...(r && r.data ? r.data : {}), ...((isEnvelope && errRaw.details) || {}) },
-  };
-}
-
-// task 1476: render a failed claim as GUIDANCE, not a raw object dump. The API
-// returns the R01 error envelope (ADR 0116): { error: { code, message, details } }.
-// Older paths returned a flat { error: 'CODE', ...fields } shape. claimErrorInfo
-// normalizes BOTH — without it `r.data.error` is now an object (never === a
-// string), so every branch below silently missed and the refusal printed as
-// `[object Object]`. Pure (no console / no process.exit) + exported so it can be
-// unit-tested against the real envelope shapes. Returns { lines, exit }.
-//
-// task 1002592: server-supplied prose (a task title, a flag reason, a hint) is
-// echoed to the operator's terminal by the branches below. It is our own API, so
-// this is hygiene rather than a live threat — but an unbounded string can carry
-// control characters that repaint a terminal, and a runaway one can bury the
-// guidance it was meant to add. Clip to one line, strip C0/C1 controls, cap length.
-const MAX_LISTED_TASKS = 20;
-
-// QUEUE_GATED_EXIT — the one refusal that is about the QUEUE, not the task
-// (task 1004396). REBASE_REQUIRED refuses every claim until a stranded confirmed
-// task lands, so an unattended caller that reads it as "this task is refused"
-// sets aside task after task for a fault none of them has. Every other refusal
-// keeps exit 1. The autobongos runner is the consumer and pins the same value
-// in a test.
-const QUEUE_GATED_EXIT = 4;
-function clip(s, max = 160) {
-  if (s == null) return '';
-  // eslint-disable-next-line no-control-regex
-  const flat = String(s).replace(/[\u0000--Ÿ]+/g, ' ').trim();
-  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
-}
-
-// task 1002592: `ctx` carries what the CALLER knows about the tree
-// ({ worktree, isMainCheckout }) so the session-claim branch can tell a real
-// conflict apart from a failed worktree detection. Optional and defaulted — the
-// function stays pure and every existing caller/test keeps working.
-function formatClaimFailure(r, taskId, ctx) {
-  const info = claimErrorInfo(r);
-  const { lines, exit } = claimFailureGuidance(info, r, taskId, ctx);
-  // task 1003989: the same refusal in plain words, AFTER the curated text so nothing
-  // an engineer relies on moves. The owed-task gate names a flagged reason per task;
-  // the first one is translated too, because that token is what a builder is stuck on.
-  const { code, d } = info;
-  const owed = code === 'REBASE_REQUIRED' ? (d.rebaseTasks || d.rebase_tasks || []) : [];
-  const flagged = owed.length ? plainCardLines(String(owed[0].reason || '')) : [];
-  return { lines: [...lines, ...plainCardLines(code), ...flagged], exit };
-}
-
-function claimFailureGuidance({ code, message, d }, r, taskId, ctx) {
-  const lines = [];
-
-  // #766: a generic onboarding stage gate (kept rendering cleanly, not as raw JSON).
-  if (code === 'stage_required') {
-    lines.push(`Task #${taskId} can't be claimed yet.`);
-    lines.push(`  ${d.what_to_do || `Clear "${d.required_stage_label || d.required_stage}" first.`}`);
-    return { lines, exit: 1 };
-  }
-  // task 1476 (the core case): a session may hold at most ONE active claim
-  // (task 1642 / ADR 0097). This is the most common refusal and previously fell
-  // straight through to the raw dump — the exact "reads like you can't hold more
-  // than one task" complaint from idea 218. Surface it as guidance AND teach how
-  // to parallelize (a separate worktree/session per task, or the hall bulk-claim).
-  if (code === 'session_already_has_active_claim' || code === 'session_claim_check_failed') {
-    const n = d.active_task_id;
-    lines.push(n
-      ? `This session already holds task #${n}${d.active_task_title ? `: ${d.active_task_title}` : ''}.`
-      : 'This session already holds an active claim.');
-    lines.push(`  ${d.what_to_do || (n
-      ? `Run /builder-ship ${n} (or /builder-release ${n}) first, or open a fresh worktree/session for this task.`
-      : 'Ship or release the in-flight claim, or start a fresh worktree/session.')}`);
-    lines.push('  One claim per session keeps each ship isolated (task 1642). To work tasks in PARALLEL, open a separate worktree/session per task — each holds its own single claim — or use the hall work board’s multi-select bulk-claim.');
-    lines.push(...worktreeDetectionNote(ctx, taskId));
-    return { lines, exit: 1 };
-  }
-  if (code === 'newcomer_must_ship_first') {
-    lines.push(`Task #${taskId} can't be claimed yet — your first work isn't shipped.`);
-    lines.push(`  You're holding an active claim on #${d.active_task_id}: ${d.active_task_title}`);
-    lines.push(`  ${d.what_to_do || 'Ship or release the current claim first.'}`);
-    return { lines, exit: 1 };
-  }
-  // task 1002589: the per-session DB backstop index tripped. Distinct from
-  // session_already_has_active_claim (the route guard's own refusal): since
-  // core_204 (task 1002570) the index keys per (session, worktree) —
-  // matching the guard — so this mainly surfaces the same-tree race the guard
-  // couldn't see, or fires on a DB still carrying the migration-180
-  // session-only index. Either way the target task itself is NOT taken — never
-  // render this as "claimed by another session".
-  if (code === 'session_already_has_bound_claim') {
-    const n = d.active_task_id;
-    lines.push(n
-      ? `Task #${taskId} is still free — but this session already holds a bound claim on #${n}${d.active_task_title ? `: ${d.active_task_title}` : ''}.`
-      : `Task #${taskId} is still free — but this session already holds a bound claim on another task.`);
-    lines.push(`  ${d.what_to_do || `Run /builder-ship ${n || '<task>'} (or /builder-release ${n || '<task>'}) first, claim from a separate worktree, or claim with {"bind_session":false} (an unbound claim always coexists).`}`);
-    return { lines, exit: 1 };
-  }
-  // task 1002592: ADR 0120 part 3's owed-rebase gate refuses EVERY new claim, so
-  // it is the refusal a builder is most stuck behind — and it was the only one
-  // with no branch here, printing as a bare `[REBASE_REQUIRED]: REBASE_REQUIRED`
-  // code echo. The server builds a full way-forward menu for it
-  // (rebaseRequiredHint, task 1003768 — /strand-fix leads because it is the one
-  // exit that works with no GitHub push credential, the DOCUMENTED default
-  // posture) and this surface dropped it on the floor. Name the owed tasks, then
-  // print the server's menu.
-  if (code === 'REBASE_REQUIRED') {
-    // task 1004788: only the fixable ones gate; set-aside ones are listed apart.
-    const all = (d.rebaseTasks || d.rebase_tasks || []);
-    const owed = all.filter((t) => !t.waiting).slice(0, MAX_LISTED_TASKS);
-    const waiting = all.filter((t) => t.waiting).slice(0, MAX_LISTED_TASKS);
-    lines.push(owed.length
-      ? `Your queue is gated — ${owed.length} confirmed task(s) are waiting on your rebase:`
-      : 'Your queue is gated — a confirmed task is waiting on your rebase.');
-    for (const t of owed) {
-      lines.push(`  - task ${t.id}${t.title ? `  ${clip(t.title)}` : ''}`);
-      if (t.reason) lines.push(`      flagged: ${clip(t.reason)}`);
-    }
-    if (waiting.length) lines.push('  Waiting, not on you (set aside; they land on their own):');
-    for (const t of waiting) lines.push(`  - task ${t.id}${t.title ? `  ${clip(t.title)}` : ''} — ${clip(t.waits_on || t.reason || 'outside you')}`);
-    lines.push(`  ${clip(d.hint, 600) || 'Clear it with /strand-fix N, or rebase the branch and re-ship — or /builder-release it to give up on one.'}`);
-    return { lines, exit: QUEUE_GATED_EXIT };
-  }
-  if (code === 'ALREADY_CLAIMED') {
-    lines.push(`Task #${taskId} was just claimed by another session. Try a different task.`);
-    return { lines, exit: 1 };
-  }
-  if (code === 'MODULE_CONFLICT') {
-    lines.push(`Task #${taskId} has module_key='${d.module_key}', but another active claim already owns that module:`);
-    for (const t of d.conflictTaskTitles || []) lines.push(`  - ${t}`);
-    lines.push('Two tasks in the same module cannot run concurrently. Ship or release the in-flight claim first.');
-    return { lines, exit: 1 };
-  }
-  if (code === 'TOUCHES_CONFLICT') {
-    lines.push(`Task #${taskId} touches files currently in flight on another claim:`);
-    for (const t of d.conflictTaskTitles || []) lines.push(`  - ${t}`);
-    lines.push('Pick a task with disjoint touches[], or run it in a separate session once the other ships.');
-    return { lines, exit: 1 };
-  }
-  if (code === 'TASK_NOT_READY') {
-    lines.push(`Task #${taskId} is not ready (current status: ${d.currentStatus}).`);
-    if (d.hint) lines.push(`  ${d.hint}`);
-    return { lines, exit: 1 };
-  }
-  if (code === 'TASK_NOT_FOUND') {
-    lines.push(`Task #${taskId} not found — check the id (run /builder-start to list claimable tasks).`);
-    return { lines, exit: 1 };
-  }
-  if (code === 'DEPS_NOT_SHIPPED') {
-    // task 1003153: an ABANDONED dependency can never ship, so "ship those
-    // first" was impossible advice — the task is STRANDED, not waiting. Mark the
-    // dead edges in the list and relay the server's hint (deadDepHint), which
-    // names the two real remedies. Falls back to the original wording when every
-    // unmet dep is genuinely still pending.
-    const dead = new Set(splitDeadDeps(d.deps).dead.map((x) => String(x.id)));
-    lines.push(dead.size
-      ? `Task #${taskId} is STRANDED — a dependency was abandoned and can never satisfy:`
-      : `Task #${taskId} can't be claimed yet — these dependencies are not shipped:`);
-    for (const dep of d.deps || []) {
-      const flag = dead.has(String(dep.id)) ? '  ← ABANDONED: this edge will never satisfy' : '';
-      lines.push(`  - #${dep.id}  [${dep.status}]  ${dep.title}${flag}`);
-    }
-    lines.push(d.hint || deadDepHint(d.deps, taskId) || 'Ship those first (or release them) and try again.');
-    return { lines, exit: 1 };
-  }
-  if (code === 'OPEN_BLOCKER') {
-    // task 1002650: the same rule the claimable feed enforces, spoken at the gate.
-    lines.push(`Task #${taskId} is waiting on an open blocker:`);
-    for (const b of d.blockers || []) lines.push(`  - blocker ${b.id}  ${b.title}`);
-    lines.push('Resolve it first (/blocker-solve N drives one to done; resolving auto-promotes its linked tasks) — or pick another task from /builder-start.');
-    return { lines, exit: 1 };
-  }
-  if (code === 'GOAL_MEMBERSHIP_REQUIRED') {
-    // task 1003138: the non-interactive rendering of the membership refusal —
-    // the interactive offer (runGoalJoinFlow) normally intercepts this code
-    // before it gets here; this branch covers a retry that re-refused, an
-    // unexpected body, or a decline.
-    lines.push(`Task #${taskId} lives in goal ${d.goal_id}${d.goal_title ? ` ("${d.goal_title}")` : ''}${d.visibility ? ` (${d.visibility})` : ''} — you are not a member.`);
-    lines.push(d.action === 'apply'
-      ? `  Apply to join (POST /api/bongos/goals/${d.goal_id}/requests) — nothing can be claimed until an owner approves. Re-run with --join to file the application from here.`
-      : `  Join and claim in one command:  node scripts/gds/claim.js ${taskId} --join`);
-    return { lines, exit: 1 };
-  }
-  // Fallback — still readable: the message + code, never a raw [object Object].
-  lines.push(`Claim failed (${r ? r.status : '?'})${code ? ` [${code}]` : ''}${message ? `: ${message}` : ''}.`);
-  // task 1002592: whatever the code, if the server sent a way forward, PRINT it.
-  // REBASE_REQUIRED sat in this fallback with a fully-formed hint in its body and
-  // nothing rendered it. The branches above stay the curated wording; this is the
-  // floor, so the next unmapped code can never be mute the same way.
-  if (d && d.hint) lines.push(`  ${clip(d.hint, 600)}`);
-  return { lines, exit: 1 };
-}
-
-// task 1003138 (owner ask, verbatim: 'claude should offer to join so they dont
-// need to go through the ui') — the goal-membership refusal (403
-// GOAL_MEMBERSHIP_REQUIRED, the task-1003137 gate) is resolvable in-session.
-// goalMembershipOfferPlan is the PURE half: given the refusal details it names
-// the offer to make. Exported for unit tests; the I/O lives in runGoalJoinFlow.
-// Returns null when the body is missing the fields the flow needs (falls back
-// to formatClaimFailure), else { action, headerLines, question }.
-function goalMembershipOfferPlan(d, taskId) {
-  if (!d || d.goal_id == null || (d.action !== 'join' && d.action !== 'apply')) return null;
-  const g = d.goal_id;
-  if (d.action === 'join') {
-    return {
-      action: 'join',
-      headerLines: [
-        `✗ Task ${taskId} lives in goal ${g}`,
-        ...(d.goal_title ? [`    "${d.goal_title}" (${d.visibility || 'public'})`] : []),
-        '    You are not a member.',
-      ],
-      question: `Join goal ${g} and claim? [Y/n] `,
-    };
-  }
-  // 'apply' — a private goal, or a public one whose scope is Archon-mediated
-  // (the server folds both to apply; a pending request grants nothing yet).
-  return {
-    action: 'apply',
-    headerLines: d.visibility === 'private'
-      ? [`✗ Goal ${g} is private.`]
-      : [
-        `✗ Task ${taskId} lives in goal ${g}${d.goal_title ? ` ("${d.goal_title}")` : ''} — joining needs approval (Archon-mediated scope).`,
-      ],
-    question: 'Apply to join? [Y/n] ',
-  };
-}
-
-// One yes/no on the real terminal (default yes — the owner-approved [Y/n]
-// shape). Returns null when there is no TTY to ask — the caller then prints
-// the --join re-run hint instead of hanging a non-interactive session.
-async function promptYesNo(question) {
-  if (!process.stdin.isTTY) return null;
-  const readline = require('node:readline/promises');
-  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-  try {
-    const a = (await rl.question(question)).trim().toLowerCase();
-    return a === '' || a === 'y' || a === 'yes';
-  } finally {
-    rl.close();
-  }
-}
-
-// The I/O half of the offer. Outcomes: 'retry' (joined — re-POST the claim),
-// 'stop' (declined / filed / blocked — everything already printed, exit 1),
-// 'unhandled' (fall through to formatClaimFailure). Never joins or files
-// without a yes: --join is the standing yes for non-interactive sessions.
-async function runGoalJoinFlow({ api, d, taskId, assumeYes }) {
-  const plan = goalMembershipOfferPlan(d, taskId);
-  if (!plan) return 'unhandled';
-  const goalId = d.goal_id;
-  for (const line of plan.headerLines) console.error(line);
-
-  const yes = assumeYes ? true : await promptYesNo(plan.question);
-  if (yes === null) {
-    // Non-interactive (an agent session): make the one-command path explicit.
-    console.error(plan.action === 'join'
-      ? `  To join goal ${goalId} and claim in one command:  node scripts/gds/claim.js ${taskId} --join`
-      : `  To file the application from here:  node scripts/gds/claim.js ${taskId} --join   (nothing claimable until approved)`);
-    return 'stop';
-  }
-  if (!yes) {
-    // The owner chose the explicit-join model — declining leaves NO membership
-    // row and NO request.
-    console.error(plan.action === 'join'
-      ? '  Declined — nothing joined, nothing claimed.'
-      : '  Declined — no application filed, nothing claimed.');
-    return 'stop';
-  }
-
-  if (plan.action === 'join') {
-    const jr = await api.goals.postGoalsIdJoin({ id: goalId, body: {} });
-    if (jr.status === 200 || jr.status === 201) {
-      console.error(`+ joined goal ${goalId} (member)`);
-      return 'retry';
-    }
-    const j = claimErrorInfo(jr);
-    if (j.code === 'archon_approval_required') {
-      // The third branch, handled honestly (routes/goals.js:615): a PUBLIC goal
-      // with protected scope is not self-joinable — don't loop, name the path.
-      console.error(`✗ Goal ${goalId}'s scope is Archon-mediated — self-join is not allowed.`);
-      console.error(`  Request to join instead:  node scripts/gds/claim.js ${taskId} --join  (after the server re-offers apply), or ask an Archon to add you.`);
-      return 'stop';
-    }
-    if (j.code === 'goal_private') {
-      // Visibility flipped between refusal and join — report, don't loop.
-      console.error(`✗ Goal ${goalId} is private now — request to join (POST /api/bongos/goals/${goalId}/requests) and wait for approval.`);
-      return 'stop';
-    }
-    console.error(`✗ join failed (${jr.status})${j.code ? ` [${j.code}]` : ''}${j.message ? `: ${j.message}` : ''}.`);
-    return 'stop';
-  }
-
-  // 'apply' — file the request; a pending row grants nothing, so never retry
-  // the claim here.
-  const ar = await api.goals.postGoalsIdRequests({ id: goalId, body: {} });
-  if (ar.status === 201) {
-    console.error('+ request filed — pending owner approval');
-    console.error('  (nothing to claim until approved)');
-    return 'stop';
-  }
-  const a = claimErrorInfo(ar);
-  if (a.code === 'request_pending') {
-    // The core_188 partial-unique: one pending ask per goal per builder —
-    // re-running reports, it does not error.
-    console.error('• already pending — your earlier request for this goal awaits owner approval.');
-    console.error('  (nothing to claim until approved)');
-    return 'stop';
-  }
-  console.error(`✗ application failed (${ar.status})${a.code ? ` [${a.code}]` : ''}${a.message ? `: ${a.message}` : ''}.`);
-  return 'stop';
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  const taskId = Number(args[0]);
-  if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join] [--here]');
-    process.exit(2);
-  }
-  // task 1002579: worktree-per-claim, enforced BEFORE anything happens — before
-  // the session check, before the POST. The whole point is that the builder
-  // learns at claim time, not from a stranded ship hours later.
-  const tree = enforceWorktreeClaim(taskId, { allowMainCheckout: args.includes(ESCAPE_FLAG) });
-  await requireSession();
-  const wIdx = args.indexOf('--worktree');
-  // Explicit --worktree always wins; otherwise auto-detect a linked worktree so
-  // parallel worktrees off one login each hold their own claim (the server guard
-  // keys on this). null in the main checkout → unchanged one-claim behaviour.
-  const worktree = (wIdx >= 0 ? args[wIdx + 1] : null) || detectWorktreeName();
-  // touches[] cleanup [5/8] (task 880): touches[] overlap with another active
-  // claim is ADVISORY for an interactive human claim (just a warning — git merge
-  // is the real collision detector). The autonomous --parallel runner passes
-  // --enforce-touches so adjacency becomes a HARD refusal (it fans concurrent
-  // unsupervised agents that could clobber each other on shared files).
-  const enforceTouches = args.includes('--enforce-touches');
-  // task 1003138: --join is the standing yes to the goal-membership offer —
-  // join (public) or file the application (private/protected) and, for a join,
-  // retry the claim, all in one command. Without it an interactive session is
-  // asked [Y/n]; a non-TTY session is shown the --join re-run line.
-  const assumeYes = args.includes('--join');
-  const headSha = captureHeadSha();
-
-  const api = await cliClient();
-  const postClaim = () => api.claims.postClaims({
-    body: {
-      task_id: taskId,
-      worktree_name: worktree,
-      head_sha: headSha,
-      enforce_touches: enforceTouches,
-      // --auto-pickup (task 1004679, ADR 0371 D5): the Autobongos tweak lane's mark.
-      ...(args.includes('--auto-pickup') ? { auto_pickup: true } : {}),
-    },
-  });
-  let r = await postClaim();
-  // task 1003138: a goal-membership refusal (the task-1003137 gate) is
-  // resolvable in-session — offer the join/application, and on a successful
-  // join retry the claim ONCE (a second refusal falls through to the plain
-  // rendering; never loop).
-  if (r.status !== 201 && claimErrorInfo(r).code === 'GOAL_MEMBERSHIP_REQUIRED') {
-    const outcome = await runGoalJoinFlow({ api, d: claimErrorInfo(r).d, taskId, assumeYes });
-    if (outcome === 'retry') {
-      r = await postClaim();
-    } else if (outcome === 'stop') {
-      return cliExit(1); // everything already printed; no claim landed
-    }
-  }
-  if (r.status === 201) {
-    const { claim, task } = r.data;
-    console.log(`Claimed task #${task.id}: ${task.title}`);
-    console.log(`Claim id: ${claim.id}`);
-    // The reward figure is the task's ADVERTISED estimate. On a cost-plus-only
-    // instance it is never paid, so label it as an estimate and name the real
-    // payer right here — this line is where the expectation forms (task 1002469).
-    const rewardLabel = rewardPolicy(r.data.reward).perTaskCredit ? 'Credit reward' : 'Credit reward (est. only)';
-    console.log(`Version: ${task.version_id}  ·  Priority: P${task.priority ?? '?'}  ·  ${rewardLabel}: ${task.credits_reward}`);
-    const cpNote = costPlusOnlyNote(r.data.reward);
-    if (cpNote) console.log(`  ${cpNote}`);
-    if (task.parallel_safe === true) console.log('Parallel-safe: yes (eligible for a parallel autonomous slot)');
-    // BV1.R53 (task 1422): module_key is the primary scope signal. touches[] is
-    // demoted to derived/advisory for module-keyed tasks; fall back to it for
-    // tasks that predate module affinity.
-    if (task.module_key) {
-      console.log(`Module scope: ${task.module_key}   →  modules/${task.module_key}/`);
-      console.log('  Build within that directory tree. Files outside it will trigger a drift warning at ship time.');
-    } else {
-      console.log(`Touches: ${fmtTouches(task.touches)}`);
-      // touches[] cleanup [7/8] (task 882): the planning field is optional now.
-      // If none was declared, it'll be backfilled from the real diff at ship.
-      if (!Array.isArray(task.touches) || task.touches.length === 0) {
-        console.log('  (no touches declared — backfilled from your committed diff at ship; build where the work leads)');
-      }
-    }
-    // touches[] cleanup [5/8] (task 880): advisory overlap notice. The claim
-    // succeeded; this is a heads-up that another active claim declares
-    // overlapping files. Self-serialize only if it's genuinely the same code.
-    if (Array.isArray(r.data.overlap_warning) && r.data.overlap_warning.length > 0) {
-      console.log(`\n⚠ touches[] overlaps an active claim: ${r.data.overlap_warning.join(', ')}`);
-      console.log('  Advisory only — your claim stands; git merge is the authoritative collision check.');
-    }
-    // task 1001741: goal-aware — an unclaimed OPEN sibling in the same goal
-    // declares overlapping files. Same advisory posture as above.
-    if (Array.isArray(r.data.sibling_overlap_warning) && r.data.sibling_overlap_warning.length > 0) {
-      console.log('\n⚠ touches[] overlaps open sibling task(s) in this goal:');
-      for (const s of r.data.sibling_overlap_warning) {
-        console.log(`  #${s.task_id} ${s.title} — ${s.overlapping_paths.join(', ')}`);
-      }
-      console.log('  Advisory only — a goal owner can sequence or rescope these from the goal page.');
-    }
-    for (const ach of (r.data.just_unlocked || [])) {
-      const bonus = ach.credit_bonus > 0 ? ` (+${ach.credit_bonus}c bonus)` : '';
-      console.log(`✨ Achievement unlocked: ${ach.name}${bonus}`);
-    }
-    // task 1278: surface a stale-scripts nudge early, so the builder can merge
-    // main before diving in (and pick up newer skills + the completion cards).
-    warnIfToolingStale();
-    // Claim-time context pack (V4.R26 / #964): the AUTHORITATIVE next-free ADR +
-    // migration numbers, computed deterministically from origin/main ∪ the local
-    // working tree (next-number.js). This supersedes blind trust in the drift-prone
-    // claim-time DB counter, which has handed out already-applied numbers and now
-    // sits ahead of the committed files. Best-effort — never break a claim.
-    let nn = null;
-    try { nn = nextNumbers(); } catch { /* fail-open: skip the hint */ }
-    if (nn) {
-      console.log(`\nNext free numbers (from ${nn.source} ∪ local):`);
-      console.log(`  ADR:        ${padAdr(nn.adr)}   →  docs/adr/${padAdr(nn.adr)}-<slug>.md`);
-      // New core migrations are namespaced core_ (ADR 0108 §5) so a stem can't collide with an
-      // instance/module migration across repos; instance seeds stay bare in migrations/instance/.
-      console.log(`  migration:  ${padMig(nn.migration)}   →  migrations/${CORE_NS}_${padMig(nn.migration)}_<slug>.sql   (core; instance seed → migrations/instance/${padMig(nn.migration)}_<slug>.sql bare)`);
-      if (nn.degraded) console.log('  ⚠ origin/main unreachable — recompute with `node scripts/gds/next-number.js` before committing.');
-    }
-    if (claim.reserved_migration_number != null) {
-      const padded = String(claim.reserved_migration_number).padStart(3, '0');
-      // The DB counter still reserves a number (parallel-claim arbitration), but
-      // it can drift; if it disagrees with the file-derived next-free, trust the
-      // file-derived one (it reflects what is actually committed/applied).
-      const driftNote = nn && nn.migration !== claim.reserved_migration_number
-        ? `  ⚠ DB counter reserved ${padded}, but ${padMig(nn.migration)} is the next free on origin/main — use ${padMig(nn.migration)}.`
-        : '  (No other parallel claim can be allocated this number.)';
-      console.log(`\nMigration counter reserved: ${padded}`);
-      console.log(driftNote);
-    }
-    // Claim-time context pack (V4.R04 / #942, criterion sessions-start-knowing).
-    // Fetch /me ONCE here — it gives the builder's currently-held claims for the
-    // pack, and is reused for the onboarding nudge at the end. Best-effort: the
-    // pack is a UX surface and a /me hiccup must never break a successful claim.
-    let meRes = null;
-    try {
-      const api = await cliClient();
-      meRes = await api.me.getMe();
-    } catch (_) { /* fail-open */ }
-    try {
-      const activeClaims = (meRes && meRes.ok && meRes.data)
-        ? (meRes.data.active_claims || (meRes.data.active_claim ? [meRes.data.active_claim] : []))
-        : [];
-      console.log('');
-      console.log(formatContextPack(contextPack({ activeClaims, currentTaskId: task.id })));
-    } catch (_) { /* never block a claim on the pack */ }
-    if (task.description) {
-      console.log('');
-      console.log(task.description);
-    }
-    // The craft's role line (and, for a mode that opts in, its module-owned
-    // skills). The full directive reaches the session through the Conductor —
-    // task 1002992.
-    printRoleLine(task);
-    // task 1004202: a task that changes a page is told to use /design and get its
-    // human's OK on the before/after. A nudge, never a gate: gating on that OK would
-    // put a person's approval in the land path, which ADR 0162 retired.
-    try {
-      const nudge = visualReviewNudge(task);
-      if (nudge) console.log(`\n${nudge.join('\n')}`);
-    } catch (_) { /* never let a hint break a successful claim */ }
-    if (worktree) console.log(`\nWorktree: ${worktree}`);
-    // Claim-time knowledge (#956 / V4.R18, criterion sessions-start-knowing):
-    // learnings first (curated, short), then the top recall sources for this task
-    // (ADR 0060 search layer), deduped against the learnings just shown. Both are
-    // best-effort and never block the claim.
-    const shownLearningKeys = await printRelevantLearnings(task);
-    await printClaimRecall(task, { excludeKeys: shownLearningKeys });
-    console.log('\nWhen you finish:');
-    console.log(`  node scripts/gds/ship.js ${task.id} --notes "..." --summary "..."`);
-    console.log('Or to abandon:');
-    console.log(`  node scripts/gds/release.js ${task.id}`);
-    // V3.R13 (#237): post-claim nudge — for a newcomer, this becomes
-    // "Next: Ship thy first work" so the path forward is visible. Reuses the
-    // /me fetched above for the context pack (no second round-trip).
-    try {
-      if (meRes && meRes.ok) {
-        console.log('');
-        printOnboardingNudge(meRes.data);
-      }
-    } catch (_) {
-      // never let a UX nudge break a successful claim
-    }
-    // task 1275: the claimed lifecycle card, last so it's the visual anchor.
-    // task 1279: honour the builder's render-widgets knob (resolved from the /me
-    // fetched above; default ON if /me was unavailable).
-    const widgetsEnabled = meRes && meRes.ok ? (meRes.data?.render?.widgets_enabled !== false) : true;
-    printClaimCard(task, widgetsEnabled);
-    return;
-  }
-  // Any non-201 comes here. formatClaimFailure normalizes the R01 error envelope
-  // and renders the refusal as guidance (task 1476) — one place, unit-tested.
-  const failure = formatClaimFailure(r, taskId, {
-    worktree,
-    isMainCheckout: tree ? tree.isMainCheckout : null,
-  });
-  for (const line of failure.lines) console.error(line);
-  // task 1002592: this exit runs immediately after the claim request, which is
-  // exactly where Windows aborts teardown — "Assertion failed: !(handle->flags &
-  // UV_HANDLE_CLOSING)" — turning a refusal's intended exit 1 into 127. Measured
-  // 3/3 aborting before this change. Set the code, let the loop drain (1002734).
-  cliExit(failure.exit);
-}
-
-// Only auto-run when invoked directly (`node claim.js …`); a `require()` (the
-// unit test) just imports formatClaimFailure without executing the claim flow.
-if (require.main === module) {
-  main().catch((err) => {
-    console.error('fatal:', err);
-    cliExit(1);
-  });
-}
-
-module.exports = { formatClaimFailure, claimErrorInfo, goalMembershipOfferPlan, materializeModeSkills, printRoleLine, worktreeDetectionNote, QUEUE_GATED_EXIT };
+// scripts/gds/claim.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/claim.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'claim.js');