@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/cli/feature-list-bridge.mjs

@@ -0,0 +1,400 @@
+/**
+ * cli/feature-list-bridge.mjs
+ *
+ * F-035 (MetaHarness) — wraps `feature_list.json` with claim semantics.
+ *
+ * Source-of-truth port from
+ *   ruflo/v3/@claude-flow/cli/src/services/claim-service.ts (ClaimService,
+ *   ADR-016) — issues.ts is the CLI surface we mirror.
+ *
+ * Status state machine:
+ *   unclaimed -> claimed
+ *   claimed -> active             (start work)
+ *   active -> paused
+ *   paused -> active
+ *   active -> handoff-pending     (initiated)
+ *   handoff-pending -> claimed    (accepted by recipient)
+ *   active -> blocked             (caller marked a blocker)
+ *   blocked -> active
+ *   {claimed,active,paused,blocked,handoff-pending}
+ *                          -> completed
+ *   {claimed,active,...}   -> unclaimed (release)
+ *
+ * Steal reasons (per spec): overloaded | stale | blocked-timeout | voluntary
+ *
+ * Persistence model: we ADD the following fields on each feature entry —
+ *   claimant      : { type: 'human'|'agent', id, name }
+ *   claimStatus   : ClaimStatus
+ *   claimedAt     : ISO timestamp
+ *   claimHistory  : Array<{ event, claimant?, ts, reason? }>
+ *
+ * We MUST NOT modify the existing `vcr` / `passing` semantics of
+ * feature_list.json — claims are additive fields only.
+ *
+ * File writes are atomic via the standard `writeFileSync` to .tmp +
+ * `renameSync` pattern.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, statSync, copyFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+// ── Constants ────────────────────────────────────────────────────────
+
+export const CLAIM_STATUSES = Object.freeze([
+  'unclaimed',
+  'claimed',
+  'active',
+  'paused',
+  'handoff-pending',
+  'blocked',
+  'completed',
+]);
+
+export const STEAL_REASONS = Object.freeze([
+  'overloaded',
+  'stale',
+  'blocked-timeout',
+  'voluntary',
+]);
+
+// Transitions the bridge will allow without complaint. Anything else
+// emits a typed error.
+const ALLOWED_TRANSITIONS = {
+  unclaimed:          new Set(['claimed']),
+  claimed:            new Set(['active', 'unclaimed', 'completed', 'handoff-pending']),
+  active:             new Set(['paused', 'blocked', 'completed', 'handoff-pending', 'unclaimed']),
+  paused:             new Set(['active', 'unclaimed', 'completed']),
+  'handoff-pending':  new Set(['claimed', 'unclaimed']),
+  blocked:            new Set(['active', 'unclaimed']),
+  completed:          new Set([]),
+};
+
+// ── Errors ───────────────────────────────────────────────────────────
+
+export class ClaimError extends Error {
+  constructor(code, message) {
+    super(message || code);
+    this.name = 'ClaimError';
+    this.code = code;
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function readJsonSafe(file) {
+  try {
+    if (!existsSync(file)) return null;
+    const txt = readFileSync(file, 'utf8');
+    return JSON.parse(txt);
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonAtomic(file, data) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp.${randomUUID()}`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+  renameSync(tmp, file);
+}
+
+function appendHistory(feature, event, extra) {
+  const prev = Array.isArray(feature.claimHistory) ? feature.claimHistory : [];
+  feature.claimHistory = [...prev, { event, ts: nowIso(), ...(extra || {}) }];
+}
+
+function setClaim(feature, status, claimant, reason) {
+  feature.claimant = claimant || null;
+  feature.claimStatus = status;
+  if (status === 'claimed' || status === 'active' || status === 'paused' || status === 'handoff-pending' || status === 'blocked') {
+    if (!feature.claimedAt) feature.claimedAt = nowIso();
+  }
+  if (status === 'unclaimed' || status === 'completed') {
+    // Keep claimedAt as historical record.
+  }
+  if (reason) feature.claimReason = reason;
+}
+
+function assertStatus(s) {
+  if (!CLAIM_STATUSES.includes(s)) {
+    throw new ClaimError('UNKNOWN_STATUS', `Unknown claim status: ${s}`);
+  }
+}
+
+function assertReason(r) {
+  if (!STEAL_REASONS.includes(r)) {
+    throw new ClaimError('UNKNOWN_STEAL_REASON', `Unknown steal reason: ${r}`);
+  }
+}
+
+// ── FeatureListBridge ────────────────────────────────────────────────
+
+export class FeatureListBridge {
+  /**
+   * @param {object|string} opts Either a path string or `{ filePath, backup }`.
+   *   - filePath: path to feature_list.json (default: ./feature_list.json)
+   *   - backup  : write a .bak copy before each write (default: true)
+   */
+  constructor(opts = {}) {
+    if (typeof opts === 'string') {
+      this.filePath = resolve(opts);
+    } else {
+      this.filePath = resolve(opts.filePath || 'feature_list.json');
+      this.backup = opts.backup !== false;
+    }
+  }
+
+  /** Load the feature list from disk. Returns the parsed JSON. */
+  load() {
+    const data = readJsonSafe(this.filePath);
+    if (!data) {
+      throw new ClaimError('NO_FILE', `feature_list.json not found at ${this.filePath}`);
+    }
+    if (!Array.isArray(data.features)) {
+      throw new ClaimError('SCHEMA', 'feature_list.json missing top-level features[]');
+    }
+    return data;
+  }
+
+  /** Save + atomic temp-rename. Creates a .bak if `backup=true`. */
+  save(data, { reason = 'update' } = {}) {
+    if (this.backup && existsSync(this.filePath)) {
+      try { copyFileSync(this.filePath, `${this.filePath}.bak`); } catch { /* best-effort */ }
+    }
+    writeJsonAtomic(this.filePath, data);
+    return { ok: true, path: this.filePath, reason };
+  }
+
+  _find(data, featureId) {
+    const idx = data.features.findIndex((f) => f.id === featureId);
+    if (idx === -1) {
+      throw new ClaimError('NOT_FOUND', `Feature ${featureId} not in feature_list.json`);
+    }
+    return idx;
+  }
+
+  _getOrThrow(data, featureId) {
+    return data.features[this._find(data, featureId)];
+  }
+
+  // ── claim ─────────────────────────────────────────────────────────
+
+  /**
+   * @param {string} featureId
+   * @param {{type:'human'|'agent', id:string, name?:string}} claimant
+   * @param {string} reason
+   * @returns {{ ok: true, feature: object }}
+   */
+  claim(featureId, claimant, reason) {
+    if (!claimant || (claimant.type !== 'human' && claimant.type !== 'agent')) {
+      throw new ClaimError('BAD_CLAIMANT', 'claimant must be {type:"human"|"agent", id, name?}');
+    }
+    const data = this.load();
+    const feature = this._getOrThrow(data, featureId);
+    const prev = feature.claimant || null;
+    const prevStatus = feature.claimStatus || 'unclaimed';
+
+    if (prevStatus !== 'unclaimed' && prevStatus !== 'completed') {
+      throw new ClaimError(
+        'ALREADY_CLAIMED',
+        `Feature ${featureId} is ${prevStatus} by ${prev?.name || prev?.id || 'unknown'} — release or steal first.`,
+      );
+    }
+
+    feature.claimant = claimant;
+    feature.claimStatus = 'claimed';
+    feature.claimedAt = nowIso();
+    if (reason) feature.claimReason = reason;
+    appendHistory(feature, 'claim', { claimant, reason });
+
+    this.save(data, { reason: `claim:${featureId}` });
+    return { ok: true, feature, previousClaimant: prev };
+  }
+
+  // ── release ───────────────────────────────────────────────────────
+
+  /**
+   * @param {string} featureId
+   * @param {{id:string}} claimant   expected to match the current claimant
+   * @param {string} reason
+   */
+  release(featureId, claimant, reason) {
+    const data = this.load();
+    const feature = this._getOrThrow(data, featureId);
+    const prevStatus = feature.claimStatus || 'unclaimed';
+    if (prevStatus === 'unclaimed' || prevStatus === 'completed') {
+      throw new ClaimError(
+        'NOT_CLAIMED',
+        `Feature ${featureId} is ${prevStatus}; nothing to release.`,
+      );
+    }
+    if (claimant && feature.claimant && feature.claimant.id !== claimant.id) {
+      throw new ClaimError(
+        'WRONG_CLAIMANT',
+        `Feature ${featureId} is claimed by ${feature.claimant.name || feature.claimant.id}, not ${claimant.name || claimant.id}.`,
+      );
+    }
+    const prev = feature.claimant;
+    feature.claimStatus = 'unclaimed';
+    appendHistory(feature, 'release', { releasedBy: claimant, reason });
+    // Keep claimant for historical record (the entry's `claimHistory`
+    // captures who held it); but flip `claimant` to null so further
+    // list({status: 'claimed'}) filters don't pick it up accidentally.
+    feature.claimant = null;
+
+    this.save(data, { reason: `release:${featureId}` });
+    return { ok: true, feature, previousClaimant: prev };
+  }
+
+  // ── handoff ───────────────────────────────────────────────────────
+
+  /**
+   * Hand off the feature from one claimant to another.
+   * The recipient must be a valid claimant shape.
+   */
+  handoff(featureId, fromClaimant, toClaimant, reason) {
+    if (!toClaimant || (toClaimant.type !== 'human' && toClaimant.type !== 'agent')) {
+      throw new ClaimError('BAD_CLAIMANT', 'toClaimant must be {type:"human"|"agent", id, name?}');
+    }
+    const data = this.load();
+    const feature = this._getOrThrow(data, featureId);
+    const prevStatus = feature.claimStatus || 'unclaimed';
+    if (prevStatus === 'unclaimed' || prevStatus === 'completed') {
+      throw new ClaimError('NOT_CLAIMED', `Feature ${featureId} is ${prevStatus}; cannot handoff.`);
+    }
+    if (fromClaimant && feature.claimant && feature.claimant.id !== fromClaimant.id) {
+      throw new ClaimError(
+        'WRONG_CLAIMANT',
+        `Feature ${featureId} is held by ${feature.claimant.name || feature.claimant.id}, not ${fromClaimant.name || fromClaimant.id}.`,
+      );
+    }
+
+    appendHistory(feature, 'handoff-initiated', { from: feature.claimant, to: toClaimant, reason });
+    feature.handoffTo = toClaimant;
+    feature.claimStatus = 'handoff-pending';
+
+    // Synchronous accept per the simplest semantics — the CLI flag
+    // `bizar claim handoff` accepts immediately. An async workflow
+    // would split this into handoff-initiate + handoff-accept, but
+    // v1 keeps it atomic.
+    feature.claimant = toClaimant;
+    feature.claimStatus = 'claimed';
+    feature.claimedAt = nowIso();
+    appendHistory(feature, 'handoff-accepted', { by: toClaimant, reason });
+    delete feature.handoffTo;
+
+    this.save(data, { reason: `handoff:${featureId}` });
+    return { ok: true, feature };
+  }
+
+  // ── steal ─────────────────────────────────────────────────────────
+
+  /**
+   * Steal a feature from the current claimant. Requires a `stealReason`
+   * (one of STEAL_REASONS). Records the event in `claimHistory`.
+   */
+  steal(featureId, newClaimant, reason) {
+    assertReason(reason);
+    if (!newClaimant || (newClaimant.type !== 'human' && newClaimant.type !== 'agent')) {
+      throw new ClaimError('BAD_CLAIMANT', 'newClaimant must be {type:"human"|"agent", id, name?}');
+    }
+    const data = this.load();
+    const feature = this._getOrThrow(data, featureId);
+    const prevStatus = feature.claimStatus || 'unclaimed';
+    if (prevStatus === 'unclaimed' || prevStatus === 'completed') {
+      throw new ClaimError('NOT_CLAIMED', `Feature ${featureId} is ${prevStatus}; nothing to steal.`);
+    }
+    const prev = feature.claimant;
+    appendHistory(feature, 'steal', { stolenFrom: prev, stolenBy: newClaimant, reason });
+    feature.claimant = newClaimant;
+    feature.claimStatus = 'claimed';
+    feature.claimedAt = nowIso();
+    feature.claimReason = reason;
+
+    this.save(data, { reason: `steal:${featureId}` });
+    return { ok: true, feature, previousClaimant: prev, stealReason: reason };
+  }
+
+  // ── transition ────────────────────────────────────────────────────
+
+  /**
+   * Generic status transition (active / paused / blocked / completed).
+   * Used by the CLI to mark a claim actively-in-progress, paused,
+   * blocked, or completed.
+   */
+  transition(featureId, newStatus, claimant, reason) {
+    assertStatus(newStatus);
+    const data = this.load();
+    const feature = this._getOrThrow(data, featureId);
+    const prevStatus = feature.claimStatus || 'unclaimed';
+    if (newStatus === prevStatus) {
+      return { ok: true, feature, unchanged: true };
+    }
+    const allowed = ALLOWED_TRANSITIONS[prevStatus] || new Set();
+    if (!allowed.has(newStatus)) {
+      throw new ClaimError(
+        'BAD_TRANSITION',
+        `Cannot transition ${featureId}: ${prevStatus} → ${newStatus} not allowed.`,
+      );
+    }
+    if (claimant && feature.claimant && feature.claimant.id !== claimant.id) {
+      throw new ClaimError(
+        'WRONG_CLAIMANT',
+        `Feature ${featureId} is held by ${feature.claimant.name || feature.claimant.id}, not ${claimant.name || claimant.id}.`,
+      );
+    }
+    appendHistory(feature, 'transition', { from: prevStatus, to: newStatus, by: claimant, reason });
+    feature.claimStatus = newStatus;
+
+    this.save(data, { reason: `transition:${featureId}:${newStatus}` });
+    return { ok: true, feature };
+  }
+
+  // ── list ──────────────────────────────────────────────────────────
+
+  /**
+   * List features, optionally filtered by status or claimant.
+   * @param {{status?:string|string[], claimantId?:string}} filters
+   */
+  list(filters = {}) {
+    const data = this.load();
+    let out = data.features.slice();
+    if (filters.status) {
+      const statuses = Array.isArray(filters.status) ? filters.status : [filters.status];
+      out = out.filter((f) => statuses.includes(f.claimStatus || 'unclaimed'));
+    }
+    if (filters.claimantId) {
+      out = out.filter((f) => f.claimant && f.claimant.id === filters.claimantId);
+    }
+    if (filters.claimedByHuman != null) {
+      out = out.filter((f) => Boolean(f.claimant) === Boolean(filters.claimedByHuman) && (!f.claimant || f.claimant.type === 'human'));
+    }
+    if (filters.claimedByAgent != null) {
+      out = out.filter((f) => Boolean(f.claimant) && f.claimant.type === 'agent');
+    }
+    return out;
+  }
+
+  /** Get a single feature with its full claim history. */
+  get(featureId) {
+    const data = this.load();
+    return this._getOrThrow(data, featureId);
+  }
+}
+
+// ── Path helper ──────────────────────────────────────────────────────
+
+import { cwd } from 'node:process';
+
+/** Default path under cwd / feature_list.json. */
+export function defaultFeatureListPath() {
+  if (process.env.BIZAR_FEATURE_LIST && process.env.BIZAR_FEATURE_LIST.trim()) {
+    return resolve(process.env.BIZAR_FEATURE_LIST);
+  }
+  return join(cwd(), 'feature_list.json');
+}

package/.claude/worktrees/kanban-overhaul/cli/heads-up.mjs

@@ -0,0 +1,295 @@
+/**
+ * heads-up.mjs — `bizar heads-up` subcommand.
+ *
+ * Reads and manages .bizar/PRE_PUSH_NOTES.md — a per-project file for
+ * tracking gotchas, risks, and things-to-verify before pushing/publishing.
+ *
+ * Subcommands:
+ *   list         Print active heads-up entries
+ *   check        Exit code 0 (no blockers) or 1 (blockers found); batches
+ *                with warnings printed to stderr
+ *   archive      Move all active entries to the Resolved section
+ */
+
+import chalk from 'chalk';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Entry parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse entries from the "Active heads-ups" section of a PRE_PUSH_NOTES.md.
+ * Returns an array of { title, severity, area, affected, description,
+ * mitigation, verified, lines } objects.
+ */
+function parseActiveEntries(content) {
+  const entries = [];
+
+  // Find the Active heads-ups section. We stop at the next h2 that starts
+  // with an uppercase letter (section header like "## Resolved") but NOT
+  // at entry titles that start with a date bracket "## [YYYY-MM-DD]".
+  const activeMatch = content.match(/## Active heads-ups\n([\s\S]*?)(?=\n## [A-Z]|$)/);
+  if (!activeMatch) return entries;
+
+  const section = activeMatch[1];
+
+  // Each entry starts with "## [YYYY-MM-DD] ..."
+  const entryBlocks = section.split(/(?=^## \[)/m);
+  for (const block of entryBlocks) {
+    const trimmed = block.trim();
+    if (!trimmed || trimmed.startsWith('<!--')) continue;
+
+    const titleMatch = trimmed.match(/^##\s+(\[.+?\]\s*.+)$/m);
+    if (!titleMatch) continue;
+
+    const severityMatch = trimmed.match(/^Severity:\s*(\S+)/m);
+    const areaMatch = trimmed.match(/^Area:\s*(.+)$/m);
+    const affectedMatch = trimmed.match(/^Affected versions:\s*(.+)$/m);
+    const descMatch = trimmed.match(/^Description:\s*(.+)$/m);
+    const mitigMatch = trimmed.match(/^Mitigation:\s*(.+)$/m);
+    const verifiedMatch = trimmed.match(/^Verified:\s*(.+)$/m);
+
+    entries.push({
+      title: titleMatch[1].trim(),
+      severity: severityMatch ? severityMatch[1].trim().toLowerCase() : 'info',
+      area: areaMatch ? areaMatch[1].trim() : null,
+      affected: affectedMatch ? affectedMatch[1].trim() : null,
+      description: descMatch ? descMatch[1].trim() : null,
+      mitigation: mitigMatch ? mitigMatch[1].trim() : null,
+      verified: verifiedMatch ? verifiedMatch[1].trim() : '☐',
+      lines: trimmed,
+    });
+  }
+
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// File helpers
+// ---------------------------------------------------------------------------
+
+function readPrePushNotes(bizarDir) {
+  const file = join(bizarDir, 'PRE_PUSH_NOTES.md');
+  if (!existsSync(file)) return null;
+  return readFileSync(file, 'utf8');
+}
+
+function findBizarDir(cwd) {
+  // Walk up from cwd looking for .bizar/
+  let dir = cwd;
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(dir, '.bizar');
+    if (existsSync(candidate)) return candidate;
+    const parent = join(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Severity label helpers
+// ---------------------------------------------------------------------------
+
+function severityLabel(severity) {
+  switch (severity) {
+    case 'blocker': return chalk.bold.red('blocker');
+    case 'warning': return chalk.bold.yellow('warning');
+    case 'info':    return chalk.bold.blue('info');
+    default:        return severity;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Subcommands
+// ---------------------------------------------------------------------------
+
+/**
+ * `bizar heads-up list` — print active entries.
+ */
+async function listHeadsUps(bizarDir) {
+  const content = readPrePushNotes(bizarDir);
+  if (!content) {
+    console.log(chalk.yellow('  No .bizar/PRE_PUSH_NOTES.md found. Run `bizar init` first.'));
+    return;
+  }
+
+  const entries = parseActiveEntries(content);
+  if (entries.length === 0) {
+    console.log(chalk.green('  ✓ No active heads-ups.'));
+    return;
+  }
+
+  console.log(chalk.bold('\n  ⚠  Active heads-ups:\n'));
+  for (const entry of entries) {
+    console.log(`  ${chalk.bold(entry.title)}  ${severityLabel(entry.severity)}`);
+    if (entry.area)      console.log(`    Area:       ${entry.area}`);
+    if (entry.affected)  console.log(`    Affects:    ${entry.affected}`);
+    if (entry.description) console.log(`    ${chalk.dim(entry.description)}`);
+    if (entry.mitigation)  console.log(`    Mitigation: ${chalk.cyan(entry.mitigation)}`);
+    console.log(`    Verified:   ${entry.verified === '☑' ? chalk.green('☑') : chalk.dim('☐')}`);
+    console.log('');
+  }
+}
+
+/**
+ * `bizar heads-up check` — exit 0 if clear, 1 if blockers.
+ * Used by update/publish flows as a pre-flight gate.
+ */
+async function checkHeadsUps(bizarDir) {
+  const content = readPrePushNotes(bizarDir);
+  if (!content) {
+    // No file = no pre-push notes = clear
+    return { ok: true, blockerCount: 0, warningCount: 0, entries: [] };
+  }
+
+  const entries = parseActiveEntries(content);
+  const blockers = entries.filter((e) => e.severity === 'blocker');
+  const warnings = entries.filter((e) => e.severity === 'warning');
+
+  if (blockers.length > 0) {
+    console.error(chalk.bold.red(`\n  ✗ ${blockers.length} blocker(s) in active heads-ups:\n`));
+    for (const b of blockers) {
+      console.error(chalk.red(`    • ${b.title}`));
+      if (b.description) console.error(chalk.dim(`      ${b.description}`));
+      if (b.mitigation)  console.error(chalk.cyan(`      Fix: ${b.mitigation}`));
+      console.error('');
+    }
+  }
+  if (warnings.length > 0) {
+    console.error(chalk.yellow(`\n  ⚠ ${warnings.length} warning(s) in active heads-ups:\n`));
+    for (const w of warnings) {
+      console.error(chalk.yellow(`    • ${w.title}`));
+      if (w.description) console.error(chalk.dim(`      ${w.description}`));
+      console.error('');
+    }
+  }
+
+  return {
+    ok: blockers.length === 0,
+    blockerCount: blockers.length,
+    warningCount: warnings.length,
+    entries,
+  };
+}
+
+/**
+ * `bizar heads-up archive` — move all active entries to the Resolved section.
+ */
+async function archiveHeadsUps(bizarDir) {
+  const file = join(bizarDir, 'PRE_PUSH_NOTES.md');
+  const content = readPrePushNotes(bizarDir);
+  if (!content) {
+    console.log(chalk.yellow('  No .bizar/PRE_PUSH_NOTES.md found. Nothing to archive.'));
+    return;
+  }
+
+  const entries = parseActiveEntries(content);
+  if (entries.length === 0) {
+    console.log(chalk.dim('  No active entries to archive.'));
+    return;
+  }
+
+  // Build resolved entries block (with indented detail lines for readability)
+  const today = new Date().toISOString().slice(0, 10);
+  const newResolvedEntries = entries
+    .map((e) => {
+      const lines = e.lines.split('\n');
+      const header = lines[0];
+      const body = lines.slice(1).map((l) => `  ${l}`).join('\n');
+      return `${header}\n${body}`;
+    })
+    .join('\n\n');
+
+  // Clean the Active section — strip entries, keep header + comment
+  const cleanActive = '## Active heads-ups\n\n<!--\n  Entries archived. See "Resolved" below.\n-->\n';
+
+  let newContent;
+
+  // Check if a "## Resolved" section already exists
+  const resolvedMatch = content.match(/## Resolved[\s\S]*$/);
+  if (resolvedMatch) {
+    // Remove active entries from the Active section
+    newContent = content.replace(/## Active heads-ups[\s\S]*?(?=\n## Resolved|$)/, cleanActive);
+
+    // Prepend new resolved entries into the existing Resolved section,
+    // right after the header (first line "## Resolved").
+    const oldResolved = resolvedMatch[0];
+    const firstNewlineAfterHeader = oldResolved.indexOf('\n');
+    const prefix = oldResolved.slice(0, firstNewlineAfterHeader + 1); // "## Resolved\n"
+    const suffix = oldResolved.slice(firstNewlineAfterHeader + 1);    // everything after
+
+    const updatedResolved = `${prefix}<!-- Resolved on ${today} -->\n\n${newResolvedEntries}\n\n${suffix.trimStart()}\n`;
+
+    newContent = newContent.replace(resolvedMatch[0], updatedResolved);
+  } else {
+    // No existing Resolved section — replace Active section and append Resolved
+    newContent = content.replace(/## Active heads-ups[\s\S]*?(?=\n## |$)/, cleanActive);
+    const resolvedSection = `## Resolved\n\n<!-- Resolved on ${today} -->\n\n${newResolvedEntries}\n`;
+    newContent = `${newContent.trim()}\n\n${resolvedSection}\n`;
+  }
+
+  writeFileSync(file, newContent);
+  console.log(chalk.green(`  ✓ Archived ${entries.length} heads-up(s) to Resolved section.`));
+}
+
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+
+function showHeadsUpHelp() {
+  console.log(`
+  bizar heads-up — Manage pre-push / pre-release heads-ups
+
+  Usage:
+    bizar heads-up list       Show active heads-up entries
+    bizar heads-up check      Exit 0 if no blockers, 1 if blockers exist
+    bizar heads-up archive    Move all active entries to Resolved
+
+  Description:
+    Reads .bizar/PRE_PUSH_NOTES.md in the current (or nearest parent)
+    project. The file is created automatically by \`bizar init\`.
+
+    Add entries as agent-discovered gotchas before pushing or publishing.
+    The \`check\` subcommand is invoked automatically by \`bizar update\`
+    to gate pushes when unresolved blockers exist.
+  `);
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function runHeadsUp(sub, args = []) {
+  const bizarDir = findBizarDir(process.cwd());
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    showHeadsUpHelp();
+    return;
+  }
+
+  if (!bizarDir) {
+    console.log(chalk.yellow('  No .bizar/ directory found in this project.'));
+    console.log(chalk.dim('  Run `bizar init` to create one.'));
+    process.exit(1);
+  }
+
+  if (sub === 'list') {
+    await listHeadsUps(bizarDir);
+  } else if (sub === 'check') {
+    const result = await checkHeadsUps(bizarDir);
+    if (!result.ok) process.exit(1);
+    console.log(chalk.green('  ✓ No active blocker heads-ups.'));
+  } else if (sub === 'archive') {
+    await archiveHeadsUps(bizarDir);
+  } else {
+    console.error(chalk.red(`  ✗ Unknown heads-up subcommand: ${sub}`));
+    showHeadsUpHelp();
+    process.exit(1);
+  }
+}
+
+// Also export utilities so update.mjs and other commands can import them
+export { checkHeadsUps, parseActiveEntries, findBizarDir, readPrePushNotes };