npm - pluribus-context - Versions diffs - 0.3.40 → 0.3.42 - Mend

pluribus-context 0.3.40 → 0.3.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

package/docs/cursor-claude-context-handoff.md CHANGED Viewed

@@ -90,6 +90,74 @@ I am building Acme Billing, a TypeScript service used by finance operators.
 4. **Audit:** run `pluribus audit` locally or in CI to catch drift when someone edits generated files directly.
 5. **Use memory separately:** if you also run an MCP memory server, keep the recall/store protocol in `pluribus.md` and let the memory server store durable facts.
+## What usually breaks first
+When developers switch seriously between Cursor, Claude Code, Codex/Copilot-style tools, Windsurf, and terminal agents, the failure is rarely “there is no context anywhere.” It is usually one of these smaller breaks:
+| Break | Symptom | Fast check |
+| --- | --- | --- |
+| Source file stale | `AGENTS.md`, `CLAUDE.md`, or `.cursorrules` still describes old paths, commands, or architecture | Run `pluribus audit`; compare generated output to the committed `pluribus.md` source |
+| Tool-specific layer diverged | Cursor rules say one convention, Claude/Codex instructions say another | Keep tool-specific files generated/thin; review manual edits as drift |
+| Memory became authority | An MCP memory/Obsidian/Notion note overrides the current repo state | Put memory recall/store policy in `pluribus.md`; require code/tests/current docs to win over recalled facts |
+| Commands or paths changed | The agent follows a dead build/test command copied from an older chat | Keep commands in `package.json`, `Makefile`, `justfile`, or scripts; link to them from context instead of duplicating shell snippets |
+| Context was never loaded | The right file exists, but the active tool/session did not read it | Ask for a short handoff receipt before edits: which source file, generated target, memory recall, and test command were actually used |
+## Copyable handoff receipt
+Use this as a lightweight debugging note before a risky cross-tool handoff. It is intentionally privacy-safe: hashes, paths, and decisions instead of raw prompt transcripts or private source content.
+```json
+{
+  "handoff_id": "cursor-to-claude-2026-06-16-001",
+  "from_tool": "cursor",
+  "to_tool": "claude-code",
+  "repo_ref": {
+    "branch": "main",
+    "head_sha": "abc1234"
+  },
+  "source_of_truth": {
+    "path": "pluribus.md",
+    "sha256": "hash-of-current-project-context",
+    "validated_at": "2026-06-16T00:00:00Z"
+  },
+  "generated_context": [
+    {
+      "tool": "cursor",
+      "path": ".cursorrules",
+      "status": "in_sync"
+    },
+    {
+      "tool": "claude-code",
+      "path": "CLAUDE.md",
+      "status": "in_sync"
+    },
+    {
+      "tool": "openclaw-or-codex-style-agent",
+      "path": "AGENTS.md",
+      "status": "in_sync"
+    }
+  ],
+  "memory_policy": {
+    "mcp_memory_allowed": true,
+    "current_repo_overrides_memory": true,
+    "store_new_facts_without_review": false
+  },
+  "active_task": {
+    "summary": "Implement the smallest safe patch for issue #123",
+    "allowed_paths": ["src/billing/**", "tests/billing/**"],
+    "required_checks": ["npm test -- billing"]
+  },
+  "loaded_evidence": {
+    "agent_says_it_read": ["CLAUDE.md", "package.json"],
+    "missing_or_deferred": ["old Obsidian architecture note"],
+    "stale_conflicts_found": []
+  },
+  "safe_to_continue": true
+}
+```
+The receipt should be boring. If it shows stale conflicts, missing generated files, or memory overriding current repo state, stop and fix the source of truth before asking another agent to write code.
 ## What this deliberately does not solve
 - It does not move active chat state from Cursor to Claude Code.

package/docs/index.html ADDED Viewed

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Pluribus Context Receipts</title>
+  <style>
+    :root { color-scheme: dark light; --bg:#0b1020; --card:#121a33; --text:#e8ecf8; --muted:#aab4cf; --accent:#8ee6c4; --border:#283454; }
+    body { margin:0; font:16px/1.55 system-ui,-apple-system,Segoe UI,sans-serif; background:var(--bg); color:var(--text); }
+    main { max-width:880px; margin:0 auto; padding:56px 20px; }
+    a { color:var(--accent); }
+    .card { background:var(--card); border:1px solid var(--border); border-radius:18px; padding:24px; margin:20px 0; }
+    code { background:#060a15; padding:.15rem .35rem; border-radius:6px; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Pluribus Context Receipts</h1>
+    <p>Privacy-safe evidence for AI context boundaries: what crossed into the agent, what stayed out, and what should stop before edits or tool calls.</p>
+    <div class="card">
+      <h2>Browser playground</h2>
+      <p>Try receipt validation without installing anything or sending data to a server. Current samples cover MCP tool-surface diffs, retrieved-context attention, CLAUDE.md rule-attention drift, skill install provenance, and retrieval adoption evidence. If you are debugging MCP context bloat before startup, use the <a href="https://github.com/caioribeiroclw-pixel/pluribus/tree/main/examples/task-scoped-mcp-config">task-scoped MCP config receipt demo</a>. If a Skill or paste-cleaning CLI claims token savings, use the <a href="https://github.com/caioribeiroclw-pixel/pluribus/tree/main/examples/semantic-anchor-receipts">semantic anchor preservation receipt demo</a> to prove it kept version/API/security anchors. If a Cursor/Claude Code workflow requires a first tool or pre-tool hook before edits, use the <a href="session-preflight-receipts.md">session preflight receipt</a> and <a href="https://github.com/caioribeiroclw-pixel/pluribus/tree/main/examples/session-preflight-receipts">copyable rule/example</a>.</p>
+      <p><a href="receipt-playground.html">Open the receipt playground →</a></p>
+    </div>
+    <div class="card">
+      <h2>CLI quick checks</h2>
+      <p><code>npx --yes pluribus-context@latest demo tool-surface-diff --json</code></p>
+      <p><code>npx --yes pluribus-context@latest validate</code></p>
+    </div>
+    <div class="card">
+      <h2>Agent Skills discovery</h2>
+      <p>Pluribus publishes a well-known Agent Skills index so compatible clients can discover the low-authority <code>context-receipts</code> and <code>skill-policy-receipts</code> skills without scraping GitHub.</p>
+      <p><a href=".well-known/agent-skills/index.json">Open <code>/.well-known/agent-skills/index.json</code> →</a></p>
+    </div>
+    <p><a href="https://github.com/caioribeiroclw-pixel/pluribus">GitHub repo</a> · <a href="https://www.npmjs.com/package/pluribus-context">npm package</a></p>
+  </main>
+</body>
+</html>

package/docs/receipt-playground.html ADDED Viewed

@@ -0,0 +1,304 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Pluribus Receipt Playground</title>
+  <style>
+    :root { color-scheme: dark light; --bg:#0b1020; --card:#121a33; --text:#e8ecf8; --muted:#aab4cf; --accent:#8ee6c4; --bad:#ff8f9c; --warn:#ffd166; --ok:#8ee6c4; --border:#283454; }
+    * { box-sizing:border-box; }
+    body { margin:0; font:15px/1.5 system-ui,-apple-system,Segoe UI,sans-serif; background:linear-gradient(180deg,#0b1020,#10182e); color:var(--text); }
+    main { max-width:1120px; margin:0 auto; padding:34px 18px 48px; }
+    h1 { font-size:clamp(2rem,4vw,3.4rem); line-height:1.05; margin:.2rem 0 1rem; letter-spacing:-.04em; }
+    h2 { margin-top:0; }
+    p, li { color:var(--muted); }
+    a { color:var(--accent); }
+    .grid { display:grid; grid-template-columns:1fr; gap:16px; }
+    @media (min-width:900px) { .grid { grid-template-columns:1.1fr .9fr; } }
+    .card { background:rgba(18,26,51,.92); border:1px solid var(--border); border-radius:18px; padding:18px; box-shadow:0 20px 80px rgba(0,0,0,.24); }
+    textarea { width:100%; min-height:560px; resize:vertical; border:1px solid var(--border); border-radius:14px; padding:14px; background:#060a15; color:#e8ecf8; font:13px/1.45 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+    button, select { border:1px solid var(--border); border-radius:999px; background:#182344; color:var(--text); padding:10px 14px; cursor:pointer; }
+    button:hover, select:hover { border-color:var(--accent); }
+    .controls { display:flex; flex-wrap:wrap; gap:10px; align-items:center; margin:0 0 12px; }
+    .result { white-space:pre-wrap; overflow:auto; border-radius:14px; padding:14px; background:#060a15; border:1px solid var(--border); min-height:210px; font:13px/1.45 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+    .ok { color:var(--ok); }
+    .bad { color:var(--bad); }
+    .warn { color:var(--warn); }
+    .pill { display:inline-block; border:1px solid var(--border); border-radius:999px; padding:.2rem .55rem; color:var(--muted); margin:.1rem .2rem .1rem 0; }
+    code { background:#060a15; padding:.12rem .32rem; border-radius:6px; color:#d7e2ff; }
+  </style>
+</head>
+<body>
+  <main>
+    <p><a href="index.html">← Pluribus</a></p>
+    <h1>Receipt playground</h1>
+    <p>Paste a Pluribus receipt and validate the boundary evidence locally in your browser. No network calls, no raw prompts/results required.</p>
+    <div class="grid">
+      <section class="card">
+        <div class="controls">
+          <select id="sample">
+            <option value="toolSurface">Sample: MCP tool-surface diff</option>
+            <option value="attentionPass">Sample: context attention pass</option>
+            <option value="attentionFail">Sample: context attention fail</option>
+            <option value="ruleAttention">Sample: CLAUDE.md rule attention drift</option>
+            <option value="skillInstall">Sample: Agent Skill install provenance</option>
+            <option value="retrievalAdoption">Sample: retrieval adoption receipt</option>
+          </select>
+          <button id="load">Load sample</button>
+          <button id="validate">Validate</button>
+        </div>
+        <textarea id="receipt" spellcheck="false"></textarea>
+      </section>
+      <aside class="card">
+        <h2>Validation result</h2>
+        <div id="result" class="result">Click Validate.</div>
+        <h2>What this checks</h2>
+        <p><span class="pill">tool-surface diff</span> proves runtime discovery changes without logging raw schemas/prompts/results.</p>
+        <p><span class="pill">context attention</span> proves required retrieved context was delivered, acknowledged, and cited before edits.</p>
+        <p><span class="pill">rule attention</span> shows whether project rules were re-read, cited in the pre-edit plan, and checked before changes.</p>
+        <p><span class="pill">skill install provenance</span> shows which <code>SKILL.md</code> source path won, which mirrors were ignored, and whether install metadata stayed content-safe.</p>
+        <p><span class="pill">retrieval adoption</span> shows whether an available graph/RAG tool was actually used before claims, not just configured.</p>
+        <h2>CLI equivalent</h2>
+        <p><code>npx --yes pluribus-context@latest demo tool-surface-diff --json</code></p>
+      </aside>
+    </div>
+  </main>
+  <script>
+    const samples = {
+      toolSurface: {
+        schema: 'pluribus.mcp_tool_surface_diff_receipt.v1',
+        run_id: 'tool-surface-diff-demo',
+        generated_at: '2026-06-09T13:00:00Z',
+        platform: { name: 'enterprise-mcp-dynamic-discovery', audit_sink: 'admin-center-or-siem' },
+        catalog: { server_id: 'mcp://sales-ops-gateway', previous_hash: 'sha256:previous-catalog-redacted', current_hash: 'sha256:current-catalog-redacted' },
+        runtime_discovery: { enabled: true, trigger: 'runtime_tool_catalog_diff' },
+        privacy_boundary: { raw_schemas: 'omitted_hash_only', raw_prompts: 'omitted', raw_results: 'omitted' },
+        tools: [
+          { tool_id: 'tool:crm.search_accounts', name_hash: 'sha256:0cc2...', schema_hash: 'sha256:6f4f...', status: 'activated', validation_outcome: 'accepted', diff_summary: { added_fields: 1, removed_fields: 0, changed_fields: 0 } },
+          { tool_id: 'tool:crm.export_contacts', name_hash: 'sha256:f38f...', schema_hash: 'sha256:95dd...', status: 'blocked', validation_outcome: 'blocked_by_rai', diff_summary: { added_fields: 4, removed_fields: 0, changed_fields: 2 } },
+          { tool_id: 'tool:billing.refund_invoice', name_hash: 'sha256:abfd...', schema_hash: 'sha256:3b4f...', status: 'withheld', validation_outcome: 'entitlement_filtered', diff_summary: { added_fields: 0, removed_fields: 0, changed_fields: 0 } }
+        ]
+      },
+      attentionPass: {
+        schema: 'pluribus.context_attention_receipt.v1', receipt_id: 'attn_demo_pass', task_id: 'claude-code-refactor-184', agent_surface: 'claude_code', retrieval_system: 'graph_memory_mcp',
+        required_context: [{ id: 'ctx:architecture:tenant-routing' }, { id: 'ctx:decision:readonly-audit-first' }],
+        delivery: { surface: 'mcp_tool_response', delivered_context_ids: ['ctx:architecture:tenant-routing', 'ctx:decision:readonly-audit-first'], raw_context_omitted: true, evidence_path: '.pluribus/receipts/context-attention.ndjson' },
+        attention: { acknowledged_before_plan: ['ctx:architecture:tenant-routing', 'ctx:decision:readonly-audit-first'], cited_in_plan: ['ctx:architecture:tenant-routing', 'ctx:decision:readonly-audit-first'], missing_context_stop: false },
+        privacy: { raw_prompts_omitted: true, raw_documents_omitted: true, source_code_omitted: true, tool_outputs_omitted: true, tokens_omitted: true, customer_data_omitted: true },
+        result: { status: 'safe_to_continue', next_safe_action: 'continue with dry-run refactor plan' }
+      },
+      attentionFail: {
+        schema: 'pluribus.context_attention_receipt.v1', receipt_id: 'attn_demo_fail', task_id: 'claude-code-refactor-185', agent_surface: 'claude_code', retrieval_system: 'graph_memory_mcp',
+        required_context: [{ id: 'ctx:architecture:tenant-routing' }, { id: 'ctx:decision:readonly-audit-first' }],
+        delivery: { surface: 'mcp_tool_response', delivered_context_ids: ['ctx:architecture:tenant-routing', 'ctx:decision:readonly-audit-first'], raw_context_omitted: true, evidence_path: '.pluribus/receipts/context-attention.ndjson' },
+        attention: { acknowledged_before_plan: ['ctx:architecture:tenant-routing'], cited_in_plan: [], missing_context_stop: false },
+        privacy: { raw_prompts_omitted: true, raw_documents_omitted: true, source_code_omitted: true, tool_outputs_omitted: true, tokens_omitted: true, customer_data_omitted: true },
+        result: { status: 'unsafe_to_continue', next_safe_action: 'stop and re-deliver required context before editing' }
+      },
+      ruleAttention: {
+        schema: 'pluribus.claude_code_rule_attention_receipt.v1',
+        receipt_id: 'rule_attn_demo_62087',
+        task_id: 'claude-code-long-session-62087',
+        agent_surface: 'claude_code',
+        context_boundary: { session_phase: 'post-compaction-long-session', before_first_edit: true },
+        rules: [
+          { rule_id: 'CLAUDE.md:test-after-plan', source: 'CLAUDE.md#workflow', last_loaded_at: '2026-06-09T22:41:00Z', last_referenced_at: null, cited_in_pre_edit_plan: false, edit_check: 'missing', violation_category: 'loaded_but_not_referenced' },
+          { rule_id: 'CLAUDE.md:no-skip-steps', source: 'CLAUDE.md#workflow', last_loaded_at: '2026-06-09T22:41:00Z', last_referenced_at: '2026-06-09T22:58:00Z', cited_in_pre_edit_plan: true, edit_check: 'pass', violation_category: null }
+        ],
+        privacy: { raw_prompts_omitted: true, raw_claude_md_omitted: true, source_code_omitted: true, tool_outputs_omitted: true, tokens_omitted: true, customer_data_omitted: true },
+        result: { status: 'unsafe_to_edit', next_safe_action: 'stop, re-read missing rule ids, and restate the pre-edit plan with citations' }
+      },
+      retrievalAdoption: {
+        schema: 'pluribus.retrieval_adoption_receipt.v1',
+        receipt_id: 'retrieval_adoption_graph_demo',
+        task_id: 'medusa-code-audit-graph-usage',
+        agent_surface: 'claude_code',
+        retrieval_surface: { kind: 'knowledge_graph_mcp', name: 'project-graph', available: true, forced: false },
+        claim: { expected_use: 'graph_retrieval_before_code_audit', evaluation_window: 'before_final_audit_claims' },
+        availability_evidence: {
+          tool_catalog_contains: ['graph.search', 'graph.neighbors', 'graph.explain_path'],
+          graph_index: { nodes: 3863, edges: 11204, snapshot_hash: 'sha256:graph-snapshot-redacted' },
+          raw_graph_omitted: true
+        },
+        adoption_evidence: {
+          retrieval_calls: [],
+          native_escape_hatch_calls: [
+            { kind: 'grep', count: 14 },
+            { kind: 'read_file', count: 39 }
+          ],
+          cited_retrieved_context_ids: [],
+          graph_grounded_findings: 0,
+          raw_tool_outputs_omitted: true
+        },
+        boundary_checks: {
+          retrieval_available_but_unused: true,
+          required_retrieval_gate_present: false,
+          no_retrieval_claim_allowed: true
+        },
+        privacy: { raw_prompts_omitted: true, raw_graph_nodes_omitted: true, source_code_omitted: true, tool_outputs_omitted: true, customer_data_omitted: true },
+        result: { status: 'availability_not_adoption', next_safe_action: 'treat graph/RAG as unadopted unless a gate requires or verifies retrieval before final claims' }
+      },
+      skillInstall: {
+        schema: 'pluribus.agent_skill_install_provenance_receipt.v1',
+        receipt_id: 'skill_install_openskills_demo',
+        installer: { name: 'agent-skill-package-manager', mode: 'universal', target_agent_dir: '.agent/skills' },
+        source: { kind: 'github_repo', repo: 'caioribeiroclw-pixel/pluribus', requested_ref: 'v0.3.40', resolved_sha: 'sha256:resolved-commit-redacted' },
+        discovery: {
+          requested_skill_names: ['context-receipts', 'skill-policy-receipts'],
+          discovered_source_paths: [
+            'skills/context-receipts/SKILL.md',
+            'examples/agent-skills/context-receipts/SKILL.md',
+            'docs/.well-known/agent-skills/context-receipts/SKILL.md',
+            'skills/skill-policy-receipts/SKILL.md',
+            'examples/agent-skills/skill-policy-receipts/SKILL.md',
+            'docs/.well-known/agent-skills/skill-policy-receipts/SKILL.md'
+          ],
+          duplicate_resolution: 'prefer_top_level_skills_dir'
+        },
+        selected_skills: [
+          { name: 'context-receipts', selected_source_path: 'skills/context-receipts/SKILL.md', target_path: '.agent/skills/context-receipts/SKILL.md', operation: 'install', lockfile_entry_written: true },
+          { name: 'skill-policy-receipts', selected_source_path: 'skills/skill-policy-receipts/SKILL.md', target_path: '.agent/skills/skill-policy-receipts/SKILL.md', operation: 'install', lockfile_entry_written: true }
+        ],
+        ignored_duplicates: [
+          { name: 'context-receipts', ignored_source_path: 'examples/agent-skills/context-receipts/SKILL.md', reason: 'duplicate_mirror_not_canonical' },
+          { name: 'context-receipts', ignored_source_path: 'docs/.well-known/agent-skills/context-receipts/SKILL.md', reason: 'duplicate_mirror_not_canonical' },
+          { name: 'skill-policy-receipts', ignored_source_path: 'examples/agent-skills/skill-policy-receipts/SKILL.md', reason: 'duplicate_mirror_not_canonical' },
+          { name: 'skill-policy-receipts', ignored_source_path: 'docs/.well-known/agent-skills/skill-policy-receipts/SKILL.md', reason: 'duplicate_mirror_not_canonical' }
+        ],
+        safety: { content_sanitizers: ['frontmatter-parse', 'markdown-only'], raw_secret_or_env_values_copied: false, scripts_or_hooks_installed: false, network_capability_added: false, manual_review_required: true },
+        privacy: { raw_skill_body_omitted: true, raw_env_values_omitted: true, auth_headers_omitted: true, customer_data_omitted: true },
+        result: { status: 'safe_to_install_after_review', installed_count: 2, ignored_duplicate_count: 4 }
+      }
+    }
+    const receiptEl = document.querySelector('#receipt')
+    const resultEl = document.querySelector('#result')
+    document.querySelector('#load').addEventListener('click', loadSample)
+    document.querySelector('#validate').addEventListener('click', validate)
+    document.querySelector('#sample').addEventListener('change', loadSample)
+    loadSample()
+    function loadSample() {
+      const key = document.querySelector('#sample').value
+      receiptEl.value = JSON.stringify(samples[key], null, 2)
+      validate()
+    }
+    function validate() {
+      let receipt
+      try { receipt = JSON.parse(receiptEl.value) }
+      catch (error) { return render({ ok:false, errors:[`invalid JSON: ${error.message}`], warnings:[] }) }
+      if (receipt.schema === 'pluribus.mcp_tool_surface_diff_receipt.v1') return render(validateToolSurface(receipt))
+      if (receipt.schema === 'pluribus.context_attention_receipt.v1') return render(validateAttention(receipt))
+      if (receipt.schema === 'pluribus.claude_code_rule_attention_receipt.v1') return render(validateRuleAttention(receipt))
+      if (receipt.schema === 'pluribus.agent_skill_install_provenance_receipt.v1') return render(validateSkillInstall(receipt))
+      if (receipt.schema === 'pluribus.retrieval_adoption_receipt.v1') return render(validateRetrievalAdoption(receipt))
+      render({ ok:false, errors:[`unsupported schema: ${receipt.schema || '(missing)'}`], warnings:[] })
+    }
+    function validateToolSurface(r) {
+      const errors = [], warnings = []
+      const privacy = r.privacy_boundary || {}
+      if (!r.catalog?.current_hash) errors.push('catalog.current_hash is required')
+      if (!Array.isArray(r.tools) || r.tools.length === 0) errors.push('tools must include at least one discovered/activated/withheld/blocked tool')
+      for (const field of ['raw_schemas','raw_prompts','raw_results']) if (!String(privacy[field] || '').startsWith('omitted')) errors.push(`privacy_boundary.${field} must be omitted`)
+      const counts = countBy(r.tools || [], 'status')
+      if (!counts.activated && !counts.withheld && !counts.blocked) warnings.push('receipt has no activated/withheld/blocked status counts')
+      return { ok: errors.length === 0, schema:r.schema, summary:counts, errors, warnings }
+    }
+    function validateAttention(r) {
+      const errors = [], warnings = []
+      const required = ids((r.required_context || []).map(x => x.id))
+      const delivered = ids(r.delivery?.delivered_context_ids)
+      const ack = ids(r.attention?.acknowledged_before_plan)
+      const cited = ids(r.attention?.cited_in_plan)
+      if (!required.length) errors.push('required_context must name at least one id')
+      for (const id of required) {
+        if (!delivered.includes(id)) errors.push(`required context not delivered: ${id}`)
+        if (!ack.includes(id)) errors.push(`required context not acknowledged before plan: ${id}`)
+        if (!cited.includes(id)) errors.push(`required context not cited in plan: ${id}`)
+      }
+      if (r.delivery?.raw_context_omitted !== true) errors.push('delivery.raw_context_omitted must be true')
+      for (const field of ['raw_prompts_omitted','raw_documents_omitted','source_code_omitted','tool_outputs_omitted','tokens_omitted','customer_data_omitted']) if (r.privacy?.[field] !== true) errors.push(`privacy.${field} must be true`)
+      if (errors.length && r.attention?.missing_context_stop !== true) errors.push('missing_context_stop must be true when required attention evidence is incomplete')
+      if (!r.delivery?.evidence_path) warnings.push('delivery.evidence_path is missing')
+      return { ok: errors.length === 0, schema:r.schema, required_count:required.length, delivered_count:delivered.length, acknowledged_count:ack.length, cited_count:cited.length, errors, warnings }
+    }
+    function validateRuleAttention(r) {
+      const errors = [], warnings = []
+      const rules = Array.isArray(r.rules) ? r.rules : []
+      if (!rules.length) errors.push('rules must include at least one project rule')
+      for (const rule of rules) {
+        if (!rule.rule_id) errors.push('each rule must include rule_id')
+        if (!rule.source) errors.push(`${rule.rule_id || 'rule'} must include source`)
+        if (!rule.last_loaded_at) errors.push(`${rule.rule_id || 'rule'} must include last_loaded_at`)
+        if (rule.cited_in_pre_edit_plan !== true) warnings.push(`${rule.rule_id || 'rule'} was not cited in the pre-edit plan`)
+        if (!['pass','fail','missing'].includes(rule.edit_check)) errors.push(`${rule.rule_id || 'rule'} edit_check must be pass, fail, or missing`)
+      }
+      for (const field of ['raw_prompts_omitted','raw_claude_md_omitted','source_code_omitted','tool_outputs_omitted','tokens_omitted','customer_data_omitted']) if (r.privacy?.[field] !== true) errors.push(`privacy.${field} must be true`)
+      const missing = rules.filter(rule => rule.cited_in_pre_edit_plan !== true || rule.edit_check !== 'pass')
+      if (missing.length && r.result?.status === 'safe_to_edit') errors.push('result.status cannot be safe_to_edit while a required rule is uncited or failing')
+      return { ok: errors.length === 0 && missing.length === 0, schema:r.schema, rules_count:rules.length, uncited_or_failing_rules:missing.map(rule => rule.rule_id), errors, warnings }
+    }
+    function validateRetrievalAdoption(r) {
+      const errors = [], warnings = []
+      const catalogTools = Array.isArray(r.availability_evidence?.tool_catalog_contains) ? r.availability_evidence.tool_catalog_contains : []
+      const retrievalCalls = Array.isArray(r.adoption_evidence?.retrieval_calls) ? r.adoption_evidence.retrieval_calls : []
+      const escapeCalls = Array.isArray(r.adoption_evidence?.native_escape_hatch_calls) ? r.adoption_evidence.native_escape_hatch_calls : []
+      const cited = Array.isArray(r.adoption_evidence?.cited_retrieved_context_ids) ? r.adoption_evidence.cited_retrieved_context_ids : []
+      if (!r.retrieval_surface?.kind) errors.push('retrieval_surface.kind is required')
+      if (r.retrieval_surface?.available !== true) errors.push('retrieval_surface.available must be true before adoption can be measured')
+      if (!catalogTools.length) errors.push('availability_evidence.tool_catalog_contains must list at least one retrieval tool')
+      if (r.availability_evidence?.raw_graph_omitted !== true) errors.push('availability_evidence.raw_graph_omitted must be true')
+      if (r.adoption_evidence?.raw_tool_outputs_omitted !== true) errors.push('adoption_evidence.raw_tool_outputs_omitted must be true')
+      for (const field of ['raw_prompts_omitted','raw_graph_nodes_omitted','source_code_omitted','tool_outputs_omitted','customer_data_omitted']) if (r.privacy?.[field] !== true) errors.push(`privacy.${field} must be true`)
+      const graphGroundedFindings = Number(r.adoption_evidence?.graph_grounded_findings || 0)
+      const usedRetrieval = retrievalCalls.length > 0 || cited.length > 0 || graphGroundedFindings > 0
+      if (r.boundary_checks?.retrieval_available_but_unused === true && usedRetrieval) errors.push('retrieval_available_but_unused cannot be true when retrieval calls/citations/findings exist')
+      if (!usedRetrieval && r.boundary_checks?.no_retrieval_claim_allowed !== true) errors.push('no_retrieval_claim_allowed must be true when retrieval was available but no adoption evidence exists')
+      if (!usedRetrieval && !escapeCalls.length) warnings.push('no retrieval adoption and no native escape-hatch calls recorded; receipt may be missing usage telemetry')
+      return { ok: errors.length === 0, schema:r.schema, retrieval_available:r.retrieval_surface?.available === true, retrieval_call_count:retrievalCalls.length, cited_context_count:cited.length, graph_grounded_findings:graphGroundedFindings, native_escape_hatch_calls:escapeCalls, status: usedRetrieval ? 'retrieval_adopted' : 'availability_not_adoption', errors, warnings }
+    }
+    function validateSkillInstall(r) {
+      const errors = [], warnings = []
+      const selected = Array.isArray(r.selected_skills) ? r.selected_skills : []
+      const ignored = Array.isArray(r.ignored_duplicates) ? r.ignored_duplicates : []
+      const discovered = Array.isArray(r.discovery?.discovered_source_paths) ? r.discovery.discovered_source_paths : []
+      if (!r.source?.repo) errors.push('source.repo is required')
+      if (!r.source?.resolved_sha) errors.push('source.resolved_sha is required')
+      if (!r.installer?.target_agent_dir) errors.push('installer.target_agent_dir is required')
+      if (!selected.length) errors.push('selected_skills must include at least one installed skill')
+      for (const skill of selected) {
+        if (!skill.name) errors.push('each selected skill must include name')
+        if (!skill.selected_source_path) errors.push(`${skill.name || 'skill'} must include selected_source_path`)
+        if (!skill.target_path) errors.push(`${skill.name || 'skill'} must include target_path`)
+        if (skill.lockfile_entry_written !== true) warnings.push(`${skill.name || 'skill'} did not write lockfile metadata`)
+      }
+      const selectedNames = selected.map(skill => skill.name).filter(Boolean)
+      for (const name of selectedNames) {
+        const discoveredForName = discovered.filter(path => path.includes(`/${name}/`) || path.includes(`${name}/SKILL.md`)).length
+        const ignoredForName = ignored.filter(item => item.name === name).length
+        if (discoveredForName > 1 && ignoredForName === 0) errors.push(`${name} has multiple discovered paths but no ignored_duplicates evidence`)
+      }
+      if (r.safety?.raw_secret_or_env_values_copied !== false) errors.push('safety.raw_secret_or_env_values_copied must be false')
+      if (r.safety?.scripts_or_hooks_installed !== false) errors.push('safety.scripts_or_hooks_installed must be false for a low-authority skill receipt')
+      if (r.safety?.network_capability_added !== false) errors.push('safety.network_capability_added must be false for a skill-only install')
+      for (const field of ['raw_skill_body_omitted','raw_env_values_omitted','auth_headers_omitted','customer_data_omitted']) if (r.privacy?.[field] !== true) errors.push(`privacy.${field} must be true`)
+      if (selected.length !== new Set(selectedNames).size) errors.push('selected_skills contains duplicate names after resolution')
+      return { ok: errors.length === 0, schema:r.schema, selected_count:selected.length, ignored_duplicate_count:ignored.length, discovered_source_count:discovered.length, selected_source_paths:selected.map(skill => skill.selected_source_path), errors, warnings }
+    }
+    function countBy(items, key) { return items.reduce((acc, item) => (acc[item[key] || 'unknown'] = (acc[item[key] || 'unknown'] || 0) + 1, acc), {}) }
+    function ids(v) { return Array.isArray(v) ? v.filter(x => typeof x === 'string' && x) : [] }
+    function render(obj) {
+      resultEl.className = 'result ' + (obj.ok ? 'ok' : 'bad')
+      resultEl.textContent = JSON.stringify(obj, null, 2)
+    }
+  </script>
+</body>
+</html>

package/docs/session-preflight-receipts.md ADDED Viewed

@@ -0,0 +1,77 @@
+# Session preflight receipts
+Cursor Forum users are asking for a "required first tool" or pre-tool hook so an agent cannot skip required project context before Grep, Shell, Write, or MCP calls. A behavioral rule is not enough: the first useful question is whether the session actually initialized its context before work began.
+A **session preflight receipt** is a small, privacy-safe record produced before any side-effecting agent work. It does not log raw memory, prompts, secrets, or file contents. It records which required context sources were checked, which tool surfaces were available, and whether the agent is allowed to proceed.
+Use this when rules like "read `MEMORY.md` first" or "call `session_init` before work" are important enough to audit.
+## Minimal receipt
+```json
+{
+  "schema": "pluribus.session_preflight_receipt.v1",
+  "session_id": "local-2026-06-17T11:00Z",
+  "client": "cursor",
+  "required_first_step": {
+    "kind": "mcp_tool",
+    "name": "session_guard.session_init",
+    "enforcement": "behavioral_rule_only"
+  },
+  "required_context": [
+    {
+      "id": "project-memory",
+      "path": "MEMORY.md",
+      "status": "loaded",
+      "fingerprint": "sha256:example-non-secret-digest"
+    }
+  ],
+  "tool_surface": {
+    "mcp_servers_seen": ["session-guard", "playwright"],
+    "side_effecting_tools_blocked_until_preflight": ["Shell", "Write"]
+  },
+  "decision": {
+    "allowed_to_start_work": true,
+    "mode": "read_then_patch",
+    "reason": "required context was checked before tool use"
+  }
+}
+```
+## What this proves
+- The agent had an explicit preflight gate before work.
+- Required context sources were checked or clearly missing.
+- Side-effecting tools were blocked, downgraded, or allowed for a reason.
+- A reviewer can tell whether the run began from known project context or from blind rediscovery.
+## What this does not prove
+- It is not an authorization decision.
+- It does not prove the model fully understood the context.
+- It does not replace Cursor, Claude Code, or MCP-native enforcement.
+- It does not require logging private memory content.
+## Failure modes to record
+```json
+{
+  "schema": "pluribus.session_preflight_receipt.v1",
+  "decision": {
+    "allowed_to_start_work": false,
+    "mode": "read_only",
+    "reason": "required context missing or session_init skipped"
+  },
+  "failures": [
+    {
+      "kind": "required_context_missing",
+      "id": "project-memory",
+      "path": "MEMORY.md"
+    }
+  ]
+}
+```
+The key distinction: **a required first tool is the enforcement hook; the receipt is the evidence that the hook actually ran before work.**
+See `examples/session-preflight-receipts/` for a copyable Cursor-style rule and JSON fixture.

package/examples/claude-md-read-receipts/README.md ADDED Viewed

@@ -0,0 +1,70 @@
+# CLAUDE.md read receipt
+A tiny, manual-first receipt for Claude Code sessions where `CLAUDE.md` is read at startup but trust erodes after a long session, compaction, `/clear`, or a topic switch.
+Use it before asking the agent to edit again. The agent does **not** need to dump raw prompts or file contents. It should name the routing/index files it reloaded, the constraints it is carrying forward, and the relevant files it intentionally did not load.
+## Prompt pattern
+```text
+Before continuing, give me a context read receipt:
+- current task/topic
+- session state: fresh, compacted, topic_switched, or resumed
+- indexed files you reloaded and why
+- 3-5 active constraints carried forward
+- relevant files you did not load
+- stale/historical notes you are not treating as current authority
+- whether it is safe to edit now
+```
+If the agent cannot name what it reloaded, it probably has not grounded.
+## Run the sample checker
+```bash
+cd examples/claude-md-read-receipts
+node check-read-receipt.mjs --receipt sample-read-receipt.json
+```
+The bundled passing receipt models a topic switch from payments work to upload API work. It keeps `CLAUDE.md` as the router, reloads the topic doc and migration notes, lists active constraints, and marks the session safe to edit.
+A stale receipt should fail:
+```bash
+node check-read-receipt.mjs --receipt stale-read-receipt.json
+```
+## Receipt shape
+```json
+{
+  "schema": "pluribus.claude_md_read_receipt.v1",
+  "session_state": "topic_switched",
+  "current_task": "Update upload API retry handling",
+  "reloaded_files": [
+    { "path": "CLAUDE.md", "role": "router", "why": "Selects topic-specific docs" }
+  ],
+  "active_constraints": [
+    "Do not log raw file contents",
+    "Preserve max 3 retries with exponential backoff",
+    "Treat v2.4.0 migration notes as current authority"
+  ],
+  "not_loaded_files": [
+    { "path": "docs/payments.md", "why": "Previous topic only" }
+  ],
+  "safe_to_edit": true
+}
+```
+## Why this exists
+The market signal from Claude Code users is practical: people already maintain lean `CLAUDE.md` index files and topic memory docs, but they still have to ask whether the agent actually re-read the right material after a topic switch or compaction.
+This receipt keeps the ritual lightweight and falsifiable:
+- `CLAUDE.md` can stay small and act as a router.
+- Topic docs can be reloaded only when relevant.
+- Current authority is separated from stale/historical notes.
+- `safe_to_edit=false` is allowed when the session cannot prove it is grounded.
+Pair this with Pluribus' sync/audit workflow when file drift is the problem. Use this receipt when runtime grounding is the problem.