pluribus-context 0.3.33 → 0.3.35

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.

package/examples/claude-code-review-hook/check-review-receipt-hook.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const [receiptPathArg] = process.argv.slice(2)
+
+if (!receiptPathArg) {
+  console.error(JSON.stringify({ ok: false, errors: ['usage: node check-review-receipt-hook.mjs <receipt.json>'] }, null, 2))
+  process.exit(2)
+}
+
+const stdin = readFileSync(0, 'utf8').trim()
+let hookInput = {}
+if (stdin) {
+  try {
+    hookInput = JSON.parse(stdin)
+  } catch (error) {
+    console.error(JSON.stringify({ ok: false, errors: [`invalid hook JSON on stdin: ${error.message}`] }, null, 2))
+    process.exit(2)
+  }
+}
+
+const here = dirname(fileURLToPath(import.meta.url))
+const localGate = resolve(here, '../review-primitive-gate/check-review-receipt.mjs')
+const copiedGate = resolve(here, 'check-review-receipt.mjs')
+const gatePath = process.env.PLURIBUS_REVIEW_GATE || (exists(copiedGate) ? copiedGate : localGate)
+const receiptPath = resolve(process.cwd(), receiptPathArg)
+
+const result = spawnSync(process.execPath, [gatePath, receiptPath], {
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'pipe']
+})
+
+let gateResult = null
+try {
+  gateResult = JSON.parse(result.stdout || '{}')
+} catch {
+  gateResult = { ok: false, errors: ['review gate did not return JSON'], raw_stdout: result.stdout.trim() }
+}
+
+const hookEventName = hookInput.hook_event_name || hookInput.hookEventName || hookInput.event || 'unknown'
+const output = {
+  ok: result.status === 0 && gateResult.ok === true,
+  hook_event_name: hookEventName,
+  receipt_path: receiptPathArg,
+  resume_state: gateResult.resume_state,
+  assignment_id: gateResult.assignment_id,
+  run_id: gateResult.run_id,
+  next_safe_action: readNextSafeAction(receiptPath),
+  errors: gateResult.errors || [],
+  warnings: gateResult.warnings || []
+}
+
+if (output.ok) {
+  console.log(JSON.stringify(output, null, 2))
+  process.exit(0)
+}
+
+console.error(JSON.stringify(output, null, 2))
+process.exit(result.status || 1)
+
+function exists(path) {
+  try {
+    readFileSync(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function readNextSafeAction(path) {
+  try {
+    const receipt = JSON.parse(readFileSync(path, 'utf8'))
+    return receipt?.handoff?.next_safe_action || null
+  } catch {
+    return null
+  }
+}

package/examples/claude-code-review-hook/sample-task-completed-event.json

@@ -0,0 +1,6 @@
+{
+  "hook_event_name": "TaskCompleted",
+  "session_id": "demo-session",
+  "transcript_path": "redacted/transcript.jsonl",
+  "cwd": "/repo/example"
+}