pluribus-context 0.3.35 → 0.3.36

package/docs/phase-boundary-contracts.md

@@ -0,0 +1,87 @@
+# Phase-boundary contracts for multi-model coding workflows
+
+Use this when a coding workflow routes work through phases such as **Explore → Propose → Spec → Design → Tasks → Apply → Verify**, especially when different tools or models handle different phases.
+
+The problem is not only “which model is best for this step”. The failure mode is handoff: a plan agent burns context, a build agent receives a lossy summary, a verifier cannot tell which decisions are current, and stale assumptions leak from one phase into the next.
+
+A phase-boundary contract makes every transition explicit:
+
+- what input context was allowed into the phase;
+- what artifact the phase had to produce;
+- what evidence is required before the next phase may start;
+- what context must not be carried forward;
+- which stop conditions require human review or a fresh phase run.
+
+This keeps Pluribus out of the orchestration layer. The workflow runner can be OpenCode, Claude Code, Cursor, OpenClaw, Codex, a local script, or a human checklist. Pluribus supplies the evidence shape.
+
+## Contract shape
+
+```json
+{
+  "schema": "pluribus.phase-boundary-contract.v1",
+  "workflowId": "checkout-refactor-2026-06-03",
+  "currentPhase": "apply",
+  "nextPhase": "verify",
+  "allowedInput": [
+    {
+      "kind": "approved_plan",
+      "ref": "plans/checkout-refactor.md",
+      "contentHash": "sha256:...",
+      "required": true
+    }
+  ],
+  "outputArtifact": {
+    "kind": "patch",
+    "ref": "git:working-tree",
+    "contentHash": "sha256:..."
+  },
+  "evidenceGate": {
+    "requiredBeforeNextPhase": ["changed_files", "tests_run", "open_risks", "stop_conditions"],
+    "status": "pass"
+  },
+  "droppedContext": [
+    {
+      "kind": "exploration_transcript",
+      "reason": "not authoritative after approved plan"
+    }
+  ],
+  "stopConditions": []
+}
+```
+
+## Minimum fields
+
+| Field | Why it exists |
+| --- | --- |
+| `workflowId` | Correlates phase records without storing a transcript. |
+| `currentPhase` / `nextPhase` | Makes the handoff boundary explicit. |
+| `allowedInput[]` | Prevents the next model from inheriting stale scratch context accidentally. |
+| `outputArtifact` | Names the thing this phase produced: plan, spec, task list, patch, review, or verification report. |
+| `evidenceGate.requiredBeforeNextPhase[]` | Forces the phase to prove the minimum facts the next phase depends on. |
+| `droppedContext[]` | Records what intentionally did **not** cross the boundary. |
+| `stopConditions[]` | Lets the workflow stop instead of laundering uncertainty into the next model. |
+
+## Apply → Verify is the strictest boundary
+
+For coding workflows, the most useful hard gate is often between Apply and Verify. The verifier should receive a compact evidence packet, not a vague “I implemented it” summary:
+
+- decision implemented;
+- source/plan hash used;
+- changed files or file-set hash;
+- tests/commands run with pass/fail state;
+- open risks and skipped checks;
+- whether secrets, schema migrations, data writes, or external calls were touched;
+- explicit stop condition if verification cannot be trusted.
+
+## Privacy boundary
+
+Do not put raw source, prompts, transcripts, secrets, full command output, absolute local paths, or customer data in the contract. Use stable refs, hashes, counts, risk classes, and short non-secret labels.
+
+## Try it
+
+```bash
+cd examples/phase-boundary-contract
+node check-phase-boundary.mjs phase-boundary-contract.json
+```
+
+The checker is intentionally small. It is a copyable acceptance test for workflow builders: if a phase handoff cannot pass this gate, the next model should not pretend it has reliable state.

package/docs/review-primitive-gate.md

@@ -77,6 +77,8 @@ The copyable demo in [`examples/review-primitive-gate/`](../examples/review-prim
 
 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.
 
+If you review AI-authored pull requests, the [`examples/ai-pr-review-receipts/`](../examples/ai-pr-review-receipts/) recipe shows the same gate as a GitHub Actions merge/check primitive for PR blast-radius evidence.
+
 ```bash
 node examples/review-primitive-gate/check-review-receipt.mjs \
   examples/review-primitive-gate/pass-review-receipt.json

package/docs/skill-install-receipts.md

@@ -0,0 +1,102 @@
+# Skill install/load receipts
+
+Privacy-safe receipts for answering a narrow setup question:
+
+> After a skill installer ran, which agent targets can actually discover and load the installed skill, and what context budget did the install create?
+
+This is not a skill marketplace, package manager, or telemetry backend. Use this receipt next to tools such as `npx skills add`, team setup scripts, Claude Code plugins, Codex/Cursor/OpenClaw skill folders, or internal bootstrap scripts when the risky part is crossing several boundaries at once:
+
+1. the installer selected a source package/ref;
+2. files were written into project or global skill roots;
+3. each target agent discovered the installed manifest/resource;
+4. the runtime either injected/read the skill on activation or deferred/skipped it; and
+5. the new always-loaded or advertised context cost did not make the first session unsafe.
+
+The receipt should stay reviewable without raw skill bodies, private paths, prompts, transcripts, environment dumps, secrets, tool outputs, or customer data.
+
+## When to use it
+
+Use a skill install/load receipt when:
+
+- a setup command installs the same Skill into Claude Code, Codex, Cursor, OpenClaw, Zed/ACP, or another agent client;
+- a plugin/installer claims "cross-agent" support but you need proof per target;
+- a user says the Skill exists on disk but the runtime does not use it;
+- an installer adds MCP, hooks, rules, commands, or skill folders and could increase startup context cost; or
+- CI/review needs a compact proof that install succeeded without dumping the installed content.
+
+For mutation planning before any writes begin, use [install-plan receipts](install-plan-receipts.md). For runtime-only debugging where the file already exists but disappears in ACP/Zed/CLI/chat, use [loaded-resource boundary receipts](loaded-resource-boundary.md). This receipt sits between them: installer result + per-target discovery/load/budget proof.
+
+## Minimum contract
+
+```json
+{
+  "receipt_type": "agent.skill_install_receipt.v1",
+  "run_id": "skill-install-demo-001",
+  "installer": {
+    "name": "skills-cli",
+    "command_class": "skill_package_install",
+    "source": {
+      "kind": "git_ref",
+      "package": "vercel-labs/skills/context-budget-preflight",
+      "ref": "sha256:source-package-hash"
+    }
+  },
+  "mode_effective": "post_install_check",
+  "writes_completed": true,
+  "targets": [
+    {
+      "agent": "claude-code",
+      "scope": "project",
+      "required": true,
+      "install_status": "installed",
+      "discovery_status": "discovered",
+      "load_status": "activation_required",
+      "activation": "on_demand_skill_description",
+      "context_cost_bucket": "0-1k",
+      "safe_to_start_session": true
+    }
+  ],
+  "overall_safe_to_start_session": true,
+  "privacy_exclusions": ["raw_skill_body", "raw_prompt", "transcript", "secrets", "env_dump", "private_absolute_path"]
+}
+```
+
+## Fields that matter most
+
+- `installer.source` — package/ref/hash identity without embedded credentials.
+- `targets[].agent` and `targets[].scope` — which client and project/global root were targeted.
+- `targets[].install_status` — `installed`, `skipped`, or `failed`.
+- `targets[].discovery_status` — whether the target client can discover the installed manifest/resource.
+- `targets[].load_status` — `injected`, `readable`, `activation_required`, `deferred`, `not_tested`, or `failed`.
+- `targets[].context_cost_bucket` — coarse estimate such as `0-1k`, `1k-5k`, `5k-20k`, `over_budget`, or `unknown`; do not log raw schemas or skill text.
+- `targets[].safe_to_start_session` — false if a required target failed install/discovery, the runtime load test failed, or budget is already over cap.
+- `overall_safe_to_start_session` — false unless every required target is safe.
+
+## Copyable smoke test
+
+```bash
+node examples/skill-install-receipts/check-skill-install-receipt.mjs \
+  examples/skill-install-receipts/skill-install-receipt.json
+```
+
+Expected output:
+
+```text
+skill install receipt ok: 3 targets checked
+```
+
+## What this proves / does not prove
+
+Proves:
+
+- the installer wrote or skipped the intended targets;
+- each required target has an explicit discovery/load status;
+- context cost is bucketed before a session starts; and
+- raw skill/source content stayed out of the receipt.
+
+Does not prove:
+
+- the Skill is semantically good;
+- the agent will choose the Skill for every matching task;
+- the source package is trustworthy beyond the pinned ref/hash; or
+- runtime behavior in clients not listed in `targets`.

package/docs/skill-use-rate-receipts.md

@@ -0,0 +1,104 @@
+# Skill use-rate receipts
+
+Agent Skill installers are getting good at the first boundary: download a Skill and attach it to Claude Code, Cursor, Codex, OpenCode, or another harness. The next boundary is harder: **installed is not used**.
+
+A skill use-rate receipt is a privacy-safe record that separates four states:
+
+1. **Discovered** — the installer/catalog found the Skill.
+2. **Installed/attached** — files or symlinks were written for a target agent/scope.
+3. **Invoked** — a session actually selected or loaded the Skill.
+4. **Useful enough to keep** — the Skill affected a reviewed action, check, or decision in a defined window.
+
+This matters when a team installs many Skills, plugins, commands, or subagents and later cannot tell which ones are just prompt clutter. The receipt should prove lifecycle state and usage counters without logging raw Skill bodies, prompts, source code, transcripts, or tool output.
+
+## Minimal receipt shape
+
+```json
+{
+  "schema": "pluribus.skill_use_rate_receipt.v1",
+  "run_id": "skills-audit-2026-06-05T13:00Z",
+  "generated_at": "2026-06-05T13:00:00Z",
+  "installer": {
+    "name": "skills",
+    "version": "1.5.9",
+    "command_digest": "sha256:..."
+  },
+  "window": {
+    "started_at": "2026-05-22T00:00:00Z",
+    "ended_at": "2026-06-05T13:00:00Z"
+  },
+  "skills": [
+    {
+      "skill_id": "frontend-design",
+      "source_ref": "github:vercel-labs/agent-skills/skills/frontend-design@main",
+      "target_agent": "claude-code",
+      "scope": "project",
+      "install_method": "symlink",
+      "discovered": true,
+      "installed": true,
+      "attached": true,
+      "invoked_count": 7,
+      "acted_on_count": 3,
+      "last_invoked_at": "2026-06-05T10:12:08Z",
+      "unused_since_install": false,
+      "context_cost_bucket": "small",
+      "evidence": [
+        {
+          "kind": "session_log_digest",
+          "ref": "sha256:0b7d..."
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Evaluation questions
+
+Use this receipt to ask:
+
+- Which Skills are installed but never discovered by the harness?
+- Which Skills are discoverable but never invoked?
+- Which Skills are invoked but never acted on?
+- Which Skills are globally installed but only useful in one project?
+- Which Skills should be detached, narrowed, or promoted to a hard policy/check?
+
+## Privacy boundary
+
+Do record:
+
+- source refs and commit/tag when available;
+- target agent and scope;
+- install method (`copy`, `symlink`, generated file, ephemeral use);
+- boolean lifecycle states;
+- invocation and acted-on counters;
+- timestamps, hashes, and non-sensitive evidence refs.
+
+Do **not** record:
+
+- full Skill Markdown bodies;
+- raw user prompts or transcripts;
+- source code or tool output;
+- private file paths beyond a reviewed alias;
+- secrets, tokens, customer data, or unredacted environment values.
+
+## Copyable checker
+
+The [skill use-rate receipt example](../examples/skill-use-rate-receipts/) includes a small checker that validates required lifecycle fields and prints installed-but-unused Skills as review warnings rather than pretending installation equals adoption.
+
+```bash
+node examples/skill-use-rate-receipts/check-skill-use-rate.mjs \
+  examples/skill-use-rate-receipts/skill-use-rate-receipt.json
+```
+
+Expected output:
+
+```text
+skill use-rate receipt ok: 3 skills checked, 1 unused install warning
+```
+
+## Where this fits
+
+This is adjacent to [Skill install/load receipts](skill-install-receipts.md), but it answers a different question. Install/load receipts decide whether it is safe to start a session after an installer runs. Skill use-rate receipts decide whether a Skill actually earned its place after real sessions.
+
+The market signal behind this is current Skill/plugin consolidation pressure: teams can install many prompt resources, but the useful metric is not package count. It is `invoked / installed` and, when possible, `acted_on / invoked` over a reviewable window.

package/examples/agent-firewall-denial-audit/README.md

@@ -0,0 +1,14 @@
+# Agent firewall denial/audit example
+
+This example turns an agent-firewall block into two privacy-safe artifacts:
+
+- `denial-envelope.json` — what the model is allowed to see.
+- `operator-audit-record.json` — what the operator/dashboard/CI can audit.
+
+Run the checker:
+
+```bash
+node check-denial-audit.mjs .
+```
+
+The checker enforces the core invariant: blocks should be structured enough for the model to stop or ask for approval, but not detailed enough to reveal raw commands, secrets, private paths, or bypassable policy internals.

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/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

@@ -1,5 +1,55 @@
 # AI PR review receipts example
 
-This example contains a copyable GitHub PR template for agent-generated or agent-modified pull requests.
+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/compaction-resume-receipts/README.md

@@ -0,0 +1,12 @@
+# Compaction resume receipt gate
+
+This example validates a privacy-safe receipt for `PostCompact`, `SessionStart(compact)`, or any workflow that resumes an AI coding session after summarization.
+
+Run:
+
+```bash
+node check-resume-receipt.mjs safe-resume-receipt.json
+node check-resume-receipt.mjs unsafe-resume-receipt.json
+```
+
+Use it as a tiny CI/hook check before an agent continues work after compaction. The receipt records hashes, refs, and verdicts — not raw transcripts or raw instruction bodies.