pluribus-context 0.3.34 → 0.3.35

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

package/examples/install-plan-receipts/agent-install-plan-receipt.json

@@ -0,0 +1,56 @@
+{
+  "receipt_type": "agent.install.plan.v1",
+  "run_id": "demo-install-2026-05-29T16:00Z",
+  "installer": "example-agent-setup",
+  "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_local_mcp_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_receipt_guard",
+      "backup_planned": true
+    }
+  ],
+  "external_commands_planned": [
+    {
+      "phase": "apply",
+      "command_class": "package_manager_install"
+    }
+  ],
+  "network_after_install": "local_mcp_server_only",
+  "writes_started": false,
+  "next_safe_command": "example-agent-setup apply --from-plan install-plan.json",
+  "privacy_exclusions": [
+    "raw_source",
+    "secrets",
+    "env_dump",
+    "raw_prompt",
+    "transcript",
+    "raw_tool_output",
+    "customer_data",
+    "private_absolute_path"
+  ]
+}

package/examples/review-primitive-gate/README.md

@@ -0,0 +1,19 @@
+# Review primitive gate example
+
+This example validates a privacy-safe agent handoff receipt as a reviewer/CI primitive.
+
+Run the passing fixture:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/review-primitive-gate/pass-review-receipt.json
+```
+
+Run the failing fixture:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/review-primitive-gate/fail-review-receipt.json
+```
+
+The script exits non-zero if the run is partial/unsafe, if a required check failed or was skipped, or if the agent changed scope/access without approval.

package/examples/review-primitive-gate/check-review-receipt.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+
+const [file] = process.argv.slice(2)
+
+if (!file) {
+  console.error('Usage: node check-review-receipt.mjs <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.review_primitive_receipt.v1') {
+  errors.push('type must be agent.review_primitive_receipt.v1')
+}
+
+for (const key of ['assignment_id', 'run_id']) {
+  if (!receipt[key] || typeof receipt[key] !== 'string') {
+    errors.push(`${key} is required`)
+  }
+}
+
+const boundaries = receipt.approved_boundaries || {}
+if (!Array.isArray(boundaries.read) || boundaries.read.length === 0) {
+  errors.push('approved_boundaries.read must name at least one coarse read boundary')
+}
+if (!Array.isArray(boundaries.write)) {
+  errors.push('approved_boundaries.write must be an array, even for read-only runs')
+}
+
+const scopeChanges = receipt.scope_access_changes || []
+if (!Array.isArray(scopeChanges)) {
+  errors.push('scope_access_changes must be an array')
+} else {
+  for (const [index, change] of scopeChanges.entries()) {
+    if (change?.approved !== true) {
+      errors.push(`scope_access_changes[${index}] is not explicitly approved`)
+    }
+  }
+}
+
+const checks = receipt.commands_and_checks || []
+if (!Array.isArray(checks) || checks.length === 0) {
+  errors.push('commands_and_checks must include at least one required check/test')
+} else {
+  for (const [index, check] of checks.entries()) {
+    if (!String(check?.kind || '').startsWith('required_')) continue
+    if (check.status !== 'passed') {
+      errors.push(`commands_and_checks[${index}] required check did not pass: ${check.status || 'missing status'}`)
+    }
+    if (!check.evidence || check.evidence === 'not-run') {
+      errors.push(`commands_and_checks[${index}] required check is missing evidence`)
+    }
+  }
+}
+
+const allowedResumeStates = new Set(['complete', 'partial', 'unsafe-to-resume'])
+if (!allowedResumeStates.has(receipt.resume_state)) {
+  errors.push('resume_state must be complete, partial, or unsafe-to-resume')
+}
+if (receipt.resume_state !== 'complete') {
+  errors.push(`resume_state is ${receipt.resume_state}; reviewer must inspect before merge/continuation`)
+}
+
+const handoff = receipt.handoff || {}
+if (!handoff.next_safe_action || typeof handoff.next_safe_action !== 'string') {
+  errors.push('handoff.next_safe_action is required')
+}
+if (!handoff.evidence_path || typeof handoff.evidence_path !== 'string') {
+  warnings.push('handoff.evidence_path is recommended for review traceability')
+}
+
+const privacy = receipt.privacy || {}
+for (const key of ['raw_prompts_logged', 'raw_tool_output_logged', 'source_code_logged', 'secrets_logged']) {
+  if (privacy[key] !== false) {
+    errors.push(`privacy.${key} must be false for this gate`) 
+  }
+}
+
+const result = {
+  ok: errors.length === 0,
+  file,
+  assignment_id: receipt.assignment_id,
+  run_id: receipt.run_id,
+  resume_state: receipt.resume_state,
+  errors,
+  warnings
+}
+
+console.log(JSON.stringify(result, null, 2))
+process.exit(result.ok ? 0 : 1)

package/examples/review-primitive-gate/fail-review-receipt.json

@@ -0,0 +1,42 @@
+{
+  "type": "agent.review_primitive_receipt.v1",
+  "assignment_id": "agent-auth-audit-43",
+  "run_id": "run-2026-05-31T17-05Z",
+  "agent": {
+    "tool": "claude-code",
+    "role": "auth-reviewer"
+  },
+  "approved_boundaries": {
+    "read": ["src/auth/**", "tests/auth/**"],
+    "write": ["tests/auth/**"],
+    "network": false
+  },
+  "scope_access_changes": [
+    {
+      "change": "write src/auth/session.ts",
+      "reason": "agent decided implementation change was easier than fixture-only test",
+      "approved": false
+    }
+  ],
+  "commands_and_checks": [
+    {
+      "name": "npm test -- tests/auth",
+      "kind": "required_test",
+      "status": "skipped",
+      "evidence": "not-run"
+    }
+  ],
+  "refused_operations": [],
+  "handoff": {
+    "changed_files_bucket": "under_5",
+    "evidence_path": "artifacts/agent-auth-audit-43.json",
+    "next_safe_action": "human must review scope change before any continuation"
+  },
+  "resume_state": "unsafe-to-resume",
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_tool_output_logged": false,
+    "source_code_logged": false,
+    "secrets_logged": false
+  }
+}

package/examples/review-primitive-gate/pass-review-receipt.json

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

package/examples/subagent-role-receipts/README.md

@@ -0,0 +1,15 @@
+# Subagent role receipts example
+
+This directory contains a small `agents.toml` example for teams experimenting with project-local subagent roles.
+
+The important artifact is not the exact TOML dialect. The important artifact is the receipt that proves the role boundary:
+
+- requested role vs effective role;
+- role source and coarse hash/version;
+- whether role instructions loaded;
+- allowed/refused write and tool capabilities;
+- boundary decisions made by the role;
+- where the role stopped and the next safe action;
+- privacy flags excluding raw prompts, code, transcripts, secrets, customer data, and raw tool output.
+
+See [`../../docs/subagent-role-receipts.md`](../../docs/subagent-role-receipts.md) for the full recipe.

package/examples/subagent-role-receipts/agents.toml

@@ -0,0 +1,36 @@
+# Example only: adapt field names and location to the subagent runner you use.
+# The stable idea is the receipt, not this exact TOML dialect.
+
+[[agents]]
+name = "blast-radius-reviewer"
+description = "Reviews AI-generated PRs by operational blast radius before merge."
+model = "default"
+tools = ["read", "grep", "test-summary"]
+writes_allowed = false
+instructions = """
+Review by blast radius, not diff size.
+
+Require explicit evidence for:
+- schema or persisted data contracts;
+- live reader/writer compatibility;
+- async jobs, queues, cron, webhooks, and retries;
+- rollout gates, feature flags, or kill switches;
+- external side effects such as email, payments, auth, billing, analytics, or third-party APIs;
+- generated files, public APIs, plugin manifests, MCP/Skill/hook configuration.
+
+Do not approve merge when any high-risk boundary is ambiguous. Emit a privacy-safe review.blast_radius.v1 or subagent.role_boundary.v1 receipt instead of logging raw source, prompts, transcripts, or tool output.
+"""
+
+[[agents]]
+name = "temporal-authority-checker"
+description = "Checks whether matched docs/specs are current authority or historical citations before edits."
+model = "default"
+tools = ["read", "grep"]
+writes_allowed = false
+instructions = """
+Before code changes, identify the current authority source and any historical/superseded specs.
+
+Refuse writes when two sources conflict and neither one declares status, date, scope, or superseded_by metadata. Emit a privacy-safe context.temporal_authority.v1 or subagent.role_boundary.v1 receipt with coarse document names, status, decision, stopped_at, and next_safe_action.
+
+Do not log raw prompts, source code, private paths, transcripts, secrets, or customer data.
+"""

package/examples/temporal-context-receipts/CURRENT_STATE.md

@@ -0,0 +1,13 @@
+# Current state
+
+## checkout-flow
+
+- status: current
+- as_of: 2026-05-28
+- current authority: this section
+- scope: checkout-flow
+- related historical specs:
+  - `specs/2025-checkout-rewrite.md` — superseded; rationale only
+  - `specs/2026-checkout-risk-notes.md` — current supporting context
+
+Agents may cite superseded specs for rationale, but must not implement from them unless this file explicitly reactivates that behavior.

package/examples/temporal-context-receipts/specs/2025-checkout-rewrite.md

@@ -0,0 +1,10 @@
+---
+status: superseded
+scope: checkout-flow
+date: 2025-11-10
+superseded_by: ../CURRENT_STATE.md#checkout-flow
+---
+
+# 2025 checkout rewrite
+
+Historical note. This file is kept for rationale only and is not implementation authority.

package/examples/temporal-context-receipts/specs/2026-checkout-risk-notes.md

@@ -0,0 +1,10 @@
+---
+status: current
+scope: checkout-flow
+date: 2026-05-20
+superseded_by: null
+---
+
+# 2026 checkout risk notes
+
+Current supporting context for known risk areas. Use together with `CURRENT_STATE.md`.

package/examples/temporal-context-receipts/temporal-authority-receipt.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.34",
+  "version": "0.3.35",
   "description": "AI context and rules sync CLI for Claude.md, Claude Code, Cursor, and Copilot instructions, with privacy-safe context receipts that prove what memory, tools, skills, compactions, and security findings crossed agent boundaries without logging raw content.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.34'
+export const VERSION = '0.3.35'