pluribus-context 0.3.34 → 0.3.36

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"
+}

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.

package/examples/compaction-resume-receipts/check-resume-receipt.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+
+const [file] = process.argv.slice(2)
+
+if (!file) {
+  console.error('Usage: node check-resume-receipt.mjs <compaction-resume-receipt.json>')
+  process.exit(2)
+}
+
+let receipt
+try {
+  receipt = JSON.parse(readFileSync(file, 'utf8'))
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, file, errors: [`invalid JSON: ${error.message}`] }, null, 2))
+  process.exit(2)
+}
+
+const errors = []
+const warnings = []
+
+if (receipt.type !== 'agent.compaction_resume_receipt.v1') {
+  errors.push('type must be agent.compaction_resume_receipt.v1')
+}
+
+for (const key of ['compaction_event_id', 'session_id', 'trigger']) {
+  if (!receipt[key] || typeof receipt[key] !== 'string') {
+    errors.push(`${key} is required`)
+  }
+}
+
+const transcript = receipt.transcript || {}
+if (!transcript.range || typeof transcript.range !== 'string') {
+  errors.push('transcript.range is required')
+}
+if (!transcript.content_hash || typeof transcript.content_hash !== 'string') {
+  errors.push('transcript.content_hash is required; do not log raw transcript text')
+}
+if (transcript.raw_text_logged !== false) {
+  errors.push('transcript.raw_text_logged must be false')
+}
+
+const summary = receipt.summary || {}
+if (!summary.content_hash || typeof summary.content_hash !== 'string') {
+  errors.push('summary.content_hash is required')
+}
+if (!Number.isInteger(summary.token_count) || summary.token_count <= 0) {
+  errors.push('summary.token_count must be a positive integer')
+}
+
+const reloads = Array.isArray(receipt.instruction_sources_reloaded)
+  ? receipt.instruction_sources_reloaded
+  : []
+if (reloads.length === 0) {
+  errors.push('instruction_sources_reloaded must include at least one source')
+}
+for (const [index, source] of reloads.entries()) {
+  if (!source.kind || typeof source.kind !== 'string') {
+    errors.push(`instruction_sources_reloaded[${index}].kind is required`)
+  }
+  if (!source.ref || typeof source.ref !== 'string') {
+    errors.push(`instruction_sources_reloaded[${index}].ref is required`)
+  }
+  if (!source.content_hash || typeof source.content_hash !== 'string') {
+    errors.push(`instruction_sources_reloaded[${index}].content_hash is required`)
+  }
+  if (source.raw_body_logged !== false) {
+    errors.push(`instruction_sources_reloaded[${index}].raw_body_logged must be false`)
+  }
+}
+
+const state = receipt.state || {}
+const kept = Array.isArray(state.kept) ? state.kept : []
+const lost = Array.isArray(state.lost) ? state.lost : []
+if (kept.length === 0) {
+  warnings.push('state.kept is empty; reviewers may not know what survived compaction')
+}
+if (!Array.isArray(state.lost)) {
+  errors.push('state.lost must be an array, even when empty')
+}
+
+const verdict = receipt.resume_verdict || {}
+if (!['true', 'false', 'unknown'].includes(String(verdict.safe_to_resume))) {
+  errors.push('resume_verdict.safe_to_resume must be true, false, or unknown')
+}
+if (!Array.isArray(verdict.reasons) || verdict.reasons.length === 0) {
+  errors.push('resume_verdict.reasons must explain the verdict')
+}
+if (String(verdict.safe_to_resume) !== 'true') {
+  errors.push(`safe_to_resume is ${verdict.safe_to_resume}; stop, reload, or ask before continuing`)
+}
+if (lost.some((item) => item && item.blocks_resume === true)) {
+  errors.push('state.lost contains at least one blocks_resume=true item')
+}
+
+const privacy = receipt.privacy || {}
+for (const key of ['raw_prompts_logged', 'raw_tool_output_logged', 'secrets_logged', 'full_instruction_bodies_logged']) {
+  if (privacy[key] !== false) {
+    errors.push(`privacy.${key} must be false`)
+  }
+}
+
+const result = {
+  ok: errors.length === 0,
+  file,
+  compaction_event_id: receipt.compaction_event_id,
+  session_id: receipt.session_id,
+  safe_to_resume: verdict.safe_to_resume,
+  reloaded_sources: reloads.map((source) => `${source.kind}:${source.ref}`),
+  lost: lost.map((item) => item.ref || item.kind || 'unknown'),
+  errors,
+  warnings
+}
+
+console.log(JSON.stringify(result, null, 2))
+process.exit(result.ok ? 0 : 1)

package/examples/compaction-resume-receipts/safe-resume-receipt.json

@@ -0,0 +1,52 @@
+{
+  "type": "agent.compaction_resume_receipt.v1",
+  "compaction_event_id": "compact-2026-06-01T15-02-59Z",
+  "session_id": "codex-session-42",
+  "trigger": "PostCompact",
+  "transcript": {
+    "range": "messages:1-184",
+    "content_hash": "sha256-7f8f6fbf8a3e3fe0e9f6b59efac0e771d8f64a9ebff3e9b0f5162e43c2e3e89a",
+    "raw_text_logged": false
+  },
+  "summary": {
+    "content_hash": "sha256-8a4f6242e9800f1452bcfd5dbec7e9f1f0b543d72b0c96e57dece44f6c4b8de4",
+    "token_count": 1240
+  },
+  "instruction_sources_reloaded": [
+    {
+      "kind": "AGENTS.md",
+      "ref": "repo-root/AGENTS.md",
+      "content_hash": "sha256-06c39dfb1ba74f5ac6f0e1a6d6b4c65358c3f1a872e96f3fe8d61da947caa1d4",
+      "mtime": "2026-06-01T14:58:02Z",
+      "raw_body_logged": false
+    },
+    {
+      "kind": "plan",
+      "ref": "memory/current-plan.md#active",
+      "content_hash": "sha256-a9b30f8a50dd31ec3c818c9c0d05282bf97f54991a4032f2d547a30174de1c61",
+      "mtime": "2026-06-01T14:59:44Z",
+      "raw_body_logged": false
+    }
+  ],
+  "state": {
+    "kept": [
+      { "kind": "active_plan", "ref": "plan:fix-auth-smoke", "summary_hash": "sha256-4c0f7fd0a72b8cf7e45c0fb97b893590fa12e931f914a34b94756de0d876182c" },
+      { "kind": "open_diff", "ref": "git:working-tree", "summary_hash": "sha256-2e5a0da4b6b4e9d07f11c8f10f332fc74497ef6d052a46997c4f5d0bdb0e1b07" }
+    ],
+    "lost": []
+  },
+  "resume_verdict": {
+    "safe_to_resume": true,
+    "reasons": [
+      "instruction sources reloaded with hashes",
+      "active plan and open diff summarized",
+      "no blocking lost fields recorded"
+    ]
+  },
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_tool_output_logged": false,
+    "secrets_logged": false,
+    "full_instruction_bodies_logged": false
+  }
+}

package/examples/compaction-resume-receipts/unsafe-resume-receipt.json

@@ -0,0 +1,41 @@
+{
+  "type": "agent.compaction_resume_receipt.v1",
+  "compaction_event_id": "compact-2026-06-01T15-02-59Z",
+  "session_id": "codex-session-42",
+  "trigger": "PostCompact",
+  "transcript": {
+    "range": "messages:1-184",
+    "content_hash": "sha256-7f8f6fbf8a3e3fe0e9f6b59efac0e771d8f64a9ebff3e9b0f5162e43c2e3e89a",
+    "raw_text_logged": true
+  },
+  "summary": {
+    "content_hash": "sha256-8a4f6242e9800f1452bcfd5dbec7e9f1f0b543d72b0c96e57dece44f6c4b8de4",
+    "token_count": 880
+  },
+  "instruction_sources_reloaded": [
+    {
+      "kind": "AGENTS.md",
+      "ref": "repo-root/AGENTS.md",
+      "content_hash": "",
+      "mtime": "2026-06-01T14:58:02Z",
+      "raw_body_logged": true
+    }
+  ],
+  "state": {
+    "kept": [],
+    "lost": [
+      { "kind": "rejected_decisions", "ref": "decision-log:missing", "blocks_resume": true },
+      { "kind": "pending_tests", "ref": "test-plan:unknown", "blocks_resume": true }
+    ]
+  },
+  "resume_verdict": {
+    "safe_to_resume": "unknown",
+    "reasons": ["AGENTS.md hash missing and blocking state was lost"]
+  },
+  "privacy": {
+    "raw_prompts_logged": true,
+    "raw_tool_output_logged": false,
+    "secrets_logged": false,
+    "full_instruction_bodies_logged": true
+  }
+}

package/examples/controlled-learning-queue/README.md

@@ -0,0 +1,26 @@
+# Controlled learning queue example
+
+A copyable layout for Claude Code/OpenClaw/Cursor-style "AI employee" agents that use a role file, Skills, memory, and external tools.
+
+The pattern is simple:
+
+- `role/job-contract.md` defines what the agent is allowed to do.
+- `skills/*.md` define procedures with inputs, outputs, and stop conditions.
+- `memory/durable.md` contains approved facts only.
+- `memory/working-notes.md` can hold temporary observations.
+- `learning_queue.md` is where the agent proposes durable memory changes as reviewable diffs.
+- `leads/*.md` are tiny active job cards.
+
+Run the smoke check:
+
+```bash
+node check-learning-queue.mjs learning_queue.md
+```
+
+Expected output:
+
+```text
+learning queue ok: 2 proposal(s), 1 pending review
+```
+
+Why it exists: agents can learn from outcomes, but durable cross-run memory should not be rewritten by one edge case without source, scope, expiry, and a promote/reject decision.

package/examples/controlled-learning-queue/check-learning-queue.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+const file = process.argv[2] || new URL('./learning_queue.md', import.meta.url).pathname;
+const text = fs.readFileSync(file, 'utf8');
+const proposals = text.split(/^## Proposal /m).slice(1);
+const required = ['Status', 'Source', 'Observed', 'Proposed durable change', 'Reason', 'Scope', 'Expiry', 'Reviewer', 'Decision'];
+const rawRisk = /(api[_-]?key|secret|password|token\s*[:=]|-----BEGIN|raw transcript|verbatim customer|full email)/i;
+const errors = [];
+let pending = 0;
+
+if (proposals.length === 0) errors.push('missing proposals');
+
+for (const [index, block] of proposals.entries()) {
+  const id = block.split('\n', 1)[0].trim() || `#${index + 1}`;
+  for (const field of required) {
+    if (!new RegExp(`^${field}:\\s*\\S`, 'mi').test(block)) {
+      errors.push(`${id}: missing ${field}`);
+    }
+  }
+
+  const status = block.match(/^Status:\s*(.+)$/mi)?.[1]?.trim().toLowerCase();
+  const reviewer = block.match(/^Reviewer:\s*(.+)$/mi)?.[1]?.trim().toLowerCase();
+  const decision = block.match(/^Decision:\s*(.+)$/mi)?.[1]?.trim().toLowerCase();
+
+  if (status === 'proposed') pending += 1;
+  if (status === 'promoted' && (!reviewer || reviewer === 'pending' || !decision || decision === 'pending')) {
+    errors.push(`${id}: promoted proposal needs reviewer and decision`);
+  }
+  if (/(auto-promote|autopromote|self-approved|self approved)/i.test(block)) {
+    errors.push(`${id}: auto-promotion is not allowed`);
+  }
+  if (rawRisk.test(block)) {
+    errors.push(`${id}: possible raw secret/private payload in learning queue`);
+  }
+}
+
+if (errors.length) {
+  console.error(`learning queue failed (${errors.length}):`);
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log(`learning queue ok: ${proposals.length} proposal(s), ${pending} pending review`);

package/examples/controlled-learning-queue/leads/acme-job-card.md

@@ -0,0 +1,12 @@
+# Lead job card: acme
+
+## Goal
+Prepare a qualification summary for a human owner.
+
+## Known facts
+- Source: demo form `lead-acme-2026-06-02`.
+- Interest: AI agent workflows for sales operations.
+- Constraint: no pricing promises without human owner.
+
+## Next safe action
+Draft questions about current workflow, systems of record, and approval boundaries.

package/examples/controlled-learning-queue/learning_queue.md

@@ -0,0 +1,27 @@
+# Learning queue
+
+Agents may propose durable memory updates here. Humans or maintainers promote/reject them.
+
+## Proposal 2026-06-02-001
+
+Status: proposed
+Source: lead-acme-2026-06-02 job card, redacted summary only
+Observed: Prospect asked how to prevent a role-based agent from changing ICP after one edge case.
+Proposed durable change: Add "role-based agents may propose ICP changes, but ICP memory changes require human promote/reject review" to `memory/durable.md`.
+Reason: This is a reusable safety boundary for future lead qualification runs.
+Scope: sales-ops-agent / ICP memory
+Expiry: 2026-07-02
+Reviewer: pending
+Decision: pending
+
+## Proposal 2026-06-02-002
+
+Status: rejected
+Source: lead-beta-2026-06-01 job card, redacted summary only
+Observed: One prospect wanted a custom discount workflow.
+Proposed durable change: Add "discount requests are common" to `memory/durable.md`.
+Reason: Rejected because one request is not enough to change durable market assumptions.
+Scope: sales-ops-agent / pricing assumptions
+Expiry: 2026-06-15
+Reviewer: owner@example.invalid
+Decision: reject; keep as working note only

package/examples/controlled-learning-queue/memory/durable.md

@@ -0,0 +1,10 @@
+# Durable memory
+
+Approved facts only.
+
+## ICP
+- Early-stage teams adopting AI coding agents need lightweight reviewable context, not another opaque memory dump.
+
+## Boundaries
+- Do not store raw customer messages, secrets, or private transcripts.
+- Pricing, legal commitments, and delivery promises require human review.

package/examples/controlled-learning-queue/memory/working-notes.md

@@ -0,0 +1,5 @@
+# Working notes
+
+Temporary notes may live here during an active job. Promote nothing from this file into durable memory without a `learning_queue.md` proposal.
+
+- 2026-06-02 lead-acme: asked about using Skills for sales ops. Needs human review before any pricing language.

package/examples/controlled-learning-queue/role/job-contract.md

@@ -0,0 +1,18 @@
+# Sales ops agent role
+
+## Mission
+Help qualify inbound leads and prepare concise handoff notes for a human owner.
+
+## Allowed
+- Read approved lead/job cards.
+- Draft next-step suggestions.
+- Propose changes to durable memory through `learning_queue.md`.
+
+## Not allowed
+- Promise pricing, discounts, contracts, legal terms, or delivery dates.
+- Rewrite `memory/durable.md` directly.
+- Store raw private email/chat text in durable memory.
+
+## Escalate when
+- A lead asks for legal/financial commitments.
+- A proposed learning would change ICP, pricing assumptions, compliance boundaries, or data-retention rules.

package/examples/controlled-learning-queue/skills/qualify-lead.md

@@ -0,0 +1,17 @@
+# Skill: qualify lead
+
+## Inputs
+- Lead job card path.
+- Current durable memory.
+- Any approved working notes for this lead.
+
+## Output
+- Qualification summary.
+- Open questions.
+- Suggested next action.
+- Optional `learning_queue.md` proposal if the case reveals a reusable durable fact.
+
+## Stop conditions
+- Missing consent or unclear data source.
+- Request requires a human commitment.
+- Proposed durable learning lacks source, scope, or expiry.

package/examples/dynamic-workflow-run-receipts/README.md

@@ -0,0 +1,18 @@
+# Dynamic workflow run receipt example
+
+This example is a copyable privacy-safe receipt for Claude Code-style dynamic workflows, ultracode runs, local LLM gateway orchestration, or any script that spawns several subagents to audit, migrate, research, or verify a codebase.
+
+Use it when the parent session only sees the final report, but reviewers still need to understand:
+
+- which phases ran;
+- how many agents were spawned;
+- which role/model/provider each agent actually used;
+- which context was loaded, skipped, or suppressed;
+- which tools/capabilities were granted and used;
+- how token spend was bucketed;
+- where each agent stopped;
+- which gaps remain before mutation or merge.
+
+The example intentionally uses coarse labels, buckets, and hashes instead of raw prompts, source code, exact paths, transcripts, tool output, secrets, or customer data.
+
+See [`docs/dynamic-workflow-run-receipts.md`](../../docs/dynamic-workflow-run-receipts.md) for the checklist and field rationale.

package/examples/dynamic-workflow-run-receipts/workflow-run-receipt.json

@@ -0,0 +1,112 @@
+{
+  "type": "dynamic.workflow.run_receipt.v1",
+  "workflow": {
+    "workflow_id": "wf_checkout_auth_audit_2026_05_30",
+    "runner": "claude-code-dynamic-workflow",
+    "script_source": "generated-then-reviewed-command",
+    "script_hash": "sha256:example-only",
+    "task_kind": "codebase_auth_audit",
+    "plan_approved_before_run": true,
+    "resumable": true,
+    "max_wall_clock_bucket": "under_15m",
+    "kill_switch_available": true,
+    "started_at": "2026-05-30T15:20:00Z",
+    "completed_at": "2026-05-30T15:31:42Z"
+  },
+  "permissions": {
+    "tool_allowlist_inherited": true,
+    "writes_allowed": false,
+    "network_allowed": false,
+    "external_commands_allowed": ["grep", "test --dry-run"],
+    "permission_profile": "review-only"
+  },
+  "phases": [
+    {
+      "phase_id": "route-inventory",
+      "purpose": "find candidate auth-sensitive routes",
+      "agent_count": 3,
+      "token_spend_bucket": "under_50k",
+      "elapsed_ms_bucket": "under_2m",
+      "result": "completed"
+    },
+    {
+      "phase_id": "adversarial-review",
+      "purpose": "cross-check candidate misses",
+      "agent_count": 2,
+      "token_spend_bucket": "under_25k",
+      "elapsed_ms_bucket": "under_2m",
+      "result": "completed_with_gaps"
+    }
+  ],
+  "agents": [
+    {
+      "agent_id": "agent-route-auditor-1",
+      "phase_id": "route-inventory",
+      "role": "route-auth-auditor",
+      "model": "claude-sonnet",
+      "provider": "anthropic",
+      "context_loaded": ["repo-policy", "auth-boundary-rules", "route-index-summary"],
+      "context_skipped_or_suppressed": [
+        {
+          "source": "customer-fixture-dump",
+          "reason": "contains raw customer data; summary hash only"
+        }
+      ],
+      "tools_granted": ["read", "grep"],
+      "tools_used": ["grep"],
+      "feature_areas_checked": ["checkout routes", "admin routes"],
+      "token_budget_bucket": "under_25k",
+      "token_spend_bucket": "under_10k",
+      "max_iterations": 8,
+      "iterations_used": 3,
+      "heartbeat_seen_at": "2026-05-30T15:25:00Z",
+      "partial_progress_reported": true,
+      "fuse_triggered": false,
+      "stop_reason": "completed_assigned_partition",
+      "confidence": "medium",
+      "known_gaps": ["did not execute integration tests"],
+      "raw_prompt_logged": false,
+      "raw_tool_output_logged": false,
+      "raw_paths_logged": false
+    },
+    {
+      "agent_id": "agent-reviewer-1",
+      "phase_id": "adversarial-review",
+      "role": "adversarial-auth-reviewer",
+      "model": "local-codex-compatible",
+      "provider": "local-llm-gateway",
+      "context_loaded": ["candidate-findings-summary", "public-api-contract-summary"],
+      "context_skipped_or_suppressed": [],
+      "tools_granted": ["read"],
+      "tools_used": ["read"],
+      "feature_areas_checked": ["route findings cross-check"],
+      "token_budget_bucket": "under_10k",
+      "token_spend_bucket": "under_10k",
+      "max_iterations": 5,
+      "iterations_used": 5,
+      "heartbeat_seen_at": "2026-05-30T15:30:00Z",
+      "partial_progress_reported": true,
+      "fuse_triggered": true,
+      "stop_reason": "iteration_budget_reached_before_claim_verified",
+      "confidence": "low",
+      "known_gaps": ["one route requires owner confirmation before merge"],
+      "raw_prompt_logged": false,
+      "raw_tool_output_logged": false,
+      "raw_paths_logged": false
+    }
+  ],
+  "handoff": {
+    "final_result_kind": "workflow_review_receipt",
+    "claims_rejected_or_deferred": 1,
+    "next_safe_action": "ask route owner to confirm checkout callback auth before writing fix",
+    "where_it_stopped": "ambiguous auth boundary before mutation"
+  },
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_source_logged": false,
+    "raw_tool_output_logged": false,
+    "transcripts_logged": false,
+    "secrets_logged": false,
+    "customer_data_logged": false
+  }
+}

package/examples/install-plan-receipts/README.md

@@ -0,0 +1,34 @@
+# Install-plan receipt example
+
+This example is for one-command agent setup tools that configure MCP, Skills, instruction files, hooks, or plugins across multiple AI coding tools.
+
+Use it when you want a setup script to prove what it will write before it writes anything.
+
+## Copyable preflight checklist
+
+Before applying installer changes, ask the agent or setup script to emit an `agent.install.plan.v1` receipt with:
+
+- `agents_detected`
+- `agents_selected`
+- `planned_writes[]` with `kind`, `target`, `operation`, and `backup_planned`
+- `external_commands_planned[]`
+- `network_after_install`
+- `writes_started=false`
+- `next_safe_command`
+
+Review the receipt, then run the apply command only if the planned writes match your intent.
+
+## Smoke test
+
+The sample receipt is intentionally static JSON so it can be inspected without running an installer:
+
+```bash
+cat examples/install-plan-receipts/agent-install-plan-receipt.json
+node -e "const r=require('./examples/install-plan-receipts/agent-install-plan-receipt.json'); if (r.writes_started !== false) process.exit(1); console.log(r.receipt_type, r.planned_writes.length)"
+```
+
+Expected output:
+
+```text
+agent.install.plan.v1 3
+```