@cryptolibertus/pi-peer 0.4.0 → 0.5.0

package/README.md

@@ -17,7 +17,7 @@ pi install ./packages/pi-peer
 - Local peer discovery and transport using project `.pi/peers.json`
 - Repo-scoped discovery: only Pi sessions in the same git repo/project appear as local peers
 - Idle watcher daemon: idle peers nudge stuck inbound activations and proactively inspect open goal-board work
-- Persona-aware scout routing: goal-board suggestions include recommended lanes, preferred roles, claim mode, and rationale so proactive peers can choose work that fits their role/persona
+- Persona-aware scout routing: goal-board suggestions include recommended lanes, preferred roles, claim mode, work keys, and rationale so proactive peers can self-select complementary work that fits their role/persona
 - Protocol compatibility metadata (`protocolVersion`, min/max compatible versions), peer manifests, capabilities, and trust summaries in descriptors/status/list output
 - `PI_PEER_ID` runtime override for running multiple local Pi sessions
 - `pi-peer-publish` skill for safe npm release checks, version bumping, tag push, publish, and verification
@@ -58,7 +58,7 @@ Useful commands (long form and short aliases):
 
 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. Each goal-linked dispatch also gets a semantic work key (`goalId | lane | objective | mode | paths`) so duplicate read/review/research lanes are leased just like write paths; pass `--key <work-key>` / `workKey` for an explicit fingerprint and `--duplicate-policy allow-parallel` only when independent second opinions are intentional. The default dispatch policy is `reuse`, so a matching active work key returns the existing claim/task handle instead of starting another peer. `/peer goal fanout` turns a goal into role-specific peer lanes, while `peer_progress` reports checkpoints from an inbound long-running task. Scout suggestions are persona-aware: they surface a recommended lane (`research`, `review`, `coordination`, etc.), preferred roles, a safe default claim mode, rationale, and suppress suggestions already covered by active work keys. Active write claims conflict on overlapping paths; active semantic claims conflict on matching work keys; 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`.
+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. Each goal-linked dispatch also gets a semantic work key (`goalId | lane | objective | mode | paths`) so duplicate read/review/research lanes are leased just like write paths; pass `--key <work-key>` / `workKey` for an explicit fingerprint and `--duplicate-policy allow-parallel` only when independent second opinions are intentional. The default dispatch policy is `reuse`, so a matching active work key returns the existing claim/task handle instead of starting another peer. `/peer goal fanout` turns a goal into role-specific peer lanes, while `peer_progress` reports checkpoints from an inbound long-running task. Scout suggestions are persona-aware: they surface a recommended lane (`research`, `review`, `implementation`, `coordination`, etc.), preferred roles, a safe default claim mode, a stable work key, rationale, and suppress suggestions already covered by active work keys. `/peer scout` prints the exact work key and a copyable `claim:` command for each read-only suggestion, so idle peers can claim the same semantic lane the scout is using instead of inventing generic seed keys. Empty goals emit multiple lane-specific read-only suggestions so idle peers can self-select research, review/QA, or implementation-planning work instead of waiting for a planner to assign lanes. Lane-tagged proposals (for example `/peer goal propose <goal> "Check package contents" --lane review --key review:package-contents`) become matching scout suggestions that reuse the proposal work key, letting the next suitable peer claim or review that proposed lane and suppress duplicate suggestions while the lane is active. Active write claims conflict on overlapping paths; active semantic claims conflict on matching work keys; released, stale, or expired claims are kept visible but inactive. Completed goal-linked tasks are shown with their handoff status instead of remaining visually stuck as `running`. 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. 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptolibertus/pi-peer",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi package for local Pi-to-Pi peer messaging, slash commands, tools, and runtime transport.",
   "type": "module",
   "license": "MIT",

package/src/peers/command.mjs

@@ -146,8 +146,8 @@ export function formatPeerHelp() {
     "- `/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, 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 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 scout [goal-id] [--limit <n>] [--include-closed]` — read-only proactive suggestions with exact work keys and copyable claim commands for what peers could do next",
+    "- `/peer goal task|finding|proposal|handoff|note <goal-id> <summary> [--path <a,b>] [--lane research|review|implementation] [--status done]` — post goal-board events; lane-tagged proposals become scout suggestions peers can self-select",
     "- `/peer goal claim <goal-id> <task> --mode read|write --path <a,b> [--key <work-key>] [--duplicate-policy error|allow-parallel] [--ttl-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",

package/src/peers/goal-board.mjs

@@ -16,9 +16,14 @@ const SCOUT_LANES = Object.freeze({
   "stale-claim": { recommendedLane: "coordination", preferredRoles: ["planner", "coordinator"], claimMode: "read", suggestedIntent: "coordinate", rationale: "Stale claims need owner follow-up or release, not duplicate writes." },
   "open-proposal": { recommendedLane: "coordination", preferredRoles: ["planner", "coordinator", "reviewer"], claimMode: "read", suggestedIntent: "review", rationale: "Open proposals need triage into accept, defer, or resolve decisions." },
   close: { recommendedLane: "coordination", preferredRoles: ["planner", "coordinator", "reviewer"], claimMode: "read", suggestedIntent: "coordinate", rationale: "Ready goals need final closure checks and a concise handoff." },
-  "next-step": { recommendedLane: "research", preferredRoles: ["researcher", "reviewer", "planner", "coordinator", "worker"], claimMode: "read", suggestedIntent: "review", rationale: "Empty goals benefit from a read-only lane before write claims." },
+  "next-step": { recommendedLane: "research", preferredRoles: ["researcher", "reviewer", "planner", "coordinator"], claimMode: "read", suggestedIntent: "review", rationale: "Empty goals benefit from peers self-selecting read-only lanes before write claims." },
   review: { recommendedLane: "review", preferredRoles: ["reviewer", "qa", "coordinator", "planner"], claimMode: "read", suggestedIntent: "review", rationale: "Goals without current votes need read-only validation before closure." },
 });
+const STARTUP_SCOUT_LANES = Object.freeze([
+  { lane: "research", preferredRoles: ["researcher", "planner", "coordinator"], summary: "No active work yet; self-select a research lane to map risks, options, and next moves." },
+  { lane: "review", preferredRoles: ["reviewer", "qa", "planner", "coordinator"], summary: "No active work yet; self-select a read-only review/QA lane to validate the plan and risks." },
+  { lane: "implementation", preferredRoles: ["worker"], summary: "No active work yet; self-select an implementation-planning lane, then claim write paths only after naming them." },
+]);
 const GOAL_BOARD_LOCK_STALE_MS = 30_000;
 const GOAL_BOARD_LOCK_RETRY_MS = 10;
 const GOAL_BOARD_LOCK_TIMEOUT_MS = 5_000;
@@ -243,7 +248,7 @@ export function deriveGoalState(goal, options = {}) {
   const failedVotes = currentVotes.filter((vote) => vote.verdict === "fail");
   const passingVotes = currentVotes.filter((vote) => vote.verdict === "pass" || vote.verdict === "pass-with-risks");
   const activeWriteClaims = activeClaims.filter((claim) => claim.mode === "write");
-  const tasks = events.filter((event) => event.type === "task").map(projectEventSummary);
+  const tasks = events.filter((event) => event.type === "task").map((event) => projectTaskSummary(event, events));
   return {
     ...goal,
     events,
@@ -286,9 +291,12 @@ export function formatPeerGoalScout(board, options = {}) {
   for (const suggestion of suggestions.slice(0, limit)) {
     const pathText = suggestion.paths?.length ? ` · paths: ${suggestion.paths.join(", ")}` : "";
     const laneText = suggestion.recommendedLane ? ` · lane: ${suggestion.recommendedLane}${suggestion.preferredRoles?.length ? ` for ${suggestion.preferredRoles.join("/")}` : ""}${suggestion.claimMode ? ` (${suggestion.claimMode})` : ""}` : "";
-    lines.push(`- ${suggestion.priority} · ${suggestion.goalId} · ${suggestion.kind}: ${suggestion.summary}${laneText}${pathText}`);
+    const keyText = suggestion.workKey ? ` · key: ${suggestion.workKey}` : "";
+    lines.push(`- ${suggestion.priority} · ${suggestion.goalId} · ${suggestion.kind}: ${suggestion.summary}${laneText}${pathText}${keyText}`);
+    const claim = formatScoutClaimCommand(suggestion);
+    if (claim) lines.push(`  claim: ${claim}`);
   }
-  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.");
+  lines.push("", "Next: post one with `/peer goal propose <goal-id> <summary>` or claim the exact suggested lane with the printed `claim:` command/work key. Scout does not mutate the board.");
   return lines.join("\n");
 }
 
@@ -318,6 +326,20 @@ export function derivePeerGoalScoutSuggestions(board, options = {}) {
       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) {
+      for (const proposal of state.openProposals.filter((item) => item.lane)) {
+        const lane = normalizeLaneName(proposal.lane);
+        const summary = `Self-select proposed ${lane} lane: ${proposal.summary}`;
+        push("P1", "open-proposal", summary, {
+          paths: proposal.paths,
+          recommendedLane: lane,
+          preferredRoles: preferredRolesForLane(lane),
+          claimMode: "read",
+          suggestedIntent: suggestedIntentForLane(lane),
+          rationale: "A peer proposed a lane; matching idle peers can claim or review it without planner assignment.",
+          workKey: proposal.workKey || derivePeerGoalWorkKey({ goalId: goal.id, lane, objective: proposal.summary, mode: "read", paths: proposal.paths }),
+          relatedEventId: proposal.id,
+        });
+      }
       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) {
@@ -325,7 +347,15 @@ export function derivePeerGoalScoutSuggestions(board, options = {}) {
       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.");
+      for (const lane of STARTUP_SCOUT_LANES) {
+        push("P2", "next-step", lane.summary, {
+          recommendedLane: lane.lane,
+          preferredRoles: lane.preferredRoles,
+          claimMode: "read",
+          suggestedIntent: suggestedIntentForLane(lane.lane),
+          rationale: "Multiple lane-specific suggestions let idle peers self-select complementary work and suppress duplicates by work key.",
+        });
+      }
     } 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.");
     }
@@ -535,6 +565,26 @@ function projectEventSummary(event) {
   });
 }
 
+function projectTaskSummary(task, events) {
+  const handoff = latestEvent(events.filter((event) => taskMatchesHandoff(task, event, events)));
+  const projected = projectEventSummary(task);
+  if (!handoff) return projected;
+  return stripEmpty({
+    ...projected,
+    status: handoff.status || "done",
+    completedAt: handoff.at,
+    handoffEventId: handoff.id,
+  });
+}
+
+function taskMatchesHandoff(task, event, events) {
+  if (event.type !== "handoff" || event.at < task.at) return false;
+  if (task.taskId && event.taskId === task.taskId) return true;
+  if (event.taskId === task.id) return true;
+  if (task.taskId || event.taskId || !task.workKey || event.workKey !== task.workKey) return false;
+  return events.filter((item) => item.type === "task" && item.workKey === task.workKey).length === 1;
+}
+
 function projectClaimSummary(claim, events, now) {
   const heartbeat = latestEvent(events.filter((event) => event.type === "heartbeat" && event.resolves === claim.id));
   const lastHeartbeatAt = heartbeat?.at;
@@ -591,7 +641,7 @@ function normalizeDuplicatePolicy(value) {
 
 function enrichScoutSuggestion(suggestion = {}) {
   const lane = SCOUT_LANES[suggestion.kind] || {};
-  const recommendedLane = suggestion.recommendedLane || lane.recommendedLane;
+  const recommendedLane = normalizeLaneName(suggestion.recommendedLane || lane.recommendedLane);
   const claimMode = cleanText(suggestion.claimMode || lane.claimMode);
   const enriched = stripEmpty({
     ...suggestion,
@@ -601,13 +651,48 @@ function enrichScoutSuggestion(suggestion = {}) {
     claimMode,
     suggestedIntent: cleanText(suggestion.suggestedIntent || lane.suggestedIntent),
     rationale: cleanText(suggestion.rationale || lane.rationale),
+    relatedEventId: cleanText(suggestion.relatedEventId),
   });
   return stripEmpty({
     ...enriched,
-    workKey: suggestion.workKey || derivePeerGoalWorkKey({ goalId: enriched.goalId, lane: recommendedLane, objective: enriched.summary, mode: claimMode, paths: enriched.paths }),
+    workKey: normalizeWorkKey(suggestion.workKey) || derivePeerGoalWorkKey({ goalId: enriched.goalId, lane: recommendedLane, objective: enriched.summary, mode: claimMode, paths: enriched.paths }),
   });
 }
 
+function formatScoutClaimCommand(suggestion = {}) {
+  if (suggestion.claimMode !== "read" || !suggestion.workKey || !suggestion.goalId || !suggestion.summary) return "";
+  const lane = suggestion.recommendedLane ? ` --lane ${shellQuote(suggestion.recommendedLane)}` : "";
+  const paths = suggestion.paths?.length ? suggestion.paths.map((path) => ` --path ${shellQuote(path)}`).join("") : "";
+  return `/peer goal claim ${shellQuote(suggestion.goalId)} ${shellQuote(suggestion.summary)} --mode read${lane} --key ${shellQuote(suggestion.workKey)}${paths}`;
+}
+
+function shellQuote(value) {
+  const text = String(value || "");
+  if (/^[A-Za-z0-9_./:-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, `'"'"'`)}'`;
+}
+
+function normalizeLaneName(value) {
+  const lane = cleanText(value).toLowerCase();
+  if (["qa", "quality", "test", "testing"].includes(lane)) return "review";
+  if (["implement", "implementation", "developer", "engineer", "worker", "code", "coding"].includes(lane)) return "implementation";
+  if (["coordinate", "coordinator", "planning", "planner", "orchestration"].includes(lane)) return "coordination";
+  if (["researcher", "scout", "investigation"].includes(lane)) return "research";
+  return lane || "review";
+}
+
+function preferredRolesForLane(lane) {
+  const normalized = normalizeLaneName(lane);
+  if (normalized === "implementation") return ["worker"];
+  if (normalized === "research") return ["researcher", "planner", "coordinator"];
+  if (normalized === "coordination") return ["planner", "coordinator", "reviewer"];
+  return ["reviewer", "qa", "planner", "coordinator"];
+}
+
+function suggestedIntentForLane(lane) {
+  return normalizeLaneName(lane) === "implementation" ? "task" : "review";
+}
+
 function hasActiveClaimForScoutSuggestion(state, suggestion) {
   if (!suggestion?.workKey) return false;
   return state.activeClaims.some((claim) => claim.workKey === suggestion.workKey);

package/src/peers/guidance.mjs

@@ -11,7 +11,7 @@ const PEER_SEND_GUIDANCE = "Use peer_send to send a prompt-first message to a pe
 const PEER_AWAIT_GUIDANCE = "Use peer_await with messageId values from queued or timed-out peer_send calls to read final assistant replies.";
 const PEER_GET_GUIDANCE = "Use peer_get to inspect a peer, message, conversation, runtime summary, active tasks via 'tasks', fan-out suggestions via 'fanout', or redacted audit state by id.";
 const PEER_PROGRESS_GUIDANCE = "Use peer_progress from inside an inbound long-running peer task to send structured checkpoint updates before the final handoff.";
-const PEER_FANOUT_GUIDANCE = "Fan-out gate: for multi-part, long-running, or implementation-plus-review work, call peer_list and delegate research/review/QA lanes with peer_send unless the user explicitly says to work solo; if you skip fan-out, state the reason in the final response.";
+const PEER_FANOUT_GUIDANCE = "Fan-out gate: for multi-part, long-running, or implementation-plus-review work, call peer_list and use a goal board plus peer_send for research/review/QA lanes unless the user explicitly says to work solo. For emergent self-organization tests, create/reuse a peer goal and let peers inspect scout suggestions or claim lane-specific work keys instead of over-assigning every lane; if you skip fan-out, state the reason in the final response.";
 
 export const PEER_INBOUND_FINAL_RESPONSE_GUIDANCE = "For inbound peer asks, answer the inbound ask in your final assistant response; that final assistant response is returned to the requesting peer. For write-capable task intents, end with a concise handoff: status, files changed, verification commands with exit status, and blockers.";
 

package/src/peers/idle-watcher.mjs

@@ -139,13 +139,28 @@ export function buildPeerIdleActivationPrompt(activation, options = {}) {
   const peerId = options.localPeerId || "this-peer";
   const paths = activation.paths?.length ? `\nPaths: ${activation.paths.join(", ")}` : "";
   const lane = activation.recommendedLane ? `\nRecommended lane: ${activation.recommendedLane}${activation.claimMode ? ` (${activation.claimMode})` : ""}${activation.preferredRoles?.length ? ` · preferred roles: ${activation.preferredRoles.join(", ")}` : ""}` : "";
+  const workKey = activation.workKey ? `\nWork key: ${activation.workKey}` : "";
+  const suggestedClaim = buildSuggestedReadClaim(activation);
   const rationale = activation.rationale ? `\nRationale: ${activation.rationale}` : "";
   const fit = activation.personaFit?.matched?.length ? `\nPersona fit: matched ${activation.personaFit.matched.join(", ")}` : "";
-  return `[Pi peer idle watcher]\nYou are local peer '${peerId}' and Pi is idle. A proactive goal-board scout suggestion is available.\n\nGoal: ${activation.goalId}\nSuggestion: ${activation.kind} (${activation.priority}) — ${activation.summary}${lane}${rationale}${fit}${paths}\n\nInstructions:\n- First inspect current state with peer_get id '${activation.goalId}'.\n- If useful, take one small safe action that fits the recommended lane: post a proposal/finding/vote, claim a read-only review lane, or claim write work only when you intend to edit and can name the paths.\n- Do not duplicate active claims or proposals. If the board is no longer actionable, say so briefly and stop.\n- For write work, respect goal-board claims and end with the required peer handoff sections.\n- Keep the response concise.`;
+  return `[Pi peer idle watcher]\nYou are local peer '${peerId}' and Pi is idle. A proactive goal-board scout suggestion is available.\n\nGoal: ${activation.goalId}\nSuggestion: ${activation.kind} (${activation.priority}) — ${activation.summary}${lane}${workKey}${rationale}${fit}${paths}${suggestedClaim}\n\nInstructions:\n- First inspect current state with peer_get id '${activation.goalId}'.\n- If useful, take one small safe action that fits the recommended lane: claim a read-only lane with the work key above, post a proposal/finding/vote, or claim write work only when you intend to edit and can name the paths.\n- If the suggested claim fails as duplicate, inspect the board and stop with a brief handoff instead of starting parallel work.\n- Do not duplicate active claims, work keys, or proposals. If the board is no longer actionable, say so briefly and stop.\n- For write work, respect goal-board claims and end with the required peer handoff sections.\n- Keep the response concise.`;
+}
+
+function buildSuggestedReadClaim(activation = {}) {
+  if (activation.claimMode !== "read" || !activation.workKey) return "";
+  const lane = activation.recommendedLane ? ` --lane ${shellQuote(activation.recommendedLane)}` : "";
+  const paths = activation.paths?.length ? activation.paths.map((path) => ` --path ${shellQuote(path)}`).join("") : "";
+  return `\nSuggested first action: /peer goal claim ${shellQuote(activation.goalId)} ${shellQuote(activation.summary)} --mode read${lane} --key ${shellQuote(activation.workKey)}${paths}`;
+}
+
+function shellQuote(value) {
+  const text = String(value || "");
+  if (/^[A-Za-z0-9_./:-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, `'"'"'`)}'`;
 }
 
 export function peerIdleActivationKey(activation = {}) {
-  return [activation.goalId, activation.kind, activation.recommendedLane, activation.summary, ...(activation.paths || [])].join("|");
+  return [activation.goalId, activation.kind, activation.recommendedLane, activation.workKey, activation.summary, ...(activation.paths || [])].join("|");
 }
 
 function isActivationCoolingDown(state, activation, config, nowMs) {
@@ -167,6 +182,7 @@ function normalizeActivation(suggestion = {}, localPeerId, options = {}) {
     claimMode: cleanString(suggestion.claimMode),
     suggestedIntent: cleanString(suggestion.suggestedIntent),
     rationale: cleanString(suggestion.rationale),
+    workKey: cleanString(suggestion.workKey),
     personaFit,
     paths: Array.isArray(suggestion.paths) ? suggestion.paths.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()) : [],
     peerId: localPeerId,

package/src/peers/runtime.mjs

@@ -195,7 +195,7 @@ export async function getPeerRuntimeValue(runtime, id) {
     const peers = await runtime.comms.listPeers();
     const messages = await runtime.comms.listMessages();
     const suggestion = deriveFanoutSuggestion(peers, messages);
-    return { type: "fanout", value: { ...suggestion, checklist: ["Run peer_list before multi-lane work", "Create or reuse /peer goal", "Use /peer goal fanout or peer_send goalId+claimedPaths", "Final response must include Fan-out used: yes/no and peer handles"] } };
+    return { type: "fanout", value: { ...suggestion, checklist: ["Run peer_list before multi-lane work", "Create or reuse /peer goal", "For emergent self-organization, ask peers to inspect /peer scout or claim lane-specific work keys before assigning every lane", "Use /peer goal fanout or peer_send goalId+claimedPaths when direct dispatch is needed", "Final response must include Fan-out used: yes/no and peer handles"] } };
   }
   if (id === "audit") return { type: "audit", value: await runtime.comms.getAuditEntries() };