pluribus-context 0.3.34 → 0.3.36

package/CHANGELOG.md

@@ -4,6 +4,29 @@
 
 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.
+- Added a review primitive gate example that fails unsafe agent handoffs on unapproved scope changes, skipped/failed required checks, missing evidence, privacy leaks, or `partial` / `unsafe-to-resume` state.
+- Added a Claude Code hook bridge that runs the review primitive gate from lifecycle hook JSON, making handoff proof enforceable at `TaskCompleted` / `PostCompact` style boundaries.
+- Tracked fresh market signals around dynamic workflow cost accounting, post-compact recovery, active idea indexes, Skill policy alternatives, and control-plane buying thresholds.
+
+- Add Skill policy receipts guide and copyable Agent Skill recipe for hard-rule enforcement, target allow/refuse decisions, and post-write guards.
+- Add temporal context receipts guide and copyable current-state/spec example for long-lived projects where old docs still match search but are no longer implementation authority.
+- Add AI PR review receipts guide and copyable PR template for reviewing agent-generated changes by blast radius instead of diff size alone.
+- Add subagent role receipts guide and copyable `agents.toml` example for proving requested role, effective role, loaded instruction source, allowed/refused capabilities, stop point, and next safe action.
+- Add install-plan receipts guide and copyable example for setup scripts that configure MCP servers, Skills, instruction files, hooks, or plugins across multiple AI coding tools before writes begin.
+- Added an MCP tool visibility receipts checklist for debugging servers that launch and return `tools/list` directly but do not surface tools in the actual agent client catalog.
+- Tracked GBrain `unify-types` mutation-mode feedback as an external receipt signal for protected migrations that may default from dry-run into writes.
+
 ## 0.3.34 - 2026-05-26
 
 - Repositioned README and the community review packet around privacy-safe agent context receipts first, with instruction-file audit/sync as the supporting workflow, so directory reviewers do not mistake Pluribus for another generic ContextOps, memory, RAG, or rules-sync tool.

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 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
 
@@ -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
+- [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
 - [Remote Composable Context Imports](docs/remote-composable-context-imports.md) — design notes for lockfile/cache/auth hardening
 - [Context Format Spec](spec/context-format.md) — the `pluribus.md` format reference
 - [Skills Format Spec](spec/skills-format.md) — how adapters work and how to write custom skills

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

@@ -0,0 +1,173 @@
+# AI PR review receipts
+
+AI-generated PRs are not risky because they are large or small. They are risky when the reviewer cannot tell which operational boundaries the agent touched.
+
+Use this recipe when Claude Code, Cursor, Codex, Copilot agents, OpenClaw, or another coding agent opens a PR and the team needs a compact review artifact before merge.
+
+The goal is not to log prompts, transcripts, source code, stack traces, secrets, customer data, or raw tool output. The goal is a privacy-safe receipt that proves the review unit: blast radius.
+
+## When this helps
+
+Use an AI PR review receipt when a change may affect:
+
+- database schema, migrations, backfills, or persisted data contracts;
+- readers/writers that run while a migration or rollout is in progress;
+- async jobs, queues, cron tasks, webhooks, retries, or background workers;
+- feature flags, rollout gates, kill switches, or compatibility shims;
+- external side effects such as payments, email, auth, billing, search indexes, analytics, or third-party APIs;
+- generated files, public APIs, plugin manifests, MCP/Skill/hook configuration, or security-sensitive project config.
+
+If none of these apply, the receipt can say so. That negative claim is still useful because it tells the human reviewer what the agent believes it did **not** touch.
+
+## Receipt shape
+
+Attach this as a PR body section, `REVIEW.md` note, check-run summary, or bot comment.
+
+```json
+{
+  "type": "review.blast_radius.v1",
+  "pr": {
+    "source": "agent-pr",
+    "review_requested": true,
+    "human_review_required": true
+  },
+  "boundaries": [
+    {
+      "name": "schema_or_data_contract",
+      "status": "touched",
+      "evidence": "migration file added; live reader compatibility checked",
+      "risk_tier": "high",
+      "review_owner": "backend"
+    },
+    {
+      "name": "async_or_background_path",
+      "status": "not_touched",
+      "evidence": "no queue/cron/webhook paths changed in diff summary",
+      "risk_tier": "low"
+    },
+    {
+      "name": "rollout_gate",
+      "status": "present",
+      "evidence": "feature flag path exists before new behavior is enabled",
+      "risk_tier": "medium"
+    },
+    {
+      "name": "external_side_effect",
+      "status": "ambiguous",
+      "evidence": "email sender import changed; no dry-run evidence found",
+      "risk_tier": "high",
+      "blocked_until": "reviewer confirms side-effect behavior"
+    }
+  ],
+  "tests_and_checks": [
+    {
+      "name": "unit_or_integration_tests",
+      "status": "passed",
+      "scope": "changed package only"
+    },
+    {
+      "name": "migration_or_rollback_check",
+      "status": "missing",
+      "blocks_merge": true
+    }
+  ],
+  "decision": {
+    "merge_ready": false,
+    "reason": "external side effect and rollback evidence are ambiguous",
+    "next_safe_action": "ask backend owner to review email behavior and migration rollback before merge"
+  },
+  "privacy": {
+    "raw_prompt_logged": false,
+    "raw_source_logged": false,
+    "raw_tool_output_logged": false,
+    "secrets_logged": false,
+    "customer_data_logged": false
+  }
+}
+```
+
+## Minimal PR template
+
+Copy this into `.github/pull_request_template.md` or a review-bot comment.
+
+```markdown
+## AI PR review receipt
+
+This PR was prepared or modified by an AI coding agent. Review by blast radius, not by diff size alone.
+
+### Boundary receipt
+
+| Boundary | Status | Evidence | Risk tier | Owner / blocker |
+| --- | --- | --- | --- | --- |
+| Schema / persisted data contract | `touched / not_touched / ambiguous` |  |  |  |
+| Live reader/writer compatibility | `checked / missing / n/a` |  |  |  |
+| Async jobs / queues / cron / webhooks | `touched / not_touched / ambiguous` |  |  |  |
+| Rollout gate / feature flag / kill switch | `present / missing / n/a` |  |  |  |
+| External side effects | `declared / not_touched / ambiguous` |  |  |  |
+| Generated files / public API / plugin config | `touched / not_touched / ambiguous` |  |  |  |
+
+### Checks
+
+- [ ] Tests relevant to touched boundaries passed.
+- [ ] Migration/backfill/rollback behavior is explicit, or not applicable.
+- [ ] External side effects are declared, or not touched.
+- [ ] Any `ambiguous` boundary has an owner before merge.
+
+### Privacy
+
+This receipt does not include raw prompts, transcripts, source code, secrets, customer data, stack traces, or raw tool output.
+
+### Decision
+
+`merge_ready: yes/no`
+
+`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:
+
+- `review_boundary_schema_data`
+- `live_reader_writer_compatibility`
+- `review_boundary_async_path`
+- `rollout_gate_present`
+- `external_side_effects_declared`
+- `not_touched_boundary_claim`
+- `ambiguous_boundary_blocks_merge`
+- `risk_tier_evidence`
+- `next_safe_action`
+
+The same terms can appear in a GitHub PR template, a Claude Code `/code-review` note, an OpenClaw task receipt, a CI check summary, or a release checklist.
+
+## Bad receipts
+
+Avoid receipts that say only:
+
+- “tests passed”;
+- “Claude reviewed it”;
+- “small PR”;
+- “no issues found”;
+- “looks safe.”
+
+Those are conclusions. A useful receipt names the boundary, the evidence, the risk tier, and the next safe action when something is ambiguous.

package/docs/canonical-output-receipts.md

@@ -0,0 +1,107 @@
+# Canonical output receipts
+
+Claude Projects, long Claude Code sessions, and other agent workspaces are useful archives, but search is a weak source of truth. Exact phrases can be hard to recover, project-scoped search may miss the last clean version, and a later chat can overwrite the user's memory of which artifact is authoritative.
+
+Use a canonical output receipt when a session produces something that should be found and reused later: a master prompt, escalation memo, architecture decision, migration plan, test matrix, runbook, product brief, or reviewed context file.
+
+The receipt is not persistent memory and not a transcript dump. It is a small index card for the last clean artifact: stable id/path, version, exact grep phrases, decisions, rejected alternatives, open questions, and next action — without logging raw private content, secrets, customer data, or full chat history.
+
+## When this helps
+
+Use this receipt when:
+
+- a Claude Project or long chat produces a canonical artifact that must survive fuzzy chat search;
+- several sessions produce competing versions and a reviewer needs the current one;
+- the source chat may be compacted, archived, deleted, exported, or hard to search;
+- a team needs to know which artifact should be copied into repo docs, `pluribus.md`, `CLAUDE.md`, `AGENTS.md`, a prompt library, or a ticket;
+- exact phrases, dates, decisions, and rejected options matter more than the full conversation.
+
+## Receipt shape
+
+Attach this to the artifact, repo issue, PR body, project notes, or a `canonical_outputs.md` index.
+
+```json
+{
+  "type": "canonical.output.receipt.v1",
+  "artifact": {
+    "stable_id": "project-alpha-master-prompt-2026-05-30",
+    "name": "Project Alpha master prompt",
+    "kind": "master_prompt",
+    "canonical_path": "docs/prompts/project-alpha-master-prompt.md",
+    "current_version": "2026-05-30.1",
+    "content_hash": "sha256:example-only",
+    "status": "current",
+    "owner_label": "product-ops",
+    "created_at": "2026-05-30T21:40:00Z",
+    "last_reviewed_at": "2026-05-30T21:58:00Z"
+  },
+  "source": {
+    "workspace": "claude-project-alpha",
+    "source_session_id": "session-redacted-2026-05-30",
+    "source_tool": "claude-projects",
+    "source_chat_title": "Master prompt rebuild",
+    "source_url_or_path_redacted": true,
+    "raw_transcript_logged": false
+  },
+  "index": {
+    "exact_phrases_worth_grepping": [
+      "do not collapse escalation paths into summaries",
+      "billing exports are evidence, not source of truth",
+      "final prompt contract v3"
+    ],
+    "tags": ["master-prompt", "billing", "escalation", "current-state"],
+    "related_artifacts": ["billing-escalation-runbook-2026-05-28"]
+  },
+  "decisions": {
+    "accepted": [
+      "Use repo-owned markdown as the canonical copy, not old chats",
+      "Keep escalation criteria in the prompt body and test cases in a separate appendix"
+    ],
+    "rejected": [
+      {
+        "option": "Rely on Claude Project conversation search for recovery",
+        "reason": "exact phrase and project-scoped search were unreliable during rebuild"
+      }
+    ],
+    "open_questions": [
+      "Does support need a shorter handoff summary for weekend rotations?"
+    ],
+    "next_action": "Open a PR that adds the canonical prompt and this receipt to docs/prompts/"
+  },
+  "privacy": {
+    "raw_prompt_logged": false,
+    "raw_chat_logged": false,
+    "customer_data_logged": false,
+    "secrets_logged": false,
+    "proprietary_paths_logged": false
+  }
+}
+```
+
+## Minimal checklist
+
+Before treating an artifact as recoverable, capture:
+
+- stable id, human name, artifact kind, canonical path, version/date, owner label, status, and content hash;
+- source workspace/tool/session label, with private URLs or IDs redacted when needed;
+- exact phrases worth grepping, tags, and related artifacts;
+- decisions accepted, options rejected with reasons, open questions, and next action;
+- privacy flags proving raw chats, raw prompts, customer data, secrets, and private paths were not logged.
+
+## `canonical_outputs.md` sketch
+
+For small teams, a plain markdown index is enough:
+
+```markdown
+# Canonical outputs
+
+| Stable ID | Current path | Version | Status | Exact phrase to grep | Next action |
+| --- | --- | --- | --- | --- | --- |
+| project-alpha-master-prompt-2026-05-30 | docs/prompts/project-alpha-master-prompt.md | 2026-05-30.1 | current | final prompt contract v3 | PR canonical copy |
+```
+
+Old chats should be evidence. The source of truth should be the artifact plus the receipt.
+
+## What not to log
+
+Do not include raw chat transcripts, full prompts that contain private context, customer data, secrets, credentials, exact private paths, proprietary document bodies, or unredacted project URLs. Prefer hashes, stable ids, coarse tags, short grep phrases, version dates, and decision states.

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.