pluribus-context 0.3.34 → 0.3.36

package/examples/agent-firewall-denial-audit/check-denial-audit.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const dir = process.argv[2] || new URL('.', import.meta.url).pathname;
+const envelopePath = path.join(dir, 'denial-envelope.json');
+const auditPath = path.join(dir, 'operator-audit-record.json');
+const envelope = JSON.parse(fs.readFileSync(envelopePath, 'utf8'));
+const audit = JSON.parse(fs.readFileSync(auditPath, 'utf8'));
+const errors = [];
+
+const secretLike = /(api[_-]?key|secret|password|token\s*[:=]|-----BEGIN|bearer\s+[a-z0-9._-]+|raw transcript|verbatim customer|full email)/i;
+const rawCommandLike = /\b(rm\s+-rf|git\s+push|git\s+reset|npm\s+publish|curl\s+https?:|gh\s+(issue|pr)\s+(create|edit))\b/i;
+const absolutePathLike = /(^|["'\s])\/(home|Users|var|etc|tmp)\/[\w./-]+/i;
+const sha256Like = /^sha256:[a-f0-9]{64}$/;
+const allowedReasonClasses = new Set([
+  'destructive_git',
+  'filesystem_write_out_of_scope',
+  'outbound_after_secret_read',
+  'credential_exposure_risk',
+  'package_publish_requires_approval',
+  'unknown_policy_boundary'
+]);
+const retrySafety = new Set(['safe_to_retry', 'unsafe_until_approved', 'unsafe_do_not_retry']);
+
+function requireString(object, field, label) {
+  if (typeof object[field] !== 'string' || object[field].trim() === '') {
+    errors.push(`${label}: missing ${field}`);
+    return '';
+  }
+  return object[field];
+}
+
+function inspectModelVisible(value, prefix = 'envelope') {
+  if (typeof value === 'string') {
+    if (secretLike.test(value)) errors.push(`${prefix}: possible secret/private payload leak`);
+    if (rawCommandLike.test(value)) errors.push(`${prefix}: raw command leaked to model-visible denial`);
+    if (absolutePathLike.test(value)) errors.push(`${prefix}: absolute private path leaked to model-visible denial`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => inspectModelVisible(item, `${prefix}[${index}]`));
+    return;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, item] of Object.entries(value)) {
+      if (/raw(command|input|prompt|policy|file|content)|secret|token|password/i.test(key)) {
+        errors.push(`${prefix}.${key}: forbidden model-visible field`);
+      }
+      inspectModelVisible(item, `${prefix}.${key}`);
+    }
+  }
+}
+
+if (envelope.type !== 'agent_firewall_denial.v1') errors.push('envelope: wrong type');
+if (audit.type !== 'agent_firewall_operator_audit.v1') errors.push('audit: wrong type');
+if (envelope.decision !== 'blocked') errors.push('envelope: decision must be blocked');
+if (audit.decision !== 'blocked') errors.push('audit: decision must be blocked');
+
+const correlationId = requireString(envelope, 'correlationId', 'envelope');
+if (correlationId !== audit.correlationId) errors.push('audit: correlationId does not match envelope');
+
+const reasonClass = requireString(envelope, 'reasonClass', 'envelope');
+if (reasonClass && !allowedReasonClasses.has(reasonClass)) {
+  errors.push(`envelope: unknown or too-specific reasonClass ${reasonClass}`);
+}
+
+const alternative = requireString(envelope, 'safeAlternative', 'envelope');
+if (alternative.length > 240) errors.push('envelope: safeAlternative should stay short');
+if (typeof envelope.requiresApproval !== 'boolean') errors.push('envelope: requiresApproval must be boolean');
+if (!retrySafety.has(envelope.retrySafety)) errors.push('envelope: invalid retrySafety');
+inspectModelVisible(envelope);
+
+if (!['Bash', 'Edit', 'Write', 'WebFetch', 'MCP', 'Task', 'Agent'].includes(audit.tool)) {
+  errors.push('audit: unexpected or missing tool class');
+}
+if (!sha256Like.test(audit.commandHash || '')) errors.push('audit: commandHash must be sha256:<64 hex>');
+if (!sha256Like.test(audit.cwdHash || '')) errors.push('audit: cwdHash must be sha256:<64 hex>');
+if (!Array.isArray(audit.matchedPolicyIds) || audit.matchedPolicyIds.length === 0) {
+  errors.push('audit: matchedPolicyIds must be a non-empty array');
+}
+if (!audit.sessionTaint || typeof audit.sessionTaint !== 'object') errors.push('audit: missing sessionTaint object');
+if (!audit.approval || typeof audit.approval !== 'object') errors.push('audit: missing approval object');
+if (!retrySafety.has(audit.retrySafety)) errors.push('audit: invalid retrySafety');
+if (typeof audit.modelEnvelopeHash !== 'string' || !sha256Like.test(audit.modelEnvelopeHash)) {
+  errors.push('audit: modelEnvelopeHash must be sha256:<64 hex>');
+}
+
+function inspectAuditValues(value, prefix = 'audit') {
+  if (typeof value === 'string') {
+    if (/(api[_-]?key\s*[:=]|secret\s*[:=]|password\s*[:=]|token\s*[:=]|-----BEGIN|bearer\s+[a-z0-9._-]+|raw transcript|verbatim customer|full email)/i.test(value)) {
+      errors.push(`${prefix}: possible raw secret/private payload`);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => inspectAuditValues(item, `${prefix}[${index}]`));
+    return;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, item] of Object.entries(value)) inspectAuditValues(item, `${prefix}.${key}`);
+  }
+}
+
+inspectAuditValues(audit);
+if ('rawCommand' in audit || 'rawPrompt' in audit || 'rawPolicy' in audit || 'rawFileContent' in audit) {
+  errors.push('audit: raw private payload fields are not allowed');
+}
+
+if (errors.length) {
+  console.error(`agent firewall denial/audit failed (${errors.length}):`);
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log(`agent firewall denial/audit ok: ${correlationId}, ${reasonClass}, ${audit.matchedPolicyIds.length} policy id(s)`);

package/examples/agent-firewall-denial-audit/denial-envelope.json

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

package/examples/agent-firewall-denial-audit/operator-audit-record.json

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

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/.github/workflows/ai-pr-review-receipt.yml

@@ -0,0 +1,25 @@
+name: AI PR review receipt gate
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+jobs:
+  review-receipt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Put your agent/bot-generated receipt at this path, or adjust RECEIPT_PATH.
+      # Keep the receipt privacy-safe: no raw prompts, transcripts, source code,
+      # tool output, secrets, stack traces, or customer data.
+      - name: Validate AI PR review receipt
+        env:
+          RECEIPT_PATH: artifacts/review-primitive-receipt.json
+        run: |
+          test -f "$RECEIPT_PATH"
+          npm install --no-save --ignore-scripts pluribus-context@latest
+          node node_modules/pluribus-context/examples/review-primitive-gate/check-review-receipt.mjs "$RECEIPT_PATH"

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

@@ -0,0 +1,55 @@
+# AI PR review receipts example
+
+This example contains a copyable GitHub PR template and CI gate 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.
+
+The point is not to make every AI PR small. It is to make the risky boundaries reviewable enough that CI or a maintainer can decide: merge, route to a human owner, or stop.
+
+## Files
+
+- [`.github/pull_request_template.md`](.github/pull_request_template.md) — human-readable PR body section for blast-radius review.
+- [`.github/workflows/ai-pr-review-receipt.yml`](.github/workflows/ai-pr-review-receipt.yml) — copyable GitHub Actions gate that validates a machine-readable receipt.
+- [`review-primitive-receipt.json`](review-primitive-receipt.json) — passing receipt fixture.
+- [`incomplete-review-primitive-receipt.json`](incomplete-review-primitive-receipt.json) — failing fixture for partial/unsafe evidence.
+
+## 60-second local smoke
+
+From the repository root:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/ai-pr-review-receipts/review-primitive-receipt.json
+```
+
+Expected: `ok: true`.
+
+Then run the incomplete fixture:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/ai-pr-review-receipts/incomplete-review-primitive-receipt.json
+```
+
+Expected: non-zero exit. The failure is intentional: unapproved scope change, skipped required test, missing evidence, and `partial` resume state should not silently pass a merge gate.
+
+## GitHub Actions usage
+
+1. Copy `.github/workflows/ai-pr-review-receipt.yml` into your repo.
+2. Have your Claude Code / Codex / Cursor / OpenClaw / review bot emit a privacy-safe receipt at `artifacts/review-primitive-receipt.json`.
+3. Keep raw prompts, transcripts, source code, secrets, stack traces, customer data, and raw tool output out of the receipt.
+4. Let the workflow fail if the receipt is partial, unsafe, missing evidence, or outside approved boundaries.
+
+The template and JSON receipt can be used together: the PR body explains the blast radius to humans, while the JSON receipt gives CI a hard decision primitive.
+
+## Why this exists
+
+Large AI PRs are not automatically unsafe, and small PRs are not automatically reviewable. Diff size is a proxy. This receipt makes the underlying question explicit:
+
+- Which assignment did the agent accept?
+- What read/write boundaries were approved?
+- Did scope or access change mid-run, and was it approved?
+- Which required checks actually ran, with evidence?
+- Did the agent refuse unsafe operations?
+- Is the handoff `complete`, `partial`, or `unsafe-to-resume`?
+- What is the next safe action for the reviewer?

package/examples/ai-pr-review-receipts/incomplete-review-primitive-receipt.json

@@ -0,0 +1,43 @@
+{
+  "type": "agent.review_primitive_receipt.v1",
+  "assignment_id": "pr-483-agent-review",
+  "run_id": "run-2026-05-31T23-10Z",
+  "agent": {
+    "tool": "claude-code-github-actions",
+    "role": "pr-reviewer"
+  },
+  "approved_boundaries": {
+    "read": ["src/auth/**", "tests/auth/**"],
+    "write": ["tests/auth/**"],
+    "network": false
+  },
+  "scope_access_changes": [
+    {
+      "change": "write src/auth/session.ts",
+      "reason": "agent attempted to patch production auth code during review",
+      "approved": false,
+      "approved_by": ""
+    }
+  ],
+  "commands_and_checks": [
+    {
+      "name": "npm test -- tests/auth",
+      "kind": "required_test",
+      "status": "skipped",
+      "evidence": "not-run"
+    }
+  ],
+  "refused_operations": [],
+  "handoff": {
+    "changed_files_bucket": "under_10",
+    "evidence_path": "artifacts/pr-483/review-primitive-receipt.json",
+    "next_safe_action": "human must inspect attempted auth write and run required tests before merge"
+  },
+  "resume_state": "partial",
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_tool_output_logged": false,
+    "source_code_logged": false,
+    "secrets_logged": false
+  }
+}

package/examples/ai-pr-review-receipts/review-primitive-receipt.json

@@ -0,0 +1,60 @@
+{
+  "type": "agent.review_primitive_receipt.v1",
+  "assignment_id": "pr-482-agent-review",
+  "run_id": "run-2026-05-31T23-00Z",
+  "agent": {
+    "tool": "claude-code-github-actions",
+    "role": "pr-reviewer"
+  },
+  "approved_boundaries": {
+    "read": ["src/billing/**", "tests/billing/**", "docs/rollout/**"],
+    "write": ["tests/billing/**", "docs/review-receipts/**"],
+    "network": false
+  },
+  "scope_access_changes": [
+    {
+      "change": "read docs/rollout/**",
+      "reason": "verify feature-flag and rollback evidence for the PR receipt",
+      "approved": true,
+      "approved_by": "maintainer"
+    }
+  ],
+  "commands_and_checks": [
+    {
+      "name": "npm test -- tests/billing",
+      "kind": "required_test",
+      "status": "passed",
+      "evidence": "https://github.com/example/repo/actions/runs/123#billing-tests"
+    },
+    {
+      "name": "npm run lint",
+      "kind": "required_check",
+      "status": "passed",
+      "evidence": "https://github.com/example/repo/actions/runs/123#lint"
+    },
+    {
+      "name": "migration rollback smoke",
+      "kind": "required_check",
+      "status": "passed",
+      "evidence": "artifacts/pr-482/rollback-smoke.txt"
+    }
+  ],
+  "refused_operations": [
+    {
+      "operation": "write src/billing/charge-customer.ts",
+      "reason": "outside approved write boundary; reviewer requested tests/docs only"
+    }
+  ],
+  "handoff": {
+    "changed_files_bucket": "under_5",
+    "evidence_path": "artifacts/pr-482/review-primitive-receipt.json",
+    "next_safe_action": "review billing test assertions and rollback evidence before merge"
+  },
+  "resume_state": "complete",
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_tool_output_logged": false,
+    "source_code_logged": false,
+    "secrets_logged": false
+  }
+}

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.