pluribus-context 0.3.41 → 0.3.42

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.42 - 2026-06-17
+
+- Added `pluribus demo context-sufficiency-trace`, a tiny npm-runnable pass/fail demo for checking whether a compressed context bundle preserved the task's required files before editing began.
+
 ## 0.3.41 - 2026-06-10
 
 - Added npm Agent Skills discovery keywords (`agent-skill`, `skillpm`, and `agent-skills-registry`) so `pluribus-context` can be indexed by npm-backed skill package managers while continuing to ship the existing low-authority `skills/*/SKILL.md` recipes.

package/README.md

@@ -14,7 +14,7 @@ The original sync workflow is still useful: Pluribus can keep project instructio
 
 It is **not** a persistent memory layer, retrieval system, agent orchestrator, enterprise ContextOps platform, or agent-merging framework. Think evidence for context boundaries: `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `AGENTS.md`, MCP Tool Search, Agent Skills, RAG/code-search, pruning, and compaction — with privacy-safe receipts instead of raw content dumps.
 
-**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and disposable 60-second smoke tests. If you only run one command for the cross-tool audit, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, load evidence, duplicate-load selection evidence, manual activation requirements, effective context scope, and semantic differences. For the agent-observability wedge, start with [context-budget receipts](docs/context-budget-receipts.md): privacy-safe evidence for what MCP schemas, skills, memory, subagents, CLI help, retrieval chunks, pruning runs, or compaction summaries crossed an agent boundary. It now explicitly covers the "Tool Search fixed MCP bloat" objection: the receipt proves which lane stayed deferred, which tool was expanded, and whether schemas leaked through `messages`/bootstrap anyway. For a 60-second runtime-discovery proof, run `npx --yes pluribus-context@latest demo tool-surface-diff --json`; it validates a receipt for discovered → activated → withheld/blocked MCP tools without raw schemas/prompts/results. If you are coming from Claude Code, GraphRAG, or memory tooling where retrieval succeeds but the agent ignores it, try the [context attention receipt example](examples/context-attention-receipts/) to prove required context was delivered, acknowledged, and cited before edits. If you want the same idea as a copyable skill, use the [context-receipts Agent Skill recipe](skills/context-receipts/). npm `latest` is currently aligned with the GitHub release; the review packet also documents a GitHub-release smoke fallback for future release-lag windows.
+**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and disposable 60-second smoke tests. If you are comparing plugins, Skills registries, config-sync tools, MCP setups, or Claude→Codex worker flows, start with the [Agent surface proof chain](docs/agent-surface-proof-chain.md) to separate install diffs, sync manifests, apply ledgers, surface state, selection traces, context-boundary spans, and handoff envelopes. If you only run one command for the cross-tool audit, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, load evidence, duplicate-load selection evidence, manual activation requirements, effective context scope, and semantic differences. For the agent-observability wedge, start with [context-budget receipts](docs/context-budget-receipts.md): privacy-safe evidence for what MCP schemas, skills, memory, subagents, CLI help, retrieval chunks, pruning runs, or compaction summaries crossed an agent boundary. It now explicitly covers the "Tool Search fixed MCP bloat" objection: the receipt proves which lane stayed deferred, which tool was expanded, and whether schemas leaked through `messages`/bootstrap anyway. For a 60-second runtime-discovery proof, run `npx --yes pluribus-context@latest demo tool-surface-diff --json`; it validates a receipt for discovered → activated → withheld/blocked MCP tools without raw schemas/prompts/results. If you are coming from Claude Code, GraphRAG, or memory tooling where retrieval succeeds but the agent ignores it, try the [context attention receipt example](examples/context-attention-receipts/) to prove required context was delivered, acknowledged, and cited before edits. If MCP server catalogs are burning context before the task needs them, try the [task-scoped MCP config receipt demo](examples/task-scoped-mcp-config/) to generate a minimal `--mcp-config` plus a receipt for selected vs withheld servers. If a Claude Code Skill or paste-cleaning CLI claims big token savings, try the [semantic anchor preservation receipt demo](examples/semantic-anchor-receipts/) to prove the cleaned paste kept headings, API signatures, version notes, and security constraints. If a long Claude Code session, compaction, or topic switch makes `CLAUDE.md` feel stale, try the [CLAUDE.md read receipt example](examples/claude-md-read-receipts/) to prove which index/topic files were reloaded before the next edit. If Claude Code, Codex, or an API-backed agent starts timing out, drifting on tool choice, or producing bad patch formats while the status page is unclear, try the [provider degradation canary receipt example](examples/provider-degradation-canaries/) to decide whether writes should continue, fallback, or pause. If you want the same idea as a copyable skill, use the [context-receipts Agent Skill recipe](skills/context-receipts/). npm `latest` is currently aligned with the GitHub release; the review packet also documents a GitHub-release smoke fallback for future release-lag windows.
 
 ---
 
@@ -161,7 +161,7 @@ npx --yes pluribus-context@latest sync --dry-run
 
 If the preview looks right, run `npx --yes pluribus-context@latest sync` to write the tool-specific files.
 
-For a fuller walkthrough, see the [Quickstart](docs/quickstart.md). To enforce generated context files in pull requests, use the [CI audit example](docs/ci-audit-example.md); to catch drift before commits leave your machine, use the [Pre-commit Audit Hook](docs/pre-commit-audit.md). If your repo already has `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, run a [Context Drift Audit](docs/context-drift-audit.md) first, try the intentionally drifted [audit example](examples/context-drift-audit/), then follow [Migrate Existing AI Context Files](docs/migrate-existing-context.md). If you switch between Cursor, Claude Code, Copilot, and terminal agents, try the [Cursor ↔ Claude Code context handoff guide](docs/cursor-claude-context-handoff.md) and its [example source file](examples/context-handoff/pluribus.md). If you run multiple AI sessions on the same project, try the [Coordination Contract guide](docs/coordination-contract.md) and its [example source file](examples/coordination-contract/pluribus.md) to keep event-log/scratchpad protocol rules aligned without turning Pluribus into an orchestrator. If you evaluate code-search, MCP retrieval, RAG-over-notes, or agent memory tools, use the [Orchestration-layer Search Receipts](docs/orchestration-search-receipts.md) sketch to measure retrieved context from the harness layer without asking retrieval tools to inspect whole transcripts. If you are adding agent observability, traces, or OpenTelemetry-style events, start with [Context Receipts for Agent Observability](docs/context-receipts-for-agent-observability.md), then use the [Context Input Evidence](docs/context-input-evidence.md) sketch and its [executable demos](examples/context-input-evidence/) to separate source bytes, canonical text, delivered hashes, post-hoc session-log receipts, skill/plugin invocation receipts, shared-memory retrieval receipts, self-remediating brain/doctor receipts, and OpenTelemetry-style SpanEvents. If you publish AI rules, skills, or instruction bundles as "portable", use the [Portability Fidelity Report](docs/portability-fidelity-report.md) and its [example source file](examples/portability-fidelity/pluribus.md) to make compatibility claims evidence-based instead of self-attested. Before committing shared or generated AI instructions, use the [Context File Review Checklist](docs/context-file-review.md). If you're deciding between Pluribus and a one-way rules converter, see [When to use Pluribus](docs/when-to-use-pluribus.md). If you are debugging "context drift" after compaction or long sessions, start with the [Context Drift Taxonomy](docs/context-drift-taxonomy.md) to separate file drift from runtime precedence drift. If you use MCP memory or knowledge-graph tools, try the [MCP memory handoff demo](docs/memory-mcp-handoff.md) to keep recall/store protocols aligned across AI coding tools without turning Pluribus into a memory server. If your shared-memory or knowledge-graph setup lets agents write durable facts, use [Memory write policy receipts](docs/memory-write-policy-receipts.md) and the [copyable gate](examples/memory-write-policy/) to require proposed diffs, scope, lifecycle, visibility, approval, and privacy checks before one run can teach every harness. If hooks, local gateways, or agent firewalls block risky tool calls, use [Agent firewall denial/audit receipts](docs/agent-firewall-denial-audit.md) and the [copyable checker](examples/agent-firewall-denial-audit/) to split model-visible denial from private operator audit evidence. If you are turning Claude Code/OpenClaw/Cursor into role-based “AI employee” agents with Skills and memory folders, use the [Controlled learning queue](docs/controlled-learning-queue.md) and [copyable example](examples/controlled-learning-queue/) to let agents propose durable memory changes without silently rewriting shared ICP, pricing, compliance, or process assumptions. If `PreCompact` / `PostCompact` or `SessionStart(compact)` workflows decide whether an agent may continue after summarization, use [Compaction resume receipts](docs/compaction-resume-receipts.md) and the [copyable gate](examples/compaction-resume-receipts/) to prove what was summarized, which instruction sources reloaded, what state was lost/kept, and whether `safe_to_resume` is actually true. If an MCP server is healthy but tools are missing in Claude Code/Cursor/Codex, use the [MCP tool visibility receipts](docs/mcp-tool-visibility-receipts.md) checklist to separate launch, handshake, `tools/list`, client catalog, and first invocation failures. If a Claude Code/OpenClaw-style Skill states a hard rule but the run still violates it, use the [Skill policy receipts](docs/skill-policy-receipts.md) guide and [copyable Skill recipe](skills/skill-policy-receipts/) to turn target decisions, refusals, and post-write guards into privacy-safe evidence. If a Skill, plugin resource, MCP instruction, or custom-agent file exists but disappears in ACP/Zed/CLI/chat parity tests, use [Loaded-resource boundary receipts](docs/loaded-resource-boundary.md) and the [copyable checker](examples/loaded-resource-boundary/) to prove discovered, attached, injected, readable, and skipped-resource stages. If long-lived projects keep old specs/TODOs that still match grep but are no longer authoritative, use [Temporal context receipts](docs/temporal-context-receipts.md) and the [copyable current-state example](examples/temporal-context-receipts/) to separate current authority from historical citations before an agent writes code. If AI-generated pull requests are hard to review because diff size hides operational risk, use [AI PR review receipts](docs/ai-pr-review-receipts.md), the [copyable PR template](examples/ai-pr-review-receipts/), and the [GitHub Actions receipt gate](examples/ai-pr-review-receipts/.github/workflows/ai-pr-review-receipt.yml) to review by blast radius: schema/data contracts, async paths, rollout gates, side effects, and ambiguous boundaries. If you delegate work to Codex/Claude Code/Cursor/OpenClaw-style specialist subagents, use [Subagent role receipts](docs/subagent-role-receipts.md) and the [example role definitions](examples/subagent-role-receipts/) to prove the requested role, effective role, loaded instruction source, allowed/refused capabilities, stop point, and next safe action. If you run Claude Code-style dynamic workflows, ultracode, or local LLM gateway orchestration that spawns many agents, use [Dynamic workflow run receipts](docs/dynamic-workflow-run-receipts.md) and the [copyable workflow example](examples/dynamic-workflow-run-receipts/) to prove phases, per-agent roles/models, context loaded/skipped, tool grants, token spend buckets, per-agent fuses, heartbeat, stop reasons, and known gaps. If your workflow routes Explore/Propose/Spec/Design/Tasks/Apply/Verify across OpenCode, Claude Code, Cursor, Codex, or different models, use [Phase-boundary contracts](docs/phase-boundary-contracts.md) and the [copyable Apply→Verify gate](examples/phase-boundary-contract/) to prove allowed input context, output artifact, evidence required before the next phase, dropped context, and stop conditions. If you need CI/reviewers to decide whether an agent handoff can continue, must be reviewed, or should be rejected, use the [Review primitive gate](docs/review-primitive-gate.md), its [copyable gate example](examples/review-primitive-gate/), and the [Claude Code review hook bridge](examples/claude-code-review-hook/) to validate assignment boundaries, approved scope/access changes, required checks, privacy flags, and `complete / partial / unsafe-to-resume` state from CI or Claude Code `TaskCompleted` / `PostCompact` hooks. If Claude Projects, long chats, or compaction make the last clean artifact hard to recover, use [Canonical output receipts](docs/canonical-output-receipts.md) and the [copyable index example](examples/canonical-output-receipts/) to track stable IDs, paths, versions, exact grep phrases, decisions, rejected options, and next actions. If a setup script installs MCP servers, Skills, instruction files, hooks, or plugins across multiple agents, use [Install-plan receipts](docs/install-plan-receipts.md) and the [copyable example](examples/install-plan-receipts/) to prove planned writes, backups, network behavior, and `writes_started=false` before mutation. After a Skill installer runs, use [Skill install/load receipts](docs/skill-install-receipts.md) and the [copyable checker](examples/skill-install-receipts/) to prove source ref, target agents/scopes, discovery/load status, context-cost bucket, and `safe_to_start_session` without logging raw Skill bodies. If you are pruning Skill sprawl after real sessions, use [Skill use-rate receipts](docs/skill-use-rate-receipts.md) and the [copyable checker](examples/skill-use-rate-receipts/) to separate discovered/installed/attached from invoked/acted-on and catch "installed but unused" resources. If you supervise multiple Claude Code/Cursor/Codex/OpenClaw sessions in parallel, use the [Parallel session review ledger](docs/parallel-session-review-ledger.md) and [copyable checker](examples/parallel-session-review-ledger/) to decide which sessions are complete, partial, blocked, or unsafe to resume without trusting an agent summary. If you are reviewing Pluribus for a list, newsletter, or tool directory, use the [Community Review Packet](docs/community-review-packet.md) for directory submission fields, a one-line description, safety notes, and a disposable 60-second smoke test. Maintainers can track package/repo discovery with the [Discovery Smoke Checks](docs/discovery-smoke.md).
+For a fuller walkthrough, see the [Quickstart](docs/quickstart.md). To enforce generated context files in pull requests, use the [CI audit example](docs/ci-audit-example.md); to catch drift before commits leave your machine, use the [Pre-commit Audit Hook](docs/pre-commit-audit.md). If your repo already has `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, run a [Context Drift Audit](docs/context-drift-audit.md) first, try the intentionally drifted [audit example](examples/context-drift-audit/), then follow [Migrate Existing AI Context Files](docs/migrate-existing-context.md). If you switch between Cursor, Claude Code, Copilot, and terminal agents, try the [Cursor ↔ Claude Code context handoff guide](docs/cursor-claude-context-handoff.md), its [example source file](examples/context-handoff/pluribus.md), and the copyable handoff receipt for checking stale source files, diverged tool rules, wrong memories, dead commands, and not-loaded context before another agent writes code. If you run multiple AI sessions on the same project, try the [Coordination Contract guide](docs/coordination-contract.md) and its [example source file](examples/coordination-contract/pluribus.md) to keep event-log/scratchpad protocol rules aligned without turning Pluribus into an orchestrator. If you evaluate code-search, MCP retrieval, RAG-over-notes, or agent memory tools, use the [Orchestration-layer Search Receipts](docs/orchestration-search-receipts.md) sketch to measure retrieved context from the harness layer without asking retrieval tools to inspect whole transcripts. If you are adding agent observability, traces, or OpenTelemetry-style events, start with [Context Receipts for Agent Observability](docs/context-receipts-for-agent-observability.md), then use the [Context Input Evidence](docs/context-input-evidence.md) sketch and its [executable demos](examples/context-input-evidence/) to separate source bytes, canonical text, delivered hashes, post-hoc session-log receipts, skill/plugin invocation receipts, shared-memory retrieval receipts, self-remediating brain/doctor receipts, and OpenTelemetry-style SpanEvents. If you publish AI rules, skills, or instruction bundles as "portable", use the [Portability Fidelity Report](docs/portability-fidelity-report.md) and its [example source file](examples/portability-fidelity/pluribus.md) to make compatibility claims evidence-based instead of self-attested. Before committing shared or generated AI instructions, use the [Context File Review Checklist](docs/context-file-review.md). If you're deciding between Pluribus and a one-way rules converter, see [When to use Pluribus](docs/when-to-use-pluribus.md). If you are debugging "context drift" after compaction or long sessions, start with the [Context Drift Taxonomy](docs/context-drift-taxonomy.md) to separate file drift from runtime precedence drift, then use the [CLAUDE.md read receipt example](examples/claude-md-read-receipts/) when the practical question is whether a session actually reloaded the right index/topic files before editing. If you use MCP memory or knowledge-graph tools, try the [MCP memory handoff demo](docs/memory-mcp-handoff.md) to keep recall/store protocols aligned across AI coding tools without turning Pluribus into a memory server. If a provider/model may be silently degraded, use the [provider degradation canary receipt example](examples/provider-degradation-canaries/) to record transport health, capability canaries, fallback choice, and the write gate before side effects. If your shared-memory or knowledge-graph setup lets agents write durable facts, use [Memory write policy receipts](docs/memory-write-policy-receipts.md) and the [copyable gate](examples/memory-write-policy/) to require proposed diffs, scope, lifecycle, visibility, approval, and privacy checks before one run can teach every harness. If hooks, local gateways, or agent firewalls block risky tool calls, use [Agent firewall denial/audit receipts](docs/agent-firewall-denial-audit.md) and the [copyable checker](examples/agent-firewall-denial-audit/) to split model-visible denial from private operator audit evidence. If you are turning Claude Code/OpenClaw/Cursor into role-based “AI employee” agents with Skills and memory folders, use the [Controlled learning queue](docs/controlled-learning-queue.md) and [copyable example](examples/controlled-learning-queue/) to let agents propose durable memory changes without silently rewriting shared ICP, pricing, compliance, or process assumptions. If `PreCompact` / `PostCompact` or `SessionStart(compact)` workflows decide whether an agent may continue after summarization, use [Compaction resume receipts](docs/compaction-resume-receipts.md) and the [copyable gate](examples/compaction-resume-receipts/) to prove what was summarized, which instruction sources reloaded, what state was lost/kept, and whether `safe_to_resume` is actually true. If MCP tools consume context before a task needs them, use the [Task-scoped MCP config receipt demo](examples/task-scoped-mcp-config/) to generate a minimal `--mcp-config` and prove which servers were selected or withheld before startup. If an MCP server is healthy but tools are missing in Claude Code/Cursor/Codex, use the [MCP tool visibility receipts](docs/mcp-tool-visibility-receipts.md) checklist to separate launch, handshake, `tools/list`, client catalog, and first invocation failures. If a Claude Code/OpenClaw-style Skill states a hard rule but the run still violates it, use the [Skill policy receipts](docs/skill-policy-receipts.md) guide and [copyable Skill recipe](skills/skill-policy-receipts/) to turn target decisions, refusals, and post-write guards into privacy-safe evidence. If a Skill, plugin resource, MCP instruction, or custom-agent file exists but disappears in ACP/Zed/CLI/chat parity tests, use [Loaded-resource boundary receipts](docs/loaded-resource-boundary.md) and the [copyable checker](examples/loaded-resource-boundary/) to prove discovered, attached, injected, readable, and skipped-resource stages. If long-lived projects keep old specs/TODOs that still match grep but are no longer authoritative, use [Temporal context receipts](docs/temporal-context-receipts.md) and the [copyable current-state example](examples/temporal-context-receipts/) to separate current authority from historical citations before an agent writes code. If AI-generated pull requests are hard to review because diff size hides operational risk, use [AI PR review receipts](docs/ai-pr-review-receipts.md), the [copyable PR template](examples/ai-pr-review-receipts/), and the [GitHub Actions receipt gate](examples/ai-pr-review-receipts/.github/workflows/ai-pr-review-receipt.yml) to review by blast radius: schema/data contracts, async paths, rollout gates, side effects, and ambiguous boundaries. If you delegate work to Codex/Claude Code/Cursor/OpenClaw-style specialist subagents, use [Subagent role receipts](docs/subagent-role-receipts.md) and the [example role definitions](examples/subagent-role-receipts/) to prove the requested role, effective role, loaded instruction source, allowed/refused capabilities, stop point, and next safe action. If you run Claude Code-style dynamic workflows, ultracode, or local LLM gateway orchestration that spawns many agents, use [Dynamic workflow run receipts](docs/dynamic-workflow-run-receipts.md) and the [copyable workflow example](examples/dynamic-workflow-run-receipts/) to prove phases, per-agent roles/models, context loaded/skipped, tool grants, token spend buckets, per-agent fuses, heartbeat, stop reasons, and known gaps. If your workflow routes Explore/Propose/Spec/Design/Tasks/Apply/Verify across OpenCode, Claude Code, Cursor, Codex, or different models, use [Phase-boundary contracts](docs/phase-boundary-contracts.md) and the [copyable Apply→Verify gate](examples/phase-boundary-contract/) to prove allowed input context, output artifact, evidence required before the next phase, dropped context, and stop conditions. If you need CI/reviewers to decide whether an agent handoff can continue, must be reviewed, or should be rejected, use the [Review primitive gate](docs/review-primitive-gate.md), its [copyable gate example](examples/review-primitive-gate/), and the [Claude Code review hook bridge](examples/claude-code-review-hook/) to validate assignment boundaries, approved scope/access changes, required checks, privacy flags, and `complete / partial / unsafe-to-resume` state from CI or Claude Code `TaskCompleted` / `PostCompact` hooks. If Claude Projects, long chats, or compaction make the last clean artifact hard to recover, use [Canonical output receipts](docs/canonical-output-receipts.md) and the [copyable index example](examples/canonical-output-receipts/) to track stable IDs, paths, versions, exact grep phrases, decisions, rejected options, and next actions. If a setup script installs MCP servers, Skills, instruction files, hooks, or plugins across multiple agents, use [Install-plan receipts](docs/install-plan-receipts.md) and the [copyable example](examples/install-plan-receipts/) to prove planned writes, backups, network behavior, and `writes_started=false` before mutation. After a Skill installer runs, use [Skill install/load receipts](docs/skill-install-receipts.md) and the [copyable checker](examples/skill-install-receipts/) to prove source ref, target agents/scopes, discovery/load status, context-cost bucket, and `safe_to_start_session` without logging raw Skill bodies. If you are pruning Skill sprawl after real sessions, use [Skill use-rate receipts](docs/skill-use-rate-receipts.md) and the [copyable checker](examples/skill-use-rate-receipts/) to separate discovered/installed/attached from invoked/acted-on and catch "installed but unused" resources. If you supervise multiple Claude Code/Cursor/Codex/OpenClaw sessions in parallel, use the [Parallel session review ledger](docs/parallel-session-review-ledger.md) and [copyable checker](examples/parallel-session-review-ledger/) to decide which sessions are complete, partial, blocked, or unsafe to resume without trusting an agent summary. If you are reviewing Pluribus for a list, newsletter, or tool directory, use the [Community Review Packet](docs/community-review-packet.md) for directory submission fields, a one-line description, safety notes, and a disposable 60-second smoke test. Maintainers can track package/repo discovery with the [Discovery Smoke Checks](docs/discovery-smoke.md).
 
 ### Usage
 
@@ -407,6 +407,7 @@ If you've felt this pain, tell me about your setup. What tools do you use? How d
 - [OpenClaw Integration](docs/openclaw-integration.md) — how Pluribus generates `AGENTS.md` for OpenClaw
 - [Composable Contexts](docs/composable-contexts.md) — local/remote imports, merge behavior, and safety rules
 - [MCP Memory Handoff](docs/memory-mcp-handoff.md) — demo for keeping memory recall/store protocols aligned across tool-specific instruction files
+- [Task-scoped MCP Config Receipt](examples/task-scoped-mcp-config/) — generate a minimal `--mcp-config` plus selected/withheld server receipt for MCP context-bloat reviews
 - [MCP Tool Visibility Receipts](docs/mcp-tool-visibility-receipts.md) — checklist for debugging healthy MCP servers whose tools do not appear in the agent client catalog
 - [MCP Runtime Config Receipts](docs/mcp-runtime-config-receipts.md) — live-vs-template evidence for MCP permission/config drift review
 - [Remote Composable Context Imports](docs/remote-composable-context-imports.md) — design notes for lockfile/cache/auth hardening

package/bin/pluribus.js

@@ -70,6 +70,7 @@ OPTIONS (demo)
   --receipt       Validate a custom demo receipt JSON file
   --input         Import a custom demo input file, such as rpc-messages.jsonl
   --json          Print machine-readable demo results
+  --pass          For context-sufficiency-trace, use the bundled passing trace
 
 EXAMPLES
   pluribus init
@@ -96,6 +97,7 @@ EXAMPLES
   pluribus demo mcp-telemetry-import --json
   pluribus demo tool-surface-diff
   pluribus demo tool-surface-diff --json
+  pluribus demo context-sufficiency-trace --json
 
 DOCS
   https://github.com/caioribeiroclw-pixel/pluribus
@@ -107,7 +109,7 @@ const COMMAND_FLAGS = {
   validate: new Set(['source', 'update-imports']),
   audit: new Set(['source', 'tools', 'update-imports', 'strict', 'ci', 'json', 'output', 'github-annotations', 'fidelity-report']),
   watch: new Set(['source', 'tools', 'update-imports', 'dry-run', 'once', 'debounce']),
-  demo: new Set(['receipt', 'input', 'json']),
+  demo: new Set(['receipt', 'input', 'json', 'pass']),
 }
 
 function getFlagNames(argv) {

package/docs/agent-surface-proof-chain.md

@@ -0,0 +1,176 @@
+# Agent surface proof chain
+
+Agent setup is becoming a bundle, not a file: Skills, hooks, MCP servers, subagents, slash commands, permissions, profiles, plugins, and cross-model workers all get installed or synced together.
+
+A single “receipt” is too vague for that surface. Use the smallest proof object for the boundary you are crossing, and do not let one green check imply the next boundary worked.
+
+## Quick model
+
+```text
+registry publishes
+  → installer plans writes
+  → sync applies writes
+  → host exposes surface
+  → task makes tools/skills eligible
+  → runtime calls or activates them
+  → workers hand results back
+  → reviewer/CI promotes state
+```
+
+Each arrow can fail independently.
+
+## Boundary-specific proof objects
+
+| Boundary | Use this proof object | Proves | Does **not** prove |
+| --- | --- | --- | --- |
+| Setup script or plugin is about to write files | **Install diff** | Planned files, permissions, hooks, MCP servers, Skills, commands, backups, network/env access, and `writes_started=false` before mutation | The host later loaded or used any installed surface |
+| Registry sync says it succeeded | **Post-sync manifest** | Published asset version, target agents/scopes, written paths, content hashes, skipped targets, errors, and restart requirements | Runtime discovery or activation |
+| Continuous config sync ran with `--apply` | **Post-apply ledger** | What was actually written, skipped, backed up, failed, or sent to manual review after apply | That Claude/Codex/Cursor followed the config |
+| Host starts after install/sync | **Surface state** | What is visible/attached/discovered vs skipped/withheld: Skills, hooks, MCP tools, agents, slash commands, instruction files | That a specific task selected the right surface |
+| Runtime task decides what to use | **Selection trace** | Available → eligible → called → enforced for tools/Skills/MCP, with privacy-safe reasons | That the output is correct |
+| Model/provider may be silently degraded | **Degradation decision record** | Transport health, app-critical canaries, fallback choice, degradation confidence, and whether writes should continue | That the provider is globally healthy or that future turns will remain stable |
+| Long session, compaction, or topic switch resumes work | **Read receipt / safe-to-edit gate** | Which index/topic files or summaries reloaded, active constraints, stale notes rejected, and whether editing is safe | That future turns will keep following the context |
+| Debugger shows a chain of LLM calls | **Context-boundary span** | Which context inputs crossed into each node, hashes/paths by default, withheld inputs, replay reason, downstream invalidations | A raw prompt dump, secret-safe by itself, or full correctness |
+| Claude delegates to Codex/Gemini/subagents | **Handoff envelope** | Task, parent-plan hash, allowed files/commands, passed context sources, output schema, timeout, and insufficient-context path | That worker output is trusted project state |
+| Worker results are merged back | **Merge-back evidence** | What changed, evidence used, assumptions, invalidated downstream outputs, and reviewer/CI promotion decision | That the original worker had complete context |
+
+## Minimal fields by proof object
+
+### Install diff
+
+```json
+{
+  "proof_type": "install_diff",
+  "installer": "claude-code-setup",
+  "targets": ["claude-code", "codex"],
+  "planned_writes": [
+    {"path": ".claude/hooks/pretooluse.json", "kind": "hook", "backup": true},
+    {"path": ".mcp.json", "kind": "mcp_config", "backup": true}
+  ],
+  "env_or_network_access": ["ANTHROPIC_API_KEY:required-not-recorded"],
+  "writes_started": false,
+  "review_required": true
+}
+```
+
+### Post-sync manifest
+
+```json
+{
+  "proof_type": "post_sync_manifest",
+  "run_id": "skills-sync-2026-06-14T21:00Z",
+  "source": "team-skills-registry",
+  "targets": [
+    {
+      "agent": "claude-code",
+      "scope": "project",
+      "skills_dir": ".claude/skills",
+      "written": [{"name": "review-pr", "version": "1.4.2", "sha256": "..."}],
+      "skipped": []
+    }
+  ],
+  "restart_required": true
+}
+```
+
+### Post-apply ledger
+
+```json
+{
+  "proof_type": "post_apply_ledger",
+  "run_id": "config-sync-123",
+  "plan_hash": "sha256:...",
+  "writes_started": true,
+  "backup_root": ".agent-sync/backups/2026-06-14T21-00Z",
+  "operations": [
+    {
+      "path": "AGENTS.md",
+      "status": "written",
+      "before_hash": "sha256:old",
+      "after_hash": "sha256:new",
+      "backup_path": ".agent-sync/backups/.../AGENTS.md"
+    },
+    {
+      "path": ".codex/config.toml",
+      "status": "manual_review",
+      "reason": "permission profile changed"
+    }
+  ]
+}
+```
+
+### Selection trace
+
+```json
+{
+  "proof_type": "selection_trace",
+  "turn_id": "turn-42",
+  "loaded_instructions": ["CLAUDE.md", ".claude/skills/memory/SKILL.md"],
+  "mcp_tools_visible": ["memory.search", "memory.write"],
+  "task_intent": "recall prior decision before editing auth flow",
+  "expected_tools": ["memory.search"],
+  "eligible_tools": ["memory.search"],
+  "called_tools": ["memory.search"],
+  "enforced_by_hook": true
+}
+```
+
+### Degradation decision record
+
+```json
+{
+  "proof_type": "degradation_decision_record",
+  "run_id": "agent-run-2026-06-15T20:02Z",
+  "provider": "anthropic",
+  "model": "claude-sonnet-4",
+  "region": "us-east-1",
+  "prompt_template_hash": "sha256:...",
+  "canary_suite_version": "coding-agent-smoke-2026-06-15",
+  "transport": {
+    "ttft_p95_ms": 1400,
+    "total_latency_p95_ms": 9200,
+    "timeout_rate": 0.01,
+    "error_rate": 0
+  },
+  "capability_canaries": [
+    {"name": "json_schema", "status": "pass", "severity": "write_blocking"},
+    {"name": "tool_choice", "status": "pass", "severity": "write_blocking"},
+    {"name": "patch_format", "status": "pass", "severity": "write_blocking"}
+  ],
+  "confidence": "healthy",
+  "write_gate": "continue"
+}
+```
+
+### Handoff envelope
+
+```json
+{
+  "proof_type": "handoff_envelope",
+  "from": "opus-supervisor",
+  "to": "codex-worker-2",
+  "task": "compare parser failures in imports.test.js",
+  "parent_plan_hash": "sha256:...",
+  "allowed_files": ["src/utils/imports.js", "test/imports.test.js"],
+  "allowed_commands": ["npm test -- imports"],
+  "context_sources_passed": ["spec/context-format.md#remote-imports"],
+  "expected_output_schema": "worker_result_v1",
+  "stop_condition": "one patch candidate or explicit insufficient_context"
+}
+```
+
+## Practical rules
+
+1. **Do not promote intent as outcome.** A dry-run plan is not an apply ledger.
+2. **Do not promote visibility as use.** A visible MCP tool or Skill is not an activated/called one.
+3. **Do not promote latency as reliability.** A low-latency provider call can still fail app-critical canaries, and a slow call may still be safe for read-only work.
+4. **Do not promote worker output as project truth.** Merge-back needs evidence and invalidation notes.
+5. **Keep receipts privacy-safe by default.** Prefer paths, hashes, names, versions, statuses, and reasons; expand raw bodies only under explicit local review.
+6. **Name skipped and withheld context.** What did not load is often the failure.
+7. **Use the product’s own vocabulary.** Say install diff for installers, ledger for sync apply, span for debuggers, envelope for delegation, degradation decision for provider/model health, and read receipt for re-grounding.
+
+## When Pluribus fits
+
+Use Pluribus when you need privacy-safe evidence around agent context boundaries: generated instruction files, Skills, MCP tools, memory/RAG results, compaction, pruning, provider/model degradation decisions, plugin setup, or cross-tool handoffs.
+
+Do not use Pluribus as a registry, memory server, agent orchestrator, or replacement for Claude/Codex/Cursor runtime diagnostics. It is the evidence layer around those systems.

package/docs/cursor-claude-context-handoff.md

@@ -90,6 +90,74 @@ I am building Acme Billing, a TypeScript service used by finance operators.
 4. **Audit:** run `pluribus audit` locally or in CI to catch drift when someone edits generated files directly.
 5. **Use memory separately:** if you also run an MCP memory server, keep the recall/store protocol in `pluribus.md` and let the memory server store durable facts.
 
+## What usually breaks first
+
+When developers switch seriously between Cursor, Claude Code, Codex/Copilot-style tools, Windsurf, and terminal agents, the failure is rarely “there is no context anywhere.” It is usually one of these smaller breaks:
+
+| Break | Symptom | Fast check |
+| --- | --- | --- |
+| Source file stale | `AGENTS.md`, `CLAUDE.md`, or `.cursorrules` still describes old paths, commands, or architecture | Run `pluribus audit`; compare generated output to the committed `pluribus.md` source |
+| Tool-specific layer diverged | Cursor rules say one convention, Claude/Codex instructions say another | Keep tool-specific files generated/thin; review manual edits as drift |
+| Memory became authority | An MCP memory/Obsidian/Notion note overrides the current repo state | Put memory recall/store policy in `pluribus.md`; require code/tests/current docs to win over recalled facts |
+| Commands or paths changed | The agent follows a dead build/test command copied from an older chat | Keep commands in `package.json`, `Makefile`, `justfile`, or scripts; link to them from context instead of duplicating shell snippets |
+| Context was never loaded | The right file exists, but the active tool/session did not read it | Ask for a short handoff receipt before edits: which source file, generated target, memory recall, and test command were actually used |
+
+## Copyable handoff receipt
+
+Use this as a lightweight debugging note before a risky cross-tool handoff. It is intentionally privacy-safe: hashes, paths, and decisions instead of raw prompt transcripts or private source content.
+
+```json
+{
+  "handoff_id": "cursor-to-claude-2026-06-16-001",
+  "from_tool": "cursor",
+  "to_tool": "claude-code",
+  "repo_ref": {
+    "branch": "main",
+    "head_sha": "abc1234"
+  },
+  "source_of_truth": {
+    "path": "pluribus.md",
+    "sha256": "hash-of-current-project-context",
+    "validated_at": "2026-06-16T00:00:00Z"
+  },
+  "generated_context": [
+    {
+      "tool": "cursor",
+      "path": ".cursorrules",
+      "status": "in_sync"
+    },
+    {
+      "tool": "claude-code",
+      "path": "CLAUDE.md",
+      "status": "in_sync"
+    },
+    {
+      "tool": "openclaw-or-codex-style-agent",
+      "path": "AGENTS.md",
+      "status": "in_sync"
+    }
+  ],
+  "memory_policy": {
+    "mcp_memory_allowed": true,
+    "current_repo_overrides_memory": true,
+    "store_new_facts_without_review": false
+  },
+  "active_task": {
+    "summary": "Implement the smallest safe patch for issue #123",
+    "allowed_paths": ["src/billing/**", "tests/billing/**"],
+    "required_checks": ["npm test -- billing"]
+  },
+  "loaded_evidence": {
+    "agent_says_it_read": ["CLAUDE.md", "package.json"],
+    "missing_or_deferred": ["old Obsidian architecture note"],
+    "stale_conflicts_found": []
+  },
+  "safe_to_continue": true
+}
+```
+
+The receipt should be boring. If it shows stale conflicts, missing generated files, or memory overriding current repo state, stop and fix the source of truth before asking another agent to write code.
+
 ## What this deliberately does not solve
 
 - It does not move active chat state from Cursor to Claude Code.

package/docs/index.html

@@ -19,7 +19,7 @@
     <p>Privacy-safe evidence for AI context boundaries: what crossed into the agent, what stayed out, and what should stop before edits or tool calls.</p>
     <div class="card">
       <h2>Browser playground</h2>
-      <p>Try receipt validation without installing anything or sending data to a server. Current samples cover MCP tool-surface diffs, retrieved-context attention, and CLAUDE.md rule-attention drift.</p>
+      <p>Try receipt validation without installing anything or sending data to a server. Current samples cover MCP tool-surface diffs, retrieved-context attention, CLAUDE.md rule-attention drift, skill install provenance, and retrieval adoption evidence. If you are debugging MCP context bloat before startup, use the <a href="https://github.com/caioribeiroclw-pixel/pluribus/tree/main/examples/task-scoped-mcp-config">task-scoped MCP config receipt demo</a>. If a Skill or paste-cleaning CLI claims token savings, use the <a href="https://github.com/caioribeiroclw-pixel/pluribus/tree/main/examples/semantic-anchor-receipts">semantic anchor preservation receipt demo</a> to prove it kept version/API/security anchors. If a Cursor/Claude Code workflow requires a first tool or pre-tool hook before edits, use the <a href="session-preflight-receipts.md">session preflight receipt</a> and <a href="https://github.com/caioribeiroclw-pixel/pluribus/tree/main/examples/session-preflight-receipts">copyable rule/example</a>.</p>
       <p><a href="receipt-playground.html">Open the receipt playground →</a></p>
     </div>
     <div class="card">

package/docs/receipt-playground.html

@@ -42,6 +42,7 @@
             <option value="attentionFail">Sample: context attention fail</option>
             <option value="ruleAttention">Sample: CLAUDE.md rule attention drift</option>
             <option value="skillInstall">Sample: Agent Skill install provenance</option>
+            <option value="retrievalAdoption">Sample: retrieval adoption receipt</option>
           </select>
           <button id="load">Load sample</button>
           <button id="validate">Validate</button>
@@ -56,6 +57,7 @@
         <p><span class="pill">context attention</span> proves required retrieved context was delivered, acknowledged, and cited before edits.</p>
         <p><span class="pill">rule attention</span> shows whether project rules were re-read, cited in the pre-edit plan, and checked before changes.</p>
         <p><span class="pill">skill install provenance</span> shows which <code>SKILL.md</code> source path won, which mirrors were ignored, and whether install metadata stayed content-safe.</p>
+        <p><span class="pill">retrieval adoption</span> shows whether an available graph/RAG tool was actually used before claims, not just configured.</p>
         <h2>CLI equivalent</h2>
         <p><code>npx --yes pluribus-context@latest demo tool-surface-diff --json</code></p>
       </aside>
@@ -106,6 +108,36 @@
         privacy: { raw_prompts_omitted: true, raw_claude_md_omitted: true, source_code_omitted: true, tool_outputs_omitted: true, tokens_omitted: true, customer_data_omitted: true },
         result: { status: 'unsafe_to_edit', next_safe_action: 'stop, re-read missing rule ids, and restate the pre-edit plan with citations' }
       },
+      retrievalAdoption: {
+        schema: 'pluribus.retrieval_adoption_receipt.v1',
+        receipt_id: 'retrieval_adoption_graph_demo',
+        task_id: 'medusa-code-audit-graph-usage',
+        agent_surface: 'claude_code',
+        retrieval_surface: { kind: 'knowledge_graph_mcp', name: 'project-graph', available: true, forced: false },
+        claim: { expected_use: 'graph_retrieval_before_code_audit', evaluation_window: 'before_final_audit_claims' },
+        availability_evidence: {
+          tool_catalog_contains: ['graph.search', 'graph.neighbors', 'graph.explain_path'],
+          graph_index: { nodes: 3863, edges: 11204, snapshot_hash: 'sha256:graph-snapshot-redacted' },
+          raw_graph_omitted: true
+        },
+        adoption_evidence: {
+          retrieval_calls: [],
+          native_escape_hatch_calls: [
+            { kind: 'grep', count: 14 },
+            { kind: 'read_file', count: 39 }
+          ],
+          cited_retrieved_context_ids: [],
+          graph_grounded_findings: 0,
+          raw_tool_outputs_omitted: true
+        },
+        boundary_checks: {
+          retrieval_available_but_unused: true,
+          required_retrieval_gate_present: false,
+          no_retrieval_claim_allowed: true
+        },
+        privacy: { raw_prompts_omitted: true, raw_graph_nodes_omitted: true, source_code_omitted: true, tool_outputs_omitted: true, customer_data_omitted: true },
+        result: { status: 'availability_not_adoption', next_safe_action: 'treat graph/RAG as unadopted unless a gate requires or verifies retrieval before final claims' }
+      },
       skillInstall: {
         schema: 'pluribus.agent_skill_install_provenance_receipt.v1',
         receipt_id: 'skill_install_openskills_demo',
@@ -160,6 +192,7 @@
       if (receipt.schema === 'pluribus.context_attention_receipt.v1') return render(validateAttention(receipt))
       if (receipt.schema === 'pluribus.claude_code_rule_attention_receipt.v1') return render(validateRuleAttention(receipt))
       if (receipt.schema === 'pluribus.agent_skill_install_provenance_receipt.v1') return render(validateSkillInstall(receipt))
+      if (receipt.schema === 'pluribus.retrieval_adoption_receipt.v1') return render(validateRetrievalAdoption(receipt))
       render({ ok:false, errors:[`unsupported schema: ${receipt.schema || '(missing)'}`], warnings:[] })
     }
 
@@ -210,6 +243,27 @@
       return { ok: errors.length === 0 && missing.length === 0, schema:r.schema, rules_count:rules.length, uncited_or_failing_rules:missing.map(rule => rule.rule_id), errors, warnings }
     }
 
+
+    function validateRetrievalAdoption(r) {
+      const errors = [], warnings = []
+      const catalogTools = Array.isArray(r.availability_evidence?.tool_catalog_contains) ? r.availability_evidence.tool_catalog_contains : []
+      const retrievalCalls = Array.isArray(r.adoption_evidence?.retrieval_calls) ? r.adoption_evidence.retrieval_calls : []
+      const escapeCalls = Array.isArray(r.adoption_evidence?.native_escape_hatch_calls) ? r.adoption_evidence.native_escape_hatch_calls : []
+      const cited = Array.isArray(r.adoption_evidence?.cited_retrieved_context_ids) ? r.adoption_evidence.cited_retrieved_context_ids : []
+      if (!r.retrieval_surface?.kind) errors.push('retrieval_surface.kind is required')
+      if (r.retrieval_surface?.available !== true) errors.push('retrieval_surface.available must be true before adoption can be measured')
+      if (!catalogTools.length) errors.push('availability_evidence.tool_catalog_contains must list at least one retrieval tool')
+      if (r.availability_evidence?.raw_graph_omitted !== true) errors.push('availability_evidence.raw_graph_omitted must be true')
+      if (r.adoption_evidence?.raw_tool_outputs_omitted !== true) errors.push('adoption_evidence.raw_tool_outputs_omitted must be true')
+      for (const field of ['raw_prompts_omitted','raw_graph_nodes_omitted','source_code_omitted','tool_outputs_omitted','customer_data_omitted']) if (r.privacy?.[field] !== true) errors.push(`privacy.${field} must be true`)
+      const graphGroundedFindings = Number(r.adoption_evidence?.graph_grounded_findings || 0)
+      const usedRetrieval = retrievalCalls.length > 0 || cited.length > 0 || graphGroundedFindings > 0
+      if (r.boundary_checks?.retrieval_available_but_unused === true && usedRetrieval) errors.push('retrieval_available_but_unused cannot be true when retrieval calls/citations/findings exist')
+      if (!usedRetrieval && r.boundary_checks?.no_retrieval_claim_allowed !== true) errors.push('no_retrieval_claim_allowed must be true when retrieval was available but no adoption evidence exists')
+      if (!usedRetrieval && !escapeCalls.length) warnings.push('no retrieval adoption and no native escape-hatch calls recorded; receipt may be missing usage telemetry')
+      return { ok: errors.length === 0, schema:r.schema, retrieval_available:r.retrieval_surface?.available === true, retrieval_call_count:retrievalCalls.length, cited_context_count:cited.length, graph_grounded_findings:graphGroundedFindings, native_escape_hatch_calls:escapeCalls, status: usedRetrieval ? 'retrieval_adopted' : 'availability_not_adoption', errors, warnings }
+    }
+
     function validateSkillInstall(r) {
       const errors = [], warnings = []
       const selected = Array.isArray(r.selected_skills) ? r.selected_skills : []

package/docs/session-preflight-receipts.md

@@ -0,0 +1,77 @@
+# Session preflight receipts
+
+Cursor Forum users are asking for a "required first tool" or pre-tool hook so an agent cannot skip required project context before Grep, Shell, Write, or MCP calls. A behavioral rule is not enough: the first useful question is whether the session actually initialized its context before work began.
+
+A **session preflight receipt** is a small, privacy-safe record produced before any side-effecting agent work. It does not log raw memory, prompts, secrets, or file contents. It records which required context sources were checked, which tool surfaces were available, and whether the agent is allowed to proceed.
+
+Use this when rules like "read `MEMORY.md` first" or "call `session_init` before work" are important enough to audit.
+
+## Minimal receipt
+
+```json
+{
+  "schema": "pluribus.session_preflight_receipt.v1",
+  "session_id": "local-2026-06-17T11:00Z",
+  "client": "cursor",
+  "required_first_step": {
+    "kind": "mcp_tool",
+    "name": "session_guard.session_init",
+    "enforcement": "behavioral_rule_only"
+  },
+  "required_context": [
+    {
+      "id": "project-memory",
+      "path": "MEMORY.md",
+      "status": "loaded",
+      "fingerprint": "sha256:example-non-secret-digest"
+    }
+  ],
+  "tool_surface": {
+    "mcp_servers_seen": ["session-guard", "playwright"],
+    "side_effecting_tools_blocked_until_preflight": ["Shell", "Write"]
+  },
+  "decision": {
+    "allowed_to_start_work": true,
+    "mode": "read_then_patch",
+    "reason": "required context was checked before tool use"
+  }
+}
+```
+
+## What this proves
+
+- The agent had an explicit preflight gate before work.
+- Required context sources were checked or clearly missing.
+- Side-effecting tools were blocked, downgraded, or allowed for a reason.
+- A reviewer can tell whether the run began from known project context or from blind rediscovery.
+
+## What this does not prove
+
+- It is not an authorization decision.
+- It does not prove the model fully understood the context.
+- It does not replace Cursor, Claude Code, or MCP-native enforcement.
+- It does not require logging private memory content.
+
+## Failure modes to record
+
+```json
+{
+  "schema": "pluribus.session_preflight_receipt.v1",
+  "decision": {
+    "allowed_to_start_work": false,
+    "mode": "read_only",
+    "reason": "required context missing or session_init skipped"
+  },
+  "failures": [
+    {
+      "kind": "required_context_missing",
+      "id": "project-memory",
+      "path": "MEMORY.md"
+    }
+  ]
+}
+```
+
+The key distinction: **a required first tool is the enforcement hook; the receipt is the evidence that the hook actually ran before work.**
+
+See `examples/session-preflight-receipts/` for a copyable Cursor-style rule and JSON fixture.

package/examples/claude-md-read-receipts/README.md

@@ -0,0 +1,70 @@
+# CLAUDE.md read receipt
+
+A tiny, manual-first receipt for Claude Code sessions where `CLAUDE.md` is read at startup but trust erodes after a long session, compaction, `/clear`, or a topic switch.
+
+Use it before asking the agent to edit again. The agent does **not** need to dump raw prompts or file contents. It should name the routing/index files it reloaded, the constraints it is carrying forward, and the relevant files it intentionally did not load.
+
+## Prompt pattern
+
+```text
+Before continuing, give me a context read receipt:
+- current task/topic
+- session state: fresh, compacted, topic_switched, or resumed
+- indexed files you reloaded and why
+- 3-5 active constraints carried forward
+- relevant files you did not load
+- stale/historical notes you are not treating as current authority
+- whether it is safe to edit now
+```
+
+If the agent cannot name what it reloaded, it probably has not grounded.
+
+## Run the sample checker
+
+```bash
+cd examples/claude-md-read-receipts
+node check-read-receipt.mjs --receipt sample-read-receipt.json
+```
+
+The bundled passing receipt models a topic switch from payments work to upload API work. It keeps `CLAUDE.md` as the router, reloads the topic doc and migration notes, lists active constraints, and marks the session safe to edit.
+
+A stale receipt should fail:
+
+```bash
+node check-read-receipt.mjs --receipt stale-read-receipt.json
+```
+
+## Receipt shape
+
+```json
+{
+  "schema": "pluribus.claude_md_read_receipt.v1",
+  "session_state": "topic_switched",
+  "current_task": "Update upload API retry handling",
+  "reloaded_files": [
+    { "path": "CLAUDE.md", "role": "router", "why": "Selects topic-specific docs" }
+  ],
+  "active_constraints": [
+    "Do not log raw file contents",
+    "Preserve max 3 retries with exponential backoff",
+    "Treat v2.4.0 migration notes as current authority"
+  ],
+  "not_loaded_files": [
+    { "path": "docs/payments.md", "why": "Previous topic only" }
+  ],
+  "safe_to_edit": true
+}
+```
+
+## Why this exists
+
+The market signal from Claude Code users is practical: people already maintain lean `CLAUDE.md` index files and topic memory docs, but they still have to ask whether the agent actually re-read the right material after a topic switch or compaction.
+
+This receipt keeps the ritual lightweight and falsifiable:
+
+- `CLAUDE.md` can stay small and act as a router.
+- Topic docs can be reloaded only when relevant.
+- Current authority is separated from stale/historical notes.
+- `safe_to_edit=false` is allowed when the session cannot prove it is grounded.
+
+Pair this with Pluribus' sync/audit workflow when file drift is the problem. Use this receipt when runtime grounding is the problem.