@poa-box/agent 0.1.0

package/dist/lib/brain-projections.js

@@ -0,0 +1,829 @@
+"use strict";
+/**
+ * Brain projections — pure functions that render an Automerge brain doc
+ * (as a plain JS object) to human-readable markdown.
+ *
+ * Called by `pop brain snapshot --doc <id>` and by the heartbeat skill
+ * at end of heartbeat. The output is a .generated.md file that lives
+ * alongside the hand-written brain knowledge files; step 8 of the plan
+ * is when the hand-written files are retired and the projection becomes
+ * the source of truth.
+ *
+ * ## Design notes
+ *
+ * - **Pure functions only.** No I/O, no CLI state, no Date.now(). Makes
+ *   them trivially testable and idempotent: same input → byte-identical
+ *   output.
+ *
+ * - **Schema-tolerant.** The current pop.brain.shared schema stores a
+ *   `lessons` list. Older revisions may use `rules` / `operatingConstraints` /
+ *   `orgState`. The projection renders whichever of those fields exist,
+ *   in a canonical order, and falls back to a JSON dump for any
+ *   unrecognized fields so future schema changes don't silently drop data.
+ *
+ * - **Top-of-file banner.** Every generated file starts with a
+ *   DO-NOT-HAND-EDIT banner so reviewers can spot a hand-edit in a diff.
+ *
+ * - **Stable field ordering.** Lessons (and other lists) are rendered in
+ *   index order. If we later want time-sorted output, sort by timestamp
+ *   inside the renderer — do NOT sort by ID (the CRDT list order is
+ *   already deterministic across replicas thanks to Automerge).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectShared = projectShared;
+exports.projectProjects = projectProjects;
+exports.projectRetros = projectRetros;
+exports.projectBrainstorms = projectBrainstorms;
+exports.projectForDoc = projectForDoc;
+const GENERATED_BANNER = '# GENERATED BY `pop brain snapshot` — DO NOT HAND-EDIT\n' +
+    '<!-- Source of truth: Automerge CRDT doc in ~/.pop-agent/brain/helia-blocks -->\n' +
+    '<!-- Edits to this file will be overwritten on the next `pop brain snapshot` run. -->\n';
+/**
+ * Render one lesson as a markdown block.
+ * Lessons have inconsistent field naming historically (text vs body,
+ * title vs none) — prefer title for the header, body/text for the
+ * content, fall back to JSON if neither exists.
+ */
+/**
+ * Format a timestamp value that may be a unix-seconds number, a unix-millis
+ * number, or an already-formatted ISO string. Returns null if the value
+ * can't be coerced — callers skip the field rather than crash. This is
+ * the schema-tolerant principle applied to the timestamp field: agents
+ * have historically written `timestamp` as both numeric and ISO-string,
+ * and the projector must not crash on either.
+ */
+function formatTimestamp(ts) {
+    if (ts == null)
+        return null;
+    if (typeof ts === 'string') {
+        // Assume already-formatted ISO; validate by round-tripping.
+        const parsed = new Date(ts);
+        return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+    }
+    if (typeof ts === 'number' && Number.isFinite(ts)) {
+        // Heuristic: < 1e12 means unix seconds (≤ year 33658); else millis.
+        const ms = ts < 1e12 ? ts * 1000 : ts;
+        const parsed = new Date(ms);
+        return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+    }
+    return null;
+}
+function renderLesson(lesson, index) {
+    const header = lesson.title || lesson.id || `Lesson ${index + 1}`;
+    const body = lesson.body ?? lesson.text ?? '';
+    const meta = [];
+    if (lesson.author)
+        meta.push(`author: ${lesson.author}`);
+    const iso = formatTimestamp(lesson.timestamp ?? lesson.ts);
+    if (iso)
+        meta.push(`at: ${iso}`);
+    if (lesson.id)
+        meta.push(`id: ${lesson.id}`);
+    const lines = [];
+    lines.push(`### ${header}`);
+    if (meta.length > 0)
+        lines.push(`*${meta.join(' · ')}*`);
+    lines.push('');
+    if (body) {
+        lines.push(String(body));
+    }
+    else {
+        // No body — dump the raw JSON so nothing is silently lost.
+        lines.push('```json');
+        lines.push(JSON.stringify(lesson, null, 2));
+        lines.push('```');
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function renderRule(rule, index) {
+    const lines = [];
+    const header = rule.id || `Rule ${index + 1}`;
+    lines.push(`- **${header}** — ${rule.text ?? JSON.stringify(rule)}`);
+    const meta = [];
+    if (rule.author)
+        meta.push(`author: ${rule.author}`);
+    const iso = formatTimestamp(rule.timestamp ?? rule.ts);
+    if (iso)
+        meta.push(`at: ${iso}`);
+    if (meta.length > 0) {
+        lines.push(`  *${meta.join(' · ')}*`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Project a pop.brain.shared doc to markdown.
+ *
+ * Pure function — given the same input JS object, returns the exact
+ * same string every time. No Date.now(), no environment reads, no I/O.
+ *
+ * @param doc      The Automerge doc as a plain JS object (from Automerge.toJS)
+ * @param headCid  Optional head CID to include in the header for traceability
+ */
+function projectShared(doc, headCid = null) {
+    const parts = [];
+    parts.push(GENERATED_BANNER);
+    parts.push('# Shared Agent Brain — `pop.brain.shared`');
+    if (headCid)
+        parts.push(`*Head CID: \`${headCid}\`*`);
+    parts.push('');
+    // Rules — canonical short-form list.
+    if (Array.isArray(doc.rules) && doc.rules.length > 0) {
+        parts.push('## Rules');
+        parts.push('');
+        parts.push(doc.rules.map((r, i) => renderRule(r, i)).join('\n'));
+        parts.push('');
+    }
+    // Operating constraints — short-form list, same renderer as rules.
+    if (Array.isArray(doc.operatingConstraints) && doc.operatingConstraints.length > 0) {
+        parts.push('## Operating Constraints');
+        parts.push('');
+        parts.push(doc.operatingConstraints.map((c, i) => renderRule(c, i)).join('\n'));
+        parts.push('');
+    }
+    // Lessons — long-form, one block per lesson. The primary field today.
+    // Tombstoned lessons (removed === true) are filtered out of the main
+    // Lessons section but surfaced in a short "Removed lessons" summary
+    // at the bottom so operators can see something was removed without
+    // the content polluting the main view.
+    const allLessons = Array.isArray(doc.lessons) ? doc.lessons : [];
+    const liveLessons = allLessons.filter(l => l?.removed !== true);
+    const tombstoned = allLessons.filter(l => l?.removed === true);
+    if (liveLessons.length > 0) {
+        parts.push('## Lessons');
+        parts.push('');
+        parts.push(liveLessons.map((l, i) => renderLesson(l, i)).join('\n'));
+    }
+    else if (doc.lessons !== undefined && allLessons.length === 0) {
+        parts.push('## Lessons');
+        parts.push('');
+        parts.push('*(no lessons yet)*');
+        parts.push('');
+    }
+    // Org state — key/value dump.
+    if (doc.orgState && typeof doc.orgState === 'object' && Object.keys(doc.orgState).length > 0) {
+        parts.push('## Org State');
+        parts.push('');
+        for (const [k, v] of Object.entries(doc.orgState)) {
+            parts.push(`- **${k}**: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`);
+        }
+        parts.push('');
+    }
+    // Removed-lessons summary — count + last 3 ids only. Keeps the
+    // projection clean while making removals visible. Operators can
+    // still inspect full tombstone metadata via `pop brain read`.
+    if (tombstoned.length > 0) {
+        parts.push('## Removed lessons');
+        parts.push('');
+        parts.push(`*(${tombstoned.length} lesson${tombstoned.length === 1 ? '' : 's'} tombstoned)*`);
+        parts.push('');
+        const lastThree = tombstoned.slice(-3).map(l => l?.id ?? '(no id)');
+        for (const id of lastThree)
+            parts.push(`- ${id}`);
+        parts.push('');
+    }
+    // Unknown top-level fields — dump as JSON so schema evolution doesn't
+    // drop data on the floor.
+    const known = new Set(['lessons', 'rules', 'operatingConstraints', 'orgState']);
+    const unknownKeys = Object.keys(doc).filter(k => !known.has(k));
+    if (unknownKeys.length > 0) {
+        parts.push('## Other fields');
+        parts.push('');
+        parts.push('```json');
+        const subset = {};
+        for (const k of unknownKeys)
+            subset[k] = doc[k];
+        parts.push(JSON.stringify(subset, null, 2));
+        parts.push('```');
+        parts.push('');
+    }
+    // Always render an empty-doc marker so snapshotting a fresh doc still
+    // produces a non-degenerate file.
+    if ((!doc.lessons || (Array.isArray(doc.lessons) && doc.lessons.length === 0)) &&
+        (!doc.rules || (Array.isArray(doc.rules) && doc.rules.length === 0)) &&
+        (!doc.operatingConstraints || (Array.isArray(doc.operatingConstraints) && doc.operatingConstraints.length === 0)) &&
+        (!doc.orgState || Object.keys(doc.orgState || {}).length === 0) &&
+        unknownKeys.length === 0) {
+        parts.push('*(brain doc is empty — no content to project yet)*');
+        parts.push('');
+    }
+    // Ensure trailing newline so the file is POSIX-clean.
+    return parts.join('\n').replace(/\n+$/, '\n');
+}
+const STANCE_EMOJI = {
+    support: '✅',
+    oppose: '❌',
+    concerned: '⚠️',
+    question: '❓',
+    neutral: '➖',
+};
+function renderDiscussionEntry(entry) {
+    const bits = [];
+    if (entry.author)
+        bits.push(`**${entry.author}**`);
+    if (entry.stance) {
+        const emoji = STANCE_EMOJI[entry.stance] ?? '';
+        bits.push(`${emoji} ${entry.stance}`);
+    }
+    const iso = formatTimestamp(entry.timestamp);
+    if (iso)
+        bits.push(`*${iso}*`);
+    const header = bits.join(' · ');
+    const body = entry.message ?? entry.ipfs ?? '';
+    if (header && body)
+        return `- ${header}: ${body}`;
+    if (header)
+        return `- ${header}`;
+    return `- ${body}`;
+}
+function renderProject(p) {
+    const parts = [];
+    parts.push(`### ${p.name || p.id}`);
+    parts.push('');
+    const meta = [];
+    meta.push(`**Stage**: ${p.stage}`);
+    if (p.proposedBy) {
+        // Prefer HB# label when present (prose-era); fall back to ISO
+        // timestamp from proposedAt when the project was CLI-created.
+        let suffix = '';
+        if (p.proposedAtHB)
+            suffix = ` (HB#${p.proposedAtHB})`;
+        else {
+            const iso = formatTimestamp(p.proposedAt);
+            if (iso)
+                suffix = ` (${iso})`;
+        }
+        meta.push(`**Proposed by**: ${p.proposedBy}${suffix}`);
+    }
+    const lastAdvance = formatTimestamp(p.lastStageAdvanceAt);
+    if (lastAdvance)
+        meta.push(`**Last advance**: ${lastAdvance}`);
+    parts.push(meta.join(' · '));
+    parts.push('');
+    if (p.brief) {
+        parts.push('**Brief**');
+        parts.push('');
+        parts.push(p.brief.startsWith('http') ? `> ${p.brief}` : p.brief);
+        parts.push('');
+    }
+    if (Array.isArray(p.discussion) && p.discussion.length > 0) {
+        parts.push('**Discussion**');
+        parts.push('');
+        for (const entry of p.discussion)
+            parts.push(renderDiscussionEntry(entry));
+        parts.push('');
+    }
+    if (p.taskPlan) {
+        parts.push('**Task plan**');
+        parts.push('');
+        parts.push(p.taskPlan);
+        parts.push('');
+    }
+    if (p.proposal) {
+        parts.push('**Proposal**');
+        parts.push('');
+        parts.push(p.proposal);
+        parts.push('');
+    }
+    if (p.retrospective) {
+        parts.push('**Retrospective**');
+        parts.push('');
+        parts.push(p.retrospective);
+        parts.push('');
+    }
+    // Unknown per-project fields get dumped so nothing silently drops.
+    const known = new Set([
+        'id', 'name', 'stage', 'proposedBy', 'proposedAtHB', 'proposedAt',
+        'lastStageAdvanceAt', 'brief',
+        'discussion', 'taskPlan', 'proposal', 'retrospective',
+        'removed', 'removedAt', 'removedBy', 'removedReason',
+    ]);
+    const extra = Object.keys(p).filter(k => !known.has(k));
+    if (extra.length > 0) {
+        parts.push('*Extra fields*');
+        parts.push('');
+        parts.push('```json');
+        const subset = {};
+        for (const k of extra)
+            subset[k] = p[k];
+        parts.push(JSON.stringify(subset, null, 2));
+        parts.push('```');
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+/**
+ * Project a pop.brain.projects doc to markdown.
+ *
+ * Pure function — same input produces byte-identical output.
+ * Schema-tolerant: missing project fields are skipped, unknown
+ * top-level fields dump as JSON, empty doc renders a placeholder
+ * rather than crashing or returning an empty string.
+ */
+function projectProjects(doc, headCid = null) {
+    const parts = [];
+    parts.push(GENERATED_BANNER);
+    parts.push('# Collaborative Projects — `pop.brain.projects`');
+    if (headCid)
+        parts.push(`*Head CID: \`${headCid}\`*`);
+    parts.push('');
+    // Partition into live vs tombstoned. Only live projects render in
+    // the Summary table + per-project detail blocks. Tombstoned projects
+    // surface in a compact '## Removed projects' summary at the bottom
+    // with count + last 3 ids only — same shape as remove-lesson's
+    // '## Removed lessons' section in projectShared.
+    const allProjects = Array.isArray(doc.projects) ? doc.projects : [];
+    const liveProjects = allProjects.filter(p => p?.removed !== true);
+    const tombstonedProjects = allProjects.filter(p => p?.removed === true);
+    if (liveProjects.length === 0 && tombstonedProjects.length === 0) {
+        parts.push('*(no projects yet)*');
+        parts.push('');
+    }
+    else if (liveProjects.length === 0) {
+        parts.push('*(no live projects — all entries tombstoned)*');
+        parts.push('');
+    }
+    else {
+        // Summary table (live only).
+        parts.push('## Summary');
+        parts.push('');
+        parts.push('| ID | Name | Stage |');
+        parts.push('|---|---|---|');
+        for (const p of liveProjects) {
+            const id = (p.id ?? '(no id)').replace(/\|/g, '\\|');
+            const name = (p.name ?? '(no name)').replace(/\|/g, '\\|');
+            const stage = (p.stage ?? '(unknown)').replace(/\|/g, '\\|');
+            parts.push(`| ${id} | ${name} | ${stage} |`);
+        }
+        parts.push('');
+        // Per-project detail blocks (live only).
+        parts.push('## Projects');
+        parts.push('');
+        for (const p of liveProjects) {
+            parts.push(renderProject(p));
+        }
+    }
+    // Removed-projects summary — count + last 3 ids only. Keeps the
+    // projection clean while making removals visible. Operators can
+    // still inspect full tombstone metadata via `pop brain read`.
+    if (tombstonedProjects.length > 0) {
+        parts.push('## Removed projects');
+        parts.push('');
+        parts.push(`*(${tombstonedProjects.length} project${tombstonedProjects.length === 1 ? '' : 's'} tombstoned)*`);
+        parts.push('');
+        const lastThree = tombstonedProjects.slice(-3).map(p => p?.id ?? '(no id)');
+        for (const id of lastThree)
+            parts.push(`- ${id}`);
+        parts.push('');
+    }
+    // Unknown top-level fields — dump as JSON so schema evolution doesn't
+    // drop data on the floor (same principle as projectShared).
+    const known = new Set(['projects']);
+    const unknownKeys = Object.keys(doc).filter(k => !known.has(k));
+    if (unknownKeys.length > 0) {
+        parts.push('## Other fields');
+        parts.push('');
+        parts.push('```json');
+        const subset = {};
+        for (const k of unknownKeys)
+            subset[k] = doc[k];
+        parts.push(JSON.stringify(subset, null, 2));
+        parts.push('```');
+        parts.push('');
+    }
+    return parts.join('\n').replace(/\n+$/, '\n');
+}
+const CHANGE_STATUS_EMOJI = {
+    proposed: '📝',
+    agreed: '✅',
+    modified: '✏️',
+    rejected: '❌',
+    filed: '🎯',
+};
+function renderProposedChange(c) {
+    const emoji = CHANGE_STATUS_EMOJI[c.status] ?? '•';
+    const parts = [];
+    parts.push(`- ${emoji} **${c.id}** — ${c.summary}`);
+    if (c.status === 'filed' && c.filedTaskId) {
+        parts.push(`  *filed as task #${c.filedTaskId}*`);
+    }
+    else {
+        parts.push(`  *status: ${c.status}*`);
+    }
+    if (c.details) {
+        // Indent the detail body under the bullet so it renders as part of the item.
+        const indented = c.details.split('\n').map(line => `  ${line}`).join('\n');
+        parts.push(indented);
+    }
+    return parts.join('\n');
+}
+function renderRetroDiscussionEntry(entry) {
+    const bits = [];
+    if (entry.author)
+        bits.push(`**${entry.author}**`);
+    if (entry.hb)
+        bits.push(`HB#${entry.hb}`);
+    const iso = formatTimestamp(entry.timestamp);
+    if (iso)
+        bits.push(`*${iso}*`);
+    const header = bits.join(' · ');
+    const lines = [];
+    lines.push(`- ${header}`);
+    if (entry.message) {
+        const indented = entry.message.split('\n').map(line => `  ${line}`).join('\n');
+        lines.push(indented);
+    }
+    if (entry.votePerChange && Object.keys(entry.votePerChange).length > 0) {
+        const votes = Object.entries(entry.votePerChange)
+            .map(([changeId, vote]) => `${changeId}=${vote}`)
+            .join(', ');
+        lines.push(`  *votes: ${votes}*`);
+    }
+    return lines.join('\n');
+}
+function renderRetro(r) {
+    const parts = [];
+    parts.push(`### ${r.id}`);
+    parts.push('');
+    const meta = [];
+    if (r.author)
+        meta.push(`**Author**: ${r.author}`);
+    if (r.hb)
+        meta.push(`**At HB**: #${r.hb}`);
+    if (r.window) {
+        const fromLabel = r.window.from ? `#${r.window.from}` : '?';
+        const toLabel = r.window.to ? `#${r.window.to}` : '?';
+        meta.push(`**Window**: ${fromLabel}..${toLabel}`);
+    }
+    if (r.status)
+        meta.push(`**Status**: ${r.status}`);
+    const createdIso = formatTimestamp(r.createdAt);
+    if (createdIso)
+        meta.push(`**Created**: ${createdIso}`);
+    if (r.closedAt) {
+        const closedIso = formatTimestamp(r.closedAt);
+        if (closedIso)
+            meta.push(`**Closed**: ${closedIso}`);
+    }
+    parts.push(meta.join(' · '));
+    parts.push('');
+    if (r.observations?.worked) {
+        parts.push('**What worked**');
+        parts.push('');
+        parts.push(r.observations.worked);
+        parts.push('');
+    }
+    if (r.observations?.didntWork) {
+        parts.push('**What didn\'t work**');
+        parts.push('');
+        parts.push(r.observations.didntWork);
+        parts.push('');
+    }
+    if (Array.isArray(r.proposedChanges) && r.proposedChanges.length > 0) {
+        parts.push('**Proposed changes**');
+        parts.push('');
+        for (const change of r.proposedChanges)
+            parts.push(renderProposedChange(change));
+        parts.push('');
+    }
+    if (Array.isArray(r.discussion) && r.discussion.length > 0) {
+        parts.push('**Discussion**');
+        parts.push('');
+        for (const entry of r.discussion)
+            parts.push(renderRetroDiscussionEntry(entry));
+        parts.push('');
+    }
+    // Dump unknown per-retro fields (same pattern as renderProject).
+    const known = new Set([
+        'id', 'author', 'hb', 'window', 'observations',
+        'proposedChanges', 'discussion', 'status', 'createdAt', 'closedAt',
+        'removed', 'removedAt', 'removedBy', 'removedReason',
+    ]);
+    const extra = Object.keys(r).filter(k => !known.has(k));
+    if (extra.length > 0) {
+        parts.push('*Extra fields*');
+        parts.push('');
+        parts.push('```json');
+        const subset = {};
+        for (const k of extra)
+            subset[k] = r[k];
+        parts.push(JSON.stringify(subset, null, 2));
+        parts.push('```');
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+/**
+ * Project a pop.brain.retros doc to markdown.
+ *
+ * Same invariants as projectShared / projectProjects: pure function,
+ * schema-tolerant, empty doc renders a placeholder.
+ */
+function projectRetros(doc, headCid = null) {
+    const parts = [];
+    parts.push(GENERATED_BANNER);
+    parts.push('# Session Retros — `pop.brain.retros`');
+    if (headCid)
+        parts.push(`*Head CID: \`${headCid}\`*`);
+    parts.push('');
+    const allRetros = Array.isArray(doc.retros) ? doc.retros : [];
+    const liveRetros = allRetros.filter(r => r?.removed !== true);
+    const tombstonedRetros = allRetros.filter(r => r?.removed === true);
+    if (liveRetros.length === 0 && tombstonedRetros.length === 0) {
+        parts.push('*(no retros yet)*');
+        parts.push('');
+    }
+    else if (liveRetros.length === 0) {
+        parts.push('*(no live retros — all entries tombstoned)*');
+        parts.push('');
+    }
+    else {
+        // Summary table (live only).
+        parts.push('## Summary');
+        parts.push('');
+        parts.push('| ID | Author | Window | Status | Changes |');
+        parts.push('|---|---|---|---|---|');
+        for (const r of liveRetros) {
+            const id = (r.id ?? '(no id)').replace(/\|/g, '\\|');
+            const author = (r.author ?? '(unknown)').replace(/\|/g, '\\|');
+            const windowLabel = r.window
+                ? `#${r.window.from ?? '?'}..#${r.window.to ?? '?'}`
+                : '(no window)';
+            const status = r.status ?? 'open';
+            const changeCount = Array.isArray(r.proposedChanges) ? r.proposedChanges.length : 0;
+            parts.push(`| ${id} | ${author} | ${windowLabel} | ${status} | ${changeCount} |`);
+        }
+        parts.push('');
+        // Per-retro detail blocks (live only).
+        parts.push('## Retros');
+        parts.push('');
+        for (const r of liveRetros)
+            parts.push(renderRetro(r));
+    }
+    if (tombstonedRetros.length > 0) {
+        parts.push('## Removed retros');
+        parts.push('');
+        parts.push(`*(${tombstonedRetros.length} retro${tombstonedRetros.length === 1 ? '' : 's'} tombstoned)*`);
+        parts.push('');
+        const lastThree = tombstonedRetros.slice(-3).map(r => r?.id ?? '(no id)');
+        for (const id of lastThree)
+            parts.push(`- ${id}`);
+        parts.push('');
+    }
+    // Unknown top-level fields — dump as JSON.
+    const known = new Set(['retros']);
+    const unknownKeys = Object.keys(doc).filter(k => !known.has(k));
+    if (unknownKeys.length > 0) {
+        parts.push('## Other fields');
+        parts.push('');
+        parts.push('```json');
+        const subset = {};
+        for (const k of unknownKeys)
+            subset[k] = doc[k];
+        parts.push(JSON.stringify(subset, null, 2));
+        parts.push('```');
+        parts.push('');
+    }
+    return parts.join('\n').replace(/\n+$/, '\n');
+}
+const BRAINSTORM_STATUS_EMOJI = {
+    open: '💭',
+    voting: '🗳️',
+    promoted: '🎯',
+    closed: '✅',
+};
+const VOTE_STANCE_EMOJI = {
+    support: '✅',
+    explore: '🤔',
+    oppose: '❌',
+};
+function renderIdea(idea, index) {
+    const parts = [];
+    const header = idea.id ? `### Idea: ${idea.id}` : `### Idea ${index + 1}`;
+    parts.push(header);
+    const meta = [];
+    if (idea.author)
+        meta.push(`author: ${idea.author}`);
+    const iso = formatTimestamp(idea.timestamp);
+    if (iso)
+        meta.push(`at: ${iso}`);
+    if (idea.priority)
+        meta.push(`priority: ${idea.priority}`);
+    if (meta.length > 0)
+        parts.push(`*${meta.join(' · ')}*`);
+    if (idea.message) {
+        parts.push('');
+        parts.push(idea.message);
+    }
+    // Vote tally
+    const votes = idea.votes && typeof idea.votes === 'object' ? idea.votes : {};
+    const voteEntries = Object.entries(votes);
+    if (voteEntries.length > 0) {
+        parts.push('');
+        parts.push('**Votes**:');
+        const tally = { support: 0, explore: 0, oppose: 0 };
+        for (const [addr, stance] of voteEntries) {
+            const emoji = VOTE_STANCE_EMOJI[stance] ?? '•';
+            parts.push(`- ${emoji} \`${addr}\` — ${stance}`);
+            if (tally[stance] != null)
+                tally[stance]++;
+        }
+        parts.push(`- **Tally**: ${tally.support} support · ${tally.explore} explore · ${tally.oppose} oppose`);
+    }
+    // Promotion marker
+    if (idea.promotedProjectId) {
+        parts.push('');
+        const promotedMeta = [`**Promoted to project**: \`${idea.promotedProjectId}\``];
+        if (idea.promotedBy)
+            promotedMeta.push(`by ${idea.promotedBy}`);
+        const pIso = formatTimestamp(idea.promotedAt);
+        if (pIso)
+            promotedMeta.push(`at ${pIso}`);
+        parts.push(promotedMeta.join(' · '));
+    }
+    return parts.join('\n');
+}
+function renderBrainstormDiscussionEntry(entry) {
+    const bits = [];
+    if (entry.author)
+        bits.push(`**${entry.author}**`);
+    const iso = formatTimestamp(entry.timestamp);
+    if (iso)
+        bits.push(`*${iso}*`);
+    const header = bits.join(' · ');
+    const lines = [];
+    lines.push(`- ${header}`);
+    if (entry.message) {
+        const indented = entry.message.split('\n').map((l) => `  ${l}`).join('\n');
+        lines.push(indented);
+    }
+    return lines.join('\n');
+}
+function renderBrainstorm(b) {
+    const parts = [];
+    const emoji = BRAINSTORM_STATUS_EMOJI[b.status] ?? '•';
+    parts.push(`## ${emoji} ${b.title || b.id}`);
+    parts.push('');
+    const meta = [];
+    meta.push(`**Status**: ${b.status}`);
+    if (b.author)
+        meta.push(`**Author**: ${b.author}`);
+    const iso = formatTimestamp(b.openedAt);
+    if (iso)
+        meta.push(`**Opened**: ${iso}`);
+    if (b.window) {
+        const from = b.window.from != null ? `#${b.window.from}` : '?';
+        const to = b.window.to != null ? `#${b.window.to}` : '?';
+        meta.push(`**Window**: ${from}..${to}`);
+    }
+    if (b.id)
+        meta.push(`**ID**: \`${b.id}\``);
+    parts.push(meta.join(' · '));
+    parts.push('');
+    if (b.prompt) {
+        parts.push('**Prompt**:');
+        parts.push('');
+        parts.push(b.prompt);
+        parts.push('');
+    }
+    // Ideas
+    const ideas = Array.isArray(b.ideas) ? b.ideas : [];
+    if (ideas.length > 0) {
+        parts.push('### Ideas');
+        parts.push('');
+        ideas.forEach((idea, i) => {
+            parts.push(renderIdea(idea, i));
+            parts.push('');
+        });
+    }
+    else {
+        parts.push('*(no ideas posted yet)*');
+        parts.push('');
+    }
+    // Discussion
+    const discussion = Array.isArray(b.discussion) ? b.discussion : [];
+    if (discussion.length > 0) {
+        parts.push('### Discussion');
+        parts.push('');
+        for (const entry of discussion)
+            parts.push(renderBrainstormDiscussionEntry(entry));
+        parts.push('');
+    }
+    // Close / promotion state
+    if (b.status === 'closed' && b.closedReason) {
+        parts.push(`**Closed reason**: ${b.closedReason}`);
+        parts.push('');
+    }
+    if (Array.isArray(b.promotedToProjectIds) && b.promotedToProjectIds.length > 0) {
+        parts.push('**Promoted projects**:');
+        for (const pid of b.promotedToProjectIds)
+            parts.push(`- \`${pid}\``);
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+function projectBrainstorms(doc, headCid = null) {
+    const parts = [];
+    parts.push(GENERATED_BANNER);
+    parts.push('# Cross-Agent Brainstorms — `pop.brain.brainstorms`');
+    if (headCid)
+        parts.push(`*Head CID: \`${headCid}\`*`);
+    parts.push('');
+    const allBrainstorms = Array.isArray(doc.brainstorms) ? doc.brainstorms : [];
+    const live = allBrainstorms.filter((b) => b?.removed !== true);
+    const tombstoned = allBrainstorms.filter((b) => b?.removed === true);
+    if (live.length === 0 && tombstoned.length === 0) {
+        parts.push('*(no brainstorms yet — open one with `pop brain brainstorm-start --title ... --prompt ...`)*');
+        parts.push('');
+    }
+    else if (live.length === 0) {
+        parts.push('*(no live brainstorms — all entries tombstoned)*');
+        parts.push('');
+    }
+    else {
+        // Summary table — active states ordered before closed/promoted
+        const statusOrder = { voting: 0, open: 1, promoted: 2, closed: 3 };
+        const sorted = [...live].sort((a, b) => {
+            const aRank = statusOrder[a.status] ?? 99;
+            const bRank = statusOrder[b.status] ?? 99;
+            if (aRank !== bRank)
+                return aRank - bRank;
+            return (b.openedAt ?? 0) - (a.openedAt ?? 0);
+        });
+        parts.push('## Summary');
+        parts.push('');
+        parts.push('| Status | ID | Title | Author | Ideas | Votes |');
+        parts.push('|---|---|---|---|---|---|');
+        for (const b of sorted) {
+            const id = (b.id ?? '(no id)').replace(/\|/g, '\\|');
+            const title = (b.title ?? '(no title)').replace(/\|/g, '\\|');
+            const author = (b.author ?? '?').slice(0, 10);
+            const ideaCount = Array.isArray(b.ideas) ? b.ideas.length : 0;
+            const voteCount = (b.ideas || []).reduce((sum, idea) => {
+                const v = idea?.votes;
+                return sum + (v && typeof v === 'object' ? Object.keys(v).length : 0);
+            }, 0);
+            const statusEmoji = BRAINSTORM_STATUS_EMOJI[b.status] ?? '•';
+            parts.push(`| ${statusEmoji} ${b.status} | \`${id}\` | ${title} | ${author} | ${ideaCount} | ${voteCount} |`);
+        }
+        parts.push('');
+        parts.push('## Brainstorms');
+        parts.push('');
+        for (const b of sorted) {
+            parts.push(renderBrainstorm(b));
+            parts.push('---');
+            parts.push('');
+        }
+    }
+    if (tombstoned.length > 0) {
+        parts.push('## Removed brainstorms');
+        parts.push('');
+        parts.push(`*(${tombstoned.length} brainstorm${tombstoned.length === 1 ? '' : 's'} tombstoned)*`);
+        parts.push('');
+        for (const b of tombstoned.slice(-5)) {
+            parts.push(`- \`${b.id ?? '(no id)'}\`${b.removedReason ? ` — ${b.removedReason}` : ''}`);
+        }
+        parts.push('');
+    }
+    // Unknown top-level fields — dump as JSON
+    const known = new Set(['brainstorms']);
+    const unknownKeys = Object.keys(doc).filter((k) => !known.has(k));
+    if (unknownKeys.length > 0) {
+        parts.push('## Other fields');
+        parts.push('');
+        parts.push('```json');
+        const subset = {};
+        for (const k of unknownKeys)
+            subset[k] = doc[k];
+        parts.push(JSON.stringify(subset, null, 2));
+        parts.push('```');
+        parts.push('');
+    }
+    return parts.join('\n').replace(/\n+$/, '\n');
+}
+const PROJECTOR_REGISTRY = [
+    {
+        match: (id) => id === 'pop.brain.projects' || id.startsWith('pop.brain.projects.'),
+        fn: projectProjects,
+    },
+    {
+        match: (id) => id === 'pop.brain.retros' || id.startsWith('pop.brain.retros.'),
+        fn: projectRetros,
+    },
+    {
+        match: (id) => id === 'pop.brain.brainstorms' || id.startsWith('pop.brain.brainstorms.'),
+        fn: projectBrainstorms,
+    },
+];
+/**
+ * Look up the right projector for a docId. Falls through to
+ * projectShared as the default so every previously-written snapshot
+ * call still works.
+ */
+function projectForDoc(docId, doc, headCid) {
+    for (const entry of PROJECTOR_REGISTRY) {
+        if (entry.match(docId))
+            return entry.fn(doc, headCid);
+    }
+    return projectShared(doc, headCid);
+}