pluribus-context 0.3.33 → 0.3.35

package/docs/install-plan-receipts.md

@@ -0,0 +1,77 @@
+# Install-plan receipts
+
+Use this when an MCP server, Skill bundle, plugin, starter kit, or setup script says it can configure many AI coding tools for you.
+
+The risk is not only whether a hook later runs safely. The earlier boundary is the installer itself: it may detect agents, write MCP config, add instruction files, install Skills, register hooks, or create backups before the user understands what changed.
+
+The goal is a tiny, privacy-safe pre-mutation receipt that proves what the setup step intends to touch **before the first write starts**. Do not log prompts, source code, secrets, raw environment dumps, transcripts, raw command output, customer data, or private absolute paths.
+
+## Boundary to prove
+
+For every setup/install run, capture a plan like this before applying changes:
+
+```json
+{
+  "receipt_type": "agent.install.plan.v1",
+  "run_id": "local-install-2026-05-29T16:00Z",
+  "installer": "code-memory-mcp",
+  "mode_requested": "plan",
+  "mode_effective": "plan",
+  "agents_detected": ["claude-code", "cursor", "codex", "openclaw"],
+  "agents_selected": ["claude-code", "openclaw"],
+  "planned_writes": [
+    {
+      "kind": "mcp_config",
+      "target": "claude-code project config",
+      "operation": "add_server",
+      "backup_planned": true
+    },
+    {
+      "kind": "instruction_file",
+      "target": "AGENTS.md",
+      "operation": "append_usage_notes",
+      "backup_planned": true
+    },
+    {
+      "kind": "hook",
+      "target": "pre-tool hook config",
+      "operation": "register_command",
+      "backup_planned": true
+    }
+  ],
+  "external_commands_planned": [
+    { "phase": "apply", "command_class": "package_manager_install" }
+  ],
+  "network_after_install": "mcp_server_localhost_only",
+  "writes_started": false,
+  "next_safe_command": "installer apply --from-plan install-plan.json"
+}
+```
+
+Keep `target` values coarse enough for review. Prefer `claude-code project config` over a full local path, and `package_manager_install` over raw shell output.
+
+## Acceptance checks
+
+A safe installer should make these claims inspectable:
+
+1. **Plan mode exists** — `install --plan`, `install --dry-run`, or equivalent emits the receipt without writing files.
+2. **Effective mode is explicit** — if the user requested `apply` but policy downgraded to `plan`, the receipt says so.
+3. **Agent detection is separated from selection** — finding Cursor/Codex/Claude/OpenClaw does not imply every detected tool will be changed.
+4. **Every planned write has a kind and backup decision** — config, instruction file, Skill, hook, shell profile, lockfile, cache, or generated artifact.
+5. **Writes are still false at receipt time** — `writes_started=false` is the key trust boundary.
+6. **Apply can be repeated from the plan** — the user can review one artifact, then run a concrete next command.
+7. **No private payloads leak** — no raw source, prompts, env dumps, secrets, token values, transcripts, stack traces, or raw tool output.
+
+## Why this matters for hooks and MCP
+
+Hooks, Skills, and MCP configs are often discussed as runtime supply-chain surfaces. That is true, but it is downstream. A one-command installer can create the hook or MCP entry first.
+
+A hook receipt answers: “what executed?”
+
+An install-plan receipt answers the earlier question: **“what is about to be installed, written, and trusted?”**
+
+If an installer cannot answer that before mutation, treat it like running CI from an untrusted fork: useful, but not automatically safe.
+
+## Try the copyable example
+
+See [`examples/install-plan-receipts/`](../examples/install-plan-receipts/) for a small review checklist and sample receipt you can copy into setup scripts, README install sections, or agent-managed onboarding workflows.

package/docs/mcp-tool-visibility-receipts.md

@@ -0,0 +1,67 @@
+# MCP tool visibility receipts
+
+MCP memory, Git, GitLab, code-search, and knowledge-graph servers can be healthy while the agent still cannot see their tools.
+
+A useful debug artifact should prove each boundary separately:
+
+1. **Server launched** — the configured command starts without leaking env/secrets.
+2. **Handshake completed** — client and server agreed on a protocol version and capabilities.
+3. **Proxy catalog returned** — a direct `tools/list` call returns the expected tool count and names.
+4. **Client catalog visible** — the actual agent UI/runtime exposes the same tools under the expected names.
+5. **Invocation allowed or refused** — the first tool call either runs, or returns an explicit permission/config/schema reason.
+
+`server healthy` is not enough. `tools/list` is not enough. The receipt needs to say where the chain stopped.
+
+## 60-second probe for any stdio MCP server
+
+Replace the command after the pipe with the server command you already configured in Claude Code, Cursor, Codex, OpenClaw, or another MCP client.
+
+```bash
+(
+  printf '%s\n' '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"receipt-probe","version":"0.1.0"}},"id":1}'
+  printf '%s\n' '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'
+) | your-mcp-server-command
+```
+
+Record only metadata, not raw prompt/source/tool output:
+
+```json
+{
+  "kind": "mcp.tool_visibility.receipt",
+  "server": "gitlab",
+  "server_command_hash": "sha256:...",
+  "protocol_version_requested": "2024-11-05",
+  "handshake": "ok",
+  "proxy_tools_count": 172,
+  "proxy_tool_names_sample": ["glab_issue_list", "glab_mr_view"],
+  "client": "Claude Code",
+  "client_catalog_visible": false,
+  "client_tools_count": 0,
+  "stopped_at": "client_catalog_visible",
+  "privacy": "names/counts only; no args, outputs, tokens, paths, or source snippets"
+}
+```
+
+## Acceptance check
+
+For a release or bug report, ask for one small matrix:
+
+| Boundary | Evidence | Pass condition |
+| --- | --- | --- |
+| Launch | server command hash + exit/live status | command starts and stays alive long enough for handshake |
+| Handshake | protocol version + capabilities summary | initialized without version/schema mismatch |
+| Proxy catalog | `tools/list` count + stable tool-name sample | expected tools returned directly |
+| Client catalog | client-visible count + naming prefix | same class of tools visible to the agent |
+| First invocation | allowed/refused reason | failure explains permission/config/schema, not silent absence |
+
+This shape is intentionally compatible with GitHub/GitLab issue reports and OpenTelemetry-style events. It helps maintainers separate server bugs from client catalog, protocol-version, schema, timeout, and permission bugs without asking users to paste private output.
+
+## Why this belongs near Pluribus
+
+Pluribus should not become an MCP gateway or memory database. The narrow value is evidence for context boundaries:
+
+- generated instruction files prove what static rules were written;
+- memory/search receipts prove what retrieved context was delivered;
+- tool visibility receipts prove whether a configured MCP capability actually crossed into the agent's usable catalog.
+
+If a tool is not visible to the agent, the project has no reliable context handoff no matter how healthy the server looks.

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/context-receipts/SKILL.md

@@ -100,6 +100,27 @@ Minimal JSONL event names:
 {"event":"subagent.toolsearch.matrix.completed","tested_axis":"tools_frontmatter_shape","audit_gap":"proves ToolSearch exposure, not semantic tool relevance or runtime call success"}
 ```
 
+## Retrieval / code-search smoke
+
+For semantic code search, repo RAG, or MCP tools such as Claude Context, separate "search returned" from "agent context loaded":
+
+- which index snapshot/version was used, without raw local codebase paths;
+- what query/category/filter identity selected the candidates, without raw query text;
+- which result ids/chunk hashes were returned, with rank, score bucket, stale flag, duplicate marker, path hash/extension, and range bucket;
+- which returned chunks were actually loaded into the agent context;
+- which chunks were suppressed as duplicate, stale, clipped, policy-blocked, or over budget;
+- whether raw code, raw prompts, raw paths, customer names, URLs, secrets, and ticket text stayed out of the receipt;
+- the audit gap: this proves retrieval/loading boundaries, not semantic answer quality.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"code.index.snapshot.used","snapshot_id_hash":"sha256:...","codebase_path_hash":"sha256:...","indexed_chunk_count_bucket":"over_1k","raw_codebase_path_copied":false}
+{"event":"code.search.performed","query_hash":"sha256:...","query_category":"auth_debug","candidate_count_bucket":"over_1k","raw_query_copied":false}
+{"event":"code.search.result.returned","rank":1,"chunk_id_hash":"sha256:...","chunk_text_hash":"sha256:...","path_hash":"sha256:...","score_bucket":"high","stale":false,"raw_code_copied":false}
+{"event":"context.input.loaded","kind":"retrieved_code_chunks","loaded_chunk_count":3,"suppressed_chunk_count":2,"suppression_reasons":["duplicate","stale_snapshot_chunk"],"raw_code_copied":false}
+```
+
 ## Usage attribution smoke
 
 For `/usage`, `/context`, `/doctor`, or other context-budget breakdowns, map each displayed category to evidence that can be reviewed without exposing private content:

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).