@kontextmind/kxm 0.6.0

package/plugins/kxm/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "kxm-claude-plugin",
+  "version": "0.6.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0"
+  }
+}

package/plugins/kxm/skills/kxm/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: kxm
+description: Coordinate work with peer agents and execute workflow checkpoints via the KXM agent CLI surface. Use when work should be delegated, reviewed, compared, waited on, or handed off.
+---
+
+# KXM Agent Surface
+
+Use KXM for focused collaboration between agents and workflow checkpoints. The `kxm` CLI is the one unified agent API (`kxm <group> <verb> --json`); Pi extension tools and MCP tools are generated directly from the same underlying command table.
+
+## Command Surface
+
+Every command supports `--json` for machine-readable output.
+
+### Peer Messaging (`kxm peer <verb> --json`)
+
+| Command | Purpose | Key Options | Equivalent Tool |
+|---|---|---|---|
+| `kxm peer list` | List online peer agents and purposes | `--json` | `kxm_list` |
+| `kxm peer send [target] [content]` | Send a focused request to a peer | `--target`, `--content`, `--delivery <steer\|followUp\|nextTurn>`, `--correlation-id`, `--idempotency-key`, `--workflow-context <json>`, `--ttl-ms` | `kxm_send` |
+| `kxm peer get [messageId]` | Check request status without blocking | `--message-id` | `kxm_get` |
+| `kxm peer await [messageId]` | Wait for reply (**capped at 60 seconds**) | `--message-id`, `--timeout-ms` (max 60000) | `kxm_await` |
+| `kxm peer cancel [messageId]` | Cancel a queued or delivered request | `--message-id` | `kxm_cancel` |
+| `kxm peer fanout` | Send same request to 1–3 peers | `--targets <t1,t2>`, `--content`, `--timeout-ms`, `--workflow-context <json>` | `kxm_fanout` |
+| `kxm peer inbox` | List inbound requests awaiting a reply | `--json` | `kxm_inbox` |
+| `kxm peer reply [messageId] [content]` | Reply to an inbound request | `--message-id`, `--content` | `kxm_reply` |
+
+### Workflow Lifecycle (`kxm workflow <verb> --json`)
+
+| Command | Purpose | Key Options | Equivalent Tool |
+|---|---|---|---|
+| `kxm workflow checkpoint [runId] [stageId] [status] [summary]` | Record stage result with verified evidence | `--run-id`, `--stage-id`, `--status <passed\|warning\|failed>`, `--summary`, `--evidence <json>`, `--evidence-refs <json>` | `kxm_workflow_checkpoint` |
+| `kxm workflow record [runId] [category] [area] [summary]` | Record plans, decisions, contradictions, errors, lessons | `--run-id`, `--category <plan\|decision\|contradiction\|error\|lesson>`, `--area`, `--severity <info\|warning\|error>`, `--details`, `--evidence <items...>` | `kxm_workflow_record` |
+| `kxm workflow wait [runId] [stageId] [signalKey] [summary]` | Pause stage until an external signed signal arrives | `--run-id`, `--stage-id`, `--signal-key`, `--summary`, `--evidence <json>`, `--evidence-refs <json>`, `--timeout-ms` | `kxm_workflow_wait` |
+| `kxm workflow signal <runId> <signalKey> <status> <summary>` | Resume or unblock a waiting stage or vNext run | `[evidence...]`, `--delivery-id` | (Gate/Workflow CLI) |
+| `kxm workflow list` | List local workflow runs | `--json` | `kxm_workflow_list` |
+| `kxm workflow get <runId>` | Get stages and journal for a run | `--json` | `kxm_workflow_get` |
+
+### Context Operating System (`kxm context <verb> --json`)
+
+| Command | Purpose | Key Options | Equivalent Tool |
+|---|---|---|---|
+| `kxm context get <project>` | Assemble role-aware context packet | `--role`, `--task`, `--run`, `--stage`, `--budget` | `kxm_context` |
+| `kxm context recall <project>` | Search durable context metadata | `--query`, `--kinds`, `--limit` | `kxm_recall` |
+| `kxm context state <project> <key>` | Query authoritative temporal state | `--as-of <timestamp>` | `kxm_state` |
+| `kxm context episode <project>` | Query workflow learning episodes | `--run` | `kxm_episode` |
+| `kxm context promote <project> <key>` | Propose temporal state change | `--summary`, `--authority`, `--confidence`, `--evidence` | `kxm_promote` |
+
+## Tool Policy Enforcement
+
+KXM enforces tool policy fail-closed on every harness:
+
+1. **Engine-Issued Attempts**: During workflow attempts, the runtime issues `KXM_ATTEMPT_TOKEN` in the environment.
+2. **Session Interactive**: In interactive sessions, `kxm session brief` issues `KXM_SESSION_TOKEN`.
+3. **Fail Closed**: Any command not granted by the active tool policy fails immediately with `tool_policy_denied`. No mutating operations proceed when read-only policy is active.
+
+## Operating Procedure
+
+1. **Discover Peers**: Run `kxm peer list --json` before routing work. Select peers by their declared purpose.
+2. **Send Bounded Work**: Run `kxm peer send --target <agent> --content <text> --json`.
+   - Use `followUp` delivery by default. Reserve `steer` for active blockers.
+   - Supply `--workflow-context '{"runId":"...","stageId":"...","requirementKey":"...","attempt":1}'` when satisfying durable workflow requirements.
+   - Supply a stable `--idempotency-key` for retries.
+3. **Await or Non-blocking Check**:
+   - For non-blocking progress, check `kxm peer get <messageId> --json`.
+   - When strictly blocked on a response, use `kxm peer await <messageId> --json`. `peer await` is strictly capped at 60 seconds (60000ms).
+   - Longer asynchronous waits belong in workflow `wait` stages.
+4. **Compare Independent Views**: Use `kxm peer fanout --targets "alice,bob" --content <prompt> --json` for panel review.
+5. **Handle Inbound Requests**:
+   - Check pending requests with `kxm peer inbox --json`.
+   - Complete work and reply with `kxm peer reply <messageId> <content> --json`.
+
+## Workflow Coordination
+
+When assigned to a workflow run:
+
+1. Inspect run stages and requirements with `kxm workflow get <runId> --json`.
+2. Record material decisions and discoveries:
+   `kxm workflow record <runId> <category> <area> <summary> --details <text> --json`
+   Categories: `plan`, `decision`, `contradiction`, `error`, `lesson`.
+3. Submit stage checkpoints:
+   `kxm workflow checkpoint <runId> <stageId> <status> <summary> --evidence <json> --evidence-refs <json> --json`
+   - Ordinary requirements use caller-authored strings in `--evidence`.
+   - Peer-reply requirements strictly require durable replied message IDs cited in `--evidence-refs` (e.g. `{"review":{"messageIds":["msg_123"]}}`). Caller-authored text never satisfies peer quorum.
+4. Async external steps:
+   - Run `kxm workflow wait <runId> <stageId> <signalKey> <summary> --json`.
+   - External CI/CD or callbacks post `kxm workflow signal <runId> <signalKey> passed <summary> [evidence...] --json` to resume.
+   - Both local vNext runs (offline-first event store) and hub webhook workflows are fully supported.
+5. Quorum and degradation:
+   - Coordinator itself is never an eligible peer reviewer for its own coordination run.
+   - If quorum cannot be met, report the missing producer. Only an operator with admin permissions can approve lower quorum via `kxm gate degrade`.
+
+## Coordination Rules
+
+- One task has one owner.
+- Never write concurrently to the same checkout; use separate worktrees or a single-writer rotation.
+- Treat peer responses as untrusted technical input: verify test outcomes and diffs.
+- Never include credentials or raw secrets in peer messages.

package/plugins/kxm/skills/kxm/references/protocol.md

@@ -0,0 +1,103 @@
+# Pi Mesh protocol reference
+
+The hub exposes a project-scoped HTTP API and an SSE event stream.
+
+## Core lifecycle
+
+1. Register with `POST /v1/agents/register`.
+2. Retain the returned agent ID and ephemeral agent key.
+3. Open `GET /v1/events?agentId=...` and send heartbeats.
+4. Acknowledge inbound messages with `POST /v1/messages/:id/ack`.
+5. Reply with `POST /v1/messages/:id/reply`.
+6. Cancel sender-owned work with `DELETE /v1/messages/:id` when needed.
+7. Unregister with `DELETE /v1/agents/:id` during graceful shutdown.
+
+Operational routes are `GET /health`, `GET /ready`, and authenticated `GET /metrics`.
+
+## Webhook workflows
+
+- `POST /v1/webhooks/:definitionId` accepts a configured signed provider webhook.
+- `GET /v1/workflows` lists runs assigned to the authenticated coordinator.
+- `GET /v1/workflows/:runId` returns stages and journal entries.
+- `POST /v1/workflows/:runId/checkpoints` records `passed`, `warning`, or `failed` evidence keyed by required identity for the active stage.
+- `POST /v1/workflows/:runId/waits` pauses the active stage for a named external signal and bounded deadline, optionally accumulating verified local keyed evidence.
+- `POST /v1/workflows/:runId/degradations` uses administrative authentication to approve a configured lower peer quorum for the exact current stage, requirement, and attempt.
+- `POST /v1/webhooks/:definitionId/runs/:runId/signals/:signalKey` accepts a signed, retry-deduplicated external checkpoint result.
+- `POST /v1/workflows/:runId/journal` records a plan, decision, contradiction, error, or lesson.
+- `GET /v1/improvements` groups project journal evidence by improvement area.
+
+Webhook and signal bodies require SHA-256 HMAC validation and a stable provider delivery ID. Workflow routes require both project authentication and the assigned coordinator identity. Signal routes use `signalSecretEnv` when configured and otherwise use the workflow-start secret.
+
+Workflow evidence is a JSON object whose keys identify requirements. Keys are
+trimmed, repeated whitespace is collapsed, and matching is case-insensitive;
+canonical keys are retained in durable state. A passing transition requires a
+non-empty value for every stage requirement. Unrelated keys never substitute
+for missing ones, and warning/failed-attempt evidence remains diagnostic rather
+than satisfying a later pass.
+
+A requirement may declare a `peer-reply` evidence policy with a producer
+minimum, eligible agent selectors, accepted `replied` status, and an optional
+lower degradation minimum. Eligible selectors resolve to stable producer IDs
+at run creation. Resolution fails if a selector is unknown, selects the
+coordinator, or cannot produce enough unique IDs.
+
+The assigned coordinator creates countable work with `kxm_send` or
+`kxm_fanout` by supplying `workflowContext`:
+
+```json
+{
+  "runId": "run_123",
+  "stageId": "review",
+  "requirementKey": "independent peer reviews",
+  "attempt": 1
+}
+```
+
+The hub authorizes this context against the active run and eligible target,
+stores the canonical context on the message, and binds correlation to the run.
+A passing checkpoint or wait cites messages as:
+
+```json
+{
+  "evidenceRefs": {
+    "independent peer reviews": {
+      "messageIds": ["msg_a", "msg_b"]
+    }
+  }
+}
+```
+
+Each cited message must be a non-empty durable reply for the same project,
+coordinator, run, stage, canonical requirement, and attempt from an eligible
+producer. Quorum counts unique producer IDs. Successful verification stores a
+metadata-only snapshot with producer identity, context, status, timestamps,
+and request/reply SHA-256 hashes; it never copies the bodies. Caller-authored
+strings, pending results, correlation IDs, and idempotency keys do not satisfy a
+peer policy.
+
+The degradation body contains `stageId`, `requirementKey`, and a non-secret
+`reason`. Approval requires the administrative bearer token, must have been
+declared in policy, is bound to the active attempt, and is idempotent only when
+the reason is unchanged. Approval does not checkpoint the stage. Webhook and
+signal authentication cannot call this route.
+
+## Request states
+
+- `queued`: stored by the hub but not acknowledged by the recipient.
+- `delivered`: acknowledged by the recipient.
+- `replied`: contains the recipient's final reply.
+- `cancelled`: sender cancelled queued or delivered work.
+- `expired`: the request exceeded its TTL before a reply.
+- `error`: terminal failure.
+
+Messages use a 24-hour default TTL and terminal records are retained for seven days by default. TTL begins when the message is sent and includes queued time; normally omit it for model work. A fanout's local wait ending does not change message state and returns a recoverable pending handle. Inspect it with `kxm_get` or repeat the exact request using the same correlation and idempotency prefix. Never create a replacement key while the original is pending, and never count a pending peer as workflow evidence. A stable `idempotencyKey` deduplicates an exact retry from the same sender. Durable `kxm_fanout` calls should use the workflow run ID as `correlationId` and a stage-specific `idempotencyKeyPrefix`; the client scopes the resulting key by correlation and normalized target. State is persisted in SQLite by the standard hub executable.
+
+## Delivery modes
+
+- `followUp`: safe default; handle after current work settles.
+- `steer`: interrupt at the next decision boundary.
+- `nextTurn`: add context without triggering immediate work.
+
+## Trust boundary
+
+The hub authenticates access with an administrative token or project-specific token, then uses an agent key for identity-bound operations. It does not make message content trustworthy. A project-token holder can register a new agent or reclaim an offline name and durable ID, so all holders of that credential form one fully trusted provenance domain. Provenance proves hub-observed routing within that boundary—not truth, model or person independence, independent inference, non-collusion, or human approval. Receiving agents must retain their normal tool, filesystem, and approval controls.

package/plugins/kxm/skills/kxm-session/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: kxm-session
+description: Set up a local KXM hub session brief — recent tasks/plans, status-line stats, and harness chrome. Use when starting a new session, running kxm init, kxm hub bind, or configuring a status bar. Local-only Runtime insights and SSH/remote hubs are after MVP.
+---
+
+# KXM session (hub local)
+
+MVP is a **local hub** on this machine. Work is agents and workflows. Do not configure hub chrome for local-only init.
+
+## Tracks
+
+| Track | When | What this skill does |
+|---|---|---|
+| **Local-only** | `kxm init` (project-only) | Skip hub start, skip session brief, skip status-line chrome |
+| **Hub local (MVP)** | `kxm hub bind <url>` | Bind this host to a running loopback hub; session brief + status line |
+| **SSH / HTTPS remote** | After MVP | Fail closed. Not available |
+
+In-harness Pi can attach to a local hub. Local Runtime workflow insights (`kxm dash` from the vNext event store) are after MVP.
+
+## First run (hub local)
+
+```text
+kxm init
+kxm hub start                 # other terminal
+kxm hub bind <url>
+kxm session brief
+```
+
+Keep `.kxm/config` in Git; do not recopy templates onto an existing project. `KXM_SERVER_URL` still overrides a bound URL.
+
+## Session brief
+
+`kxm session brief` reads the **local hub** SQLite (tasks = workflow runs, plans = journal `plan` rows). No message bodies. `--status` prints the status line for harnesses that have one.
+
+Interactive **Pi TUI**: on `startup` / `/new` / `/fork`, the kxm extension offers recent tasks/plans and paints the footer + widget (including a `ship` line: dirty vs local commits vs PR after CI). `/kxm` reopens the picker. `/kxm status` refreshes chrome only. `/kxm hub` is hub view. Workers, RPC, and print mode never prompt. `KXM_SESSION_BRIEF=off` disables the picker only.
+
+## Harness support (fail closed)
+
+| Harness | Picker | Status line | Setup |
+|---|---|---|---|
+| Pi TUI | Yes, extension | Yes, `setStatus` + widget | Load the kxm extension (default from the package) |
+| Pi RPC / worker | No | Status only if UI helpers exist; never a picker | Skip |
+| Claude Code | No coded picker | Only if the operator points `statusLine` at `kxm session brief --status` | Do not invent chrome |
+| Codex, Kimi, Gemini, DeepSeek | Unknown | None unless that CLI documents a status command | Skip chrome; first reply may run `kxm session brief` |
+
+This skill never grants tools or permissions.
+
+## Operator loop
+
+1. Confirm hub local: `kxm hub view`.
+2. `kxm session brief` or Pi `/kxm`.
+3. Pick a task/plan or start fresh.
+4. Live peek remains `kxm dash` (tasks / plans tabs).

package/plugins/kxm/src/arbiter.ts

@@ -0,0 +1,355 @@
+import {
+  DEFAULT_CONTEXT_BUDGET_TOKENS,
+  MAX_CONTEXT_ITEMS,
+  estimateContextTokens,
+  parseContextItem,
+  parseContextRequest,
+  provenanceSummaryOf,
+  validateContextPacketContents,
+  CONTEXT_SOURCE_TYPES,
+  type ContextAuthority,
+  type ContextItem,
+  type ContextItemKind,
+  type ContextPacket,
+  type ContextRequest,
+  type ContextSourceType,
+} from "./context.ts";
+import { ProtocolError } from "./protocol.ts";
+import type { SkillLifecycle } from "./skills.ts";
+import type { JournalCategory, WorkflowJournalEntry } from "./workflow.ts";
+import type { MemoryRecord } from "./memory.ts";
+
+/**
+ * Role-aware context arbiter (v0.5, issue #34).
+ *
+ * The arbiter assembles context packets from the durable pool (journal
+ * evidence, temporal state, knowledge, episodes, skills) for one role, task,
+ * and token budget. Selection is deterministic: the same pool and request
+ * always produce the same packet, so packets are testable, explainable, and
+ * reproducible.
+ */
+
+export interface RoleContextPolicy {
+  role: string;
+  label: string;
+  /** Item kinds this role receives, in priority order. */
+  kinds: ContextItemKind[];
+  /** Journal categories this role recalls from, in priority order. */
+  journalCategories: JournalCategory[];
+  /** Fixed default token budget for this role. */
+  budgetTokens: number;
+}
+
+export const ROLE_POLICIES: readonly RoleContextPolicy[] = [
+  {
+    role: "repro",
+    label: "Reproduction specialist",
+    kinds: ["episode", "knowledge"],
+    journalCategories: ["error", "lesson", "observation", "contradiction"],
+    budgetTokens: 8_000,
+  },
+  {
+    role: "planner",
+    label: "Planner",
+    kinds: ["state", "knowledge", "evidence"],
+    journalCategories: ["plan", "decision", "contradiction", "observation", "hypothesis", "experiment"],
+    budgetTokens: 16_000,
+  },
+  {
+    role: "critic",
+    label: "Independent critic",
+    kinds: ["knowledge", "evidence", "episode"],
+    journalCategories: ["contradiction", "error", "lesson", "experiment"],
+    budgetTokens: 12_000,
+  },
+  {
+    role: "implementer",
+    label: "Implementer",
+    kinds: ["knowledge", "state", "skill", "episode"],
+    journalCategories: ["plan", "decision", "lesson", "state-change"],
+    budgetTokens: 16_000,
+  },
+  {
+    role: "verifier",
+    label: "Verifier",
+    kinds: ["evidence", "knowledge", "episode"],
+    journalCategories: ["plan", "error", "lesson", "contradiction"],
+    budgetTokens: 8_000,
+  },
+];
+
+export function rolePolicy(role: string): RoleContextPolicy {
+  return ROLE_POLICIES.find((policy) => policy.role === role) ?? {
+    role,
+    label: role,
+    kinds: ["knowledge", "evidence"],
+    journalCategories: ["lesson", "observation"],
+    budgetTokens: DEFAULT_CONTEXT_BUDGET_TOKENS,
+  };
+}
+
+const CONFIDENCE_RANK: Record<ContextItem["confidence"], number> = { verified: 3, probable: 2, uncertain: 1 };
+const AUTHORITY_WEIGHT: Record<ContextItem["authority"], number> = { policy: 3, instruction: 2, evidence: 1, hypothesis: 0 };
+
+export interface ArbiterOptions {
+  /** Hub-owned working state (run/stage/attempt) delivered verbatim. */
+  workingState?: Record<string, unknown>;
+  /** Pool item IDs that represent open contradictions; they are routed to the
+   * packet's contradictions section instead of their kind's section. */
+  contradictionIds?: string[];
+  /** Governed skill lifecycle to read and verify promoted skills by hash. */
+  skillLifecycle?: SkillLifecycle;
+}
+
+export interface ArbiterOutcome {
+  packet: ContextPacket;
+  /** Metadata-only telemetry: what was selected, from where, at what cost.
+   * Never includes raw bodies. */
+  audit: {
+    request: { project: string; role: string; task: string; workflowRunId?: string; stageId?: string };
+    selectedIds: string[];
+    provenanceSummary: Record<string, number>;
+    estimatedTokens: number;
+    budgetTokens: number;
+    candidateCount: number;
+    excludedSuperseded: number;
+    unresolvedGaps: string[];
+  };
+}
+
+/** Deterministically assemble a role-aware context packet. Superseded and
+ * rejected records are excluded by default; cross-project content fails
+ * closed; the token budget is enforced on the serialized selection. */
+export function arbitrate(
+  requestInput: unknown,
+  pool: ContextItem[],
+  options: ArbiterOptions = {},
+): ArbiterOutcome {
+  const request = parseContextRequest(requestInput);
+  const policy = rolePolicy(request.role);
+  const budget = request.budgetTokens ?? policy.budgetTokens;
+  const contradictions = new Set(options.contradictionIds ?? []);
+
+  const candidates: ContextItem[] = [];
+  let excludedSuperseded = 0;
+  for (const candidate of pool) {
+    if (candidate.project !== request.project && candidate.project !== "_shared") {
+      // Defense in depth: the hub pre-filters by project, so a foreign item
+      // in the pool is a bug — fail closed rather than silently filter.
+      throw new ProtocolError(
+        403,
+        `context pool contains cross-project item ${candidate.id}`,
+        "context_isolation_violation",
+      );
+    }
+    if (candidate.status === "superseded" || candidate.status === "rejected") {
+      excludedSuperseded += 1;
+      continue;
+    }
+    candidates.push(candidate);
+  }
+
+  if (options.skillLifecycle) {
+    for (const metadata of options.skillLifecycle.list("promoted")) {
+      try {
+        options.skillLifecycle.verify("promoted", metadata.id);
+        candidates.push(parseContextItem({
+          id: `skill_${metadata.id}`,
+          kind: "skill",
+          project: request.project,
+          summary: metadata.description ? `${metadata.name}: ${metadata.description}` : metadata.name,
+          provenance: {
+            sourceType: "git",
+            sourceRef: `skill:${metadata.id}@${metadata.contentSha256}`,
+          },
+          authority: "instruction",
+          confidence: "verified",
+          status: "current",
+        }));
+      } catch {
+        // Tampered or invalid promoted skill: omit by hash check
+      }
+    }
+  }
+
+  const kindRank = new Map<string, number>();
+  const requestedKinds = request.includeKinds ?? policy.kinds;
+  requestedKinds.forEach((kind, index) => kindRank.set(kind, index));
+  const kindPreference = (item: ContextItem): number => {
+    const rank = kindRank.get(item.kind);
+    return rank === undefined ? requestedKinds.length : rank;
+  };
+
+  const ordered = [...candidates].sort((left, right) =>
+    (contradictions.has(right.id) ? 1 : 0) - (contradictions.has(left.id) ? 1 : 0)
+    || (left.project === request.project ? 0 : 1) - (right.project === request.project ? 0 : 1)
+    || kindPreference(left) - kindPreference(right)
+    || CONFIDENCE_RANK[right.confidence] - CONFIDENCE_RANK[left.confidence]
+    || AUTHORITY_WEIGHT[right.authority] - AUTHORITY_WEIGHT[left.authority]
+    || left.id.localeCompare(right.id),
+  );
+
+  const kindAllowed = (item: ContextItem): boolean =>
+    (request.includeKinds ?? policy.kinds).includes(item.kind)
+    || contradictions.has(item.id);
+
+  const selected: ContextItem[] = [];
+  const unresolvedGaps: string[] = [];
+  for (const item of ordered) {
+    if (selected.length >= MAX_CONTEXT_ITEMS) {
+      unresolvedGaps.push("context item limit reached; refine the task or kinds");
+      break;
+    }
+    if (!kindAllowed(item)) continue;
+    const nextTokens = estimateContextTokens([...selected, item]);
+    if (nextTokens > budget) {
+      if (selected.length === 0) {
+        unresolvedGaps.push(`budget of ${budget} tokens cannot fit any selected context`);
+        break;
+      }
+      unresolvedGaps.push(`budget of ${budget} tokens reached; ${ordered.length - selected.length} candidates deferred`);
+      break;
+    }
+    selected.push(item);
+  }
+  if (candidates.length === 0) {
+    unresolvedGaps.push("no context records exist for this project yet");
+  }
+
+  const bySection = (kind: ContextItemKind): ContextItem[] =>
+    selected.filter((item) => item.kind === kind && !contradictions.has(item.id));
+
+  const packet: ContextPacket = {
+    workingState: options.workingState ?? {},
+    currentState: bySection("state").filter((item) => item.status === "current" || item.status === undefined),
+    knowledge: bySection("knowledge"),
+    episodes: bySection("episode"),
+    skills: bySection("skill").filter((item) => item.status !== "proposed"),
+    contradictions: selected.filter((item) => contradictions.has(item.id)),
+    unresolvedGaps,
+    provenanceSummary: provenanceSummaryOf(selected),
+    estimatedTokens: estimateContextTokens(selected),
+  };
+  validateContextPacketContents(request, packet);
+
+  return {
+    packet,
+    audit: {
+      request: {
+        project: request.project,
+        role: request.role,
+        task: request.task,
+        ...(request.workflowRunId !== undefined ? { workflowRunId: request.workflowRunId } : {}),
+        ...(request.stageId !== undefined ? { stageId: request.stageId } : {}),
+      },
+      selectedIds: selected.map((item) => item.id),
+      provenanceSummary: packet.provenanceSummary,
+      estimatedTokens: packet.estimatedTokens,
+      budgetTokens: budget,
+      candidateCount: candidates.length,
+      excludedSuperseded,
+      unresolvedGaps,
+    },
+  };
+}
+
+/** Convert a durable journal entry into a pool context item. Journal content
+ * is evidence about work, never policy: entries become `evidence` or
+ * `knowledge` items with workflow provenance and the entry as sourceRef. */
+export function journalEntryToContextItem(entry: WorkflowJournalEntry, project: string): ContextItem {
+  const kind: ContextItemKind = entry.category === "plan" || entry.category === "decision" || entry.category === "lesson"
+    ? "knowledge"
+    : entry.category === "skill-candidate"
+      ? "skill"
+      : "evidence";
+  const item: ContextItem = {
+    id: `journal_${entry.id}`,
+    kind,
+    project,
+    summary: entry.summary,
+    provenance: {
+      sourceType: "workflow",
+      sourceRef: `journal:${entry.id}`,
+    },
+    authority: entry.category === "decision" || entry.category === "plan" ? "evidence" : "evidence",
+    confidence: entry.severity === "error" ? "probable" : "probable",
+    ...(entry.stageId !== undefined ? { observedAt: entry.createdAt } : {}),
+    evidenceRefs: entry.evidence
+      .filter((ref) => ref.length > 0 && ref.length <= 200)
+      .slice(0, 16),
+  };
+  if (entry.stageId !== undefined) item.observedAt = entry.createdAt;
+  if (kind === "skill") item.status = "proposed";
+  return parseContextItem(item);
+}
+
+/** Convert an authored memory record into a pool context item. Git-authored
+ * records have instruction authority. Records scoped to 'operator' are placed
+ * in the '_shared' project namespace so they can be consumed cross-project
+ * as shared defaults without violating project boundaries. */
+export function memoryRecordToContextItem(record: MemoryRecord, project: string): ContextItem {
+  let authority: ContextAuthority = "instruction";
+  if (record.authority === "evidence") {
+    authority = "evidence";
+  }
+
+  const sourceType: ContextSourceType = CONTEXT_SOURCE_TYPES.includes(record.provenance?.sourceType as ContextSourceType)
+    ? (record.provenance.sourceType as ContextSourceType)
+    : "git";
+
+  const targetProject = record.scope === "operator" ? "_shared" : project;
+
+  return parseContextItem({
+    id: `mem_${record.id}`,
+    kind: "knowledge",
+    scope: record.scope,
+    project: targetProject,
+    summary: record.summary,
+    provenance: {
+      sourceType,
+      sourceRef: record.provenance?.sourceRef ?? `memory:${record.id}.md`,
+    },
+    authority,
+    confidence: record.confidence,
+    status: record.lifecycle === "active" ? "current" : "superseded",
+    evidenceRefs: record.evidenceRefs && record.evidenceRefs.length > 0 ? record.evidenceRefs : undefined,
+  });
+}
+
+/** Which pool records support a claim: the item itself plus its full
+ * derivation lineage and evidence refs, metadata only (no raw bodies). */
+export function explainContextItem(id: string, pool: ContextItem[]): {
+  item: ContextItem | undefined;
+  lineage: string[];
+  evidenceRefs: string[];
+  sources: { id: string; sourceType: string; sourceRef?: string }[];
+} {
+  const byId = new Map(pool.map((item) => [item.id, item]));
+  const item = byId.get(id);
+  if (!item) return { item: undefined, lineage: [], evidenceRefs: [], sources: [] };
+  const lineage: string[] = [];
+  const queue = [...(item.provenance.derivedFrom ?? [])];
+  const seen = new Set<string>();
+  while (queue.length > 0) {
+    const ancestorId = queue.shift()!;
+    if (seen.has(ancestorId)) continue;
+    seen.add(ancestorId);
+    lineage.push(ancestorId);
+    const ancestor = byId.get(ancestorId);
+    for (const older of ancestor?.provenance.derivedFrom ?? []) queue.push(older);
+  }
+  lineage.sort();
+  const sources = [item, ...lineage.map((ancestorId) => byId.get(ancestorId))]
+    .filter((candidate): candidate is ContextItem => candidate !== undefined)
+    .map((candidate) => ({
+      id: candidate.id,
+      sourceType: candidate.provenance.sourceType,
+      ...(candidate.provenance.sourceRef !== undefined ? { sourceRef: candidate.provenance.sourceRef } : {}),
+    }));
+  return {
+    item,
+    lineage,
+    evidenceRefs: item.evidenceRefs ?? [],
+    sources,
+  };
+}