pluribus-context 0.3.34 → 0.3.36

package/docs/dynamic-workflow-run-receipts.md

@@ -0,0 +1,158 @@
+# Dynamic workflow run receipts
+
+Claude Code-style dynamic workflows move orchestration into a script that can spawn many subagents, keep intermediate results outside the parent conversation, and show progress by phase, agent count, token total, and elapsed time.
+
+That is useful when a codebase audit, migration, research task, or verification pass needs more parallelism than one conversation can coordinate. It also creates a new failure mode: one child agent can loop, burn tokens, or drift while the parent workflow only shows a high-level progress line.
+
+Use a dynamic workflow run receipt when a workflow, ultracode run, local LLM gateway, or multi-agent script delegates work across several agents/models and a human needs a privacy-safe summary of what actually happened.
+
+The first thing to look for is a **per-agent fuse**: budget, heartbeat, partial progress, stop reason, and kill-switch state for every spawned agent. After that, inspect whether the expensive path bought better verification or just more context drift.
+
+This is not an orchestration framework. The receipt is the stable artifact: compact evidence for each phase and spawned agent without logging raw prompts, source code, transcripts, tool output, secrets, customer data, or proprietary file paths.
+
+## When this helps
+
+Use this receipt when:
+
+- a workflow spawns several agents to audit, migrate, research, or verify a codebase;
+- agents may run different roles, models, or local/remote providers;
+- the run has a token/cost budget that needs to be explained after the fact;
+- a child agent could loop, stall, or keep spending while the parent workflow stays mostly blind;
+- the parent session sees only the final report, not every intermediate result;
+- a reviewer needs to know what context was loaded, skipped, or suppressed for each agent;
+- the run stops, pauses, resumes, or rejects a result and the stop point matters.
+
+## Receipt shape
+
+Attach this to a workflow report, PR body, task handoff, run summary, or CI artifact.
+
+```json
+{
+  "type": "dynamic.workflow.run_receipt.v1",
+  "workflow": {
+    "workflow_id": "wf_checkout_auth_audit_2026_05_30",
+    "runner": "claude-code-dynamic-workflow",
+    "script_source": "generated-then-reviewed-command",
+    "script_hash": "sha256:example-only",
+    "task_kind": "codebase_auth_audit",
+    "plan_approved_before_run": true,
+    "resumable": true,
+    "max_wall_clock_bucket": "under_15m",
+    "kill_switch_available": true,
+    "started_at": "2026-05-30T15:20:00Z",
+    "completed_at": "2026-05-30T15:31:42Z"
+  },
+  "permissions": {
+    "tool_allowlist_inherited": true,
+    "writes_allowed": false,
+    "network_allowed": false,
+    "external_commands_allowed": ["grep", "test --dry-run"],
+    "permission_profile": "review-only"
+  },
+  "phases": [
+    {
+      "phase_id": "route-inventory",
+      "purpose": "find candidate auth-sensitive routes",
+      "agent_count": 3,
+      "token_spend_bucket": "under_50k",
+      "elapsed_ms_bucket": "under_2m",
+      "result": "completed"
+    },
+    {
+      "phase_id": "adversarial-review",
+      "purpose": "cross-check candidate misses",
+      "agent_count": 2,
+      "token_spend_bucket": "under_25k",
+      "elapsed_ms_bucket": "under_2m",
+      "result": "completed_with_gaps"
+    }
+  ],
+  "agents": [
+    {
+      "agent_id": "agent-route-auditor-1",
+      "phase_id": "route-inventory",
+      "role": "route-auth-auditor",
+      "model": "claude-sonnet",
+      "provider": "anthropic",
+      "context_loaded": ["repo-policy", "auth-boundary-rules", "route-index-summary"],
+      "context_skipped_or_suppressed": [
+        {
+          "source": "customer-fixture-dump",
+          "reason": "contains raw customer data; summary hash only"
+        }
+      ],
+      "tools_granted": ["read", "grep"],
+      "tools_used": ["grep"],
+      "feature_areas_checked": ["checkout routes", "admin routes"],
+      "token_budget_bucket": "under_25k",
+      "token_spend_bucket": "under_10k",
+      "max_iterations": 8,
+      "iterations_used": 3,
+      "heartbeat_seen_at": "2026-05-30T15:25:00Z",
+      "partial_progress_reported": true,
+      "fuse_triggered": false,
+      "stop_reason": "completed_assigned_partition",
+      "confidence": "medium",
+      "known_gaps": ["did not execute integration tests"],
+      "raw_prompt_logged": false,
+      "raw_tool_output_logged": false,
+      "raw_paths_logged": false
+    },
+    {
+      "agent_id": "agent-reviewer-1",
+      "phase_id": "adversarial-review",
+      "role": "adversarial-auth-reviewer",
+      "model": "local-codex-compatible",
+      "provider": "local-llm-gateway",
+      "context_loaded": ["candidate-findings-summary", "public-api-contract-summary"],
+      "context_skipped_or_suppressed": [],
+      "tools_granted": ["read"],
+      "tools_used": ["read"],
+      "feature_areas_checked": ["route findings cross-check"],
+      "token_budget_bucket": "under_10k",
+      "token_spend_bucket": "under_10k",
+      "max_iterations": 5,
+      "iterations_used": 5,
+      "heartbeat_seen_at": "2026-05-30T15:30:00Z",
+      "partial_progress_reported": true,
+      "fuse_triggered": true,
+      "stop_reason": "iteration_budget_reached_before_claim_verified",
+      "confidence": "low",
+      "known_gaps": ["one route requires owner confirmation before merge"],
+      "raw_prompt_logged": false,
+      "raw_tool_output_logged": false,
+      "raw_paths_logged": false
+    }
+  ],
+  "handoff": {
+    "final_result_kind": "workflow_review_receipt",
+    "claims_rejected_or_deferred": 1,
+    "next_safe_action": "ask route owner to confirm checkout callback auth before writing fix",
+    "where_it_stopped": "ambiguous auth boundary before mutation"
+  },
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_source_logged": false,
+    "raw_tool_output_logged": false,
+    "transcripts_logged": false,
+    "secrets_logged": false,
+    "customer_data_logged": false
+  }
+}
+```
+
+## Minimal checklist
+
+Before trusting the result of a dynamic workflow, ask for:
+
+- workflow/run id, runner, script source, script hash, and whether the plan was approved before execution;
+- workflow-level wall-clock budget, whether a kill switch exists, and whether the run can be paused/resumed safely;
+- permission profile, inherited tool allowlist, write/network/command capability, and whether the run was review-only or mutating;
+- phases, agent counts, token spend buckets, elapsed-time buckets, and phase result states;
+- per-agent role, model/provider actually used, context loaded, context skipped/suppressed, tools granted/used, token budget/spend, iteration budget, heartbeat, partial progress, fuse state, stop reason, confidence, and known gaps;
+- explicit privacy flags proving raw prompts, source, transcripts, tool output, paths, secrets, and customer data were not logged;
+- a handoff that says what was accepted, rejected/deferred, where the workflow stopped, and the next safe action.
+
+## What not to log
+
+Do not include raw prompts, full workflow scripts when they reveal private structure, full transcripts, source code, exact proprietary paths, tool output, secrets, credentials, customer data, stack traces, or raw LLM gateway logs. Prefer coarse names, hashes, buckets, counts, role labels, decision states, stop reasons, and owner labels.

package/docs/install-plan-receipts.md

@@ -0,0 +1,79 @@
+# Install-plan receipts
+
+Use this when an MCP server, Skill bundle, plugin, starter kit, or setup script says it can configure many AI coding tools for you.
+
+The risk is not only whether a hook later runs safely. The earlier boundary is the installer itself: it may detect agents, write MCP config, add instruction files, install Skills, register hooks, or create backups before the user understands what changed.
+
+The goal is a tiny, privacy-safe pre-mutation receipt that proves what the setup step intends to touch **before the first write starts**. Do not log prompts, source code, secrets, raw environment dumps, transcripts, raw command output, customer data, or private absolute paths.
+
+## Boundary to prove
+
+For every setup/install run, capture a plan like this before applying changes:
+
+```json
+{
+  "receipt_type": "agent.install.plan.v1",
+  "run_id": "local-install-2026-05-29T16:00Z",
+  "installer": "code-memory-mcp",
+  "mode_requested": "plan",
+  "mode_effective": "plan",
+  "agents_detected": ["claude-code", "cursor", "codex", "openclaw"],
+  "agents_selected": ["claude-code", "openclaw"],
+  "planned_writes": [
+    {
+      "kind": "mcp_config",
+      "target": "claude-code project config",
+      "operation": "add_server",
+      "backup_planned": true
+    },
+    {
+      "kind": "instruction_file",
+      "target": "AGENTS.md",
+      "operation": "append_usage_notes",
+      "backup_planned": true
+    },
+    {
+      "kind": "hook",
+      "target": "pre-tool hook config",
+      "operation": "register_command",
+      "backup_planned": true
+    }
+  ],
+  "external_commands_planned": [
+    { "phase": "apply", "command_class": "package_manager_install" }
+  ],
+  "network_after_install": "mcp_server_localhost_only",
+  "writes_started": false,
+  "next_safe_command": "installer apply --from-plan install-plan.json"
+}
+```
+
+Keep `target` values coarse enough for review. Prefer `claude-code project config` over a full local path, and `package_manager_install` over raw shell output.
+
+## Acceptance checks
+
+A safe installer should make these claims inspectable:
+
+1. **Plan mode exists** — `install --plan`, `install --dry-run`, or equivalent emits the receipt without writing files.
+2. **Effective mode is explicit** — if the user requested `apply` but policy downgraded to `plan`, the receipt says so.
+3. **Agent detection is separated from selection** — finding Cursor/Codex/Claude/OpenClaw does not imply every detected tool will be changed.
+4. **Every planned write has a kind and backup decision** — config, instruction file, Skill, hook, shell profile, lockfile, cache, or generated artifact.
+5. **Writes are still false at receipt time** — `writes_started=false` is the key trust boundary.
+6. **Apply can be repeated from the plan** — the user can review one artifact, then run a concrete next command.
+7. **No private payloads leak** — no raw source, prompts, env dumps, secrets, token values, transcripts, stack traces, or raw tool output.
+
+## Why this matters for hooks and MCP
+
+Hooks, Skills, and MCP configs are often discussed as runtime supply-chain surfaces. That is true, but it is downstream. A one-command installer can create the hook or MCP entry first.
+
+A hook receipt answers: “what executed?”
+
+An install-plan receipt answers the earlier question: **“what is about to be installed, written, and trusted?”**
+
+If an installer cannot answer that before mutation, treat it like running CI from an untrusted fork: useful, but not automatically safe.
+
+## Try the copyable example
+
+See [`examples/install-plan-receipts/`](../examples/install-plan-receipts/) for a small review checklist and sample receipt you can copy into setup scripts, README install sections, or agent-managed onboarding workflows.
+
+After the installer has run, use [Skill install/load receipts](skill-install-receipts.md) when the next question is whether each target agent can discover/load the installed Skill and whether the install made the first session unsafe by adding too much always-loaded context.

package/docs/loaded-resource-boundary.md

@@ -0,0 +1,97 @@
+# Loaded-resource boundary receipts
+
+Use this when a Skill, plugin resource, MCP-provided instruction, or custom-agent file appears to be configured correctly but does not actually reach the agent runtime.
+
+This is the failure mode behind reports like:
+
+- "the Skill works in chat but not ACP/Zed/CLI";
+- "`/skills` or the skill list is unavailable in this client";
+- "the agent followed generic instructions because the real resource was never injected";
+- "a prompt workaround says resources are preloaded, but there is no proof they were readable by the runtime".
+
+Pluribus should not become a Skill manager. The useful boundary is a small receipt that proves what crossed from configuration into the run.
+
+## Receipt shape
+
+A loaded-resource receipt separates the stages that are often collapsed into "the skill exists":
+
+| Stage | Question |
+| --- | --- |
+| `expected` | Which resources did the user/config expect for this agent and task? |
+| `discovered` | Did the host find the resource on disk, in a plugin, registry, or MCP response? |
+| `attached` | Was the resource attached to the selected agent/profile/workspace? |
+| `injected` | Did the runtime put the resource into the model/tool context for this session? |
+| `readable` | Could the agent actually read the resource bytes or resolved prompt? |
+| `skipped` | If not, what precise stage and reason explain the gap? |
+
+Recommended privacy-safe fields:
+
+```json
+{
+  "receipt_type": "pluribus.loaded_resource_boundary.v1",
+  "scenario": "custom-agent skill parity across chat and ACP",
+  "expected_resources": [
+    {
+      "id": "skill:pr-review",
+      "kind": "skill",
+      "scope": "project",
+      "source_ref": ".kiro/skills/pr-review/SKILL.md",
+      "source_hash": "sha256:...",
+      "required": true
+    }
+  ],
+  "sessions": [
+    {
+      "runtime": "chat",
+      "client": "kiro-desktop",
+      "agent": "reviewer",
+      "discovered_resources": ["skill:pr-review"],
+      "attached_resources": ["skill:pr-review"],
+      "injected_resources": ["skill:pr-review"],
+      "readable_resources": ["skill:pr-review"],
+      "skipped_resources": []
+    },
+    {
+      "runtime": "acp",
+      "client": "zed",
+      "agent": "reviewer",
+      "discovered_resources": ["skill:pr-review"],
+      "attached_resources": ["skill:pr-review"],
+      "injected_resources": [],
+      "readable_resources": [],
+      "skipped_resources": [
+        {
+          "id": "skill:pr-review",
+          "stage": "injected",
+          "reason": "runtime_does_not_inject_resources"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Do not include raw skill text, private prompts, credentials, or full project memory. Hashes, refs, stage names, and skip reasons are enough for a maintainer to reproduce the boundary.
+
+## Acceptance test
+
+For the same custom agent and the same attached Skill/resource, compare chat vs ACP/CLI/IDE sessions:
+
+1. The resource should be `discovered` in each runtime that claims to support it.
+2. If it is attached in chat but not in ACP/Zed/CLI, record `not_attached_to_agent`.
+3. If it is attached but absent from the model context, record `runtime_does_not_inject_resources`.
+4. If it was injected but the bytes cannot be resolved, record `resource_read_failed`.
+5. If trigger logic prevented loading, record `trigger_not_matched` and include the matched task label or hash, not the full prompt.
+
+A useful bug report is not "Skills are broken". It is:
+
+> For agent `reviewer`, `skill:pr-review` is discovered and attached in both chat and ACP. Chat injects and reads it; ACP/Zed does not inject it and reports `runtime_does_not_inject_resources`.
+
+## Try the example
+
+```bash
+node examples/loaded-resource-boundary/check-loaded-resource-boundary.mjs \
+  examples/loaded-resource-boundary/loaded-resource-boundary.json
+```
+
+The sample intentionally includes a chat-vs-ACP mismatch and treats that mismatch as the useful finding.

package/docs/mcp-tool-visibility-receipts.md

@@ -0,0 +1,67 @@
+# MCP tool visibility receipts
+
+MCP memory, Git, GitLab, code-search, and knowledge-graph servers can be healthy while the agent still cannot see their tools.
+
+A useful debug artifact should prove each boundary separately:
+
+1. **Server launched** — the configured command starts without leaking env/secrets.
+2. **Handshake completed** — client and server agreed on a protocol version and capabilities.
+3. **Proxy catalog returned** — a direct `tools/list` call returns the expected tool count and names.
+4. **Client catalog visible** — the actual agent UI/runtime exposes the same tools under the expected names.
+5. **Invocation allowed or refused** — the first tool call either runs, or returns an explicit permission/config/schema reason.
+
+`server healthy` is not enough. `tools/list` is not enough. The receipt needs to say where the chain stopped.
+
+## 60-second probe for any stdio MCP server
+
+Replace the command after the pipe with the server command you already configured in Claude Code, Cursor, Codex, OpenClaw, or another MCP client.
+
+```bash
+(
+  printf '%s\n' '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"receipt-probe","version":"0.1.0"}},"id":1}'
+  printf '%s\n' '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'
+) | your-mcp-server-command
+```
+
+Record only metadata, not raw prompt/source/tool output:
+
+```json
+{
+  "kind": "mcp.tool_visibility.receipt",
+  "server": "gitlab",
+  "server_command_hash": "sha256:...",
+  "protocol_version_requested": "2024-11-05",
+  "handshake": "ok",
+  "proxy_tools_count": 172,
+  "proxy_tool_names_sample": ["glab_issue_list", "glab_mr_view"],
+  "client": "Claude Code",
+  "client_catalog_visible": false,
+  "client_tools_count": 0,
+  "stopped_at": "client_catalog_visible",
+  "privacy": "names/counts only; no args, outputs, tokens, paths, or source snippets"
+}
+```
+
+## Acceptance check
+
+For a release or bug report, ask for one small matrix:
+
+| Boundary | Evidence | Pass condition |
+| --- | --- | --- |
+| Launch | server command hash + exit/live status | command starts and stays alive long enough for handshake |
+| Handshake | protocol version + capabilities summary | initialized without version/schema mismatch |
+| Proxy catalog | `tools/list` count + stable tool-name sample | expected tools returned directly |
+| Client catalog | client-visible count + naming prefix | same class of tools visible to the agent |
+| First invocation | allowed/refused reason | failure explains permission/config/schema, not silent absence |
+
+This shape is intentionally compatible with GitHub/GitLab issue reports and OpenTelemetry-style events. It helps maintainers separate server bugs from client catalog, protocol-version, schema, timeout, and permission bugs without asking users to paste private output.
+
+## Why this belongs near Pluribus
+
+Pluribus should not become an MCP gateway or memory database. The narrow value is evidence for context boundaries:
+
+- generated instruction files prove what static rules were written;
+- memory/search receipts prove what retrieved context was delivered;
+- tool visibility receipts prove whether a configured MCP capability actually crossed into the agent's usable catalog.
+
+If a tool is not visible to the agent, the project has no reliable context handoff no matter how healthy the server looks.

package/docs/memory-write-policy-receipts.md

@@ -0,0 +1,41 @@
+# Memory write policy receipts
+
+Cross-agent memory tools usually optimize recall: make Claude Code, Codex, Cursor, OpenClaw, ChatGPT, or MCP clients find the same facts later.
+
+The adoption risk is different: **who is allowed to write durable memory, under what scope, and with what rollback or review path?**
+
+Pluribus should not become another memory server. This receipt is a small governance layer for shared memory systems: every durable memory update is treated like a proposed diff before it becomes trusted context for future agents.
+
+## Receipt boundary
+
+A memory write receipt should prove:
+
+- **source** — where the proposed memory came from, with a hash/ref instead of raw transcript or raw memory body;
+- **scope** — whether the write is repo, project, org, or user scoped;
+- **proposed diff** — adds/updates/supersedes/expires by stable refs and hashes;
+- **write policy** — proposed, approved, rejected, or quarantined; who/what approved it;
+- **lifecycle** — expiry or review date so stale facts do not become immortal;
+- **injection visibility** — future sessions can see which memory was injected;
+- **privacy flags** — no raw prompts, raw tool output, raw memory text, or secrets in the receipt.
+
+## 60-second gate
+
+The copyable example is in [`examples/memory-write-policy/`](../examples/memory-write-policy/):
+
+```bash
+node examples/memory-write-policy/check-memory-update.mjs \
+  examples/memory-write-policy/approved-memory-update.json
+
+node examples/memory-write-policy/check-memory-update.mjs \
+  examples/memory-write-policy/quarantined-memory-update.json
+```
+
+The first passes because the write is approved, scoped, hashed, visible to future sessions, and has a review lifecycle. The second fails because it tries to turn a quarantined, broad user-scoped, private/sensitive update into durable shared memory and includes raw text.
+
+## Positioning
+
+Memory systems remember. Hooks and workflow engines execute. This receipt answers a narrower review question:
+
+> Is this memory update allowed to become durable context for other agents?
+
+That makes shared memory safer without requiring the memory provider to expose private content or the agent transcript.

package/docs/parallel-session-review-ledger.md

@@ -0,0 +1,103 @@
+# Parallel session review ledger
+
+Use this when you run multiple Claude Code, Cursor, Codex, OpenClaw, or terminal-agent sessions in parallel and the bottleneck is no longer starting work — it is deciding whether each result can be trusted, rejected, or safely resumed.
+
+The point is not orchestration. A review ledger is a small privacy-safe receipt that lets a human or a follow-up agent answer:
+
+- what was this session assigned to do?
+- which files, commands, and external systems was it allowed to touch?
+- what does the agent claim changed?
+- what evidence exists outside the agent summary?
+- which checks are still missing?
+- is the next reviewer allowed to continue, or should they stop and inspect?
+
+Do **not** paste raw prompts, source code, secrets, customer data, transcripts, or full tool output into the ledger. Store stable references, hashes, check names, commit ids, redacted paths, and short evidence labels instead.
+
+## Minimal receipt
+
+```json
+{
+  "schema": "pluribus.parallel_session_review_ledger.v1",
+  "generated_at": "2026-06-04T19:00:00Z",
+  "run": {
+    "orchestrator": "human",
+    "repo": "redacted-service",
+    "coordination_mode": "parallel_sessions"
+  },
+  "sessions": [
+    {
+      "id": "session-a",
+      "agent": "claude-code",
+      "assignment": "update validation for billing webhook retries",
+      "branch": "agent/billing-webhook-retry-validation",
+      "allowed_scope": {
+        "files": ["src/billing/**", "test/billing/**"],
+        "commands": ["npm test -- --test-name-pattern=billing"],
+        "network": "none"
+      },
+      "agent_claim": "added retry validation and regression coverage",
+      "evidence": [
+        {
+          "type": "commit",
+          "ref": "abc1234"
+        },
+        {
+          "type": "test",
+          "name": "billing retry validation",
+          "status": "passed"
+        }
+      ],
+      "missing_checks": [],
+      "privacy_flags": [],
+      "state": "complete",
+      "safe_next_action": "review_diff"
+    }
+  ]
+}
+```
+
+## Review states
+
+| State | Meaning | Required next action |
+| --- | --- | --- |
+| `complete` | Assignment is done and required evidence exists. | Review the diff or merge path normally. |
+| `partial` | Some useful work exists but a required check or boundary is missing. | Continue only after the missing check/scope is resolved. |
+| `blocked` | The agent stopped before a useful handoff. | Reassign or inspect the blocker before continuing. |
+| `unsafe_to_resume` | Scope, privacy, command, or evidence boundaries were violated. | Stop; inspect manually before any follow-up agent uses the result. |
+
+## Safe next actions
+
+Use constrained verbs so another session does not turn a vague summary into authority:
+
+- `review_diff`
+- `run_missing_check`
+- `continue_same_scope`
+- `ask_human`
+- `stop_manual_review`
+
+## Copyable checker
+
+The example in [`examples/parallel-session-review-ledger/`](../examples/parallel-session-review-ledger/) validates the useful minimum:
+
+- every session has an assignment, branch, allowed scope, state, and safe next action;
+- `complete` sessions have evidence and no missing checks;
+- `partial` sessions name missing checks;
+- `unsafe_to_resume` sessions use `stop_manual_review`;
+- sessions with privacy flags cannot be marked complete;
+- no session writes outside its declared file scope.
+
+Run it from the repo root:
+
+```bash
+node examples/parallel-session-review-ledger/check-parallel-session-review-ledger.mjs examples/parallel-session-review-ledger/parallel-session-review-ledger.json
+```
+
+Expected output:
+
+```text
+parallel session review ledger ok: 3 sessions checked
+```
+
+## Positioning
+
+Parallel agents do not fail only because models are weak. They fail because the human reviewer loses the boundary of each run. A ledger turns "the agent says it is done" into a small resume/reject object: assignment, scope, evidence, missing checks, and safe next action.

package/docs/phase-boundary-contracts.md

@@ -0,0 +1,87 @@
+# Phase-boundary contracts for multi-model coding workflows
+
+Use this when a coding workflow routes work through phases such as **Explore → Propose → Spec → Design → Tasks → Apply → Verify**, especially when different tools or models handle different phases.
+
+The problem is not only “which model is best for this step”. The failure mode is handoff: a plan agent burns context, a build agent receives a lossy summary, a verifier cannot tell which decisions are current, and stale assumptions leak from one phase into the next.
+
+A phase-boundary contract makes every transition explicit:
+
+- what input context was allowed into the phase;
+- what artifact the phase had to produce;
+- what evidence is required before the next phase may start;
+- what context must not be carried forward;
+- which stop conditions require human review or a fresh phase run.
+
+This keeps Pluribus out of the orchestration layer. The workflow runner can be OpenCode, Claude Code, Cursor, OpenClaw, Codex, a local script, or a human checklist. Pluribus supplies the evidence shape.
+
+## Contract shape
+
+```json
+{
+  "schema": "pluribus.phase-boundary-contract.v1",
+  "workflowId": "checkout-refactor-2026-06-03",
+  "currentPhase": "apply",
+  "nextPhase": "verify",
+  "allowedInput": [
+    {
+      "kind": "approved_plan",
+      "ref": "plans/checkout-refactor.md",
+      "contentHash": "sha256:...",
+      "required": true
+    }
+  ],
+  "outputArtifact": {
+    "kind": "patch",
+    "ref": "git:working-tree",
+    "contentHash": "sha256:..."
+  },
+  "evidenceGate": {
+    "requiredBeforeNextPhase": ["changed_files", "tests_run", "open_risks", "stop_conditions"],
+    "status": "pass"
+  },
+  "droppedContext": [
+    {
+      "kind": "exploration_transcript",
+      "reason": "not authoritative after approved plan"
+    }
+  ],
+  "stopConditions": []
+}
+```
+
+## Minimum fields
+
+| Field | Why it exists |
+| --- | --- |
+| `workflowId` | Correlates phase records without storing a transcript. |
+| `currentPhase` / `nextPhase` | Makes the handoff boundary explicit. |
+| `allowedInput[]` | Prevents the next model from inheriting stale scratch context accidentally. |
+| `outputArtifact` | Names the thing this phase produced: plan, spec, task list, patch, review, or verification report. |
+| `evidenceGate.requiredBeforeNextPhase[]` | Forces the phase to prove the minimum facts the next phase depends on. |
+| `droppedContext[]` | Records what intentionally did **not** cross the boundary. |
+| `stopConditions[]` | Lets the workflow stop instead of laundering uncertainty into the next model. |
+
+## Apply → Verify is the strictest boundary
+
+For coding workflows, the most useful hard gate is often between Apply and Verify. The verifier should receive a compact evidence packet, not a vague “I implemented it” summary:
+
+- decision implemented;
+- source/plan hash used;
+- changed files or file-set hash;
+- tests/commands run with pass/fail state;
+- open risks and skipped checks;
+- whether secrets, schema migrations, data writes, or external calls were touched;
+- explicit stop condition if verification cannot be trusted.
+
+## Privacy boundary
+
+Do not put raw source, prompts, transcripts, secrets, full command output, absolute local paths, or customer data in the contract. Use stable refs, hashes, counts, risk classes, and short non-secret labels.
+
+## Try it
+
+```bash
+cd examples/phase-boundary-contract
+node check-phase-boundary.mjs phase-boundary-contract.json
+```
+
+The checker is intentionally small. It is a copyable acceptance test for workflow builders: if a phase handoff cannot pass this gate, the next model should not pretend it has reliable state.