@poa-box/agent 0.1.0

package/dist/lib/brain-membership.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Brain dynamic allowlist — derive the authorized-author set from on-chain
+ * organization membership instead of a hand-maintained JSON file.
+ *
+ * Task #330 (HB#312 Hudson directive): the static brain-allowlist.json
+ * blocks the "clone repo → onboard → apply → vouched → fully in" flow
+ * because new members have to be added to the JSON file by hand after
+ * their vouch lands. This module replaces the JSON with a subgraph-backed
+ * lookup of active members of the configured org.
+ *
+ * Design:
+ *
+ *   - Cache the full member address set for ~5 minutes (addresses in
+ *     lowercase). Invalidating per-address on every verify would hammer
+ *     the subgraph; per-org batch fetch is the right granularity.
+ *
+ *   - On network error, throw. Callers (the verify path) catch and fall
+ *     back to the static allowlist. The fallback log is emitted by the
+ *     caller, not here, because this module is pure lookup.
+ *
+ *   - Org and chain are read from POP_DEFAULT_ORG / POP_DEFAULT_CHAIN
+ *     (or POP_BRAIN_ORG / POP_BRAIN_CHAIN if set — a future multi-org
+ *     brain layer will need per-doc org, but MVP is one-brain-per-org).
+ *
+ *   - The subgraph query is a narrow extract of the triage.ts pattern:
+ *     just organization.users with membershipStatus = Active, nothing
+ *     else. No tasks, no proposals, no treasury.
+ *
+ * The JSON allowlist stays in place for:
+ *   (1) fresh clones before the first subgraph request succeeds
+ *   (2) offline / air-gapped operators
+ *   (3) manual emergency overrides for keys outside the DAO
+ */
+/**
+ * Fetch the active member address set for an org. Caches per (chainId, orgId).
+ * Throws on subgraph error — callers handle fallback.
+ *
+ * @param orgIdOrName  Org identifier (POP_DEFAULT_ORG if undefined)
+ * @param chainId      Chain ID (POP_DEFAULT_CHAIN if undefined)
+ * @param opts.ttlMs   Override cache TTL (default 5 min)
+ */
+export declare function fetchOrgMembers(orgIdOrName?: string, chainId?: number, opts?: {
+    ttlMs?: number;
+}): Promise<Set<string>>;
+/**
+ * Is the given address currently an active member of the configured org?
+ * Returns true if the address holds the member hat, false if not found.
+ * Throws on network error — caller handles fallback.
+ */
+export declare function isOrgMember(address: string, orgIdOrName?: string, chainId?: number): Promise<boolean>;
+/** Invalidate the cache (useful for tests and pop brain doctor refreshes). */
+export declare function clearMembershipCache(): void;
+/**
+ * Non-throwing variant: returns the member set or null on any error.
+ * Used by pop brain doctor to show current dynamic membership without
+ * bailing the whole health check.
+ */
+export declare function tryFetchOrgMembers(orgIdOrName?: string, chainId?: number): Promise<Set<string> | null>;

package/dist/lib/brain-membership.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Brain dynamic allowlist — derive the authorized-author set from on-chain
+ * organization membership instead of a hand-maintained JSON file.
+ *
+ * Task #330 (HB#312 Hudson directive): the static brain-allowlist.json
+ * blocks the "clone repo → onboard → apply → vouched → fully in" flow
+ * because new members have to be added to the JSON file by hand after
+ * their vouch lands. This module replaces the JSON with a subgraph-backed
+ * lookup of active members of the configured org.
+ *
+ * Design:
+ *
+ *   - Cache the full member address set for ~5 minutes (addresses in
+ *     lowercase). Invalidating per-address on every verify would hammer
+ *     the subgraph; per-org batch fetch is the right granularity.
+ *
+ *   - On network error, throw. Callers (the verify path) catch and fall
+ *     back to the static allowlist. The fallback log is emitted by the
+ *     caller, not here, because this module is pure lookup.
+ *
+ *   - Org and chain are read from POP_DEFAULT_ORG / POP_DEFAULT_CHAIN
+ *     (or POP_BRAIN_ORG / POP_BRAIN_CHAIN if set — a future multi-org
+ *     brain layer will need per-doc org, but MVP is one-brain-per-org).
+ *
+ *   - The subgraph query is a narrow extract of the triage.ts pattern:
+ *     just organization.users with membershipStatus = Active, nothing
+ *     else. No tasks, no proposals, no treasury.
+ *
+ * The JSON allowlist stays in place for:
+ *   (1) fresh clones before the first subgraph request succeeds
+ *   (2) offline / air-gapped operators
+ *   (3) manual emergency overrides for keys outside the DAO
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchOrgMembers = fetchOrgMembers;
+exports.isOrgMember = isOrgMember;
+exports.clearMembershipCache = clearMembershipCache;
+exports.tryFetchOrgMembers = tryFetchOrgMembers;
+const subgraph_1 = require("@poa-box/cli/lib/subgraph");
+const resolve_1 = require("@poa-box/cli/lib/resolve");
+const networks_1 = require("@poa-box/cli/config/networks");
+const MEMBERS_QUERY = `
+  query BrainMembers($orgId: Bytes!) {
+    organization(id: $orgId) {
+      users(first: 100) {
+        address
+        membershipStatus
+      }
+    }
+  }
+`;
+const cache = new Map();
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+function cacheKey(orgId, chainId) {
+    return `${chainId}:${orgId.toLowerCase()}`;
+}
+/**
+ * Fetch the active member address set for an org. Caches per (chainId, orgId).
+ * Throws on subgraph error — callers handle fallback.
+ *
+ * @param orgIdOrName  Org identifier (POP_DEFAULT_ORG if undefined)
+ * @param chainId      Chain ID (POP_DEFAULT_CHAIN if undefined)
+ * @param opts.ttlMs   Override cache TTL (default 5 min)
+ */
+async function fetchOrgMembers(orgIdOrName, chainId, opts = {}) {
+    const effectiveChain = chainId ?? (process.env.POP_BRAIN_CHAIN ? Number(process.env.POP_BRAIN_CHAIN) : undefined);
+    const network = (0, networks_1.resolveNetworkConfig)(effectiveChain);
+    const resolved = await (0, resolve_1.resolveOrgModules)(orgIdOrName ?? process.env.POP_BRAIN_ORG ?? process.env.POP_DEFAULT_ORG, network.chainId);
+    const key = cacheKey(resolved.orgId, network.chainId);
+    const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt > Date.now()) {
+        return hit.members;
+    }
+    const result = await (0, subgraph_1.query)(MEMBERS_QUERY, { orgId: resolved.orgId }, network.chainId);
+    const org = result?.organization;
+    if (!org) {
+        throw new Error(`Brain membership: org ${resolved.orgId} not found in subgraph`);
+    }
+    const members = new Set();
+    for (const u of org.users || []) {
+        if (u.membershipStatus === 'Active' && u.address) {
+            members.add(String(u.address).toLowerCase());
+        }
+    }
+    cache.set(key, { members, expiresAt: Date.now() + ttl });
+    return members;
+}
+/**
+ * Is the given address currently an active member of the configured org?
+ * Returns true if the address holds the member hat, false if not found.
+ * Throws on network error — caller handles fallback.
+ */
+async function isOrgMember(address, orgIdOrName, chainId) {
+    const members = await fetchOrgMembers(orgIdOrName, chainId);
+    return members.has(address.toLowerCase());
+}
+/** Invalidate the cache (useful for tests and pop brain doctor refreshes). */
+function clearMembershipCache() {
+    cache.clear();
+}
+/**
+ * Non-throwing variant: returns the member set or null on any error.
+ * Used by pop brain doctor to show current dynamic membership without
+ * bailing the whole health check.
+ */
+async function tryFetchOrgMembers(orgIdOrName, chainId) {
+    try {
+        return await fetchOrgMembers(orgIdOrName, chainId);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/brain-migrate-projects.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Brain projects migration — one-shot parser for agent/brain/Knowledge/projects.md
+ * into a ProjectsBrainDoc.
+ *
+ * This parses the "Active Projects" H2 section only. Each '### <Name>'
+ * subsection becomes a BrainProject entry. Structured fields we extract:
+ *
+ *   - Stage           — from "- **Stage**: X"
+ *   - Proposed by     — from "- **Proposed by**: <author> (HB#N)"
+ *   - Brief           — from "- **Brief**: ..." (possibly multi-line with
+ *                        continuation indented under the bullet)
+ *
+ * Unstructured fields we preserve as raw markdown strings attached to
+ * the project:
+ *
+ *   - Discussion      → taskPlan field, prefixed '(Raw markdown from
+ *                        projects.md — parse in v2)' (TODO: split into
+ *                        ProjectDiscussionEntry[] with author / stance /
+ *                        timestamp fields when we have time)
+ *   - Task Plan       → concatenated into taskPlan
+ *   - Proposal        → concatenated into proposal
+ *   - Retrospective   → concatenated into retrospective
+ *
+ * Same discipline as parseSharedMarkdown from brain-migrate.ts: pure
+ * function, no I/O, no Date.now, caller-supplied MigrationContext for
+ * default timestamps + author.
+ *
+ * Scope: "Active Projects" H2 only. The "On-Chain Projects" table, the
+ * "How to Propose a Project" H2, the "Completed Projects" H2, and the
+ * "Lessons Learned" H2 are all skipped — they're prose / metadata, not
+ * projects-to-migrate.
+ */
+import type { ProjectsBrainDoc } from './brain-projections';
+import type { MigrationContext } from './brain-migrate';
+/**
+ * Parse projects.md → ProjectsBrainDoc. Pure function.
+ *
+ * Only looks at the "Active Projects" H2 section. Each H3 becomes a
+ * BrainProject with structured stage/proposedBy/proposedAtHB/brief
+ * and a raw-markdown taskPlan preserving Discussion + Task Plan
+ * content for later structured parsing.
+ */
+export declare function parseProjectsMarkdown(raw: string, ctx: MigrationContext): ProjectsBrainDoc;

package/dist/lib/brain-migrate-projects.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * Brain projects migration — one-shot parser for agent/brain/Knowledge/projects.md
+ * into a ProjectsBrainDoc.
+ *
+ * This parses the "Active Projects" H2 section only. Each '### <Name>'
+ * subsection becomes a BrainProject entry. Structured fields we extract:
+ *
+ *   - Stage           — from "- **Stage**: X"
+ *   - Proposed by     — from "- **Proposed by**: <author> (HB#N)"
+ *   - Brief           — from "- **Brief**: ..." (possibly multi-line with
+ *                        continuation indented under the bullet)
+ *
+ * Unstructured fields we preserve as raw markdown strings attached to
+ * the project:
+ *
+ *   - Discussion      → taskPlan field, prefixed '(Raw markdown from
+ *                        projects.md — parse in v2)' (TODO: split into
+ *                        ProjectDiscussionEntry[] with author / stance /
+ *                        timestamp fields when we have time)
+ *   - Task Plan       → concatenated into taskPlan
+ *   - Proposal        → concatenated into proposal
+ *   - Retrospective   → concatenated into retrospective
+ *
+ * Same discipline as parseSharedMarkdown from brain-migrate.ts: pure
+ * function, no I/O, no Date.now, caller-supplied MigrationContext for
+ * default timestamps + author.
+ *
+ * Scope: "Active Projects" H2 only. The "On-Chain Projects" table, the
+ * "How to Propose a Project" H2, the "Completed Projects" H2, and the
+ * "Lessons Learned" H2 are all skipped — they're prose / metadata, not
+ * projects-to-migrate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseProjectsMarkdown = parseProjectsMarkdown;
+const STAGE_WORDS = {
+    propose: 'propose',
+    discuss: 'discuss',
+    plan: 'plan',
+    vote: 'vote',
+    execute: 'execute',
+    review: 'review',
+    ship: 'ship',
+};
+const ACTIVE_PROJECTS_H2_RE = /^##\s+Active Projects\b/i;
+const H2_RE = /^##\s+/;
+const H3_RE = /^###\s+/;
+const HB_TAG_RE = /\(\s*HB#(\d+)(?:\s*,\s*([^\s)]+))?\s*\)/i;
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+/**
+ * Extract the "Active Projects" H2 block as a list of lines. Returns
+ * an empty array if the section isn't found. Fence-aware (won't split
+ * on `### ` inside a code block).
+ */
+function extractActiveProjectsBlock(raw) {
+    const lines = raw.split(/\r?\n/);
+    const out = [];
+    let inside = false;
+    let inFence = false;
+    for (const line of lines) {
+        if (/^```/.test(line)) {
+            inFence = !inFence;
+            if (inside)
+                out.push(line);
+            continue;
+        }
+        if (!inFence && H2_RE.test(line)) {
+            if (ACTIVE_PROJECTS_H2_RE.test(line)) {
+                inside = true;
+                continue;
+            }
+            if (inside)
+                break; // Hit the next H2 — end of section.
+        }
+        if (inside)
+            out.push(line);
+    }
+    return out;
+}
+/**
+ * Split an Active Projects block into per-project sections keyed by
+ * the H3 header. Fence-aware.
+ */
+function splitProjectSections(lines) {
+    const sections = [];
+    let current = null;
+    let inFence = false;
+    for (const line of lines) {
+        if (/^```/.test(line)) {
+            inFence = !inFence;
+            if (current)
+                current.body.push(line);
+            continue;
+        }
+        if (!inFence && H3_RE.test(line)) {
+            if (current)
+                sections.push(current);
+            current = { header: line.replace(H3_RE, '').trim(), body: [] };
+            continue;
+        }
+        if (current)
+            current.body.push(line);
+    }
+    if (current)
+        sections.push(current);
+    return sections;
+}
+/**
+ * Parse one project's body lines into structured fields. The shape of
+ * the hand-written projects.md body is a flat list of bullets, some of
+ * which have nested continuation lines and some of which have nested
+ * sub-bullets (Discussion / Task Plan). We scan line by line and use
+ * the '- **Field**:' prefix as a section marker.
+ */
+function parseProjectBody(header, lines, ctx) {
+    const id = slugify(header) || 'project';
+    const project = {
+        id,
+        name: header,
+        stage: 'propose', // Default — overwritten if a Stage line is found.
+    };
+    let section = 'none';
+    const accum = {
+        brief: [],
+        discussion: [],
+        taskPlan: [],
+        proposal: [],
+        retrospective: [],
+    };
+    for (const rawLine of lines) {
+        const line = rawLine;
+        // New bullet — dispatch based on the field name.
+        const bulletMatch = /^-\s+\*\*([^*]+)\*\*:?\s*(.*)$/.exec(line);
+        if (bulletMatch) {
+            const fieldRaw = bulletMatch[1].trim().toLowerCase();
+            const rest = bulletMatch[2] ?? '';
+            // Stage line — extract value directly; do not push to any section.
+            if (fieldRaw === 'stage') {
+                const stageWord = rest.trim().toLowerCase().split(/\s+/)[0];
+                const normalized = STAGE_WORDS[stageWord];
+                if (normalized)
+                    project.stage = normalized;
+                section = 'none';
+                continue;
+            }
+            // Proposed by: "<author> (HB#N)"
+            if (fieldRaw === 'proposed by') {
+                const hb = HB_TAG_RE.exec(rest);
+                if (hb) {
+                    const hbN = Number(hb[1]);
+                    const authorInTag = hb[2] ?? null;
+                    project.proposedAtHB = hbN;
+                    project.proposedBy = authorInTag ?? rest.replace(HB_TAG_RE, '').trim() ?? ctx.defaultAuthor;
+                    if (ctx.timestampForHB)
+                        project.proposedAt = ctx.timestampForHB(hbN);
+                }
+                else {
+                    project.proposedBy = rest.trim() || ctx.defaultAuthor;
+                }
+                section = 'none';
+                continue;
+            }
+            // Brief — multi-line accumulator.
+            if (fieldRaw === 'brief') {
+                section = 'brief';
+                if (rest.trim())
+                    accum.brief.push(rest.trim());
+                continue;
+            }
+            // Discussion — nested bullets preserved as raw markdown.
+            if (fieldRaw === 'discussion') {
+                section = 'discussion';
+                if (rest.trim())
+                    accum.discussion.push(rest.trim());
+                continue;
+            }
+            // Task plan — same treatment.
+            if (fieldRaw === 'task plan') {
+                section = 'taskPlan';
+                if (rest.trim())
+                    accum.taskPlan.push(rest.trim());
+                continue;
+            }
+            if (fieldRaw === 'proposal') {
+                section = 'proposal';
+                if (rest.trim())
+                    accum.proposal.push(rest.trim());
+                continue;
+            }
+            if (fieldRaw === 'retrospective') {
+                section = 'retrospective';
+                if (rest.trim())
+                    accum.retrospective.push(rest.trim());
+                continue;
+            }
+            // Unknown named bullet (e.g. "- **Execution Status**:") — push
+            // to the current section as a raw line so nothing is dropped.
+            if (section !== 'none')
+                accum[section].push(line);
+            continue;
+        }
+        // Continuation line (indented or bare text). Push to the current
+        // section if we're in one; drop otherwise.
+        if (section !== 'none' && line.trim() !== '') {
+            accum[section].push(line);
+        }
+    }
+    if (accum.brief.length > 0)
+        project.brief = accum.brief.join('\n').trim();
+    // Compose discussion + task plan into the taskPlan field as raw
+    // markdown for MVP. The structured ProjectDiscussionEntry[] parse
+    // is v2 work.
+    const discussionMd = accum.discussion.length > 0
+        ? '**Discussion (raw)**\n' + accum.discussion.join('\n').trim()
+        : '';
+    const taskPlanMd = accum.taskPlan.length > 0
+        ? '**Task plan (raw)**\n' + accum.taskPlan.join('\n').trim()
+        : '';
+    const combined = [discussionMd, taskPlanMd].filter(s => s).join('\n\n');
+    if (combined)
+        project.taskPlan = combined;
+    if (accum.proposal.length > 0)
+        project.proposal = accum.proposal.join('\n').trim();
+    if (accum.retrospective.length > 0)
+        project.retrospective = accum.retrospective.join('\n').trim();
+    return project;
+}
+/**
+ * Parse projects.md → ProjectsBrainDoc. Pure function.
+ *
+ * Only looks at the "Active Projects" H2 section. Each H3 becomes a
+ * BrainProject with structured stage/proposedBy/proposedAtHB/brief
+ * and a raw-markdown taskPlan preserving Discussion + Task Plan
+ * content for later structured parsing.
+ */
+function parseProjectsMarkdown(raw, ctx) {
+    const block = extractActiveProjectsBlock(raw);
+    const sections = splitProjectSections(block);
+    const projects = sections.map(s => parseProjectBody(s.header, s.body, ctx));
+    return { projects };
+}

package/dist/lib/brain-migrate.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Brain migration — one-shot parser that converts the hand-written
+ * agent/brain/Knowledge/shared.md (and siblings) into a structured
+ * SharedBrainDoc for seeding the Automerge CRDT layer.
+ *
+ * This is step 8 of the brain plan (cheeky-nibbling-raven.md).
+ * After this file has been run once on each hand-written knowledge
+ * file, the CRDT substrate is the source of truth and the hand-written
+ * files become historical snapshots.
+ *
+ * ## Design notes
+ *
+ * - **Pure function.** parseSharedMarkdown takes a raw string and
+ *   returns a SharedBrainDoc. No I/O, no Date.now, no environment
+ *   reads. The CLI command handles all I/O and timestamp-from-now
+ *   decisions.
+ *
+ * - **Heuristic, not canonical.** This is a one-shot parse; we're
+ *   allowed to lose fidelity on layout details as long as the
+ *   content content survives. Each H2 section becomes one entry.
+ *
+ * - **Short sections become rules, long sections become lessons.**
+ *   A rule is a short-form policy item (one to a few lines of plain
+ *   text, often bullet-led). A lesson is a longer structured
+ *   narrative. The heuristic: if a section's body has more than 200
+ *   characters OR contains a code fence, it's a lesson; otherwise
+ *   it's a rule. This maps the existing hand-written file's mix of
+ *   short policy bullets and long narrative notes to the brain doc
+ *   schema cleanly.
+ *
+ * - **HB# tags → timestamps.** Lines containing `HB#N` or `(HB#N,
+ *   author)` extract both the heartbeat number and the author.
+ *   Timestamps are derived from HB# via a caller-provided anchor
+ *   (see MigrationContext below) rather than guessed — keeps the
+ *   parser pure.
+ *
+ * - **Code fences are preserved verbatim.** We do NOT split on ##
+ *   headers inside a ``` block — that would corrupt embedded code
+ *   samples. Tracked via a simple in-fence toggle.
+ */
+import type { SharedBrainDoc } from './brain-projections';
+export interface MigrationContext {
+    /**
+     * Default author to assign to sections where no HB#/author tag was
+     * found in the source. Typically the agent running the migration.
+     */
+    defaultAuthor: string;
+    /**
+     * Unix-seconds timestamp representing "now" for the migration run.
+     * Sections without their own HB# tag get this timestamp — a
+     * reasonable proxy for "discovered at migration time."
+     */
+    defaultTimestamp: number;
+    /**
+     * Caller-supplied function that turns a heartbeat number into a
+     * unix-seconds timestamp. Pass in the "best guess" curve, typically
+     * `now - (currentHB - N) * 15 * 60`. If omitted, all HB# tagged
+     * sections fall back to defaultTimestamp.
+     */
+    timestampForHB?: (hb: number) => number;
+}
+export interface ParsedBrainDoc extends SharedBrainDoc {
+    rules: NonNullable<SharedBrainDoc['rules']>;
+    lessons: NonNullable<SharedBrainDoc['lessons']>;
+}
+/**
+ * Parse the hand-written shared.md (or similar) into a SharedBrainDoc.
+ *
+ * Dispatches to `parseModernGeneratedMd` for modern snapshots produced by
+ * `pop brain snapshot` (detected via the DO-NOT-HAND-EDIT banner), or to
+ * the legacy H2-section scanner for hand-written shared.md files.
+ *
+ * Pure function — no I/O, no Date.now, no env reads. The caller must
+ * supply the migration context (default author, default timestamp,
+ * optional HB→timestamp function).
+ */
+export declare function parseSharedMarkdown(raw: string, ctx: MigrationContext): ParsedBrainDoc;