beadcyte 0.4.0

package/src/cli.mjs

@@ -0,0 +1,577 @@
+#!/usr/bin/env node
+// beadcyte — single-SVG Gantt of bead history + projected future.
+//
+// Past bars: real `started_at → closed_at` for shipped beads (colored by
+// outcome). Future bars: greedy WIP-cap scheduler (src/scheduler.mjs) using a
+// historical-median duration estimator (src/estimator.mjs). Grouping default:
+// parent epic (unparented → "no epic" swimlane at bottom). Non-spec:ready
+// backlog is drawn faint; a bar whose assignee the scheduler inferred is
+// diagonal-hatched — the same vocabulary as the interactive Gantt.
+//
+//   beadcyte --out /tmp/gantt.svg
+//   beadcyte --from -60d --to +60d --group-by assignee
+//   beadcyte --roster ./roster.json                    # per-project WIP caps + affinities
+//   beadcyte --roster ./.beadcyte/roster.json          # conventional default
+//
+// Deliberately zero runtime deps beyond node + `bd`. Reads the CWD's beads DB
+// via `bd list --all --limit 0 --json` — run from any beads project.
+
+import { readFileSync } from "node:fs";
+import { writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { buildEstimator } from "./estimator.mjs";
+import { resolveRosterPath, ROSTER_CANDIDATES } from "./roster-path.mjs";
+import { scheduleGreedy } from "./scheduler.mjs";
+import { stageWaits } from "./stage-waits.mjs";
+import { isShipped } from "./ship.mjs";
+import { formatDays } from "./format.mjs";
+import { computeVelocity, calibrateRoster } from "./velocity.mjs";
+
+// ── args ──────────────────────────────────────────────────────────────────
+const args = parseArgs(process.argv.slice(2));
+if (args.help || args.h) {
+  printHelp();
+  process.exit(0);
+}
+const fromDays = parseRelDays(args.from ?? "-90d");
+const toDays = parseRelDays(args.to ?? "+90d");
+const groupBy = args["group-by"] ?? "epic";
+const includeDeferred = args["include-deferred"] === "true";
+const maxPerGroup = parseInt(args["max-per-group"] ?? "20", 10);
+const outPath = args.out ?? "./beadcyte.svg";
+const rosterPath = args.roster;
+const velocityLookback = parseInt(args["velocity-lookback"] ?? "60", 10);
+const noCalibrate = args["no-calibrate"] === "true";
+
+const today = startOfDay(new Date());
+const t0 = addDays(today, fromDays);
+const t1 = addDays(today, toDays);
+const totalDays = daysBetween(t0, t1);
+
+// ── data ──────────────────────────────────────────────────────────────────
+console.error("[beadcyte] loading beads…");
+const beads = JSON.parse(
+  execSync("bd list --all --limit 0 --json", {
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+  }),
+);
+console.error(`[beadcyte] loaded ${beads.length} beads`);
+
+// Roster (per-project WIP caps + affinities). Conventional path is
+// `./.beadcyte/roster.json`, override with `--roster`. Shape:
+//   {
+//     "cap": 5,                                   // default cap for humans
+//     "humans": [
+//       { "handle": "alice", "cap": 3,
+//         "labels": ["component::backend"],       // exact-match label affinities
+//         "areas":  ["schema", "sql", "backend"]  // fuzzy title/label keyword affinities
+//       },
+//       ...
+//     ]
+//   }
+// If missing, every real assignee-string on a bead becomes a human with the
+// default cap and no affinities — the model still runs, just with no synthetic
+// pool routing.
+let roster = { humans: [], cap: 5 };
+const foundRoster = resolveRosterPath(process.cwd(), rosterPath);
+if (foundRoster) {
+  roster = JSON.parse(readFileSync(foundRoster.path, "utf8"));
+} else {
+  if (rosterPath) {
+    console.error(
+      `[beadcyte] --roster ${rosterPath} does not exist; deriving from beads`,
+    );
+  }
+  const seen = new Set();
+  for (const b of beads) if (b.assignee) seen.add(b.assignee);
+  roster.humans = [...seen].map((handle) => ({ handle }));
+  console.error(
+    `[beadcyte] no roster at ${ROSTER_CANDIDATES.join(" or ")}; derived ` +
+      `${roster.humans.length} humans from beads (default cap ${roster.cap})`,
+  );
+}
+
+// Build estimator from shipped history — we need its median cycle time
+// for the Little's-Law calibration below, so build it first.
+const { estimate, stats } = buildEstimator(beads);
+
+// Reality calibration — measure per-human throughput over the last N days
+// (default 60) and clamp each human's WIP cap using Little's Law
+// (WIP = throughput × cycle time). Without this the projection assumes
+// everyone runs at max WIP forever, which turns 4 devs × cap 5 into 20
+// simultaneous in-flight beads even when the team ships ~10/month.
+// --no-calibrate skips this for brand-new projects with no ship history.
+const velocity = computeVelocity(beads, { lookbackDays: velocityLookback });
+const rawRoster = roster;
+if (!noCalibrate) {
+  roster = calibrateRoster(rawRoster, velocity, {
+    medianCycleDays: stats.median_lead_days || stats.global_median_days,
+  });
+  const nudges = roster.humans
+    .filter((h) => h._rawCap !== h.cap)
+    .map((h) => `${h.handle}=${h._rawCap}→${h.cap}`);
+  if (nudges.length) {
+    console.error(
+      `[beadcyte] calibration (${velocityLookback}d, ${velocity.totalClosedInWindow} ships, lead ${formatDays(stats.median_lead_days)}): ${nudges.join(", ")}`,
+    );
+  }
+}
+
+// Schedule the future
+const { schedule, unscheduled, unassignedBacklog, unassignedProjection } =
+  scheduleGreedy(beads, roster, estimate, t1, {
+    waits: stageWaits(beads),
+    minLeadDays: stats.median_lead_days || 0,
+  });
+
+// Merge projections into the primary schedule map for uniform lookup
+for (const [id, s] of unassignedProjection) {
+  if (!schedule.has(id)) schedule.set(id, s);
+}
+
+// ── grouping ──────────────────────────────────────────────────────────────
+const byId = new Map(beads.map((b) => [b.id, b]));
+const groupFor = (b) => {
+  if (groupBy === "epic") return b.parent || "__no_epic";
+  if (groupBy === "assignee") {
+    if (b.assignee) return b.assignee;
+    const s = schedule.get(b.id);
+    if (s?.assignee) return s.assignee; // synthetic dispatch lands here
+    return "__unassigned";
+  }
+  if (groupBy === "seat") {
+    const s = (b.labels ?? []).find((l) => l.startsWith("seat::"));
+    return s ?? "__no_seat";
+  }
+  if (groupBy === "track") {
+    const t = (b.labels ?? []).find((l) => l.startsWith("track::"));
+    return t ?? "__no_track";
+  }
+  return "__all";
+};
+
+// Filter to what actually appears in the window
+const visible = [];
+for (const b of beads) {
+  if (b.status === "deferred" && !includeDeferred) continue;
+  if (b.issue_type === "epic") continue; // epics are group headers, not rows
+
+  // Past: closed and closed_at within window
+  if (b.status === "closed") {
+    if (!b.closed_at) continue;
+    const closedDay = daysBetween(t0, new Date(b.closed_at));
+    if (closedDay < 0 || closedDay > totalDays) continue;
+    visible.push(b);
+    continue;
+  }
+  // Future: has a schedule entry, in-window
+  const sched = schedule.get(b.id);
+  if (sched) {
+    const s = daysBetween(t0, today) + sched.start_day;
+    const e = daysBetween(t0, today) + sched.end_day;
+    if (e < 0 || s > totalDays) continue;
+    visible.push(b);
+    continue;
+  }
+  // Unscheduled but still "in the future queue" — belongs on the unassigned
+  // backlog rail if we're rendering that
+  if (unscheduled.includes(b.id) || unassignedBacklog.includes(b)) {
+    // Show them stacked at horizon end (no schedule guess)
+    visible.push(b);
+  }
+}
+
+// Group visible beads
+const groups = new Map();
+for (const b of visible) {
+  const g = groupFor(b);
+  if (!groups.has(g)) groups.set(g, []);
+  groups.get(g).push(b);
+}
+// Sort groups: real epics first (by id creation order, then no_epic last)
+const groupOrder = [...groups.keys()].sort((a, b) => {
+  const aFake = a.startsWith("__");
+  const bFake = b.startsWith("__");
+  if (aFake !== bFake) return aFake ? 1 : -1;
+  return a.localeCompare(b);
+});
+// Sort within group: by start day, then priority
+const startDayOf = (b) => {
+  if (b.status === "closed") return daysBetween(t0, new Date(b.started_at ?? b.closed_at));
+  const s = schedule.get(b.id);
+  if (s) return daysBetween(t0, today) + s.start_day;
+  return totalDays + 999; // unscheduled → far right
+};
+for (const arr of groups.values()) {
+  arr.sort((a, b) => startDayOf(a) - startDayOf(b) || (a.priority ?? 4) - (b.priority ?? 4));
+}
+// Cap rows per group. Prefer keeping: in-flight + shipped-in-window +
+// spec:ready future, drop backlog-tail if we overflow. Records the drop count
+// per group for a "+N more" indicator.
+const truncatedBy = new Map();
+for (const [g, arr] of groups) {
+  if (arr.length <= maxPerGroup) continue;
+  // Priority: past-shipped in window > in-flight > spec:ready > backlog
+  const rank = (b) => {
+    if (b.status === "closed") return 0;
+    if (b.status === "in_progress" || b.status === "in_review") return 1;
+    if ((b.labels ?? []).includes("spec:ready")) return 2;
+    return 3;
+  };
+  arr.sort((a, b) => rank(a) - rank(b) || startDayOf(a) - startDayOf(b));
+  const kept = arr.slice(0, maxPerGroup);
+  truncatedBy.set(g, arr.length - maxPerGroup);
+  // Re-sort kept by time for display
+  kept.sort((a, b) => startDayOf(a) - startDayOf(b) || (a.priority ?? 4) - (b.priority ?? 4));
+  groups.set(g, kept);
+}
+
+// ── layout constants ──────────────────────────────────────────────────────
+const PX_PER_DAY = 7;
+const LEFT_COL = 340;
+const RIGHT_PAD = 24;
+const ROW_H = 20;
+const GROUP_H = 26;
+const HEADER_H = 56;
+const LEGEND_H = 120;
+const PLOT_W = totalDays * PX_PER_DAY;
+const TOTAL_W = LEFT_COL + PLOT_W + RIGHT_PAD;
+
+let plotBodyH = 0;
+for (const g of groupOrder) plotBodyH += GROUP_H + groups.get(g).length * ROW_H + 6;
+const TOTAL_H = HEADER_H + plotBodyH + LEGEND_H;
+
+// ── colors ────────────────────────────────────────────────────────────────
+const C = {
+  bg: "#0b1220",
+  panel: "#111a2b",
+  gridWeak: "#1f2a44",
+  gridStrong: "#334366",
+  text: "#e5e7eb",
+  textDim: "#94a3b8",
+  today: "#ef4444",
+  shipped: "#4ade80",
+  shippedStroke: "#166534",
+  closedNoShip: "#64748b",
+  inProgress: "#60a5fa",
+  inReview: "#fbbf24",
+  blocked: "#f87171",
+  future: "#a78bfa",
+  epicHeader: "#c084fc",
+};
+
+// ── SVG builder ───────────────────────────────────────────────────────────
+const parts = [];
+const svgOpen = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${TOTAL_W} ${TOTAL_H}" width="${TOTAL_W}" height="${TOTAL_H}" font-family="ui-sans-serif,-apple-system,Segoe UI,Roboto,sans-serif" font-size="11">`;
+parts.push(svgOpen);
+
+// Defs: diagonal hatch for a synthetic assignee + subtle stripe for
+// in_progress. The hatch is stripes of the future colour with nothing between
+// them, so a bar takes its opacity exactly as a flat fill would and a hatched
+// backlog bar is a faint hatch, not a different colour.
+parts.push(`<defs>
+  <pattern id="hatch" width="6" height="6" patternUnits="userSpaceOnUse" patternTransform="rotate(45)">
+    <rect width="3" height="6" fill="${C.future}"/>
+  </pattern>
+  <pattern id="live" width="8" height="8" patternUnits="userSpaceOnUse" patternTransform="rotate(45)">
+    <rect width="8" height="8" fill="${C.inProgress}"/>
+    <line x1="0" y1="0" x2="0" y2="8" stroke="#93c5fd" stroke-width="2"/>
+  </pattern>
+</defs>`);
+
+// Background
+parts.push(`<rect width="${TOTAL_W}" height="${TOTAL_H}" fill="${C.bg}"/>`);
+parts.push(`<rect x="${LEFT_COL}" y="${HEADER_H}" width="${PLOT_W}" height="${plotBodyH}" fill="${C.panel}"/>`);
+
+// Header: title + date axis
+parts.push(`<text x="16" y="22" fill="${C.text}" font-size="14" font-weight="600">Beads timeline · ${fmtDate(t0)} → ${fmtDate(t1)}</text>`);
+parts.push(`<text x="16" y="40" fill="${C.textDim}">group by ${groupBy} · ${visible.length} beads in window · generated ${fmtDate(today)}</text>`);
+
+// Date grid + week/month ticks
+const weekMs = 7 * 86_400_000;
+for (let d = 0; d <= totalDays; d++) {
+  const x = LEFT_COL + d * PX_PER_DAY;
+  const date = addDays(t0, d);
+  const isMonthStart = date.getDate() === 1;
+  const isWeekStart = date.getDay() === 1;
+  if (isMonthStart) {
+    parts.push(`<line x1="${x}" y1="${HEADER_H}" x2="${x}" y2="${HEADER_H + plotBodyH}" stroke="${C.gridStrong}" stroke-width="1"/>`);
+    parts.push(`<text x="${x + 3}" y="${HEADER_H - 4}" fill="${C.text}" font-size="10" font-weight="600">${fmtMonth(date)}</text>`);
+  } else if (isWeekStart) {
+    parts.push(`<line x1="${x}" y1="${HEADER_H}" x2="${x}" y2="${HEADER_H + plotBodyH}" stroke="${C.gridWeak}" stroke-width="0.5"/>`);
+  }
+}
+
+// Today marker
+const todayX = LEFT_COL + daysBetween(t0, today) * PX_PER_DAY;
+parts.push(`<line x1="${todayX}" y1="${HEADER_H}" x2="${todayX}" y2="${HEADER_H + plotBodyH}" stroke="${C.today}" stroke-width="1.5" stroke-dasharray="3,3"/>`);
+parts.push(`<text x="${todayX + 4}" y="${HEADER_H - 42}" fill="${C.today}" font-size="10" font-weight="600">TODAY</text>`);
+
+// Rows
+let y = HEADER_H + 4;
+for (const g of groupOrder) {
+  const items = groups.get(g);
+  const epicBead = byId.get(g);
+  const label =
+    g === "__no_epic"
+      ? "(no epic)"
+      : g === "__unassigned"
+        ? "(unassigned)"
+        : g === "__no_seat"
+          ? "(no seat)"
+          : g === "__no_track"
+            ? "(no track)"
+            : epicBead
+              ? `${g} · ${trunc(epicBead.title, 44)}`
+              : g;
+
+  // Group header stripe
+  parts.push(`<rect x="0" y="${y}" width="${TOTAL_W}" height="${GROUP_H}" fill="${C.gridWeak}" opacity="0.4"/>`);
+  parts.push(`<text x="10" y="${y + 17}" fill="${C.epicHeader}" font-size="12" font-weight="600">${escapeXml(label)}</text>`);
+  const dropped = truncatedBy.get(g) ?? 0;
+  const countLabel = dropped
+    ? `${items.length} shown · ${dropped} more hidden`
+    : `${items.length} bead${items.length === 1 ? "" : "s"}`;
+  parts.push(`<text x="${TOTAL_W - RIGHT_PAD}" y="${y + 17}" fill="${C.textDim}" font-size="10" text-anchor="end">${countLabel}</text>`);
+  y += GROUP_H;
+
+  for (const b of items) {
+    const rowY = y;
+    y += ROW_H;
+
+    // Left label
+    const idText = b.id;
+    const title = trunc(b.title, 38);
+    const prio = b.priority ?? 4;
+    parts.push(`<text x="18" y="${rowY + 14}" fill="${C.textDim}" font-size="10" font-family="ui-monospace,monospace">${escapeXml(idText)}</text>`);
+    parts.push(`<text x="112" y="${rowY + 14}" fill="${C.text}" font-size="11">${escapeXml(title)}</text>`);
+    parts.push(`<text x="${LEFT_COL - 8}" y="${rowY + 14}" fill="${C.textDim}" font-size="9" text-anchor="end">P${prio}</text>`);
+
+    // Bar(s)
+    const bars = barsFor(b, schedule, t0, today, totalDays);
+    for (const bar of bars) {
+      const x = LEFT_COL + bar.startDay * PX_PER_DAY;
+      const w = Math.max(2, (bar.endDay - bar.startDay) * PX_PER_DAY);
+      const barY = rowY + 4;
+      const barH = ROW_H - 8;
+      const fill = bar.fill;
+      const stroke = bar.stroke ?? "none";
+      const opacity = bar.opacity ?? 1;
+      const dashAttr = bar.strokeDash ? ` stroke-dasharray="${bar.strokeDash}"` : "";
+      parts.push(`<rect x="${x}" y="${barY}" width="${w}" height="${barH}" fill="${fill}" stroke="${stroke}" stroke-width="0.75"${dashAttr} opacity="${opacity}" rx="2"/>`);
+      if (bar.marker === "ship") {
+        parts.push(`<circle cx="${x + w}" cy="${barY + barH / 2}" r="3" fill="${C.shipped}" stroke="#052e16" stroke-width="1"/>`);
+      }
+    }
+  }
+  y += 6;
+}
+
+// Legend
+const legY = HEADER_H + plotBodyH + 20;
+parts.push(`<text x="16" y="${legY}" fill="${C.text}" font-size="12" font-weight="600">Legend</text>`);
+const legendItems = [
+  { fill: C.shipped, label: "shipped (past)" },
+  { fill: C.closedNoShip, label: "closed w/o ship" },
+  { fill: "url(#live)", label: "in progress today" },
+  { fill: C.inReview, label: "in review" },
+  { fill: C.future, label: "future · spec:ready" },
+  { fill: C.future, label: "future · backlog (faint)", opacity: 0.35 },
+  { fill: "url(#hatch)", label: "synthetic assignee (hatched)" },
+  { fill: C.blocked, label: "blocked" },
+];
+legendItems.forEach((it, i) => {
+  const lx = 16 + (i % 4) * 200;
+  const ly = legY + 14 + Math.floor(i / 4) * 20;
+  const dash = it.strokeDash ? ` stroke-dasharray="${it.strokeDash}"` : "";
+  const op = it.opacity != null ? ` opacity="${it.opacity}"` : "";
+  const stroke = it.stroke ?? "#333";
+  parts.push(`<rect x="${lx}" y="${ly}" width="16" height="12" fill="${it.fill}" stroke="${stroke}" stroke-width="1"${dash}${op} rx="2"/>`);
+  parts.push(`<text x="${lx + 22}" y="${ly + 10}" fill="${C.textDim}" font-size="11">${it.label}</text>`);
+});
+
+// Model footer
+const footerY = legY + 60;
+const modelLine =
+  `estimator: median of last ${stats.shipped_sample_size} shipped beads (with ship metadata); ` +
+  `bucketed (type,priority) for ${stats.used_type_pri}, fell back (type) for ${stats.used_type}, ` +
+  `global for ${stats.used_global}. Global median = ${formatDays(stats.global_median_days)}, ` +
+  `p90 = ${formatDays(stats.global_p90_days)}.`;
+parts.push(`<text x="16" y="${footerY}" fill="${C.textDim}" font-size="10">${escapeXml(modelLine)}</text>`);
+// Roster line names each human's calibrated cap alongside their raw cap
+// (parenthesized) + observed weekly rate, so the reader can see how the
+// projection was calibrated against reality.
+const humanBlurbs = (roster.humans ?? []).map((h) => {
+  const cap = h.cap ?? roster.cap ?? 5;
+  if (h._rawCap !== undefined && h._rawCap !== cap) {
+    return `${h.handle}=${cap} (raw ${h._rawCap}, ${h._closesPerWeek.toFixed(1)}/wk)`;
+  }
+  if (h._closesPerWeek > 0) return `${h.handle}=${cap} (${h._closesPerWeek.toFixed(1)}/wk)`;
+  return `${h.handle}=${cap}`;
+});
+const calibrationHint = noCalibrate
+  ? "calibration OFF"
+  : `calibrated to last ${velocityLookback}d (${velocity.totalClosedInWindow} ships, ${velocity.activeCount} active)`;
+parts.push(`<text x="16" y="${footerY + 14}" fill="${C.textDim}" font-size="10">scheduler: greedy WIP-cap · ${calibrationHint} · ${humanBlurbs.join(", ")}. Deps: blocks-edges; spec:ready gates dispatch.</text>`);
+parts.push(`<text x="16" y="${footerY + 28}" fill="${C.textDim}" font-size="10">${unscheduled.length} beads not scheduled within window (blocked, no assignee, or past horizon).</text>`);
+
+parts.push(`</svg>`);
+writeFileSync(outPath, parts.join("\n"));
+console.error(`[beadcyte] wrote ${outPath} (${(parts.join("").length / 1024).toFixed(1)} KB)`);
+console.error(`[beadcyte] estimator: type-pri=${stats.used_type_pri}, type=${stats.used_type}, global=${stats.used_global}`);
+console.error(`[beadcyte] unscheduled: ${unscheduled.length}`);
+
+// ── helpers ───────────────────────────────────────────────────────────────
+function barsFor(b, schedule, t0, today, totalDays) {
+  if (b.status === "closed") {
+    // Past bar. `started_at` is often minutes before `closed_at` (bd close
+    // right after claim), so enforce a minimum visual duration of 1 day —
+    // the bar is a rendering hint, the ship marker is the truth.
+    const start = b.started_at ? new Date(b.started_at) : new Date(b.closed_at);
+    const end = new Date(b.closed_at);
+    const s = daysBetween(t0, start);
+    const eRaw = daysBetween(t0, end);
+    const e = Math.max(eRaw, s + 1); // min 1-day bar
+    const sc = clamp(s, 0, totalDays);
+    const ec = clamp(e, 0, totalDays);
+    const shipped = isShipped(b);
+    return [
+      {
+        startDay: sc,
+        endDay: Math.max(ec, sc + 0.5),
+        fill: shipped ? C.shipped : C.closedNoShip,
+        stroke: shipped ? C.shippedStroke : "none",
+        marker: shipped ? "ship" : null,
+        opacity: shipped ? 0.95 : 0.5,
+      },
+    ];
+  }
+  const sched = schedule.get(b.id);
+  if (sched) {
+    const todayDay = daysBetween(t0, today);
+    // Unassigned projections use absolute day indices (from today); regular
+    // schedule entries use relative to today. Detect by presence of `unassigned`.
+    const relToday = sched.unassigned ? todayDay : todayDay;
+    const startDay = clamp(relToday + sched.start_day, 0, totalDays);
+    const endDay = clamp(relToday + sched.end_day, 0, totalDays);
+    const bars = [];
+    // Same vocabulary as the interactive Gantt (BeadsGantt.vue): backlog is
+    // faint, an inferred assignee is hatched, and the two compose — a
+    // hatched backlog bar is a faint hatch. The dashed stroke this replaces
+    // was the epic colour on the future colour, a few degrees of hue apart
+    // on a 12px bar, and read as nothing.
+    const fill = sched.synthetic_assignee ? "url(#hatch)" : C.future;
+
+    if (sched.in_progress_at_start && startDay < todayDay) {
+      bars.push({
+        startDay,
+        endDay: todayDay,
+        fill: "url(#live)",
+      });
+      bars.push({
+        startDay: todayDay,
+        endDay: Math.max(endDay, todayDay + 0.5),
+        fill,
+        opacity: sched.backlog ? 0.35 : 0.75,
+      });
+    } else {
+      bars.push({
+        startDay,
+        endDay: Math.max(endDay, startDay + 0.5),
+        fill,
+        opacity: sched.backlog ? 0.35 : sched.unassigned ? 0.45 : 0.85,
+        stroke: sched.unassigned ? "#4c1d95" : "none",
+      });
+    }
+    return bars;
+  }
+  return [];
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const k = a.slice(2);
+    const v = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+    out[k] = v;
+  }
+  return out;
+}
+function parseRelDays(s) {
+  const m = String(s).match(/^([+-]?\d+)d$/);
+  if (!m) throw new Error(`bad --from/--to: ${s} (want e.g. -90d, +30d)`);
+  return parseInt(m[1], 10);
+}
+function startOfDay(d) {
+  const x = new Date(d);
+  x.setHours(0, 0, 0, 0);
+  return x;
+}
+function addDays(d, n) {
+  const x = new Date(d);
+  x.setDate(x.getDate() + n);
+  return startOfDay(x);
+}
+function daysBetween(a, b) {
+  return Math.round((b.getTime() - a.getTime()) / 86_400_000);
+}
+function clamp(v, lo, hi) {
+  return Math.max(lo, Math.min(hi, v));
+}
+function fmtDate(d) {
+  return d.toISOString().slice(0, 10);
+}
+function fmtMonth(d) {
+  return d.toLocaleDateString("en-US", { month: "short", year: "2-digit" });
+}
+function trunc(s, n) {
+  if (!s) return "";
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}
+function escapeXml(s) {
+  return String(s ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function printHelp() {
+  console.log(`beadcyte — Gantt of bead history + projected future
+
+Usage:
+  beadcyte [--from -Nd] [--to +Nd] [--group-by MODE] [--out PATH] [flags]
+
+Runs against the beads DB in the CURRENT WORKING DIRECTORY (bd list --all).
+Emits a single self-contained SVG.
+
+Flags:
+  --from -Nd              Window start relative to today (default: -90d)
+  --to   +Nd              Window end   relative to today (default: +90d)
+  --group-by MODE         epic (default) | assignee | seat | track
+  --max-per-group N       Rows per swimlane before truncation (default: 20)
+  --include-deferred      Include status=deferred beads (default: false)
+  --roster PATH           Per-project WIP caps + affinities
+                          (default: .beadcyte/roster.json)
+  --velocity-lookback N   Days of history for close-rate calibration
+                          (default: 60)
+  --no-calibrate          Skip calibration — trust raw WIP caps as-is
+                          (useful for brand-new projects with no shipped
+                          history yet)
+  --out PATH              SVG output path (default: ./beads-gantt.svg)
+  -h, --help              This message
+
+Roster JSON shape:
+  { "cap": 5, "humans": [
+      { "handle": "alice", "cap": 3,
+        "labels": ["component::backend"],
+        "areas":  ["schema", "sql", "backend"] } ] }
+
+If no roster file exists, one is derived from bead assignees at the default cap.
+`);
+}