pluribus-context 0.3.34 → 0.3.36

package/examples/phase-boundary-contract/check-phase-boundary.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+const file = process.argv[2] || 'phase-boundary-contract.json';
+const contract = JSON.parse(fs.readFileSync(file, 'utf8'));
+const errors = [];
+
+const phases = ['explore', 'propose', 'spec', 'design', 'tasks', 'apply', 'verify'];
+const hashRe = /^sha256:[a-f0-9]{64}$/;
+const unsafeRefRe = /(^\/|\.\.|[A-Za-z]:\\|secret|token|password|private_key)/i;
+const requiredGateKeys = ['changed_files', 'tests_run', 'open_risks', 'stop_conditions'];
+
+function expect(condition, message) {
+  if (!condition) errors.push(message);
+}
+
+expect(contract.schema === 'pluribus.phase-boundary-contract.v1', 'schema must be pluribus.phase-boundary-contract.v1');
+expect(typeof contract.workflowId === 'string' && contract.workflowId.length >= 6, 'workflowId is required');
+expect(phases.includes(contract.currentPhase), 'currentPhase must be a known phase');
+expect(phases.includes(contract.nextPhase), 'nextPhase must be a known phase');
+expect(contract.currentPhase !== contract.nextPhase, 'currentPhase and nextPhase must differ');
+
+expect(Array.isArray(contract.allowedInput) && contract.allowedInput.length > 0, 'allowedInput must list at least one source');
+for (const [index, input] of (contract.allowedInput || []).entries()) {
+  expect(typeof input.kind === 'string' && input.kind.length > 0, `allowedInput[${index}].kind is required`);
+  expect(typeof input.ref === 'string' && !unsafeRefRe.test(input.ref), `allowedInput[${index}].ref must be a non-secret relative/logical ref`);
+  expect(hashRe.test(input.contentHash || ''), `allowedInput[${index}].contentHash must be sha256:<64 hex>`);
+}
+
+expect(contract.outputArtifact && typeof contract.outputArtifact.kind === 'string', 'outputArtifact.kind is required');
+expect(contract.outputArtifact && typeof contract.outputArtifact.ref === 'string' && !unsafeRefRe.test(contract.outputArtifact.ref), 'outputArtifact.ref must be a non-secret logical ref');
+expect(contract.outputArtifact && hashRe.test(contract.outputArtifact.contentHash || ''), 'outputArtifact.contentHash must be sha256:<64 hex>');
+
+const gate = contract.evidenceGate || {};
+expect(gate.status === 'pass' || gate.status === 'needs_review' || gate.status === 'fail', 'evidenceGate.status must be pass, needs_review, or fail');
+expect(Array.isArray(gate.requiredBeforeNextPhase), 'evidenceGate.requiredBeforeNextPhase must be an array');
+for (const key of requiredGateKeys) {
+  expect((gate.requiredBeforeNextPhase || []).includes(key), `evidenceGate.requiredBeforeNextPhase must include ${key}`);
+}
+expect(gate.changedFiles && Number.isInteger(gate.changedFiles.count) && gate.changedFiles.count >= 0, 'evidenceGate.changedFiles.count is required');
+expect(gate.changedFiles && hashRe.test(gate.changedFiles.fileSetHash || ''), 'evidenceGate.changedFiles.fileSetHash must be sha256:<64 hex>');
+expect(Array.isArray(gate.testsRun), 'evidenceGate.testsRun must be an array');
+for (const [index, test] of (gate.testsRun || []).entries()) {
+  expect(typeof test.name === 'string' && test.name.length > 0, `testsRun[${index}].name is required`);
+  expect(hashRe.test(test.commandHash || ''), `testsRun[${index}].commandHash must be sha256:<64 hex>`);
+  expect(['pass', 'fail', 'skipped'].includes(test.status), `testsRun[${index}].status must be pass/fail/skipped`);
+}
+expect(Array.isArray(gate.openRisks), 'evidenceGate.openRisks must be an array');
+for (const [index, risk] of (gate.openRisks || []).entries()) {
+  expect(typeof risk.riskClass === 'string' && risk.riskClass.length > 0, `openRisks[${index}].riskClass is required`);
+  expect(['low', 'medium', 'high'].includes(risk.severity), `openRisks[${index}].severity must be low/medium/high`);
+  expect(typeof risk.safeToContinue === 'boolean', `openRisks[${index}].safeToContinue must be boolean`);
+}
+
+expect(Array.isArray(contract.droppedContext), 'droppedContext must be an array');
+for (const [index, dropped] of (contract.droppedContext || []).entries()) {
+  expect(typeof dropped.kind === 'string' && dropped.kind.length > 0, `droppedContext[${index}].kind is required`);
+  expect(typeof dropped.reason === 'string' && dropped.reason.length > 0, `droppedContext[${index}].reason is required`);
+}
+expect(Array.isArray(contract.stopConditions), 'stopConditions must be an array');
+
+if (gate.status === 'pass') {
+  expect((contract.stopConditions || []).length === 0, 'pass contracts must not have active stopConditions');
+  expect((gate.openRisks || []).every((risk) => risk.safeToContinue), 'pass contracts require all open risks to be safeToContinue');
+}
+
+if (errors.length) {
+  console.error(`phase-boundary contract failed (${errors.length}):`);
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log(`phase-boundary contract ok: ${contract.workflowId} ${contract.currentPhase}->${contract.nextPhase}`);

package/examples/phase-boundary-contract/phase-boundary-contract.json

@@ -0,0 +1,68 @@
+{
+  "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:0b70d75d6c8f0e54c74e1d7ea90e7c7b3d83e15dd3a3f7b4b9e9e73339d2b22e",
+      "required": true
+    },
+    {
+      "kind": "task_list",
+      "ref": "tasks/checkout-refactor.md#apply",
+      "contentHash": "sha256:63ccf4555f0adbe64bbff5a8f7c4b24708fdb2b5e4d0e417a5cb057b9ed39a76",
+      "required": true
+    }
+  ],
+  "outputArtifact": {
+    "kind": "patch",
+    "ref": "git:working-tree",
+    "contentHash": "sha256:3f9d6216dc7dcb53e6f29ad23433de97f0c172be6a6f46d574aa67e0edfd0789"
+  },
+  "evidenceGate": {
+    "requiredBeforeNextPhase": [
+      "changed_files",
+      "tests_run",
+      "open_risks",
+      "stop_conditions"
+    ],
+    "status": "pass",
+    "changedFiles": {
+      "count": 4,
+      "fileSetHash": "sha256:5f6c8b62349d527cd2e24c6913b8c5f0af8775be1a836bf942853c39efc11f91"
+    },
+    "testsRun": [
+      {
+        "name": "unit-tests",
+        "commandHash": "sha256:1f2cc9d3f4ce8cb118198c7da4d6951de2f21485af126eb1a0fe5f1d7e0139de",
+        "status": "pass"
+      },
+      {
+        "name": "typecheck",
+        "commandHash": "sha256:54d29f16fd215f74b4c03da61e37e71918f2e5c8db454a76f5f582b76471cb13",
+        "status": "pass"
+      }
+    ],
+    "openRisks": [
+      {
+        "riskClass": "manual_browser_flow_not_verified",
+        "severity": "medium",
+        "safeToContinue": true
+      }
+    ]
+  },
+  "droppedContext": [
+    {
+      "kind": "exploration_transcript",
+      "reason": "not authoritative after approved plan"
+    },
+    {
+      "kind": "rejected_design_option",
+      "reason": "kept as citation only; not input to verify phase"
+    }
+  ],
+  "stopConditions": []
+}

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/skill-install-receipts/README.md

@@ -0,0 +1,31 @@
+# Skill install/load receipt example
+
+This example is for setup tools that install Skills across multiple agents and then need to prove whether each target can discover/load the installed resource before the first real session.
+
+It complements:
+
+- `examples/install-plan-receipts/` — pre-write plan proof (`writes_started=false`);
+- `examples/loaded-resource-boundary/` — runtime proof that an existing resource crossed discovery/attachment/injection/readability stages.
+
+## 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
+```
+
+## Review checklist
+
+A useful receipt should answer:
+
+- What installer/source ref was used, without credentials?
+- Which agent targets and scopes were touched?
+- Which targets were installed, skipped, discovered, deferred, injected, or readable?
+- Was any required target unsafe before the first session?
+- Did the receipt avoid raw skill bodies, prompts, transcripts, env dumps, secrets, and private paths?

package/examples/skill-install-receipts/check-skill-install-receipt.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+const file = process.argv[2] || new URL('./skill-install-receipt.json', import.meta.url);
+const receipt = JSON.parse(fs.readFileSync(file, 'utf8'));
+
+const allowedInstall = new Set(['installed', 'skipped', 'failed']);
+const allowedDiscovery = new Set(['discovered', 'not_discovered', 'not_tested', 'failed']);
+const allowedLoad = new Set(['injected', 'readable', 'activation_required', 'deferred', 'not_tested', 'failed']);
+const allowedCost = new Set(['0-1k', '1k-5k', '5k-20k', 'over_budget', 'unknown']);
+const requiredPrivacy = [
+  'raw_skill_body',
+  'raw_prompt',
+  'transcript',
+  'secrets',
+  'env_dump',
+  'private_absolute_path'
+];
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+assert(receipt.receipt_type === 'agent.skill_install_receipt.v1', 'unexpected receipt_type');
+assert(receipt.run_id, 'missing run_id');
+assert(receipt.installer?.name, 'missing installer.name');
+assert(receipt.installer?.source?.kind, 'missing installer.source.kind');
+assert(receipt.installer?.source?.ref, 'missing installer.source.ref');
+assert(receipt.installer.source.credentials_in_ref === false, 'source ref must not carry credentials');
+assert(Array.isArray(receipt.targets) && receipt.targets.length > 0, 'targets must be a non-empty array');
+assert(Array.isArray(receipt.privacy_exclusions), 'missing privacy_exclusions');
+
+for (const item of requiredPrivacy) {
+  assert(receipt.privacy_exclusions.includes(item), `privacy_exclusions must include ${item}`);
+}
+
+let computedOverallSafe = true;
+for (const [index, target] of receipt.targets.entries()) {
+  assert(target.agent, `targets[${index}].agent missing`);
+  assert(['project', 'global', 'workspace', 'unknown'].includes(target.scope), `targets[${index}].scope invalid`);
+  assert(typeof target.required === 'boolean', `targets[${index}].required must be boolean`);
+  assert(allowedInstall.has(target.install_status), `targets[${index}].install_status invalid`);
+  assert(allowedDiscovery.has(target.discovery_status), `targets[${index}].discovery_status invalid`);
+  assert(allowedLoad.has(target.load_status), `targets[${index}].load_status invalid`);
+  assert(allowedCost.has(target.context_cost_bucket), `targets[${index}].context_cost_bucket invalid`);
+  assert(typeof target.safe_to_start_session === 'boolean', `targets[${index}].safe_to_start_session must be boolean`);
+
+  if (target.evidence) {
+    assert(target.evidence.raw_body_logged === false, `targets[${index}] must not log raw skill body`);
+  }
+
+  const requiredTargetUnsafe = target.required && (
+    target.install_status !== 'installed' ||
+    target.discovery_status !== 'discovered' ||
+    target.load_status === 'failed' ||
+    target.load_status === 'not_tested' ||
+    target.context_cost_bucket === 'over_budget' ||
+    target.safe_to_start_session !== true
+  );
+
+  if (requiredTargetUnsafe) {
+    computedOverallSafe = false;
+  }
+}
+
+assert(receipt.overall_safe_to_start_session === computedOverallSafe, 'overall_safe_to_start_session does not match required target safety');
+
+const serialized = JSON.stringify(receipt).toLowerCase();
+for (const forbidden of ['private_key', 'api_key=', 'ghp_', 'github_pat_', 'npm_', 'bearer ']) {
+  assert(!serialized.includes(forbidden), `receipt appears to include secret marker: ${forbidden}`);
+}
+
+console.log(`skill install receipt ok: ${receipt.targets.length} targets checked`);

package/examples/skill-install-receipts/skill-install-receipt.json

@@ -0,0 +1,79 @@
+{
+  "receipt_type": "agent.skill_install_receipt.v1",
+  "run_id": "skill-install-demo-2026-06-04T13:00Z",
+  "installer": {
+    "name": "skills-cli",
+    "version_bucket": "0.x",
+    "command_class": "skill_package_install",
+    "source": {
+      "kind": "git_ref",
+      "package": "vercel-labs/skills/context-budget-preflight",
+      "ref": "sha256:demo-source-package-hash",
+      "credentials_in_ref": false
+    }
+  },
+  "mode_requested": "install_then_check",
+  "mode_effective": "post_install_check",
+  "writes_completed": true,
+  "backup_created": 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,
+      "evidence": {
+        "manifest_hash": "sha256:demo-claude-manifest-hash",
+        "skill_body_hash": "sha256:demo-claude-skill-body-hash",
+        "raw_body_logged": false
+      }
+    },
+    {
+      "agent": "codex",
+      "scope": "project",
+      "required": true,
+      "install_status": "installed",
+      "discovery_status": "discovered",
+      "load_status": "deferred",
+      "activation": "manual_or_triggered",
+      "context_cost_bucket": "0-1k",
+      "safe_to_start_session": true,
+      "evidence": {
+        "manifest_hash": "sha256:demo-codex-manifest-hash",
+        "skill_body_hash": "sha256:demo-codex-skill-body-hash",
+        "raw_body_logged": false
+      }
+    },
+    {
+      "agent": "zed-acp",
+      "scope": "project",
+      "required": false,
+      "install_status": "skipped",
+      "discovery_status": "not_tested",
+      "load_status": "not_tested",
+      "activation": "unsupported_target_in_this_installer",
+      "context_cost_bucket": "unknown",
+      "safe_to_start_session": true,
+      "skipped_reason": "target_not_selected"
+    }
+  ],
+  "overall_safe_to_start_session": true,
+  "next_safe_command": "start a disposable agent session and ask it to cite the installed Skill sentinel line",
+  "privacy_exclusions": [
+    "raw_skill_body",
+    "raw_source",
+    "raw_prompt",
+    "transcript",
+    "raw_tool_output",
+    "customer_data",
+    "secrets",
+    "env_dump",
+    "private_absolute_path"
+  ],
+  "audit_gap": "proves installer/discovery/load boundary, not skill semantic quality or future activation"
+}

package/examples/skill-use-rate-receipts/README.md

@@ -0,0 +1,16 @@
+# Skill use-rate receipts
+
+This example shows a privacy-safe receipt for the gap between installing an Agent Skill and actually using it.
+
+```bash
+node check-skill-use-rate.mjs skill-use-rate-receipt.json
+```
+
+Expected output:
+
+```text
+skill use-rate receipt ok: 3 skills checked, 1 unused install warning
+- rust-lsp-helper is installed/attached but has 0 invocations in this window
+```
+
+The warning is intentional: installation is not adoption. A skill can be installed, attached, and discoverable while still adding context surface area with no observed invocation.

package/examples/skill-use-rate-receipts/check-skill-use-rate.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+
+const receiptPath = process.argv[2] || path.join(import.meta.dirname, 'skill-use-rate-receipt.json')
+const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
+const errors = []
+const warnings = []
+
+function requireString(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    errors.push(`${field} must be a non-empty string`)
+  }
+}
+
+function requireBoolean(value, field) {
+  if (typeof value !== 'boolean') {
+    errors.push(`${field} must be boolean`)
+  }
+}
+
+function requireNonNegativeInteger(value, field) {
+  if (!Number.isInteger(value) || value < 0) {
+    errors.push(`${field} must be a non-negative integer`)
+  }
+}
+
+if (receipt.schema !== 'pluribus.skill_use_rate_receipt.v1') {
+  errors.push('schema must be pluribus.skill_use_rate_receipt.v1')
+}
+
+requireString(receipt.run_id, 'run_id')
+requireString(receipt.generated_at, 'generated_at')
+requireString(receipt.installer?.name, 'installer.name')
+requireString(receipt.window?.started_at, 'window.started_at')
+requireString(receipt.window?.ended_at, 'window.ended_at')
+
+if (!Array.isArray(receipt.skills) || receipt.skills.length === 0) {
+  errors.push('skills must be a non-empty array')
+}
+
+for (const [index, skill] of (receipt.skills || []).entries()) {
+  const prefix = `skills[${index}]`
+  requireString(skill.skill_id, `${prefix}.skill_id`)
+  requireString(skill.source_ref, `${prefix}.source_ref`)
+  requireString(skill.target_agent, `${prefix}.target_agent`)
+  requireString(skill.scope, `${prefix}.scope`)
+  requireString(skill.install_method, `${prefix}.install_method`)
+  requireBoolean(skill.discovered, `${prefix}.discovered`)
+  requireBoolean(skill.installed, `${prefix}.installed`)
+  requireBoolean(skill.attached, `${prefix}.attached`)
+  requireBoolean(skill.unused_since_install, `${prefix}.unused_since_install`)
+  requireNonNegativeInteger(skill.invoked_count, `${prefix}.invoked_count`)
+  requireNonNegativeInteger(skill.acted_on_count, `${prefix}.acted_on_count`)
+
+  if (Number.isInteger(skill.acted_on_count) && Number.isInteger(skill.invoked_count) && skill.acted_on_count > skill.invoked_count) {
+    errors.push(`${prefix}.acted_on_count cannot exceed invoked_count`)
+  }
+
+  if (skill.installed && skill.attached && skill.invoked_count === 0) {
+    if (skill.unused_since_install !== true) {
+      errors.push(`${prefix}.unused_since_install must be true when installed/attached but never invoked`)
+    }
+    warnings.push(`${skill.skill_id || prefix} is installed/attached but has 0 invocations in this window`)
+  }
+
+  if (skill.invoked_count > 0) {
+    if (skill.unused_since_install !== false) {
+      errors.push(`${prefix}.unused_since_install must be false when invoked_count > 0`)
+    }
+    if (typeof skill.last_invoked_at !== 'string' || skill.last_invoked_at.trim() === '') {
+      errors.push(`${prefix}.last_invoked_at must be set when invoked_count > 0`)
+    }
+  }
+
+  if (!Array.isArray(skill.evidence) || skill.evidence.length === 0) {
+    errors.push(`${prefix}.evidence must include at least one privacy-safe evidence ref`)
+  }
+}
+
+if (errors.length > 0) {
+  console.error('skill use-rate receipt invalid:')
+  for (const error of errors) console.error(`- ${error}`)
+  process.exit(1)
+}
+
+const warningLabel = warnings.length === 1 ? 'warning' : 'warnings'
+console.log(`skill use-rate receipt ok: ${receipt.skills.length} skills checked, ${warnings.length} unused install ${warningLabel}`)
+for (const warning of warnings) console.log(`- ${warning}`)