@cryptolibertus/pi-peer 0.3.2 → 0.3.3

package/README.md

@@ -12,7 +12,7 @@ pi install ./packages/pi-peer
 
 ## What it adds
 
-- `/peer help|setup|doctor|status|list|init|reconnect|resume|cancel|send|get|await|goal`
+- `/peer help|setup|doctor|status|list|init|reconnect|resume|cancel|send|get|await|goal|scout`
 - `peer_list`, `peer_send`, `peer_get`, `peer_await`, and `peer_progress` tools
 - Local peer discovery and transport using project `.pi/peers.json`
 - Protocol compatibility metadata (`protocolVersion`, min/max compatible versions), peer manifests, capabilities, and trust summaries in descriptors/status/list output
@@ -32,7 +32,7 @@ pi install ./packages/pi-peer
 
 ## Flat goal board
 
-`/peer goal` provides a local blackboard for flat peer collaboration. Peers can create a shared goal, post findings/tasks/handoffs, claim read or write leases, object, resolve objections, and vote without a planner assigning every step.
+`/peer goal` provides a local blackboard for flat peer collaboration. Peers can create a shared goal, post findings/tasks/proposals/handoffs, claim read or write leases, object, resolve objections, scout for proactive next steps, and vote without a planner assigning every step.
 
 Useful commands (long form and short aliases):
 
@@ -42,6 +42,8 @@ Useful commands (long form and short aliases):
 /peer send worker "Fix PR waiting path" --goal <goal-id> --claim extensions/symphony/index.ts,test/pr-watcher-runtime.test.mjs --no-await
 /peer progress "tests are running" --phase verification
 /peer goal finding <goal-id> "PR auto-close can close before merge" --path extensions/symphony/index.ts
+/peer scout <goal-id> --limit 5
+/peer goal propose <goal-id> "Add a read-only reviewer before closing" --path extensions/symphony/index.ts
 /peer goal claim <goal-id> "Fix PR waiting path" --mode write --path extensions/symphony/index.ts,test/pr-watcher-runtime.test.mjs
 /peer goal heartbeat <goal-id> <claim-event-id> "still working after reconnect" --stale-after-ms 900000
 /peer goal release <goal-id> <claim-event-id> "worker lane complete"
@@ -50,11 +52,11 @@ Useful commands (long form and short aliases):
 /peer get <goal-id>
 ```
 
-Short aliases keep common board updates terse: `/peer goals`/`/peer ls`, `/peer current`, `/peer fanout`, `/peer take`/`/peer claim`, `/peer complete`/`/peer done`, `/peer objection`/`/peer block`, `/peer unblock`, `/peer note`, `/peer finding`, `/peer ping`/`/peer heartbeat`, `/peer drop`/`/peer release`, `/peer pass`, `/peer fail`, `/peer vote`, and `/peer close` map to the corresponding `/peer goal ...` actions.
+Short aliases keep common board updates terse: `/peer goals`/`/peer ls`, `/peer current`, `/peer scout`, `/peer fanout`, `/peer proposal`/`/peer propose`, `/peer take`/`/peer claim`, `/peer complete`/`/peer done`, `/peer objection`/`/peer block`, `/peer unblock`, `/peer note`, `/peer finding`, `/peer ping`/`/peer heartbeat`, `/peer drop`/`/peer release`, `/peer pass`, `/peer fail`, `/peer vote`, and `/peer close` map to the corresponding `/peer goal ...` actions.
 
 The board is stored locally at `.pi/peer-goals.json`; outbound message snapshots are stored in `.pi/peer-messages.json` so restarted planners can still inspect disconnected historical tasks. Mutating goal-board operations take a short local lock before load/modify/save so concurrent peer appends do not drop events. `/peer send --goal <goal-id> --claim <path[,path]>` and the `peer_send` tool's `goalId`/`claimedPaths` parameters link long-running peer tasks to the board: Symphony records a task, claims overlapping write paths before dispatch, injects goal/heartbeat instructions into the peer prompt, keeps the claim alive with local heartbeats, and releases the claim after the peer returns a final response. `/peer goal fanout` turns a goal into role-specific peer lanes, while `peer_progress` reports checkpoints from an inbound long-running task. Active write claims conflict on overlapping paths; released, stale, or expired claims are kept visible but inactive. Claims become stale after 45 minutes without a heartbeat unless the claim or heartbeat sets `--stale-after-ms`.
 
-Normal goal closure requires at least one current passing vote, no current failed votes, no unresolved blocking objections, and no active write claims. Stale write claims no longer block closure or new overlapping claims; use `/peer goal heartbeat` to revive work after a reconnect and `--force` only when intentionally overriding the readiness gate. Goal-linked tasks validate final handoff headings (`Status`, `Files changed`, `Verification`, `Blockers/risks`, `Safe for review`); missing sections create a blocking objection while still releasing the write claim. For multi-part work, use the fan-out gate: list peers, create/reuse a goal, delegate research/review/worker lanes, and include `Fan-out used: yes/no` plus peer handles in the final answer.
+Normal goal closure requires at least one current passing vote, no current failed votes, no unresolved blocking objections, and no active write claims. Open proposals are intentionally non-blocking: they let peers show initiative without freezing closure. Stale write claims no longer block closure or new overlapping claims; use `/peer goal heartbeat` to revive work after a reconnect and `--force` only when intentionally overriding the readiness gate. Goal-linked tasks validate final handoff headings (`Status`, `Files changed`, `Verification`, `Blockers/risks`, `Safe for review`); missing sections create a blocking objection while still releasing the write claim. For multi-part work, use the fan-out gate: list peers, create/reuse a goal, delegate research/review/worker lanes, and include `Fan-out used: yes/no` plus peer handles in the final answer.
 
 ## Package checks
 

package/extensions/pi-peer/index.ts

@@ -6,7 +6,7 @@ import { installPeerRuntimeLifecycle } from "../../src/peers/extension-lifecycle
 import { initPeerConfig } from "../../src/peers/config.mjs";
 import { formatPeerCommandError, formatPeerHelp, formatPeerInitResult, parsePeerCommand } from "../../src/peers/command.mjs";
 import { createPeerRuntime, getPeerRuntimeValue } from "../../src/peers/runtime.mjs";
-import { appendPeerGoalEvent, beginPeerGoalTask, closePeerGoal, completePeerGoalTask, createPeerGoal, formatPeerGoal, formatPeerGoalList, loadPeerGoalBoard, recordPeerGoalTaskDispatch } from "../../src/peers/goal-board.mjs";
+import { appendPeerGoalEvent, beginPeerGoalTask, closePeerGoal, completePeerGoalTask, createPeerGoal, formatPeerGoal, formatPeerGoalList, formatPeerGoalScout, loadPeerGoalBoard, recordPeerGoalTaskDispatch } from "../../src/peers/goal-board.mjs";
 import { collectPeerRuntimeStatus, derivePeerDoctorReport, formatPeerDoctorText, formatPeerStatusLines, formatPeerStatusText } from "../../src/peers/status.mjs";
 import {
   peerAwaitToolResult,
@@ -51,7 +51,7 @@ export default function piPeerExtension(pi: ExtensionAPI) {
 
   pi.registerCommand("peer", {
     description: "Pi-to-Pi peers: setup, doctor, status, list, send, get, await, progress, goal",
-    getArgumentCompletions: (prefix: string) => ["help", "status", "list", "init", "setup", "doctor", "reconnect", "resume", "cancel", "send", "get", "await", "progress", "goal", "goals", "ls", "current", "fanout", "claim", "take", "done", "complete", "block", "objection", "unblock", "pass", "fail"]
+    getArgumentCompletions: (prefix: string) => ["help", "status", "list", "init", "setup", "doctor", "reconnect", "resume", "cancel", "send", "get", "await", "progress", "goal", "goals", "ls", "current", "scout", "fanout", "proposal", "propose", "claim", "take", "done", "complete", "block", "objection", "unblock", "pass", "fail"]
       .filter((value) => value.startsWith(prefix))
       .map((value) => ({ value, label: value })),
     handler: async (rawArgs, ctx) => {
@@ -409,8 +409,9 @@ async function handlePeerGoalCommand(parsed: any, ctx: any, runtime: any) {
     if (!goal) throw new Error(goalId ? `peer goal ${goalId} not found` : "no current peer goal");
     return formatPeerGoal(goal);
   }
+  if (parsed.goalAction === "scout") return formatPeerGoalScout(await loadPeerGoalBoard(root), { goalId: parsed.goalId, limit: parsed.limit, includeClosed: parsed.includeClosed });
   if (parsed.goalAction === "fanout") return handlePeerGoalFanout(parsed, ctx, runtime, peerId);
-  if (["task", "finding", "handoff", "note"].includes(parsed.goalAction)) {
+  if (["task", "finding", "proposal", "propose", "handoff", "note"].includes(parsed.goalAction)) {
     const result = await appendPeerGoalEvent(root, parsed.goalId, {
       type: parsed.eventType,
       peerId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptolibertus/pi-peer",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Pi package for local Pi-to-Pi peer messaging, slash commands, tools, and runtime transport.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test ../../test/peer-*.test.mjs",
+    "test": "node --test test/peer-*.test.mjs",
     "check": "npm test && npm run check:pack",
     "check:pack": "npm pack --dry-run",
     "smoke:pack": "npm run check:pack",

package/src/peers/command.mjs

@@ -7,6 +7,9 @@ const PEER_GOAL_ALIASES = Object.freeze({
   ls: ["list"],
   current: ["show"],
   fanout: ["fanout"],
+  scout: ["scout"],
+  proposal: ["proposal"],
+  propose: ["propose"],
   claim: ["claim"],
   take: ["claim"],
   heartbeat: ["heartbeat"],
@@ -136,11 +139,12 @@ export function formatPeerHelp() {
     "- `/peer cancel <message-id> [reason]` — mark a queued/running/disconnected peer message cancelled",
     "- `/peer send <peer> <prompt> [--no-await] [--intent ask] [--goal <goal-id>] [--claim <path[,path]>] [--timeout-ms <ms>] [--allow-self]` — send a prompt-first peer message",
     "- `/peer progress <summary> [--status running] [--phase <name>]` — send a structured checkpoint from an inbound long-running peer task",
-    "- `/peer goals|ls`, `/peer current [goal-id]`, `/peer fanout`, `/peer take|claim`, `/peer complete|done`, `/peer objection|block`, `/peer unblock`, `/peer ping`, `/peer drop`, `/peer pass|fail` — short goal-board aliases",
+    "- `/peer goals|ls`, `/peer current [goal-id]`, `/peer scout [goal-id]`, `/peer fanout`, `/peer propose`, `/peer take|claim`, `/peer complete|done`, `/peer objection|block`, `/peer unblock`, `/peer ping`, `/peer drop`, `/peer pass|fail` — short goal-board aliases",
     "- `/peer goal create <objective> [--constraint <a,b>]` — start a flat shared goal board",
-    "- `/peer goal list|show [goal-id]` — inspect peer goals, active claims, blockers, and votes",
+    "- `/peer goal list|show [goal-id]` — inspect peer goals, active claims, blockers, proposals, and votes",
     "- `/peer goal fanout <goal-id> <objective> --peer <id[,id]> [--path <a,b>] [--send] [--no-await]` — plan or dispatch role-specific peer lanes",
-    "- `/peer goal task|finding|handoff|note <goal-id> <summary> [--path <a,b>] [--status done]` — post goal-board events",
+    "- `/peer goal scout [goal-id] [--limit <n>] [--include-closed]` — read-only proactive suggestions for what peers could do next",
+    "- `/peer goal task|finding|proposal|handoff|note <goal-id> <summary> [--path <a,b>] [--status done]` — post goal-board events",
     "- `/peer goal claim <goal-id> <task> --mode write --path <a,b> [--ttl-ms <ms>] [--stale-after-ms <ms>]` — lease work without hierarchy",
     "- `/peer goal heartbeat <goal-id> <claim-event-id> [summary] [--ttl-ms <ms>] [--stale-after-ms <ms>]` — refresh a live or stale claim",
     "- `/peer goal release <goal-id> <claim-event-id> [summary]` — release a claimed lane",
@@ -171,6 +175,7 @@ function parsePeerGoalCommand(parsed, flags, positionals) {
     return { ...withAction, objective, constraints: listFlag(flags.constraint || flags.constraints) };
   }
   if (action === "show") return { ...withAction, goalId: rest[0] };
+  if (action === "scout") return { ...withAction, goalId: rest[0], limit: positiveIntegerFlag(flags.limit), includeClosed: flagEnabled(flags.includeClosed) };
   if (action === "fanout") {
     const goalId = rest[0];
     const objective = rest.slice(1).join(" ").trim();
@@ -189,11 +194,11 @@ function parsePeerGoalCommand(parsed, flags, positionals) {
       staleAfterMs: positiveIntegerFlag(flags.staleAfterMs),
     };
   }
-  if (["task", "finding", "handoff", "note"].includes(action)) {
+  if (["task", "finding", "proposal", "propose", "handoff", "note"].includes(action)) {
     const goalId = rest[0];
     const summary = rest.slice(1).join(" ").trim();
     if (!goalId || !summary) return { ...withAction, error: `/peer goal ${action} requires <goal-id> <summary>` };
-    return { ...withAction, goalId, eventType: action === "task" ? "task" : action, summary, paths: listFlag(flags.path || flags.paths), severity: stringFlag(flags.severity, undefined), taskId: stringFlag(flags.taskId, undefined), status: stringFlag(flags.status, undefined) };
+    return { ...withAction, goalId, eventType: action === "propose" ? "proposal" : action, summary, paths: listFlag(flags.path || flags.paths), severity: stringFlag(flags.severity, undefined), taskId: stringFlag(flags.taskId, undefined), status: stringFlag(flags.status, undefined) };
   }
   if (action === "claim") {
     if (flagEnabled(flags.write) && flags.mode === undefined) flags.mode = "write";

package/src/peers/goal-board.mjs

@@ -5,7 +5,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 export const PEER_GOAL_BOARD_RELATIVE_PATH = ".pi/peer-goals.json";
 
-const EVENT_TYPES = new Set(["finding", "task", "claim", "release", "heartbeat", "objection", "resolve", "vote", "handoff", "note"]);
+const EVENT_TYPES = new Set(["finding", "task", "proposal", "claim", "release", "heartbeat", "objection", "resolve", "vote", "handoff", "note"]);
 const BLOCKING_SEVERITIES = new Set(["blocking", "blocker", "critical"]);
 const VOTE_VERDICTS = new Set(["pass", "fail", "pass-with-risks"]);
 const DEFAULT_GOAL_CLAIM_STALE_MS = 45 * 60 * 1000;
@@ -66,6 +66,7 @@ export async function appendPeerGoalEvent(root, goalId, eventInput = {}) {
     const goal = resolveGoal(board, goalId);
     const event = normalizeEvent(eventInput);
     if (event.type === "claim") validateClaim(goal, event);
+    if (event.type === "proposal") validateProposal(event);
     if (event.type === "release") validateRelease(goal, event);
     if (event.type === "heartbeat") validateHeartbeat(goal, event);
     goal.events.push(event);
@@ -172,6 +173,8 @@ export function deriveGoalState(goal, options = {}) {
   const blockingObjections = events
     .filter((event) => event.type === "objection" && isBlockingSeverity(event.severity) && !resolvedIds.has(event.id))
     .map(projectEventSummary);
+  const proposals = events.filter((event) => event.type === "proposal").map(projectEventSummary);
+  const openProposals = proposals.filter((event) => !resolvedIds.has(event.id));
   const votes = events.filter((event) => event.type === "vote").map(projectEventSummary);
   const currentVotes = currentPeerVotes(votes);
   const failedVotes = currentVotes.filter((vote) => vote.verdict === "fail");
@@ -187,6 +190,8 @@ export function deriveGoalState(goal, options = {}) {
     staleClaims,
     releasedClaims,
     blockingObjections,
+    proposals,
+    openProposals,
     votes,
     currentVotes,
     failedVotes,
@@ -205,10 +210,62 @@ export function formatPeerGoalList(board) {
     if (state.activeClaims.length) bits.push(`${state.activeClaims.length} active claim${state.activeClaims.length === 1 ? "" : "s"}`);
     if (state.staleClaims.length) bits.push(`${state.staleClaims.length} stale claim${state.staleClaims.length === 1 ? "" : "s"}`);
     if (state.blockingObjections.length) bits.push(`${state.blockingObjections.length} blocker${state.blockingObjections.length === 1 ? "" : "s"}`);
+    if (state.openProposals.length) bits.push(`${state.openProposals.length} proposal${state.openProposals.length === 1 ? "" : "s"}`);
     return bits.join(" · ");
   }).join("\n");
 }
 
+export function formatPeerGoalScout(board, options = {}) {
+  const suggestions = derivePeerGoalScoutSuggestions(board, options);
+  if (!suggestions.length) return "No proactive scout suggestions. Open goals look idle-safe or there are no matching goals.";
+  const limit = positiveNumber(options.limit) || suggestions.length;
+  const lines = ["# Peer Scout", "", "Proactive suggestions (read-only):"];
+  for (const suggestion of suggestions.slice(0, limit)) {
+    const pathText = suggestion.paths?.length ? ` · paths: ${suggestion.paths.join(", ")}` : "";
+    lines.push(`- ${suggestion.priority} · ${suggestion.goalId} · ${suggestion.kind}: ${suggestion.summary}${pathText}`);
+  }
+  lines.push("", "Next: post one with `/peer goal propose <goal-id> <summary>` or claim safe work with `/peer goal claim <goal-id> <task> --mode read|write --path <path>`. Scout does not mutate the board.");
+  return lines.join("\n");
+}
+
+export function derivePeerGoalScoutSuggestions(board, options = {}) {
+  const normalized = normalizeBoard(board);
+  const includeClosed = options.includeClosed === true;
+  const requestedGoalId = cleanText(options.goalId);
+  const goals = Object.values(normalized.goals)
+    .filter((goal) => (!requestedGoalId || goal.id === requestedGoalId) && (includeClosed || goal.status !== "closed"))
+    .sort((a, b) => String(b.updatedAt || "").localeCompare(String(a.updatedAt || "")));
+  const suggestions = [];
+  for (const goal of goals) {
+    const state = deriveGoalState(goal);
+    const push = (priority, kind, summary, extra = {}) => suggestions.push(stripEmpty({ goalId: goal.id, priority, kind, summary, ...extra }));
+    if (state.blockingObjections.length) {
+      push("P0", "blocker", `Resolve ${state.blockingObjections.length} blocking objection${state.blockingObjections.length === 1 ? "" : "s"} before more work.`, { paths: uniqueEventPaths(state.blockingObjections) });
+      continue;
+    }
+    if (state.failedVotes.length) {
+      push("P0", "failed-vote", `Address failed vote from ${state.failedVotes.map((vote) => vote.peerId || vote.id).join(", ")}.`);
+      continue;
+    }
+    if (state.staleClaims.length) {
+      push("P1", "stale-claim", `Ask owners to heartbeat or release ${state.staleClaims.length} stale claim${state.staleClaims.length === 1 ? "" : "s"}.`, { paths: uniqueEventPaths(state.staleClaims) });
+    }
+    if (state.openProposals.length) {
+      push("P1", "open-proposal", `Triage ${state.openProposals.length} open proposal${state.openProposals.length === 1 ? "" : "s"}; claim one or resolve it if obsolete.`, { paths: uniqueEventPaths(state.openProposals) });
+    }
+    if (state.readyToClose) {
+      push("P1", "close", "Goal satisfies closure gates; close it or record a final note.");
+      continue;
+    }
+    if (!state.activeClaims.length && !state.tasks.length && !state.openProposals.length) {
+      push("P2", "next-step", "No active work yet; propose a research, review, or implementation lane.");
+    } else if (!state.currentVotes.length && !state.activeWriteClaims.length) {
+      push("P2", "review", "No current peer vote; ask a peer for read-only review or record a pass/fail vote.");
+    }
+  }
+  return suggestions;
+}
+
 export function formatPeerGoal(goal) {
   const state = goal && Array.isArray(goal.activeClaims) && Array.isArray(goal.expiredClaims) && Array.isArray(goal.staleClaims) ? goal : deriveGoalState(goal);
   const lines = [
@@ -233,6 +290,10 @@ export function formatPeerGoal(goal) {
     lines.push("", "Blocking objections:");
     for (const objection of state.blockingObjections) lines.push(`- ${objection.id} · ${objection.peerId} · ${objection.summary}`);
   }
+  if (state.openProposals.length) {
+    lines.push("", "Open proposals:");
+    for (const proposal of state.openProposals.slice(-8)) lines.push(`- ${proposal.id} · ${proposal.peerId} · ${proposal.summary}${proposal.paths?.length ? ` · ${proposal.paths.join(", ")}` : ""}`);
+  }
   if (state.currentVotes.length) {
     lines.push("", "Votes:");
     for (const vote of state.currentVotes.slice(-8)) lines.push(`- ${vote.peerId}: ${vote.verdict}${vote.confidence !== undefined ? ` (${vote.confidence})` : ""}${vote.summary ? ` — ${vote.summary}` : ""}`);
@@ -257,6 +318,10 @@ function validateClaim(goal, event) {
   }
 }
 
+function validateProposal(event) {
+  if (!event.summary) throw new Error("peer goal proposal requires a summary");
+}
+
 function validateRelease(goal, event) {
   if (!event.resolves) throw new Error("peer goal release requires a claim event id");
   const state = deriveGoalState(goal);
@@ -269,6 +334,10 @@ function validateHeartbeat(goal, event) {
   const state = deriveGoalState(goal);
   const claim = state.activeClaims.find((item) => item.id === event.resolves) || state.staleClaims.find((item) => item.id === event.resolves) || state.expiredClaims.find((item) => item.id === event.resolves);
   if (!claim) throw new Error(`peer goal heartbeat target ${event.resolves} is not an active, stale, or expired claim`);
+  if (claim.mode === "write") {
+    const conflicts = state.activeClaims.filter((item) => item.id !== claim.id && item.mode === "write" && pathsOverlap(claim.paths || [], item.paths || []));
+    if (conflicts.length) throw new Error(`heartbeat conflicts with active write claim ${conflicts.map((item) => item.id).join(", ")}`);
+  }
 }
 
 function validateGoalReadyToClose(state) {
@@ -410,6 +479,10 @@ function currentPeerVotes(votes) {
   return [...byPeer.values()];
 }
 
+function uniqueEventPaths(events) {
+  return [...new Set(events.flatMap((event) => Array.isArray(event.paths) ? event.paths : []))];
+}
+
 async function updatePeerGoalBoard(root, updater) {
   const path = goalBoardPath(root);
   await mkdir(dirname(path), { recursive: true });
@@ -460,11 +533,18 @@ function goalBoardPath(root) {
 }
 
 function pathsOverlap(a, b) {
-  return a.some((left) => b.some((right) => left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)));
+  return a.some((left) => b.some((right) => left === "." || right === "." || left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)));
 }
 
 function normalizePaths(value) {
-  return [...new Set(normalizeList(value).map((item) => item.replace(/^\.\//, "").replace(/\/+/g, "/").replace(/\/$/, "")).filter(Boolean))];
+  return [...new Set(normalizeList(value).map(normalizePath).filter(Boolean))];
+}
+
+function normalizePath(value) {
+  let path = cleanText(value).replace(/\/+/g, "/");
+  if (path === "" || path === "." || path === "/") return ".";
+  path = path.replace(/^\.\//, "").replace(/\/$/, "");
+  return path === "" || path === "." || path === "/" ? "." : path;
 }
 
 function normalizeList(value) {