pluribus-context 0.3.34 → 0.3.35

package/docs/review-primitive-gate.md

@@ -0,0 +1,107 @@
+# Review primitive gate for agent handoffs
+
+Use this when a parallel-agent run, Claude Code hook/workflow, Codex/OpenClaw handoff, or local control-plane wrapper needs to prove more than "the agent said it was done".
+
+The market question is not just what to log after a run. It is whether a reviewer or CI job can make a decision:
+
+- **continue** because the assignment stayed inside approved scope and required checks passed;
+- **review first** because the run is partial or has explicit unverified assumptions;
+- **reject / stop** because scope changed without approval, required checks were skipped or failed, or the run is unsafe to resume.
+
+Pluribus should not be the execution control plane. Worktrees, VMs, hooks, masks, and vendor guardrails can enforce parts of the run. The useful Pluribus layer is a small, privacy-safe receipt that turns those controls into reviewable evidence across tools.
+
+## Receipt shape
+
+Attach this receipt to a PR body, CI artifact, run summary, or handoff packet.
+
+```json
+{
+  "type": "agent.review_primitive_receipt.v1",
+  "assignment_id": "agent-auth-audit-42",
+  "run_id": "run-2026-05-31T17-00Z",
+  "agent": {
+    "tool": "claude-code",
+    "role": "auth-reviewer"
+  },
+  "approved_boundaries": {
+    "read": ["src/auth/**", "tests/auth/**"],
+    "write": ["tests/auth/**"],
+    "network": false
+  },
+  "scope_access_changes": [
+    {
+      "change": "read docs/security/**",
+      "reason": "needed policy wording for test fixture",
+      "approved": true,
+      "approved_by": "human-reviewer"
+    }
+  ],
+  "commands_and_checks": [
+    {
+      "name": "npm test -- tests/auth",
+      "kind": "required_test",
+      "status": "passed",
+      "evidence": "ci://job/123#auth-tests"
+    },
+    {
+      "name": "npm run lint",
+      "kind": "required_check",
+      "status": "passed",
+      "evidence": "ci://job/123#lint"
+    }
+  ],
+  "refused_operations": [
+    {
+      "operation": "write src/auth/session.ts",
+      "reason": "outside approved write boundary"
+    }
+  ],
+  "handoff": {
+    "changed_files_bucket": "under_5",
+    "evidence_path": "artifacts/agent-auth-audit-42.json",
+    "next_safe_action": "review tests/auth/session.test.ts before merge"
+  },
+  "resume_state": "complete",
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_tool_output_logged": false,
+    "source_code_logged": false,
+    "secrets_logged": false
+  }
+}
+```
+
+## Minimal gate
+
+The copyable demo in [`examples/review-primitive-gate/`](../examples/review-primitive-gate/) turns the receipt into a CI/reviewer decision.
+
+If you use Claude Code hooks, the [`examples/claude-code-review-hook/`](../examples/claude-code-review-hook/) bridge shows how to run the same gate from `TaskCompleted`, `PostCompact`, or `SessionEnd` without logging raw prompts, transcripts, tool output, source code, or secrets.
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/review-primitive-gate/pass-review-receipt.json
+
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/review-primitive-gate/fail-review-receipt.json
+```
+
+The gate passes only when:
+
+- `type` is `agent.review_primitive_receipt.v1`;
+- `assignment_id` and `run_id` exist;
+- approved read/write boundaries are present;
+- every scope/access change is explicitly approved;
+- every required check/test passed;
+- `resume_state` is `complete`.
+
+The gate fails when a run is `partial` or `unsafe-to-resume`, when a required check is skipped/failed, or when scope changed without approval. That is intentional: partial work can be valuable, but it should not silently pass a merge gate.
+
+## What to keep out
+
+Do not put raw prompts, full transcripts, source code, exact proprietary paths, secrets, customer data, or raw tool output in the receipt. Use coarse globs, hashes, CI URLs, artifact IDs, pass/fail states, and human-readable next safe actions.
+
+## Why this is different from a receipt field list
+
+A field list says what happened. A review primitive says what the next system is allowed to do with that evidence.
+
+If the artifact cannot reject a PR, pause a handoff, or force review when the run became partial/unsafe, it is probably just a nicer `plan.md`.

package/docs/skill-policy-receipts.md

@@ -0,0 +1,87 @@
+# Skill policy receipts
+
+Use this when an Agent Skill, `CLAUDE.md`, hook, or project rule says "do not touch X" but the agent can still drift into the forbidden path.
+
+The goal is not to log prompts or source code. The goal is a tiny, privacy-safe receipt that proves the run checked the policy boundary before writing code and again after writing code.
+
+This was prompted by a live `r/ClaudeCode` thread where a Skill told Claude Code not to create unit tests for internal services, but the run still generated one. Natural-language policy alone was too soft; the missing piece was an inspectable guard.
+
+## Boundary to prove
+
+For every requested change, capture:
+
+```json
+{
+  "receipt_type": "skill.policy.v1",
+  "skill": "unit-test-boundary",
+  "request_id": "local-run-2026-05-28T12:00Z",
+  "policy_scope": "unit-test targets",
+  "targets": [
+    {
+      "target": "src/public-api/client.test.ts",
+      "decision": "allowed",
+      "reason": "public API surface"
+    },
+    {
+      "target": "src/internal/billing/reconciler.test.ts",
+      "decision": "refused",
+      "reason": "internal service tests are out of scope for this Skill"
+    }
+  ],
+  "write_started": false,
+  "post_write_guard": "not_run",
+  "stopped_at": "policy_refused"
+}
+```
+
+Keep values coarse. Do not include code, secrets, customer names, stack traces, raw tool output, or full transcripts.
+
+## Minimal Skill guard
+
+Add a short preflight before the Skill writes files:
+
+```markdown
+## Policy preflight
+
+Before writing tests:
+
+1. List the intended test targets.
+2. Mark each target as `allowed` or `refused`.
+3. Refuse before writing if any target imports or exercises internal services.
+4. Emit a `skill.policy.v1` receipt with target names or coarse globs, decision, reason, and `write_started=false` when refused.
+5. Only after every target is allowed, write files.
+6. After writing, run the post-write guard and emit whether it passed.
+```
+
+Then add a post-write check that is simple enough for an agent to run reliably:
+
+```bash
+# Example: fail if generated unit tests import internal services.
+grep -R "from ['\"]\.\./\.\./internal\|from ['\"]@/internal\|require(['\"]@/internal" \
+  -- '*test.*' '*spec.*'
+```
+
+Adjust the grep for your repo. The important part is the receipt shape:
+
+- `policy_target_listed`
+- `policy_decision_allowed` / `policy_decision_refused`
+- `refusal_reason`
+- `write_started`
+- `post_write_guard_passed` / `post_write_guard_failed`
+- `stopped_at`
+
+## Why this belongs next to context receipts
+
+A Skill can be loaded and still fail to obey the boundary. That is the same class of problem as a healthy MCP server with tools invisible in the client, or a context file generated but not actually selected by the agent.
+
+The useful question is: **where did the boundary proof stop?**
+
+- Skill loaded, but no target list: policy was never made operational.
+- Target list exists, but no decisions: policy was considered but not enforced.
+- Refused target exists, but `write_started=true`: refusal came too late.
+- Post-write guard failed: generated code crossed the forbidden boundary.
+- Guard passed: the run has a small, reviewable receipt instead of only a confident claim.
+
+## Try the copyable Skill recipe
+
+See [`examples/agent-skills/skill-policy-receipts/`](../examples/agent-skills/skill-policy-receipts/) for a small `SKILL.md` recipe you can copy into Claude Code/OpenClaw-style Skill workflows.

package/docs/subagent-role-receipts.md

@@ -0,0 +1,95 @@
+# Subagent role receipts
+
+Custom subagents are useful only if the caller can tell which role instructions actually governed the delegated work.
+
+Use this recipe when a project defines Codex/Claude Code/Cursor/OpenClaw-style subagents and wants a privacy-safe receipt for the role boundary: which role was requested, which instruction source was loaded, which tools/capabilities were allowed or deferred, and where the subagent stopped before crossing an unsafe boundary.
+
+This is not a claim that every agent runner uses the same file format. Treat `agents.toml` as a portable **example** for role definitions, and treat the receipt as the stable artifact: evidence about the role boundary without logging raw prompts, source code, transcripts, tool output, secrets, or customer data.
+
+## When this helps
+
+Use a subagent role receipt when:
+
+- a manager agent delegates work to a specialist reviewer, tester, security checker, migration planner, or docs writer;
+- the role has a narrower policy than the main agent;
+- the subagent has restricted tools, MCP servers, or write permissions;
+- the role should refuse mutation and only report findings;
+- a human reviewer needs to know which role instructions were loaded before trusting the result.
+
+## Example role definition
+
+The example in [`examples/subagent-role-receipts/agents.toml`](../examples/subagent-role-receipts/agents.toml) defines two project-local roles:
+
+- `blast-radius-reviewer` — reviews AI-generated PRs by operational boundaries before merge;
+- `temporal-authority-checker` — checks whether docs/specs are current or superseded before an agent writes code.
+
+The file is intentionally small so it can be adapted to the runner you use.
+
+## Receipt shape
+
+Attach this to a PR body, task handoff, review-bot comment, or run summary.
+
+```json
+{
+  "type": "subagent.role_boundary.v1",
+  "delegation": {
+    "requested_role": "blast-radius-reviewer",
+    "effective_role": "blast-radius-reviewer",
+    "role_source": "agents.toml",
+    "role_source_hash": "sha256:example-only",
+    "caller": "manager-agent"
+  },
+  "instructions": {
+    "loaded": true,
+    "source_kind": "project-local-role-definition",
+    "raw_instruction_logged": false,
+    "policy_summary": [
+      "review by blast radius, not diff size",
+      "do not approve merge when boundary evidence is ambiguous"
+    ]
+  },
+  "capabilities": {
+    "writes_allowed": false,
+    "tools_allowed": ["read", "grep", "test-summary"],
+    "tools_deferred_or_unavailable": ["shell-write", "deploy", "migration-apply"],
+    "mcp_servers_allowed": []
+  },
+  "boundary_decisions": [
+    {
+      "boundary": "schema_or_data_contract",
+      "status": "ambiguous",
+      "decision": "blocks_merge",
+      "reason": "migration rollback evidence missing"
+    }
+  ],
+  "handoff": {
+    "result_kind": "review_receipt",
+    "stopped_at": "ambiguous boundary before merge approval",
+    "next_safe_action": "ask backend owner to confirm rollback and reader compatibility"
+  },
+  "privacy": {
+    "raw_prompt_logged": false,
+    "raw_source_logged": false,
+    "raw_tool_output_logged": false,
+    "transcript_logged": false,
+    "secrets_logged": false,
+    "customer_data_logged": false
+  }
+}
+```
+
+## Minimal checklist
+
+Before trusting a delegated subagent result, ask for:
+
+- requested role and effective role match;
+- role definition source and coarse hash/version;
+- whether role instructions loaded through the intended path;
+- allowed/refused tool and write capabilities;
+- boundary decisions made by the role;
+- where the role stopped and the next safe action;
+- explicit privacy flags showing raw prompts/source/tool output were not logged.
+
+## What not to log
+
+Do not include raw prompts, full instructions, transcripts, source code, file paths that expose private structure, tool output, secrets, credentials, customer data, stack traces, or proprietary diffs. Prefer coarse names, hashes, counts, decision states, and review-owner labels.

package/docs/temporal-context-receipts.md

@@ -0,0 +1,123 @@
+# Temporal context receipts
+
+Use this when a long-lived AI coding project has old specs, ADRs, plans, or TODOs that still match grep but are no longer the current authority.
+
+The goal is not to delete history or log raw project content. The goal is a tiny, privacy-safe receipt that proves the agent separated **current authority** from **historical citation** before it edits code.
+
+This was prompted by a live `r/ClaudeCode` thread about the temporal problem in long-running projects: Claude Code can find every old plan, but grep is blind to time. If old docs do not carry status, date, and supersession metadata, the agent can treat a stale architecture note as current truth.
+
+## Boundary to prove
+
+For every coding run that reads design/context docs, capture a coarse receipt like this:
+
+```json
+{
+  "receipt_type": "context.temporal_authority.v1",
+  "request_id": "local-run-2026-05-28T16:00Z",
+  "current_authority": {
+    "file": "CURRENT_STATE.md",
+    "status": "current",
+    "as_of": "2026-05-28",
+    "scope": "checkout-flow"
+  },
+  "sources_considered": [
+    {
+      "file": "specs/2025-checkout-rewrite.md",
+      "status": "superseded",
+      "superseded_by": "CURRENT_STATE.md#checkout-flow",
+      "decision": "historical_citation_only"
+    },
+    {
+      "file": "specs/2026-checkout-risk-notes.md",
+      "status": "current",
+      "scope": "checkout-flow",
+      "decision": "allowed_as_supporting_context"
+    }
+  ],
+  "ambiguous_sources": [],
+  "write_started": true,
+  "stopped_at": "temporal_authority_resolved"
+}
+```
+
+Keep values coarse. Do not include source code, raw plans, prompts, transcripts, secrets, customer names, stack traces, private paths, or raw tool output.
+
+## Minimal doc convention
+
+Give every long-lived context file a small frontmatter header:
+
+```markdown
+---
+status: current # current | superseded | archived
+scope: checkout-flow
+date: 2026-05-28
+superseded_by: null
+---
+```
+
+For old specs:
+
+```markdown
+---
+status: superseded
+scope: checkout-flow
+date: 2025-11-10
+superseded_by: ../CURRENT_STATE.md#checkout-flow
+---
+```
+
+Then make `CURRENT_STATE.md` the short authority file an agent must read first:
+
+```markdown
+# Current state
+
+## checkout-flow
+
+- status: current
+- as_of: 2026-05-28
+- current authority: this section
+- related historical specs:
+  - specs/2025-checkout-rewrite.md (superseded)
+  - specs/2026-checkout-risk-notes.md (current supporting context)
+
+Agents may cite superseded specs for rationale, but must not implement from them unless the current authority explicitly reactivates that behavior.
+```
+
+## Agent preflight
+
+Before editing code in a long-lived project, ask the agent to do this:
+
+```markdown
+## Temporal authority preflight
+
+Before writing code:
+
+1. Read `CURRENT_STATE.md` or the repo's current-state equivalent.
+2. List design/spec/TODO/context files found for the requested scope.
+3. Mark each source as `current`, `superseded`, `archived`, or `ambiguous`.
+4. If any relevant source is `ambiguous` or lacks `superseded_by` while contradicting current authority, stop before writing.
+5. Emit a `context.temporal_authority.v1` receipt with coarse file names/globs, status, decision, `write_started`, and `stopped_at`.
+6. Only use superseded docs as historical citations, not as implementation authority.
+```
+
+Useful receipt markers:
+
+- `context_current_authority`
+- `historical_spec_citation`
+- `status_superseded`
+- `superseded_by_resolved`
+- `ambiguous_temporal_source`
+- `stale_source_ignored`
+- `write_refused_until_authority_resolved`
+- `preflight_temporal_decision`
+
+## Where this catches failures
+
+- Old spec matches grep, but has `status: superseded`: agent can cite it but should not implement from it.
+- Old spec conflicts with `CURRENT_STATE.md` and has no `superseded_by`: agent should stop and ask for authority resolution.
+- Multiple current files claim the same scope: agent should stop before writing.
+- Current authority exists, but the run never read it: the receipt should show `stopped_at=current_authority_missing` or `write_started=false`.
+
+## Try the copyable example
+
+See [`examples/temporal-context-receipts/`](../examples/temporal-context-receipts/) for a minimal `CURRENT_STATE.md`, superseded spec, current supporting note, and receipt example.

package/examples/agent-skills/skill-policy-receipts/README.md

@@ -0,0 +1,22 @@
+# Skill policy receipts recipe
+
+This is a copyable Agent Skill recipe for cases where a natural-language rule needs an inspectable guard.
+
+Example use cases:
+
+- a Skill must not generate tests for internal services;
+- an agent must not edit generated files;
+- a hook must not call production APIs;
+- a migration helper must default to preview/dry-run unless `--apply` is explicit.
+
+Copy `SKILL.md` into your Skill registry, adjust the policy and post-write guard, then ask the agent to emit `skill.policy.v1` receipts before writes and after guard checks.
+
+The receipt should prove:
+
+- intended targets were listed;
+- each target was allowed or refused;
+- refusal happened before writes;
+- post-write guard passed or failed;
+- no raw prompt, code, secret, customer data, stack trace, or full transcript was logged.
+
+Related guide: [`docs/skill-policy-receipts.md`](../../../docs/skill-policy-receipts.md).

package/examples/agent-skills/skill-policy-receipts/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: skill-policy-receipts
+description: Use when a task must obey a hard project policy, such as "do not generate tests for internal services", "do not call production APIs", or "do not edit generated files". Emits a privacy-safe receipt before writes and after guard checks.
+---
+
+# Skill Policy Receipts
+
+This Skill turns natural-language guardrails into an inspectable policy receipt.
+
+## Preflight: decide before writing
+
+Before creating or editing files:
+
+1. List intended targets using coarse paths or globs.
+2. For each target, decide `allowed` or `refused`.
+3. Give a short reason.
+4. If any target is refused, stop before writing.
+5. Emit a receipt with `write_started=false` and `stopped_at="policy_refused"`.
+
+Receipt shape:
+
+```json
+{
+  "receipt_type": "skill.policy.v1",
+  "skill": "skill-policy-receipts",
+  "policy_scope": "<short policy name>",
+  "targets": [
+    {
+      "target": "<coarse path or glob>",
+      "decision": "allowed|refused",
+      "reason": "<short reason>"
+    }
+  ],
+  "write_started": false,
+  "post_write_guard": "not_run",
+  "stopped_at": "policy_refused|all_targets_allowed"
+}
+```
+
+Do not include raw prompts, code, secrets, customer data, stack traces, or full tool output.
+
+## Write only after all targets are allowed
+
+If every target is allowed:
+
+1. Emit or state `stopped_at="all_targets_allowed"`.
+2. Perform the write.
+3. Run the configured post-write guard.
+4. Emit whether the guard passed or failed.
+
+Post-write receipt shape:
+
+```json
+{
+  "receipt_type": "skill.policy.v1",
+  "skill": "skill-policy-receipts",
+  "policy_scope": "<short policy name>",
+  "write_started": true,
+  "post_write_guard": "passed|failed|not_configured",
+  "stopped_at": "guard_passed|guard_failed"
+}
+```
+
+## Example policy: no internal-service unit tests
+
+Policy:
+
+> Do not generate unit tests for internal services. If the requested test imports `internal/`, `@/internal`, or a known private service module, refuse before writing and explain the safer target.
+
+Example guard:
+
+```bash
+grep -R "from ['\"]\.\./\.\./internal\|from ['\"]@/internal\|require(['\"]@/internal" \
+  -- '*test.*' '*spec.*'
+```
+
+If the grep finds a match in generated tests, stop and report `post_write_guard="failed"`.

package/examples/ai-pr-review-receipts/.github/pull_request_template.md

@@ -0,0 +1,31 @@
+## 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:`

package/examples/ai-pr-review-receipts/README.md

@@ -0,0 +1,5 @@
+# AI PR review receipts example
+
+This example contains a copyable GitHub PR template for agent-generated or agent-modified pull requests.
+
+Use it when review risk depends on blast radius: schema/data contracts, async paths, rollout gates, external side effects, generated/public interfaces, or security-sensitive config.

package/examples/canonical-output-receipts/canonical-output-receipt.json

@@ -0,0 +1,55 @@
+{
+  "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
+  }
+}

package/examples/claude-code-review-hook/README.md

@@ -0,0 +1,74 @@
+# Claude Code review hook bridge
+
+This example wires the [review primitive gate](../review-primitive-gate/) into Claude Code hooks so a long agent run can be blocked at handoff time when the receipt says `partial` or `unsafe-to-resume`.
+
+Use it when you already have Claude Code hooks, a local control-plane wrapper, or CI emitting `agent.review_primitive_receipt.v1` receipts and you want Claude Code to treat the receipt as a gate rather than a note.
+
+## Copy the hook
+
+```bash
+mkdir -p .claude/hooks .pluribus/receipts
+cp examples/claude-code-review-hook/check-review-receipt-hook.mjs .claude/hooks/
+cp examples/review-primitive-gate/check-review-receipt.mjs .claude/hooks/
+```
+
+Then add this to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "TaskCompleted": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-review-receipt-hook.mjs ${CLAUDE_PROJECT_DIR}/.pluribus/receipts/latest-review-receipt.json"
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-review-receipt-hook.mjs ${CLAUDE_PROJECT_DIR}/.pluribus/receipts/latest-review-receipt.json"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The same bridge can be attached to `SessionEnd` if your workflow writes the receipt only when a session exits.
+
+## What the hook does
+
+Claude Code passes hook event JSON on stdin. The bridge reads that event for traceability, runs the review gate against the receipt path, and:
+
+- exits `0` when the receipt is complete and privacy-safe;
+- exits non-zero when required evidence is missing, checks failed/skipped, scope changes were unapproved, or `resume_state` is `partial` / `unsafe-to-resume`;
+- prints a small JSON result that names the hook event, receipt path, and next safe action.
+
+It does **not** log raw prompts, transcripts, tool output, source code, exact proprietary paths, secrets, or customer data.
+
+## Smoke test
+
+```bash
+node examples/claude-code-review-hook/check-review-receipt-hook.mjs \
+  examples/review-primitive-gate/pass-review-receipt.json \
+  < examples/claude-code-review-hook/sample-task-completed-event.json
+
+node examples/claude-code-review-hook/check-review-receipt-hook.mjs \
+  examples/review-primitive-gate/fail-review-receipt.json \
+  < examples/claude-code-review-hook/sample-task-completed-event.json
+```
+
+The first command should pass. The second should fail and tell the reviewer why the handoff should not continue.
+
+## Why this exists
+
+Claude Code hooks are good at triggering automation around `TaskCompleted`, `PostCompact`, and `SessionEnd`. Pluribus should not replace that control plane. This bridge makes the missing handoff proof explicit: before the next agent resumes, prove the assignment boundary, required checks, privacy flags, evidence path, and `complete / partial / unsafe-to-resume` state.