@bongos/core 1.17.0

package/scripts/gds/start.js

@@ -0,0 +1,782 @@
+#!/usr/bin/env node
+// Builder start — what can I claim right now?
+//
+// Usage:
+//   node scripts/gds/start.js [--version V1|PMS-V1] [--discipline engineer|artist|ideator|unclassified] [--all-disciplines] [--fit autonomous|parallel] [--limit N] [--full] [--widget] [--json]
+//
+// --fit narrows the claimable list to what the autonomous overnight
+// session-runner (#358) may pick up:
+//   autonomous — overnight-safe + manual_degree<=2 + unblocked (canonical
+//                tasks_session_fit 'autonomous' mode). The runner takes
+//                claimable[0] as the next task by priority.
+//   parallel   — autonomous AND tasks.parallel_safe = true (safe to run
+//                alongside other tasks). The runner fills its parallel slots
+//                from the top of this list.
+//
+// Output is a deterministic "card" (task 1273): one quiet status line, the
+// builder's identity, their holdings, a clean claimable table (# / Version /
+// Type / Reward / Est. / What it is), and a next-step line — identical every session.
+//   --widget : emit the card as self-contained HTML on stdout (private warnings
+//              to stderr) for the app's widget renderer (show_widget). This is
+//              the surface the /builder-start skill renders — BUT it honours the
+//              builder's per-builder "render widgets" knob (task 1279): if that
+//              builder has widgets off, --widget degrades to the markdown card so
+//              no HTML is ever emitted/relayed. Default ON. The skill detects
+//              which form it got (HTML starts with '<') and renders accordingly.
+//   (default): the markdown form of the same card — the fallback when the
+//              client can't draw widgets (raw terminal, cron, other tools).
+//   --full   : add the detailed ambient widgets + context pack (markdown).
+//   --json   : unchanged machine interface the autonomous runner reads.
+//
+// --discipline filters the claimable list by builder interest area
+// (orthogonal to kind). engineer = code/infra/gameplay/bugs; artist =
+// pixel art / sprites / the art pipeline; ideator = scoping/research/
+// docs/narrative/lore.
+//
+// DISCIPLINE ROUTING (V3.R81 / #299): by default — when no explicit
+// --discipline is passed — the claimable list is narrowed to the builder's
+// preferred_disciplines (builders.preferred_disciplines, set via
+// /me/disciplines per migrations 027 + 086). An artist shouldn't be shown
+// only engineer tasks. Two escape hatches:
+//   --all-disciplines  — ignore preferences, show every lane.
+//   --discipline X      — explicit single-lane filter (overrides preferences).
+// A builder with no stated preference (empty preferred_disciplines) sees
+// everything by default — there is no lane to narrow to.
+//
+// Below the main list, a "You might enjoy" section surfaces up to 3 claimable
+// tasks OUTSIDE the builder's disciplines, ranked by relevance. The ranking
+// mirrors db.rankCrossDisciplineRecommendations (the canonical server-side
+// home for this logic — kept in sync deliberately; start.js is a pure HTTP
+// client and cannot import the server db module).
+//
+//
+// Returns JSON if --json is passed (for the slash command to parse cleanly).
+
+const { cliClient, requireSession, fmtUsd, printOnboardingNudge, printCostWarning, printNeedsNudge } = require('./cli-lib');
+const { contextPack, formatContextPackCompact } = require('./context-pack');
+
+// task 1284: the card shows only the top N claimable rows. The table is the bulk
+// of the widget HTML the model relays verbatim, so fewer rows = fewer tokens +
+// faster render; the true total sits in the header and a "N more — show all"
+// affordance covers the rest. --json is unchanged (full list for the runner).
+const CARD_ROWS = 5;
+
+// ---------- header widget helpers ----------
+
+// Compact ascii progress bar. Width 10. Filled = █, empty = ░.
+function progressBar(percent, width = 10) {
+  const p = Math.max(0, Math.min(100, Number(percent) || 0));
+  const filled = Math.round((p / 100) * width);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+function formatVersionsRow(progress) {
+  if (!Array.isArray(progress) || progress.length === 0) return null;
+  // Only show versions currently building (status==='building').
+  // Fall back to non-shipped if none are flagged building.
+  let active = progress.filter((v) => v.status === 'building');
+  if (active.length === 0) active = progress.filter((v) => v.status !== 'shipped');
+  if (active.length === 0) return null;
+  const parts = active.map((v) => `${v.version_id} ${progressBar(v.percent_complete)} ${v.percent_complete}%`);
+  return parts.join('  ·  ');
+}
+
+function formatCostRow(cost) {
+  if (!cost || typeof cost !== 'object') return null;
+  const spent = Number(cost.total_usd) || 0;
+  const credits = Number(cost.total_value_credits) || 0;
+  // No verdict. The old line computed `credits >= spent` and printed
+  // "value > cost ✓" — comparing unitless reward drachmae against USD, so it
+  // was green by unit mismatch, not by economics (spike #482 audit, F2). It was
+  // also resting on an incomplete cost figure: cost_log captures almost no LLM
+  // spend (audit F1; api category was $0.60). Until spend is captured honestly
+  // (#483/#486) and given a real value basis, we show the two ledgers plainly
+  // and labelled for what they are — logged spend vs reward credits — and let
+  // them stand without a manufactured ✓/✗.
+  return `${fmtUsd(spent)} logged spend  ·  ${credits}c reward shipped`;
+}
+
+function formatRecentRow({ recentShipped, inboxCount, blockerCount }) {
+  const bits = [];
+  // "1 ship in last 24h" — recent_shipped returns tasks shipped within
+  // a recent window; we re-filter to strictly <24h for the header.
+  if (Array.isArray(recentShipped)) {
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    const last24 = recentShipped.filter((t) => {
+      const ts = t.shipped_at ? Date.parse(t.shipped_at) : 0;
+      return ts && ts >= cutoff;
+    }).length;
+    bits.push(`${last24} ship${last24 === 1 ? '' : 's'} in last 24h`);
+  } else {
+    bits.push('ships: N/A');
+  }
+  bits.push(inboxCount == null ? 'ideas: N/A' : `${inboxCount} idea${inboxCount === 1 ? '' : 's'} in inbox`);
+  bits.push(blockerCount == null ? 'blockers: N/A' : `${blockerCount} open blocker${blockerCount === 1 ? '' : 's'}`);
+  return bits.join('  ·  ');
+}
+
+// ---------- card helpers (task 1273) ----------
+// The default /builder-start view is a single deterministic "card" rendered as
+// markdown: a quiet status line, identity, holdings, a clean claimable table,
+// and a next-step line. Same shape every session — the skill relays this stdout
+// verbatim, which is what removes the per-session re-summarizing drift.
+
+// Shared status selection — single source of truth for what the quiet status
+// line shows, so the markdown line and the widget render the same thing.
+// Surfaces the versions with real momentum: drop not-yet-started (0%) ones,
+// lead with the most-progressed, so a dormant planning version doesn't crowd
+// out the one actually being built.
+function statusParts({ progress, recentShipped, inboxCount, blockerCount }) {
+  let versions = [];
+  if (Array.isArray(progress) && progress.length) {
+    let active = progress.filter((v) => v.status === 'building');
+    if (active.length === 0) active = progress.filter((v) => v.status !== 'shipped');
+    versions = active
+      .filter((v) => Number(v.percent_complete) > 0)
+      .sort((a, b) => Number(b.percent_complete) - Number(a.percent_complete))
+      .slice(0, 2)
+      .map((v) => ({ id: v.version_id, pct: Number(v.percent_complete) }));
+  }
+  let ships24 = null;
+  if (Array.isArray(recentShipped)) {
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    ships24 = recentShipped.filter((t) => t.shipped_at && Date.parse(t.shipped_at) >= cutoff).length;
+  }
+  return { versions, ships24, ideas: inboxCount, blockers: blockerCount };
+}
+
+// One muted line of ambient status (markdown). Italic so the feed renders it
+// quiet. null if empty.
+function quietStatusLine(header) {
+  const { versions, ships24, ideas, blockers } = statusParts(header);
+  const parts = [];
+  for (const v of versions) parts.push(`${v.id} ${progressBar(v.pct, 8)} ${v.pct}%`);
+  if (ships24 != null) parts.push(`${ships24} ship${ships24 === 1 ? '' : 's'}/24h`);
+  if (ideas != null) parts.push(`${ideas} idea${ideas === 1 ? '' : 's'} in inbox`);
+  if (blockers != null) parts.push(`${blockers} open blocker${blockers === 1 ? '' : 's'}`);
+  if (parts.length === 0) return null;
+  return `_${parts.join('  ·  ')}_`;
+}
+
+// Calibrated estimate, compact: ~8m / ~2h / ~1.5h.
+function estimateShort(t) {
+  const m = t.est_minutes_calibrated != null ? t.est_minutes_calibrated : t.est_minutes;
+  if (m == null) return '—';
+  if (m < 60) return `~${m}m`;
+  const h = m / 60;
+  return Number.isInteger(h) ? `~${h}h` : `~${h.toFixed(1)}h`;
+}
+
+function clip(s, n) {
+  s = String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+
+// Escape pipes so a title can't break the markdown table.
+function cell(s) {
+  return String(s == null ? '' : s).replace(/\|/g, '\\|');
+}
+
+// Per-column values, shared by the markdown table and the widget. Version
+// (V2 / GDS-V4) is its own column; Type is the work lane (Engineer / Artist /
+// Ideator), its own column rather than baked into the title.
+function disciplineLabel(t) {
+  const d = t.discipline;
+  return d && d !== 'unclassified' ? d.charAt(0).toUpperCase() + d.slice(1) : '';
+}
+// Per-lane accent — the OTB palette (sea / terracotta / olive); mid-ramp hexes
+// that read in both light and dark. Colours the Type column so the work lane
+// reads at a glance (task 1273 follow-up: "spice up the view").
+function disciplineColor(d) {
+  if (d === 'engineer') return '#1D9E75'; // sea-teal
+  if (d === 'artist') return '#D85A30';   // terracotta
+  if (d === 'ideator') return '#639922';  // olive
+  return '#888780';                        // unclassified — neutral gray
+}
+function whatItIs(t) {
+  return clip(t.title, 64);
+}
+
+// The claimable table — # / Version / Type / Reward / Est. / What it is.
+// Ids are emitted as hall links (renders as a clean #N) — a bare "#NNN" in a
+// relayed chat message autolinks to GitHub and 404s (CLAUDE.md ref rule).
+const HALL_TASK = 'https://amazonprimea.com/builders#/task/';
+function claimableTable(rows) {
+  const out = [
+    '| # | Version | Type | Reward | Est. | What it is |',
+    '|---|---|---|---|---|---|',
+  ];
+  for (const t of rows) {
+    out.push(`| [#${t.id}](${HALL_TASK}${t.id}) | ${cell(t.version_id || '?')} | ${cell(disciplineLabel(t) || '—')} | ${t.credits_reward ?? 0}c | ${estimateShort(t)} | ${cell(whatItIs(t))} |`);
+  }
+  return out.join('\n');
+}
+
+// ---------- widget renderer (task 1273) ----------
+// `--widget` emits this self-contained HTML on stdout; the skill pipes it
+// straight to the app's widget renderer (show_widget). Script-owned markup =
+// the same card every time, app-native. Falls back to the markdown card when
+// the client can't draw widgets. Design system: flat, 0.5px borders, CSS
+// theme vars (light/dark), Tabler icons, no emoji.
+const hesc = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const jsq = (s) => String(s == null ? '' : s).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, ' ');
+
+function miniBar(pct) {
+  // Fill tinted OTB sea-teal so the status line carries a little of the brand.
+  // Class-based (task 1279 efficiency pass): the .bs-* rules live in WIDGET_STYLE,
+  // so this markup is only meaningful inside the widget renderWidget emits.
+  return `<span class="bs-bar"><span class="bs-barfill" style="width:${pct}%;"></span></span>`;
+}
+
+// Run console.log-based helpers (printCostWarning/printOnboardingNudge) without
+// polluting stdout (which must be pure HTML in --widget mode); return the lines.
+function captureLog(fn) {
+  const orig = console.log;
+  const lines = [];
+  console.log = (...a) => lines.push(a.join(' '));
+  try { fn(); } finally { console.log = orig; }
+  return lines;
+}
+
+// task 1282: reinforce the relay contract IN-BAND, not just in the skill. The
+// rule — render/print the card verbatim, then stop; don't rebuild it into prose
+// + tables + a recommendation — used to live ONLY in SKILL.md (advisory), so a
+// model in old habits (or a stale checkout's old skill) reverted to hand-built
+// tables. This emits a one-line `[otb-card]` directive on STDERR (stdout stays
+// pure HTML/markdown, so the show_widget pipe + the skill's first-char branch
+// are untouched). The skill treats `[otb-card]` stderr lines as instructions
+// for itself and never relays them to the user. Mirrors the ship card.
+const CARD_DIRECTIVE = {
+  html: '[otb-card] stdout is the finished /builder-start card (HTML). Render it verbatim via show_widget, then stop — no extra tables, recommendation, nudge, or recap.',
+  markdown: '[otb-card] stdout is the finished /builder-start card (markdown). Output it verbatim as your reply, then stop — no rebuilt table, recommendation, nudge, or recap.',
+};
+function emitCardDirective(form) {
+  process.stderr.write(CARD_DIRECTIVE[form] + '\n');
+}
+
+// task 1279 efficiency pass: the /builder-start widget used to inline a full
+// style="…" on every one of its ~30+ elements — the 7×N claimable grid was the
+// bulk — making the HTML the agent must relay verbatim ~18.7KB. Hoisting the
+// repeated rules into one class block (the pattern the ship card already uses)
+// cuts that markup substantially with byte-identical rendering. Classes are
+// `.bs-*` (builder-start) so they can't collide with the ship card's `.cc-*`.
+const WIDGET_STYLE = `<style>
+.bs-sr{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;}
+.bs-card{background:var(--color-background-primary);border:0.5px solid var(--color-border-tertiary);border-radius:var(--border-radius-lg);padding:1rem 1.25rem;font-family:var(--font-sans);}
+.bs-head{display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap;}
+.bs-brand{display:inline-flex;align-items:center;gap:8px;}
+.bs-title{font-size:16px;font-weight:500;}
+.bs-title i{font-size:16px;vertical-align:-2px;margin-right:6px;color:#D85A30;}
+.bs-meta{font-size:13px;color:var(--color-text-secondary);}
+.bs-status{font-size:13px;color:var(--color-text-secondary);margin-top:8px;display:flex;flex-wrap:wrap;gap:4px 12px;align-items:center;}
+.bs-dot{color:var(--color-text-tertiary);}
+.bs-bar{display:inline-block;width:34px;height:5px;border-radius:3px;background:var(--color-border-tertiary);overflow:hidden;vertical-align:middle;}
+.bs-barfill{display:block;height:100%;background:#1D9E75;}
+.bs-line{font-size:13px;color:var(--color-text-secondary);margin-top:8px;}
+.bs-line i{font-size:14px;vertical-align:-2px;margin-right:4px;}
+.bs-holditem{margin-top:4px;padding-left:18px;}
+.bs-link{color:var(--color-text-secondary);}
+.bs-menuh{font-size:13px;color:var(--color-text-primary);margin-top:14px;margin-bottom:2px;font-weight:500;}
+.bs-table{width:100%;border-collapse:collapse;table-layout:fixed;font-size:13px;margin-top:4px;}
+.bs-thead{text-align:left;color:var(--color-text-tertiary);font-size:12px;}
+.bs-th{padding:0 6px 4px;font-weight:400;}
+.bs-tr{cursor:pointer;}
+.bs-td{padding:7px 6px;border-top:0.5px solid var(--color-border-tertiary);}
+.bs-id{color:var(--color-text-secondary);font-family:var(--font-mono);font-size:12px;}
+.bs-nowrap{white-space:nowrap;}
+.bs-ellip{white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+.bs-ellip-sub{color:var(--color-text-secondary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+.bs-sub{color:var(--color-text-secondary);}
+.bs-lane{display:inline-block;width:7px;height:7px;border-radius:50%;margin-right:6px;vertical-align:middle;}
+.bs-foot{font-size:13px;color:var(--color-text-tertiary);margin-top:12px;}
+</style>`;
+
+function renderWidget({ builder, claims, claimable, total, streak, recommendations, header, routingByPreference, preferred, filters, readyToClose }) {
+  const b = builder || {};
+  // Streak badge — warm amber, the one bold pop of colour + the motivational
+  // stat. Shown only on an active (>0) streak; tooltip carries the record.
+  // (Singular element — left inline; the savings live in the repeated grid.)
+  const streakBadge = (streak && Number(streak.current) > 0)
+    ? `<span title="Longest streak: ${Number(streak.longest) || 0} days" style="display:inline-flex;align-items:center;gap:4px;background:var(--color-background-warning);color:var(--color-text-warning);font-size:12px;font-weight:500;padding:2px 8px;border-radius:var(--border-radius-md);"><i class="ti ti-flame" aria-hidden="true" style="font-size:13px;"></i>${Number(streak.current)}-day streak</span>`
+    : '';
+  const rank = b.rank ? b.rank[0].toUpperCase() + b.rank.slice(1) : 'Thetes';
+  const disc = (b.preferred_disciplines && b.preferred_disciplines.length) ? b.preferred_disciplines.join(' + ') : 'all disciplines';
+  const credits = Number(b.total_credits || 0).toLocaleString();
+  const TH = (label) => `<th class="bs-th">${label}</th>`;
+  const TD = (inner, cls = '') => `<td class="bs-td${cls ? ' ' + cls : ''}">${inner}</td>`;
+
+  // status line
+  const { versions, ships24, ideas, blockers } = statusParts(header);
+  const sBits = [];
+  for (const v of versions) sBits.push(`${hesc(v.id)} ${miniBar(v.pct)} ${v.pct}%`);
+  if (ships24 != null) sBits.push(`${ships24} ship${ships24 === 1 ? '' : 's'}/24h`);
+  if (ideas != null) sBits.push(`${ideas} idea${ideas === 1 ? '' : 's'}`);
+  if (blockers != null) sBits.push(`${blockers} blocker${blockers === 1 ? '' : 's'}`);
+  const statusRow = sBits.length
+    ? `<div class="bs-status">${sBits.join('<span class="bs-dot">·</span>')}</div>`
+    : '';
+
+  // holdings — each held task gets quick actions off it (ship / release /
+  // open). Parallel sessions under one builder are normal, so this informs.
+  const hallUrl = (id) => `https://amazonprimea.com/builders#/task/${encodeURIComponent(id)}`;
+  const dot = '<span class="bs-dot"> · </span>';
+  const act = (label, msg) => `<a href="#" onclick="event.preventDefault();sendPrompt('${jsq(msg)}')" class="bs-link">${label} ↗</a>`;
+  const actionsFor = (c) => `${act('Ship', 'Ship task ' + c.task_id)}${dot}${act('Release', 'Release task ' + c.task_id)}${dot}<a href="${hesc(hallUrl(c.task_id))}" class="bs-link">Open ↗</a>`;
+  let holdings = '';
+  if (claims.length === 1) {
+    const c = claims[0];
+    holdings = `<div class="bs-line"><i class="ti ti-bookmark" aria-hidden="true"></i>Holding #${hesc(c.task_id)} — ${hesc(clip(c.title, 44))}${dot}${actionsFor(c)}</div>`;
+  } else if (claims.length > 1) {
+    const items = claims.map((c) => `<div class="bs-holditem">#${hesc(c.task_id)} — ${hesc(clip(c.title, 38))}${dot}${actionsFor(c)}</div>`).join('');
+    holdings = `<div class="bs-line"><i class="ti ti-bookmark" aria-hidden="true"></i>Holding ${claims.length} claims (parallel sessions OK):${items}</div>`;
+  }
+
+  // version-close banner (rare, Archon action)
+  const closeBanner = (readyToClose || []).map((s) =>
+    `<div class="bs-line"><i class="ti ti-flag" aria-hidden="true"></i>${hesc(s.versionId)} looks ready to close (${s.criteriaSatisfied}/${s.criteriaTotal} criteria, ${s.percentComplete}%) — <a href="#" onclick="event.preventDefault();sendPrompt('${jsq('/builder-version-close ' + s.versionId)}')" class="bs-link">close it ↗</a></div>`
+  ).join('');
+
+  // menu header note
+  const matched = routingByPreference ? ` matched to ${hesc(preferred.join(' + '))}` : '';
+  const fBits = [
+    filters.version && `in ${filters.version}`,
+    filters.discipline && `discipline=${filters.discipline}`,
+    filters.fit && `fit=${filters.fit}`,
+  ].filter(Boolean);
+  const fNote = fBits.length ? ` (${hesc(fBits.join(', '))})` : '';
+
+  // rows — click to claim. Columns: # / Version / Type / Reward /
+  // Est. / What it is (the work lane is its own column, not baked into the title).
+  const rows = claimable.map((t) => {
+    const claimMsg = jsq(`Claim task ${t.id}`);
+    const titleAttr = hesc(`Claim #${t.id}: ${t.title || ''}`);
+    const d = t.discipline;
+    const laneDot = (d && d !== 'unclassified')
+      ? `<span class="bs-lane" style="background:${disciplineColor(d)};"></span>`
+      : '';
+    return `<tr class="bs-tr" role="button" tabindex="0" title="${titleAttr}" onclick="sendPrompt('${claimMsg}')" onkeydown="if(event.key==='Enter'||event.key===' '){event.preventDefault();sendPrompt('${claimMsg}')}">`
+      + TD(`#${hesc(t.id)}`, 'bs-id')
+      + TD(hesc(t.version_id || '?'), 'bs-nowrap')
+      + TD(`${laneDot}${hesc(disciplineLabel(t) || '—')}`, 'bs-ellip-sub')
+      + TD(hesc((t.credits_reward ?? 0) + 'c'))
+      + TD(hesc(estimateShort(t)), 'bs-sub')
+      + TD(hesc(t.title || ''), 'bs-ellip')
+      + `</tr>`;
+  }).join('');
+
+  const menu = claimable.length
+    ? `<table class="bs-table">
+    <colgroup><col style="width:44px;"><col style="width:52px;"><col style="width:68px;"><col style="width:48px;"><col style="width:44px;"><col></colgroup>
+    <thead><tr class="bs-thead">${TH('#')}${TH('Version')}${TH('Type')}${TH('Reward')}${TH('Est.')}${TH('What it is')}</tr></thead>
+    <tbody>${rows}</tbody>
+  </table>`
+    : `<div class="bs-line">Nothing claimable right now — everything is in flight, blocked, or shipped. <a href="#" onclick="event.preventDefault();sendPrompt('Run blocker-review')" class="bs-link">See what's stuck ↗</a></div>`;
+
+  // footer actions: a "more" link when the list was capped, then the
+  // cross-lane pointer. (The old "just exploring" link was dropped — not
+  // picking is already "not claiming"; task 1273 follow-up.)
+  const moreCount = Math.max(0, (total || claimable.length) - claimable.length);
+  const moreLink = moreCount > 0
+    ? ` · <a href="#" onclick="event.preventDefault();sendPrompt('${jsq('Show me all ' + (total || '') + ' claimable tasks, not just the top ' + claimable.length)}')" class="bs-link">${moreCount} more — show all ↗</a>`
+    : '';
+  let crossLane = '';
+  if (recommendations.length > 0) {
+    const ids = recommendations.map((t) => '#' + t.id).join(', ');
+    crossLane = ` · <a href="#" onclick="event.preventDefault();sendPrompt('${jsq('Show me the tasks outside my disciplines: ' + ids)}')" class="bs-link">Outside your lanes: ${hesc(ids)} ↗</a>`;
+  } else if (routingByPreference) {
+    crossLane = ` · <a href="#" onclick="event.preventDefault();sendPrompt('Show me every lane, not just mine')" class="bs-link">Show all lanes ↗</a>`;
+  }
+
+  const summary = `builder-start: ${claimable.length} task${claimable.length === 1 ? '' : 's'} you can claim now, plus your current build status. Click a task to claim it.`;
+  return `${WIDGET_STYLE}
+<h2 class="bs-sr">${hesc(summary)}</h2>
+<div class="bs-card">
+  <div class="bs-head">
+    <span class="bs-brand"><span class="bs-title"><i class="ti ti-player-play" aria-hidden="true"></i>builder-start</span>${streakBadge}</span>
+    <span class="bs-meta">${hesc(b.github_login)} · ${hesc(rank)} · ${hesc(credits)} credits · ${hesc(disc)}</span>
+  </div>
+  ${statusRow}
+  ${holdings}
+  ${closeBanner}
+  <div class="bs-menuh">Claim one to start — ${total || claimable.length} ready for you right now${matched}${fNote}</div>
+  ${menu}
+  <div class="bs-foot">Click a task to claim it${moreLink}${crossLane}</div>
+</div>`;
+}
+
+// Cross-discipline recommendations — mirror of
+// db.rankCrossDisciplineRecommendations (src/bongos/db.js). Given the full
+// claimable list and the builder's preferred_disciplines, return up to `limit`
+// tasks whose discipline is OUTSIDE the builder's preferences, ranked:
+//   priority DESC, credits/min DESC, est_minutes ASC, id ASC.
+// 'unclassified' tasks are excluded (un-triaged, not a real lane). Empty
+// preferences → [] (everything is already in the main list; nothing outside).
+function rankCrossDisciplineRecommendations(claimable, preferredDisciplines, limit = 3) {
+  const rows = Array.isArray(claimable) ? claimable : [];
+  const prefs = Array.isArray(preferredDisciplines) ? preferredDisciplines : [];
+  if (prefs.length === 0) return [];
+  const prefSet = new Set(prefs);
+  const cpm = (t) => {
+    const credits = Number(t.credits_reward) || 0;
+    const mins = Number(t.est_minutes_calibrated ?? t.est_minutes) || 0;
+    return mins > 0 ? credits / mins : 0;
+  };
+  const outside = rows.filter(
+    (t) => t.discipline && t.discipline !== 'unclassified' && !prefSet.has(t.discipline)
+  );
+  outside.sort((a, b) => {
+    const pa = Number(a.priority) || 0;
+    const pb = Number(b.priority) || 0;
+    if (pb !== pa) return pb - pa;
+    const ca = cpm(a);
+    const cb = cpm(b);
+    if (cb !== ca) return cb - ca;
+    const ma = Number(a.est_minutes_calibrated ?? a.est_minutes) || Infinity;
+    const mb = Number(b.est_minutes_calibrated ?? b.est_minutes) || Infinity;
+    if (ma !== mb) return ma - mb;
+    return (Number(a.id) || 0) - (Number(b.id) || 0);
+  });
+  return outside.slice(0, Math.max(0, limit));
+}
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const versionIdx = args.indexOf('--version');
+  const version = versionIdx >= 0 ? args[versionIdx + 1] : null;
+  const disciplineIdx = args.indexOf('--discipline');
+  const discipline = disciplineIdx >= 0 ? args[disciplineIdx + 1] : null;
+  const allDisciplines = args.includes('--all-disciplines');
+  const fitIdx = args.indexOf('--fit');
+  const fit = fitIdx >= 0 ? args[fitIdx + 1] : null;
+  const limitIdx = args.indexOf('--limit');
+  const limit = limitIdx >= 0 ? Number(args[limitIdx + 1]) : 10;
+  // --full restores the detailed ambient widgets + context pack that the lean
+  // card omits (task 1273). Default is the lean card.
+  const full = args.includes('--full');
+  // --widget emits the card as self-contained HTML on stdout for the app's
+  // widget renderer (task 1273). Private warnings go to stderr so stdout stays
+  // pure HTML the skill can pipe verbatim.
+  const widget = args.includes('--widget');
+  // --hook (task 1288): machine envelope for the builder-start-card hook — both
+  // card forms (HTML + markdown) + the private warnings from a single fetch, so
+  // the hook can hand the model a finished card it only has to render. Not a
+  // user surface; stdout is the JSON envelope only.
+  const hookMode = args.includes('--hook');
+
+  // Server-side filtering: only push an explicit --discipline (single-lane
+  // override). Preference-based routing is done client-side below, because
+  // (a) a builder can prefer BOTH disciplines and the server filter takes a
+  // single value, and (b) the "You might enjoy" section needs the full
+  // claimable set (across all disciplines) to compute recommendations from.
+  const claimableQuery = {};
+  if (version) claimableQuery.version = version;
+  if (discipline) claimableQuery.discipline = discipline;
+  if (fit) claimableQuery.fit = fit;
+
+  // Fire everything in parallel. Header widgets are non-critical — if any
+  // endpoint fails, that widget degrades to "N/A" rather than killing
+  // /builder-start.
+  const api = await cliClient();
+  const [me, r, closeRes, progressRes, costRes, recentRes, inboxRes, blockersRes] = await Promise.all([
+    api.me.getMe(),
+    api.tasks.getTasksClaimable({ query: claimableQuery }),
+    api.versions.getVersionsCloseSuggestions(),
+    api.public.getPublicProgress(),
+    api.public.getPublicCostSummary(),
+    api.public.getPublicRecentShipped(),
+    api.inbox.getInbox({ query: { status: 'open' } }),
+    api.blockers.getBlockers(),
+  ]);
+  // #766: the primer-read gate on the claimable endpoint was removed, so a
+  // newcomer no longer gets a 403 stage_required here. A generic stage_required
+  // (any future onboarding gate) still renders cleanly rather than crashing.
+  if (r.status === 403 && r.data && r.data.error === 'stage_required') {
+    console.log('');
+    console.log(r.data.what_to_do || `Clear "${r.data.required_stage_label || r.data.required_stage}" before the work queue opens.`);
+    console.log('');
+    process.exit(0);
+  }
+  if (!r.ok) {
+    console.error(`failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+
+  // Full claimable set as returned by the server (already filtered for
+  // touches[] safety, version/fit, and any explicit --discipline).
+  const rawClaimable = r.data.claimable || [];
+
+  // Discipline routing (V3.R81 / #299). preferred_disciplines lives on the
+  // builder row (migration 027), surfaced via /api/gds/me.
+  const preferred = (me.ok && Array.isArray(me.data?.builder?.preferred_disciplines))
+    ? me.data.builder.preferred_disciplines
+    : [];
+  // Apply preference narrowing unless the builder explicitly opted out
+  // (--all-disciplines), explicitly chose a single lane (--discipline X,
+  // already applied server-side), or stated no preference.
+  const routingByPreference = !allDisciplines && !discipline && preferred.length > 0;
+  const filtered = routingByPreference
+    ? rawClaimable.filter((t) => preferred.includes(t.discipline))
+    : rawClaimable;
+  const claimable = filtered.slice(0, limit);
+
+  // "You might enjoy" — up to 3 claimable tasks outside the builder's lanes.
+  // Computed from the FULL set so it can reach across disciplines. Suppressed
+  // when an explicit single-lane --discipline filter is in play (the builder
+  // asked to see exactly one lane) — but shown for --all-disciplines and the
+  // default preference-routed view.
+  const recommendations = discipline
+    ? []
+    : rankCrossDisciplineRecommendations(rawClaimable, preferred, 3);
+
+  // Close-suggestions endpoint is non-critical; if it fails (e.g. older
+  // server without the route), surface no banner rather than blowing up.
+  const closeSuggestions = closeRes.ok && Array.isArray(closeRes.data?.suggestions)
+    ? closeRes.data.suggestions
+    : [];
+  const readyToClose = closeSuggestions.filter((s) => s.ready);
+
+  // Header widget data (each independently optional).
+  const progress = progressRes.ok && Array.isArray(progressRes.data?.progress) ? progressRes.data.progress : null;
+  const cost = costRes.ok ? costRes.data : null;
+  const recentShipped = recentRes.ok && Array.isArray(recentRes.data?.tasks) ? recentRes.data.tasks : null;
+  const inboxCount = inboxRes.ok && Array.isArray(inboxRes.data?.ideas)
+    ? inboxRes.data.ideas.length
+    : (inboxRes.ok && typeof inboxRes.data?.count === 'number' ? inboxRes.data.count : null);
+  const blockerCount = blockersRes.ok && Array.isArray(blockersRes.data?.blockers)
+    ? blockersRes.data.blockers.filter((b) => b.status === 'open' || !b.status).length
+    : null;
+
+  if (json) {
+    console.log(JSON.stringify(
+      {
+        me: me.data,
+        claimable,
+        recommendations,
+        discipline_routing: {
+          preferred_disciplines: preferred,
+          applied: routingByPreference,
+          all_disciplines: allDisciplines,
+          explicit_discipline: discipline || null,
+        },
+        close_suggestions: closeSuggestions,
+        header: {
+          progress,
+          cost,
+          recent_shipped: recentShipped,
+          inbox_count: inboxCount,
+          blocker_count: blockerCount,
+        },
+      },
+      null, 2
+    ));
+    return;
+  }
+
+  // ---------- widget (HTML for the app renderer) ----------
+  // task 1279: the per-builder "render widgets" knob. When a builder turns
+  // widgets off, even an explicit --widget request degrades to the markdown card
+  // below — so no HTML is emitted, read, or re-relayed (a real token saving, not
+  // just a visual change). Default ON; /me carries the resolved boolean. Headless
+  // /cron callers don't pass --widget at all (no renderer), so they're unaffected.
+  const widgetsPref = me.ok ? (me.data?.render?.widgets_enabled !== false) : true;
+  if (widget && widgetsPref) {
+    const myClaims = me.ok ? (me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : [])) : [];
+    // Private warnings (budget / onboarding next-stage) → stderr, so stdout
+    // stays pure HTML the skill can pipe straight into show_widget.
+    if (me.ok) {
+      const warnings = captureLog(() => { printOnboardingNudge(me.data); printCostWarning(me.data); printNeedsNudge(me.data); });
+      for (const w of warnings) process.stderr.write(w + '\n');
+    }
+    emitCardDirective('html');
+    process.stdout.write(renderWidget({
+      builder: me.ok ? me.data.builder : {},
+      claims: myClaims,
+      claimable: claimable.slice(0, CARD_ROWS),
+      total: filtered.length,
+      streak: me.ok ? me.data.streak : null,
+      recommendations,
+      header: { progress, recentShipped, inboxCount, blockerCount },
+      routingByPreference,
+      preferred,
+      filters: { version, discipline, fit },
+      readyToClose,
+    }) + '\n');
+    return;
+  }
+
+  // ---------- the card (default) ----------
+  // task 1288: the markdown card body, lifted into a closure so the --hook
+  // envelope can capture it (via captureLog) next to the widget HTML from the
+  // single fetch above; the normal markdown path just calls it below. The body
+  // is kept VERBATIM (same indentation) so this stays a pure wrap+call with zero
+  // change to the shipped card. Closes over the locals computed above. (task
+  // 1273: relaying this verbatim is what keeps the card identical every session;
+  // `--full` adds the ambient widgets + context pack.)
+  const emitMarkdownCard = () => {
+  // V3.R13 (#237): one-line "next stage" nudge for newcomers. Silent for
+  // graduated builders and anyone past first_ship.
+  if (me.ok) printOnboardingNudge(me.data);
+  // task 1013 / ADR 0073: flag any input the system needs from the builder
+  // (e.g. their own image-generation key once free coverage ends). Silent unless
+  // something is in the action_needed state.
+  if (me.ok) printNeedsNudge(me.data);
+
+  // identity line
+  if (me.ok) {
+    const b = me.data.builder;
+    const rankLabel = b.rank ? b.rank.charAt(0).toUpperCase() + b.rank.slice(1) : 'Thetes';
+    const discLabel = Array.isArray(b.preferred_disciplines) && b.preferred_disciplines.length
+      ? b.preferred_disciplines.join(' + ')
+      : 'all disciplines';
+    const credits = Number(b.total_credits || 0).toLocaleString();
+    console.log(`**builder-start** · ${b.github_login} (${rankLabel}) · ${credits} credits · ${discLabel}`);
+    const sk = me.data.streak;
+    if (sk && Number(sk.current) > 0) {
+      console.log(`🔥 ${sk.current}-day streak${Number(sk.longest) > Number(sk.current) ? ` · longest ${sk.longest}` : ''}`);
+    }
+  }
+
+  // ambient status: one quiet line by default; the full widgets + context pack
+  // under --full.
+  if (full) {
+    const rows = [
+      formatVersionsRow(progress),
+      formatCostRow(cost),
+      formatRecentRow({ recentShipped, inboxCount, blockerCount }),
+    ].filter(Boolean);
+    if (rows.length) console.log(rows.join('\n'));
+    // Worktree root (the #1 wrong-path footgun) + API prefix/enums. Also printed
+    // at /builder-claim, where it matters most; here it's --full-only detail.
+    try {
+      console.log('');
+      console.log(formatContextPackCompact(contextPack()));
+    } catch (_) { /* fail-open */ }
+  } else {
+    const status = quietStatusLine({ progress, recentShipped, inboxCount, blockerCount });
+    if (status) console.log(status);
+  }
+  console.log('');
+
+  // V3.R84 (#302), criterion C3: private session-start budget ping. The CLI is
+  // the builder's private channel, so the soft-cap (80%) warning / hard-cap
+  // (100%) refusal surface here rather than via Discord (a shared mirror).
+  if (me.ok) printCostWarning(me.data);
+
+  // your holdings — calm + factual, with quick actions off each held task.
+  // Parallel sessions under one builder are normal, so this informs (it does
+  // not block — feedback_parallel_sessions). Ids are hall links (ref rule).
+  if (me.ok) {
+    const myClaims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
+    const heldActions = (id) => `    → ship: \`/builder-ship ${id}\`  ·  release: \`/builder-release ${id}\`  ·  open: [#${id}](${HALL_TASK}${id})`;
+    if (myClaims.length === 1) {
+      const c = myClaims[0];
+      console.log(`You're holding [#${c.task_id}](${HALL_TASK}${c.task_id}) — ${clip(c.title, 56)}`);
+      console.log(heldActions(c.task_id));
+      console.log('');
+    } else if (myClaims.length > 1) {
+      console.log(`You're holding ${myClaims.length} claims (parallel sessions OK):`);
+      for (const c of myClaims) {
+        console.log(`  [#${c.task_id}](${HALL_TASK}${c.task_id}) — ${clip(c.title, 50)}`);
+        console.log(heldActions(c.task_id));
+      }
+      console.log('');
+    }
+  }
+
+  // Version-close gate banner — informational; fires rarely (an Archon action)
+  // when a building version is >= 80% weighted AND every criterion is satisfied.
+  for (const s of readyToClose) {
+    console.log(
+      `🚦 ${s.versionId} looks ready to close ` +
+      `(${s.criteriaSatisfied}/${s.criteriaTotal} criteria, ${s.percentComplete}% weighted; ` +
+      `${s.tasksShipped} shipped, ${s.tasksCarryOver} carry-over). Run /builder-version-close ${s.versionId}.`
+    );
+    console.log('');
+  }
+
+  // ---------- the menu ----------
+  const matched = routingByPreference ? ` matched to ${preferred.join(' + ')}` : '';
+  const filterBits = [
+    version && `in ${version}`,
+    discipline && `discipline=${discipline}`,
+    fit && `fit=${fit}`,
+  ].filter(Boolean);
+  const filterNote = filterBits.length ? ` (${filterBits.join(', ')})` : '';
+  console.log(`**Claim one to start** — ${filtered.length} ready for you right now${matched}${filterNote}:`);
+  console.log('');
+  if (claimable.length) {
+    const cardRows = claimable.slice(0, CARD_ROWS);
+    console.log(claimableTable(cardRows));
+    const moreN = filtered.length - cardRows.length;
+    if (moreN > 0) {
+      console.log('');
+      console.log(`_…and ${moreN} more — say "show all", or run with --limit 30._`);
+    }
+  } else {
+    console.log("_Nothing claimable right now — everything is in flight, blocked, or shipped. Run /blocker-review to see what's stuck._");
+  }
+
+  // Cross-discipline pointer (one line) — only when preference-routed.
+  if (recommendations.length > 0) {
+    const ids = recommendations.map((t) => `#${t.id}`).join(', ');
+    console.log('');
+    console.log(`Outside your lanes: ${ids} — say the word to see them, or run with \`--all-disciplines\`.`);
+  } else if (routingByPreference) {
+    console.log('');
+    console.log('_Showing your lanes — run with `--all-disciplines` to see every lane._');
+  }
+
+  // ---------- next ----------
+  console.log('');
+  console.log('→ **Tell me a number** to claim it.');
+  if (full) {
+    console.log('');
+    console.log('Commands:');
+    console.log('  claim:    node scripts/gds/claim.js <task-id> [--worktree NAME]');
+    console.log('  ship:     node scripts/gds/ship.js  <task-id> --notes "..." --summary "..."');
+    console.log('  release:  node scripts/gds/release.js <task-id>');
+  }
+  };
+
+  // --hook (task 1288): a UserPromptSubmit hook can neither render UI, call
+  // show_widget, nor detect whether that tool exists — only the model can. So
+  // the hook runs THIS script and injects the finished card + a one-step
+  // directive; the model's only remaining job is to emit it. Emit BOTH forms
+  // (+ the private budget/onboarding warnings) from the single fetch above as a
+  // machine envelope; stdout carries nothing else.
+  if (hookMode) {
+    const myClaims = me.ok ? (me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : [])) : [];
+    const html = widgetsPref
+      ? renderWidget({
+        builder: me.ok ? me.data.builder : {},
+        claims: myClaims,
+        claimable: claimable.slice(0, CARD_ROWS),
+        total: filtered.length,
+        streak: me.ok ? me.data.streak : null,
+        recommendations,
+        header: { progress, recentShipped, inboxCount, blockerCount },
+        routingByPreference,
+        preferred,
+        filters: { version, discipline, fit },
+        readyToClose,
+      })
+      : null;
+    const markdown = captureLog(emitMarkdownCard).join('\n');
+    const warnings = me.ok
+      ? captureLog(() => { printOnboardingNudge(me.data); printCostWarning(me.data); printNeedsNudge(me.data); })
+      : [];
+    process.stdout.write(JSON.stringify({ widgets_enabled: widgetsPref, html, markdown, warnings }) + '\n');
+    return;
+  }
+
+  // Markdown card path — default invocation, `--full`, or `--widget` with the
+  // widgets knob off. The relay directive goes to stderr (task 1282); the card
+  // body to stdout.
+  emitCardDirective('markdown');
+  emitMarkdownCard();
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});