@poa-box/agent 0.1.0

package/dist/commands/brain/retro-file-tasks.js

@@ -0,0 +1,372 @@
+"use strict";
+/**
+ * pop brain retro file-tasks — convert agreed retro changes into on-chain tasks.
+ *
+ * Usage:
+ *
+ *   pop brain retro file-tasks --retro retro-327-1776...
+ *   pop brain retro file-tasks --retro retro-327-1776... --dry-run
+ *   pop brain retro file-tasks --retro retro-327-1776... --project "CLI Infrastructure"
+ *
+ * Flow:
+ *
+ *   1. Load the retro from pop.brain.retros.
+ *   2. Find every proposed change whose status is 'agreed'. Changes at any
+ *      other status are skipped — 'proposed' needs more discussion first,
+ *      'rejected' was explicitly rejected, 'modified' needs a second round,
+ *      and 'filed' is already done (this is the idempotency guarantee:
+ *      re-running the command is safe because filed changes are no-ops).
+ *   3. For each agreed change:
+ *      a. Call `pop task create` with a structured description derived
+ *         from the change summary + details + retro window.
+ *      b. Capture the returned task id.
+ *      c. Run `updateChangeStatus` to flip the change to 'filed' with
+ *         filedTaskId set.
+ *   4. When every change is filed or rejected, the updateChangeStatus op
+ *      auto-advances the retro status to 'shipped' with a closedAt
+ *      timestamp.
+ *
+ * ## Idempotency
+ *
+ * This command is safe to run multiple times. A change with status='filed'
+ * is skipped. A change that was already converted won't be re-filed. The
+ * idempotency guarantee requires the `agreed → filed` transition to be
+ * the only way a change gets converted. Operators who want to re-file a
+ * change after filing it should run `pop brain retro respond --vote
+ * change-X=agree` again and then call file-tasks — but the previous
+ * filed task id is never overwritten, so the old task sticks around
+ * unless manually cancelled. That's a deliberate safety design: no
+ * accidental re-filing of the same work.
+ *
+ * ## Dry-run
+ *
+ * `--dry-run` prints the plan (which changes would be filed, what task
+ * description would be produced) without actually creating any tasks or
+ * mutating the retro. Use this to preview before committing.
+ *
+ * ## Project selection
+ *
+ * Defaults to "CLI Infrastructure" — the historical catch-all for brain
+ * layer + CLI work. Override with --project if the retro's proposed
+ * changes belong to a different project (e.g. "DeFi Research",
+ * "Agent Protocol").
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retroFileTasksHandler = void 0;
+const child_process_1 = require("child_process");
+const brain_1 = require("../../lib/brain");
+const brain_ops_1 = require("../../lib/brain-ops");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+/**
+ * Build a structured task description for a filed retro change. The
+ * description follows the /task-create skill template: context,
+ * deliverable, acceptance, constraints, context links.
+ */
+function buildTaskDescription(retro, change) {
+    const windowLabel = retro.window
+        ? `HB#${retro.window.from ?? '?'}..HB#${retro.window.to ?? '?'}`
+        : '(no window)';
+    const retroLabel = `retro ${retro.id} (${windowLabel})`;
+    // Short name: take the summary, trim to 60 chars, no change-id prefix
+    // so the task search UI reads cleanly.
+    const name = change.summary.slice(0, 60);
+    const descLines = [];
+    descLines.push(`[CONTEXT] This task was filed automatically by pop brain retro file-tasks from ${retroLabel}, change ${change.id}. The change was agreed during retro discussion and is ready to ship.`);
+    descLines.push('');
+    descLines.push(`[SUMMARY]`);
+    descLines.push(change.summary);
+    if (change.details) {
+        descLines.push('');
+        descLines.push(`[DETAILS]`);
+        descLines.push(change.details);
+    }
+    descLines.push('');
+    descLines.push(`[RETRO CONTEXT]`);
+    if (retro.author)
+        descLines.push(`- Retro author: ${retro.author}`);
+    descLines.push(`- Retro window: ${windowLabel}`);
+    descLines.push(`- Retro id: ${retro.id}`);
+    descLines.push(`- Change id: ${change.id}`);
+    if (Array.isArray(retro.discussion) && retro.discussion.length > 0) {
+        descLines.push(`- Discussion entries: ${retro.discussion.length}`);
+        // Find vote tallies on this specific change.
+        const voteCounts = {};
+        for (const entry of retro.discussion) {
+            const vote = entry?.votePerChange?.[change.id];
+            if (typeof vote === 'string') {
+                voteCounts[vote] = (voteCounts[vote] ?? 0) + 1;
+            }
+        }
+        if (Object.keys(voteCounts).length > 0) {
+            const tally = Object.entries(voteCounts).map(([v, n]) => `${n} ${v}`).join(', ');
+            descLines.push(`- Votes on this change: ${tally}`);
+        }
+    }
+    descLines.push('');
+    descLines.push(`[ACCEPTANCE]`);
+    descLines.push('- Implementation addresses the summary/details above');
+    descLines.push('- Any tests or verification appropriate to the change type');
+    descLines.push(`- Update the retro via pop brain retro respond with a shipped-note comment`);
+    descLines.push('');
+    descLines.push(`[CONSTRAINTS]`);
+    descLines.push('- Reuse existing POP CLI + brain infra — do not introduce new persistence layers');
+    descLines.push('- Pinned stack (helia@5.5.1, libp2p@2.10, gossipsub@14) unchanged');
+    return { name, description: descLines.join('\n') };
+}
+exports.retroFileTasksHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (default: pop.brain.retros)',
+        type: 'string',
+        default: 'pop.brain.retros',
+    })
+        .option('retro', {
+        describe: 'The retro.id whose agreed changes should be filed as tasks',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('project', {
+        describe: 'Target project for the new tasks (default: "CLI Infrastructure")',
+        type: 'string',
+        default: 'CLI Infrastructure',
+    })
+        .option('payout', {
+        describe: 'PT payout per filed task (default: 10)',
+        type: 'number',
+        default: 10,
+    })
+        .option('difficulty', {
+        describe: 'Difficulty label for filed tasks',
+        type: 'string',
+        choices: ['easy', 'medium', 'hard'],
+        default: 'medium',
+    })
+        .option('est-hours', {
+        describe: 'Estimated hours per filed task',
+        type: 'number',
+        default: 2,
+    })
+        .option('dry-run', {
+        describe: 'Preview what would be filed without creating tasks or mutating the retro',
+        type: 'boolean',
+        default: false,
+    })
+        .option('yes', {
+        alias: 'y',
+        describe: 'Skip confirmation prompts on the underlying pop task create calls',
+        type: 'boolean',
+        default: true,
+    }),
+    handler: async (argv) => {
+        try {
+            // Load the retro via openBrainDoc (same read path as retro-show).
+            const { doc } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const retros = Array.isArray(doc?.retros) ? doc.retros : [];
+            const retro = retros.find(r => r?.id === argv.retro);
+            if (!retro) {
+                const candidates = retros.map(r => r?.id).filter((id) => typeof id === 'string').slice(0, 8);
+                output.error(`Retro "${argv.retro}" not found in ${argv.doc}. ` +
+                    `Available ids (first 8): ${candidates.join(', ') || '(none)'}`);
+                process.exitCode = 1;
+                return;
+            }
+            if (retro.removed) {
+                output.error(`Retro "${argv.retro}" is tombstoned — cannot file tasks against a removed retro.`);
+                process.exitCode = 1;
+                return;
+            }
+            // Partition changes by status.
+            const changes = Array.isArray(retro.proposedChanges) ? retro.proposedChanges : [];
+            const agreed = changes.filter(c => c?.status === 'agreed');
+            const alreadyFiled = changes.filter(c => c?.status === 'filed');
+            const rejected = changes.filter(c => c?.status === 'rejected');
+            const stillProposed = changes.filter(c => c?.status === 'proposed' || c?.status === 'modified');
+            if (agreed.length === 0) {
+                if (output.isJsonMode()) {
+                    output.json({
+                        status: 'noop',
+                        docId: argv.doc,
+                        retroId: argv.retro,
+                        reason: 'no changes at status=agreed',
+                        counts: {
+                            total: changes.length,
+                            agreed: 0,
+                            alreadyFiled: alreadyFiled.length,
+                            rejected: rejected.length,
+                            stillProposed: stillProposed.length,
+                        },
+                    });
+                }
+                else {
+                    console.log('');
+                    console.log(`  No changes at status='agreed' in retro "${argv.retro}". Nothing to file.`);
+                    console.log('');
+                    console.log(`  Current status breakdown:`);
+                    console.log(`    total:         ${changes.length}`);
+                    console.log(`    agreed:        0 (ready to file)`);
+                    console.log(`    already filed: ${alreadyFiled.length}`);
+                    console.log(`    rejected:      ${rejected.length}`);
+                    console.log(`    still in discussion: ${stillProposed.length}`);
+                    console.log('');
+                    if (stillProposed.length > 0) {
+                        console.log(`  Changes still under discussion:`);
+                        for (const c of stillProposed)
+                            console.log(`    - ${c.id}: ${c.summary}`);
+                        console.log('');
+                        console.log(`  Other agents need to agree via "pop brain retro respond --to ${argv.retro} --vote ${stillProposed[0]?.id}=agree" before they can be filed.`);
+                    }
+                    console.log('');
+                }
+                return;
+            }
+            // Dry-run: print the plan and exit.
+            if (argv.dryRun) {
+                console.log('');
+                console.log(`  [DRY RUN] Would file ${agreed.length} task${agreed.length === 1 ? '' : 's'} for retro "${argv.retro}"`);
+                console.log('');
+                for (const change of agreed) {
+                    const { name, description } = buildTaskDescription(retro, change);
+                    console.log(`  === ${change.id} → new task ===`);
+                    console.log(`  name:        ${name}`);
+                    console.log(`  project:     ${argv.project}`);
+                    console.log(`  payout:      ${argv.payout} PT`);
+                    console.log(`  difficulty:  ${argv.difficulty}`);
+                    console.log(`  est hours:   ${argv.estHours}`);
+                    console.log(`  description: ${description.split('\n').slice(0, 3).join(' ').slice(0, 160)}...`);
+                    console.log('');
+                }
+                console.log(`  Already filed: ${alreadyFiled.length}  ·  rejected: ${rejected.length}  ·  still proposed: ${stillProposed.length}`);
+                console.log('');
+                console.log(`  Run without --dry-run to actually file the tasks.`);
+                console.log('');
+                return;
+            }
+            // Real run: for each agreed change, spawn `pop task create` and
+            // capture the resulting task id. Shelling out keeps this command
+            // decoupled from the task create plumbing (which has its own
+            // sponsored-tx + fee-limit logic we don't want to duplicate).
+            const cliPath = process.argv[1]; // dist/index.js, same entrypoint
+            const filed = [];
+            for (const change of agreed) {
+                const { name, description } = buildTaskDescription(retro, change);
+                const createArgs = [
+                    cliPath, 'task', 'create',
+                    '--force',
+                    '--project', argv.project,
+                    '--name', name,
+                    '--description', description,
+                    '--payout', String(argv.payout),
+                    '--difficulty', argv.difficulty,
+                    '--est-hours', String(argv.estHours),
+                    '--json',
+                    '-y',
+                ];
+                const res = (0, child_process_1.spawnSync)(process.execPath, createArgs, {
+                    encoding: 'utf8',
+                    env: process.env,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                if (res.status !== 0) {
+                    output.error(`pop task create failed for change ${change.id}: ${res.stderr || res.stdout}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(res.stdout);
+                }
+                catch (err) {
+                    output.error(`pop task create returned unparseable JSON for change ${change.id}: ${res.stdout}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                const taskId = parsed.taskId;
+                const txHash = parsed.txHash;
+                if (!taskId) {
+                    output.error(`pop task create for change ${change.id} returned no taskId: ${JSON.stringify(parsed)}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                // Flip the retro change's status to 'filed' with filedTaskId.
+                await (0, brain_ops_1.routedDispatch)({
+                    type: 'updateChangeStatus',
+                    docId: argv.doc,
+                    retroId: argv.retro,
+                    changeId: change.id,
+                    newStatus: 'filed',
+                    filedTaskId: String(taskId),
+                });
+                filed.push({ changeId: change.id, taskId: String(taskId), txHash });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    retroId: argv.retro,
+                    filed,
+                    filedCount: filed.length,
+                    skippedAlreadyFiled: alreadyFiled.length,
+                    skippedRejected: rejected.length,
+                    skippedStillProposed: stillProposed.length,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Filed ${filed.length} task${filed.length === 1 ? '' : 's'} from retro "${argv.retro}"`);
+                console.log('');
+                for (const f of filed) {
+                    console.log(`  ✓ ${f.changeId} → task #${f.taskId}`);
+                    console.log(`    tx: ${f.txHash}`);
+                }
+                console.log('');
+                if (alreadyFiled.length > 0)
+                    console.log(`  (${alreadyFiled.length} previously filed — skipped)`);
+                if (rejected.length > 0)
+                    console.log(`  (${rejected.length} rejected — skipped)`);
+                if (stillProposed.length > 0)
+                    console.log(`  (${stillProposed.length} still under discussion — skipped)`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/retro-list.d.ts

@@ -0,0 +1,28 @@
+/**
+ * pop brain retro list — list retros in pop.brain.retros.
+ *
+ * Filters:
+ *   --status open|discussed|shipped    only show retros at this status
+ *   --doc <doc-id>                     default: pop.brain.retros
+ *
+ * JSON mode emits a machine-readable array; human mode prints a table.
+ *
+ * Always reads in-process (no daemon routing) because this is a
+ * pure-read path and concurrent reads against the helia blockstore
+ * work fine alongside a running daemon (HB#323 verification).
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+import type { RetroStatus } from '../../lib/brain-projections';
+interface RetroListArgs {
+    doc: string;
+    status?: RetroStatus;
+}
+export declare const retroListHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        status: RetroStatus | undefined;
+    }>;
+    handler: (argv: ArgumentsCamelCase<RetroListArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/retro-list.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * pop brain retro list — list retros in pop.brain.retros.
+ *
+ * Filters:
+ *   --status open|discussed|shipped    only show retros at this status
+ *   --doc <doc-id>                     default: pop.brain.retros
+ *
+ * JSON mode emits a machine-readable array; human mode prints a table.
+ *
+ * Always reads in-process (no daemon routing) because this is a
+ * pure-read path and concurrent reads against the helia blockstore
+ * work fine alongside a running daemon (HB#323 verification).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retroListHandler = void 0;
+const brain_1 = require("../../lib/brain");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+const VALID_STATUSES = ['open', 'discussed', 'shipped'];
+exports.retroListHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (default: pop.brain.retros)',
+        type: 'string',
+        default: 'pop.brain.retros',
+    })
+        .option('status', {
+        describe: 'Filter by retro status',
+        type: 'string',
+        choices: VALID_STATUSES,
+    }),
+    handler: async (argv) => {
+        try {
+            const { doc } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const retros = Array.isArray(doc?.retros) ? doc.retros : [];
+            const live = retros.filter(r => r?.removed !== true);
+            const filtered = argv.status
+                ? live.filter(r => r?.status === argv.status)
+                : live;
+            if (output.isJsonMode()) {
+                output.json({
+                    docId: argv.doc,
+                    statusFilter: argv.status ?? null,
+                    count: filtered.length,
+                    retros: filtered.map(r => ({
+                        id: r.id,
+                        author: r.author,
+                        hb: r.hb,
+                        window: r.window,
+                        status: r.status ?? 'open',
+                        changeCount: Array.isArray(r.proposedChanges) ? r.proposedChanges.length : 0,
+                        discussionCount: Array.isArray(r.discussion) ? r.discussion.length : 0,
+                        createdAt: r.createdAt,
+                        closedAt: r.closedAt,
+                    })),
+                });
+                return;
+            }
+            if (filtered.length === 0) {
+                console.log(argv.status
+                    ? `No retros in ${argv.doc} with status='${argv.status}'.`
+                    : `No retros in ${argv.doc} yet. Start one with: pop brain retro start --window-from N --window-to M --changes-file <path>`);
+                return;
+            }
+            console.log('');
+            console.log(`  Retros in ${argv.doc}${argv.status ? ` (status=${argv.status})` : ''}`);
+            console.log('');
+            console.log('  ID                              Author         Window       Status     Changes');
+            console.log('  ' + '─'.repeat(80));
+            for (const r of filtered) {
+                const id = (r.id ?? '(no id)').padEnd(32).slice(0, 32);
+                const author = (r.author ?? '(unknown)').slice(0, 12).padEnd(14);
+                const windowLabel = r.window
+                    ? `#${r.window.from ?? '?'}..#${r.window.to ?? '?'}`.padEnd(12)
+                    : '(no window)'.padEnd(12);
+                const status = (r.status ?? 'open').padEnd(10);
+                const changeCount = Array.isArray(r.proposedChanges) ? r.proposedChanges.length : 0;
+                console.log(`  ${id}${author}${windowLabel}${status} ${changeCount}`);
+            }
+            console.log('');
+            console.log(`  ${filtered.length} retro${filtered.length === 1 ? '' : 's'}. Run "pop brain retro show <id>" for full detail.`);
+            console.log('');
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/retro-mark-change.d.ts

@@ -0,0 +1,58 @@
+/**
+ * pop brain retro mark-change — manually set a proposed change's status.
+ *
+ * The retro workflow separates VOTES (discussion-level signals) from
+ * CHANGE STATUS (decision). Other agents respond via `pop brain retro
+ * respond --vote change-1=agree`, which records a vote entry in the
+ * discussion array — NOT a status change on the proposed change.
+ *
+ * When the retro author (or a designated file-tasks runner) decides a
+ * change has enough agreement, they explicitly flip its status to
+ * 'agreed' with this command. Then `pop brain retro file-tasks` picks
+ * up the change and converts it into a real on-chain task.
+ *
+ * MVP design: quorum interpretation is human-judged per the task spec
+ * (#344 "out of scope: cross-agent voting quorum logic"). This command
+ * is the escape hatch that lets operators make the call explicitly.
+ *
+ * Usage:
+ *
+ *   pop brain retro mark-change retro-327-... change-1 --status agreed
+ *   pop brain retro mark-change retro-327-... change-2 --status rejected
+ *   pop brain retro mark-change retro-327-... change-3 --status modified
+ *
+ * Status values: proposed, agreed, modified, rejected, filed.
+ * Setting status to 'filed' manually is unusual — prefer `file-tasks`,
+ * which records the filedTaskId for you. Allowed here for emergency
+ * manual reconciliation.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+import type { RetroChangeStatus } from '../../lib/brain-projections';
+interface MarkChangeArgs {
+    doc: string;
+    retroId: string;
+    changeId: string;
+    status: RetroChangeStatus;
+    filedTaskId?: string;
+    'idempotency-key'?: string;
+    'no-idempotency'?: boolean;
+}
+export declare const retroMarkChangeHandler: {
+    builder: (yargs: Argv) => Argv<import("yargs").Defined<{
+        "retro-id": string | undefined;
+    } & {
+        "change-id": string | undefined;
+    } & {
+        doc: string;
+    } & {
+        status: RetroChangeStatus;
+    } & {
+        "filed-task-id": string | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }, "retro-id" | "change-id">>;
+    handler: (argv: ArgumentsCamelCase<MarkChangeArgs>) => Promise<void>;
+};
+export {};