pluribus-context 0.3.35 → 0.3.36

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.36 - 2026-06-05
+
+- Added `pluribus demo skill-use-rate`, a tiny npm-runnable demo that validates the packaged Skill use-rate receipt and warns when installed/attached Skills have no observed invocations.
+
+
+- Added a GitHub Actions AI PR review receipt gate example that validates `agent.review_primitive_receipt.v1` evidence for AI-authored pull requests.
+- Added a memory write policy receipt guide and executable gate for approving or quarantining shared-memory updates before they become durable context across agents.
+
 ## 0.3.35 - 2026-05-31
 
 - Added canonical-output receipts for preserving the last clean version of an artifact as versioned evidence instead of treating old chats as source of truth.

package/README.md

@@ -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 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](examples/agent-skills/skill-policy-receipts/) to turn target decisions, refusals, and post-write guards into privacy-safe evidence. 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) and the [copyable PR template](examples/ai-pr-review-receipts/) 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 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. 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) 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](examples/agent-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
 

package/bin/pluribus.js

@@ -10,6 +10,7 @@ import { runSync } from '../src/commands/sync.js'
 import { runValidate } from '../src/commands/validate.js'
 import { runWatch } from '../src/commands/watch.js'
 import { runAudit } from '../src/commands/audit.js'
+import { runDemo } from '../src/commands/demo.js'
 import { parseArgs } from '../src/utils/args.js'
 import { SUPPORTED_TOOLS } from '../src/skills/built-in.js'
 import { VERSION } from '../src/utils/version.js'
@@ -28,6 +29,7 @@ COMMANDS
   validate  Validate pluribus.md before syncing
   audit     Compare generated tool files with pluribus.md without writing
   watch     Watch pluribus.md and auto-sync after changes
+  demo      Run tiny packaged demos from npm without cloning the repo
   help      Show this help message
 
 OPTIONS (init)
@@ -64,6 +66,10 @@ OPTIONS (watch)
   --once          Exit after the first change-triggered sync
   --debounce      Debounce delay in ms (minimum 300, default 400)
 
+OPTIONS (demo)
+  --receipt       Validate a custom skill use-rate receipt JSON file
+  --json          Print machine-readable demo results
+
 EXAMPLES
   pluribus init
   pluribus init --dry-run
@@ -81,6 +87,8 @@ EXAMPLES
   pluribus audit --strict --github-annotations
   pluribus audit --json --fidelity-report
   pluribus watch --tools claude,cursor
+  pluribus demo skill-use-rate
+  pluribus demo skill-use-rate --json
 
 DOCS
   https://github.com/caioribeiroclw-pixel/pluribus
@@ -92,6 +100,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', 'json']),
 }
 
 function getFlagNames(argv) {
@@ -152,6 +161,9 @@ async function main() {
       case 'audit':
         await runAudit(parsedArgs)
         break
+      case 'demo':
+        await runDemo(parsedArgs, commandArgs.filter((arg) => !arg.startsWith('--') && !Object.values(parsedArgs).includes(arg)))
+        break
       default:
         console.error(`❌ Unknown command: "${command}"`)
         console.log(`Run \`pluribus help\` for usage.`)

package/docs/agent-firewall-denial-audit.md

@@ -0,0 +1,95 @@
+# Agent firewall denial/audit receipts
+
+Claude Code hooks, OpenClaw policies, local MCP gateways, and agent firewalls can block destructive commands, outbound calls, or risky writes before an agent executes them.
+
+The hard part is not only blocking. If the model sees a vague failure, it may keep trying variants. If the model sees too much detail, the denial can leak secrets, raw policy logic, or bypass hints.
+
+Use a split receipt:
+
+1. **Model-visible denial envelope** — minimal structured feedback the agent can act on safely.
+2. **Operator audit record** — privacy-safe evidence for the human/operator, CI, or local dashboard.
+
+## Model-visible denial envelope
+
+The model should receive enough information to stop, ask, or choose a safe alternative, without exposing raw secrets, raw commands, or sensitive policy internals.
+
+```json
+{
+  "type": "agent_firewall_denial.v1",
+  "decision": "blocked",
+  "reasonClass": "destructive_git",
+  "requiresApproval": true,
+  "safeAlternative": "Explain the planned git operation and wait for explicit approval.",
+  "retrySafety": "unsafe_until_approved",
+  "correlationId": "deny_2026_06_02_2200_7f3a"
+}
+```
+
+Good `reasonClass` values are coarse and non-secret:
+
+- `destructive_git`
+- `filesystem_write_out_of_scope`
+- `outbound_after_secret_read`
+- `credential_exposure_risk`
+- `package_publish_requires_approval`
+- `unknown_policy_boundary`
+
+The denial should avoid:
+
+- raw shell commands;
+- raw file contents;
+- secret values or secret-looking substrings;
+- full policy source;
+- exact bypass instructions;
+- absolute private paths when a path class or hash is enough.
+
+## Operator audit record
+
+The operator needs more detail, but still not raw prompts, code, or secrets. Prefer hashes, policy ids, classes, and booleans.
+
+```json
+{
+  "type": "agent_firewall_operator_audit.v1",
+  "decision": "blocked",
+  "correlationId": "deny_2026_06_02_2200_7f3a",
+  "tool": "Bash",
+  "commandHash": "sha256:0e5751c026e543b2a6f2b4d7a7c8d8e5b81b69c5b9f7db2a5b94f31f987e7f44",
+  "cwdHash": "sha256:dcdb704109a454784b81229d2b05f368692e758bfa33cb61d04c1b93791b0273",
+  "matchedPolicyIds": ["git.destructive.requires_approval"],
+  "sessionTaint": {
+    "secretRead": false,
+    "privateFileRead": true,
+    "networkAccessed": false
+  },
+  "approval": {
+    "state": "missing",
+    "requiredFrom": "operator"
+  },
+  "retrySafety": "unsafe_until_approved",
+  "modelEnvelopeHash": "sha256:a1bcaa1cb2572ab0e735c30062a268391d0a9d1b3dd7ff4b14065d8b29513b2a"
+}
+```
+
+## Invariant
+
+A blocked tool call should never disappear into the middle ground of “the command just failed.”
+
+- The **model** gets a safe reason class and next action.
+- The **operator** gets policy evidence and retry safety.
+- The shared identifier is a correlation id plus hashes, not raw private payloads.
+
+That makes enforcement auditable without turning policy internals into model-visible bypass material.
+
+## Try the copyable example
+
+See [`examples/agent-firewall-denial-audit/`](../examples/agent-firewall-denial-audit/) for a tiny denial envelope, operator audit record, and local checker:
+
+```bash
+node examples/agent-firewall-denial-audit/check-denial-audit.mjs examples/agent-firewall-denial-audit
+```
+
+The checker is intentionally small. It fails if the model-visible envelope leaks command/path/policy/secret-looking fields, if the audit record lacks policy ids or hash evidence, or if the envelope/audit correlation id does not match.
+
+## How this fits Pluribus
+
+Pluribus is not an agent firewall. This recipe is for teams already using hooks, policy engines, or local gateways and needing privacy-safe evidence at the enforcement boundary: what was denied, what the model was safely told, and what the operator can audit later.

package/docs/ai-pr-review-receipts.md

@@ -124,6 +124,26 @@ This receipt does not include raw prompts, transcripts, source code, secrets, cu
 `next_safe_action:`
 ```
 
+## CI gate example
+
+The copyable example in [`examples/ai-pr-review-receipts/`](../examples/ai-pr-review-receipts/) includes:
+
+- a PR template for human-readable blast-radius review;
+- a GitHub Actions workflow that validates a machine-readable `agent.review_primitive_receipt.v1` receipt;
+- a passing fixture and an intentionally failing fixture.
+
+Run the smoke locally from the repository root:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/ai-pr-review-receipts/review-primitive-receipt.json
+
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/ai-pr-review-receipts/incomplete-review-primitive-receipt.json
+```
+
+The first command should pass. The second should fail because partial/unsafe or under-evidenced agent work should not silently pass a merge gate.
+
 ## How to use with Pluribus
 
 Pluribus does not need to own your PR workflow. Use it as the neutral language for evidence that crossed an agent boundary:

package/docs/compaction-resume-receipts.md

@@ -0,0 +1,43 @@
+# Compaction resume receipts
+
+Claude Code and Codex users are asking for `PreCompact` / `PostCompact` hooks because long sessions lose thread detail, reload rules inconsistently, or continue after a summary that no one can audit.
+
+The risky moment is not compaction itself. The risky moment is **resuming as if nothing changed**.
+
+A compaction resume receipt is a small, privacy-safe handoff object emitted after a compaction/restore flow. It proves what was summarized, what instruction sources were reloaded, what state was lost or kept, and whether the next agent turn is safe to continue.
+
+## Receipt boundary
+
+A resume receipt should prove:
+
+- **event identity** — stable `compaction_event_id`, `session_id`, and trigger so a restore can be correlated with the hook that caused it;
+- **transcript boundary** — the compacted transcript range and hash, without logging raw transcript content;
+- **summary evidence** — summary hash and token count so downstream tools can detect stale or changed summaries;
+- **instruction reloads** — `AGENTS.md`, `CLAUDE.md`, skills, MCP/tool manifests, workflow plans, or project rules reloaded with hashes/mtimes;
+- **kept/lost fields** — explicit lists for active plan, open diffs, pending tests, rejected decisions, tool grants, or unresolved blockers;
+- **resume verdict** — `safe_to_resume: true | false | unknown` plus reasons;
+- **privacy flags** — no raw transcript, raw prompts, raw tool outputs, secrets, or full instruction bodies in the receipt.
+
+## 60-second gate
+
+The copyable example is in [`examples/compaction-resume-receipts/`](../examples/compaction-resume-receipts/):
+
+```bash
+node examples/compaction-resume-receipts/check-resume-receipt.mjs \
+  examples/compaction-resume-receipts/safe-resume-receipt.json
+
+node examples/compaction-resume-receipts/check-resume-receipt.mjs \
+  examples/compaction-resume-receipts/unsafe-resume-receipt.json
+```
+
+The first passes because the restore has a stable event id, compacted transcript hash, summary hash, reloaded instruction sources, explicit kept/lost state, privacy flags, and `safe_to_resume: true` with no blocking lost fields.
+
+The second fails because it tries to continue after missing `AGENTS.md`, hidden lost decisions, raw transcript logging, and an `unknown` verdict.
+
+## Positioning
+
+Memory systems remember. Hooks fire lifecycle events. This receipt answers the operational review question:
+
+> After compaction, do we have enough verified context to continue safely?
+
+That makes `PostCompact` / `SessionStart(compact)` restore flows auditable without turning Pluribus into a memory store or requiring private transcript capture.

package/docs/controlled-learning-queue.md

@@ -0,0 +1,48 @@
+# Controlled learning queue for AI employee-style agents
+
+Claude Code, OpenClaw, Cursor, and MCP tools make it easy to turn a repository into a role-based worker: `CLAUDE.md` as the job description, Skills as procedures, and a `memory/` folder as durable knowledge.
+
+That pattern compounds quickly, but it has a failure mode: the agent can overlearn from one weird lead, support ticket, or edge case and rewrite shared memory for every future run.
+
+Use a controlled learning queue when an agent is allowed to **propose** durable memory changes but not silently promote them.
+
+## Split the folders
+
+```text
+role/                  # job contract: responsibilities, boundaries, escalation
+skills/                # callable procedures with inputs, outputs, stop conditions
+memory/durable.md      # approved facts only; small enough to review
+memory/working-notes.md# scratch observations; allowed to be messy/temporary
+learning_queue.md      # proposed durable changes awaiting promote/reject
+leads/                 # tiny job cards for active work
+```
+
+The key rule: `memory/durable.md` changes only through `learning_queue.md` proposals with source, reason, scope, expiry, and reviewer decision.
+
+## Proposal shape
+
+Each proposed learning should answer:
+
+- **Source:** what run, lead, issue, or transcript produced the observation?
+- **Observed:** what happened, without storing raw private text?
+- **Proposed durable change:** the exact fact/rule to add, edit, or remove.
+- **Reason:** why this should affect future runs, not just the current case.
+- **Scope:** global, client-specific, project-specific, channel-specific, or temporary.
+- **Expiry / review date:** when this fact should be rechecked.
+- **Status:** proposed, promoted, rejected, or expired.
+
+That is enough to preserve learning while keeping an agent from slowly corrupting ICP, pricing assumptions, escalation rules, or compliance boundaries.
+
+## Try the copyable example
+
+See [`examples/controlled-learning-queue/`](../examples/controlled-learning-queue/) for a tiny AI sales/ops worker layout and a local checker:
+
+```bash
+node examples/controlled-learning-queue/check-learning-queue.mjs examples/controlled-learning-queue/learning_queue.md
+```
+
+The checker is intentionally small. It fails proposals that are missing source/reason/scope/expiry/status, that try to auto-promote without review, or that paste raw secrets/private payloads into the learning queue.
+
+## How this fits Pluribus
+
+Pluribus is not trying to be the agent's brain. This pattern keeps intentional context reviewable: durable memory is a small versioned source of truth, while working notes and proposed learnings remain visibly provisional until promoted.

package/docs/install-plan-receipts.md

@@ -75,3 +75,5 @@ If an installer cannot answer that before mutation, treat it like running CI fro
 ## 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/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.