pluribus-context 0.3.39 → 0.3.41

package/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.41 - 2026-06-10
+
+- Added npm Agent Skills discovery keywords (`agent-skill`, `skillpm`, and `agent-skills-registry`) so `pluribus-context` can be indexed by npm-backed skill package managers while continuing to ship the existing low-authority `skills/*/SKILL.md` recipes.
+
+## 0.3.40 - 2026-06-09
+
+- Added `pluribus demo tool-surface-diff`, a tiny npm-runnable MCP dynamic-discovery receipt demo for proving discovered, activated, withheld, and blocked runtime tool-surface changes without logging raw schemas, prompts, or results.
+- Expanded npm discovery keywords around MCP audit, gateways, security, tool discovery, and audit trails so the package is easier to find from the market lane now forming around MCP governance.
+
 ## 0.3.39 - 2026-06-07
 
 - Added `pluribus demo mcp-telemetry-import`, a tiny npm-runnable converter from MCP `rpc-messages.jsonl`-style JSON-RPC traces into privacy-safe audit receipts that preserve attribution, redacted shapes, status, and timing gaps without storing raw tool payloads.

package/README.md

@@ -14,7 +14,7 @@ The original sync workflow is still useful: Pluribus can keep project instructio
 
 It is **not** a persistent memory layer, retrieval system, agent orchestrator, enterprise ContextOps platform, or agent-merging framework. Think evidence for context boundaries: `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `AGENTS.md`, MCP Tool Search, Agent Skills, RAG/code-search, pruning, and compaction — with privacy-safe receipts instead of raw content dumps.
 
-**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and disposable 60-second smoke tests. If you only run one command for the cross-tool audit, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, load evidence, duplicate-load selection evidence, manual activation requirements, effective context scope, and semantic differences. For the agent-observability wedge, start with [context-budget receipts](docs/context-budget-receipts.md): privacy-safe evidence for what MCP schemas, skills, memory, subagents, CLI help, retrieval chunks, pruning runs, or compaction summaries crossed an agent boundary. If you want the same idea as a copyable skill, use the [context-receipts Agent Skill recipe](skills/context-receipts/). npm `latest` is currently aligned with the GitHub release; the review packet also documents a GitHub-release smoke fallback for future release-lag windows.
+**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and disposable 60-second smoke tests. If you only run one command for the cross-tool audit, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, load evidence, duplicate-load selection evidence, manual activation requirements, effective context scope, and semantic differences. For the agent-observability wedge, start with [context-budget receipts](docs/context-budget-receipts.md): privacy-safe evidence for what MCP schemas, skills, memory, subagents, CLI help, retrieval chunks, pruning runs, or compaction summaries crossed an agent boundary. It now explicitly covers the "Tool Search fixed MCP bloat" objection: the receipt proves which lane stayed deferred, which tool was expanded, and whether schemas leaked through `messages`/bootstrap anyway. For a 60-second runtime-discovery proof, run `npx --yes pluribus-context@latest demo tool-surface-diff --json`; it validates a receipt for discovered → activated → withheld/blocked MCP tools without raw schemas/prompts/results. If you are coming from Claude Code, GraphRAG, or memory tooling where retrieval succeeds but the agent ignores it, try the [context attention receipt example](examples/context-attention-receipts/) to prove required context was delivered, acknowledged, and cited before edits. If you want the same idea as a copyable skill, use the [context-receipts Agent Skill recipe](skills/context-receipts/). npm `latest` is currently aligned with the GitHub release; the review packet also documents a GitHub-release smoke fallback for future release-lag windows.
 
 ---
 

package/bin/pluribus.js

@@ -94,6 +94,8 @@ EXAMPLES
   pluribus demo mcp-audit-receipt --json
   pluribus demo mcp-telemetry-import
   pluribus demo mcp-telemetry-import --json
+  pluribus demo tool-surface-diff
+  pluribus demo tool-surface-diff --json
 
 DOCS
   https://github.com/caioribeiroclw-pixel/pluribus

package/docs/.well-known/agent-skills/context-receipts/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: context-receipts
+description: Emit privacy-safe receipts for context selection, deferral, hydration, compaction, pruning, delegation, usage attribution, and boundary handoffs.
+---
+
+# Context Receipts
+
+Use this skill when an agent workflow claims to save context by selecting, deferring, hydrating, summarizing, compacting, pruning, delegating, attributing usage, or isolating context.
+
+The job is not to log the private content. The job is to emit a small receipt that lets a reviewer answer:
+
+> what crossed the context boundary, what stayed out, and what audit gap remains?
+
+## Privacy defaults
+
+Never include raw prompts, raw tool schemas, raw tool arguments, raw tool results, raw skill bodies, memory bodies, secrets, customer names, or full transcripts in the receipt.
+
+Prefer:
+
+- stable ids or hashed ids;
+- counts and token/line buckets;
+- categorical reasons;
+- explicit booleans for raw content copied/not copied;
+- before/after context budget buckets;
+- an `audit_gap` field when the receipt proves routing but not semantic correctness.
+
+## 60-second Tool Search smoke
+
+For MCP Tool Search, lazy tool loading, or progressive disclosure, emit enough evidence to answer these seven checks:
+
+1. **Index-only startup:** did the session load a compact tool/server index instead of all full schemas?
+2. **Search/routing:** what hashed query/category or routing reason selected candidate tools?
+3. **Hydration:** which full tool definition was loaded, why, and how many definitions stayed suppressed?
+4. **Call:** which server/tool id was invoked, with argument/result redaction status and success/error status?
+5. **Boundary:** if a manager subagent or child agent was used, did raw child output return to the parent?
+6. **Budget:** what were the startup and post-hydration context-token buckets?
+7. **Audit gap:** what is not proven, such as whether the selected tool was semantically optimal?
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"mcp.tool_index.loaded","loaded_server_count":12,"loaded_tool_index_count":84,"full_schema_count":0,"suppressed_tool_count":84,"raw_schema_copied":false,"startup_token_bucket":"lt_1k"}
+{"event":"mcp.tool_search.performed","query_hash":"sha256:...","query_category":"repo_search","candidate_tool_count":5,"selected_tool_id":"github.search_code","raw_query_copied":false}
+{"event":"mcp.tool_definition.loaded","tool_id":"github.search_code","hydrate_reason":"selected_after_tool_search","suppressed_tool_count":83,"definition_token_bucket":"1k_2k","raw_schema_copied":false}
+{"event":"mcp.tool_call.completed","tool_id":"github.search_code","args_hash":"sha256:...","result_token_bucket":"2k_4k","raw_args_copied":false,"raw_result_copied":false,"status":"ok"}
+```
+
+## Skill / prompt context smoke
+
+For skills, rules, AGENTS.md overlays, or instruction files, answer:
+
+- which index/listing entered the session;
+- which full skill/rule/instruction body was selected;
+- which candidates were suppressed and why;
+- whether the body was loaded at session start, after a search, or after an explicit command;
+- source hash, delivered hash, and canonical form when available;
+- whether the skill/instruction text was copied into the receipt.
+
+Minimal event names:
+
+- `context.skill.registry.index.loaded`
+- `context.skill.registry.skill.read`
+- `context.skill.registry.skill.injected`
+- `context.input.loaded`
+- `context.input.candidate_suppressed`
+
+## Per-agent MCP injection smoke
+
+For role-specific subagents or per-agent MCP configs, prove the policy boundary before debugging model quality:
+
+- which subagent role/session requested tools;
+- which MCP servers were available to that role;
+- which servers were explicitly excluded before boot;
+- whether startup loaded full schemas or only a compact index;
+- how many tool definitions stayed deferred/suppressed; and
+- the startup token bucket after policy was applied.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"subagent.mcp_policy.applied","subagent_role":"testing","available_server_count":2,"available_servers_hash":"sha256:...","excluded_server_count":5,"excluded_servers_hash":"sha256:...","policy_source":"role_config","raw_server_names_copied":false}
+{"event":"subagent.context_boot.evaluated","subagent_role":"testing","loaded_tool_definition_count":0,"deferred_tool_definition_count":48,"startup_token_bucket":"50k_75k","raw_schema_copied":false,"audit_gap":"proves injection boundary, not tool relevance"}
+```
+
+## ToolSearch propagation smoke
+
+For subagents that should inherit MCP through `ToolSearch`, distinguish policy, declaration, and runtime filtering:
+
+- did the parent/orchestrator intend to expose MCP or exclude it for this subagent?
+- was the subagent spawned immediately or after parent tool calls/orchestration work?
+- was the `tools:` declaration wildcard, explicit include, or exclusion style?
+- was `ToolSearch` declared and was it actually exposed in the subagent tool surface?
+- did MCP servers/tool definitions stay deferred, or did the channel collapse to zero?
+- was the agent registry loaded at session boot, making newly added agent files invisible until restart?
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"subagent.toolsearch.propagation.evaluated","spawn_path":"Task","tools_declaration_shape":"enumerated_include","toolsearch_declared":false,"toolsearch_exposed":false,"mcp_servers_available_bucket":"0","deferred_tool_definitions_bucket":"0","filtered_by":"frontmatter_tools_policy_or_runtime_filter","raw_tool_schemas_copied":false}
+{"event":"subagent.toolsearch.matrix.completed","tested_axis":"tools_frontmatter_shape","audit_gap":"proves ToolSearch exposure, not semantic tool relevance or runtime call success"}
+```
+
+## Retrieval / code-search smoke
+
+For semantic code search, repo RAG, or MCP tools such as Claude Context, separate "search returned" from "agent context loaded":
+
+- which index snapshot/version was used, without raw local codebase paths;
+- what query/category/filter identity selected the candidates, without raw query text;
+- which result ids/chunk hashes were returned, with rank, score bucket, stale flag, duplicate marker, path hash/extension, and range bucket;
+- which returned chunks were actually loaded into the agent context;
+- which chunks were suppressed as duplicate, stale, clipped, policy-blocked, or over budget;
+- whether raw code, raw prompts, raw paths, customer names, URLs, secrets, and ticket text stayed out of the receipt;
+- the audit gap: this proves retrieval/loading boundaries, not semantic answer quality.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"code.index.snapshot.used","snapshot_id_hash":"sha256:...","codebase_path_hash":"sha256:...","indexed_chunk_count_bucket":"over_1k","raw_codebase_path_copied":false}
+{"event":"code.search.performed","query_hash":"sha256:...","query_category":"auth_debug","candidate_count_bucket":"over_1k","raw_query_copied":false}
+{"event":"code.search.result.returned","rank":1,"chunk_id_hash":"sha256:...","chunk_text_hash":"sha256:...","path_hash":"sha256:...","score_bucket":"high","stale":false,"raw_code_copied":false}
+{"event":"context.input.loaded","kind":"retrieved_code_chunks","loaded_chunk_count":3,"suppressed_chunk_count":2,"suppression_reasons":["duplicate","stale_snapshot_chunk"],"raw_code_copied":false}
+```
+
+## Usage attribution smoke
+
+For `/usage`, `/context`, `/doctor`, or other context-budget breakdowns, map each displayed category to evidence that can be reviewed without exposing private content:
+
+- what measurement window was used;
+- which categories were attributed, such as skills, subagents, plugins, MCP servers, rules, memory, or project files;
+- which components were loaded, deferred, hydrated, suppressed, pruned, or rolled back;
+- before/after or current token/cost buckets by category;
+- whether raw skill bodies, prompts, MCP schemas, tool outputs, and file paths were excluded;
+- the remaining audit gap, such as not proving semantic usefulness of a high-cost component.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"context.usage.window.measured","window":"current_session","total_token_bucket":"100k_150k","raw_prompts_copied":false}
+{"event":"context.usage.category.attributed","category":"mcp_server","component_hash":"sha256:...","loaded_token_bucket":"10k_25k","deferred_definition_count":42,"hydrated_definition_count":3,"raw_schema_copied":false}
+{"event":"context.usage.breakdown.completed","categories":["skills","subagents","plugins","mcp_server"],"audit_gap":"proves attribution buckets, not whether each component was necessary"}
+```
+
+## Pruning / compaction smoke
+
+For context-cleaning, pruning, compaction, or doctor/guard tools, answer:
+
+- what prescription/trigger started the run;
+- which strategies changed context and which candidates were protected;
+- before/after token and byte buckets;
+- whether summaries, behavioral digests, team messages, and backups were preserved;
+- whether private transcript text, raw tool output, file paths, secrets, and customer text were excluded from the receipt;
+- the remaining audit gap, such as not proving semantic quality of the pruned text.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"context.prune.started","prescription":"balanced","trigger":"manual_dry_run","before_token_bucket":"150k_200k","raw_transcript_copied":false}
+{"event":"context.prune.strategy.evaluated","strategy":"tool-output-trim","candidate_bucket":"10_25","changed_bucket":"5_10","protected_bucket":"1_5","raw_tool_output_copied":false}
+{"event":"context.prune.completed","after_token_bucket":"75k_100k","backup_verified":true,"protected_summary_count":2,"raw_text_copied":false,"audit_gap":"proves pruning/protection counts, not semantic disposability"}
+```
+
+For failed compaction, also prove transaction safety:
+
+- did the summary call succeed, fail, or timeout;
+- was a candidate summary validated before any swap;
+- did the harness commit a context swap or preserve the original context;
+- were deferred-tool registries and system-reminder queues restored on rollback;
+- did stale system reminders/tool results replay as fresh state;
+- was post-token metadata recorded as success even though summary failed.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"context.compaction.summary.attempted","summary_call_status":"failed_rate_limited","candidate_summary_available":false,"raw_error_copied":false}
+{"event":"context.compaction.rollback.completed","swap_committed":false,"original_context_preserved":true,"deferred_tool_registry_restored":true,"system_reminder_queue_restored":true,"replayed_system_reminder_count":0}
+{"event":"context.compaction.transaction.completed","status":"rolled_back","authoritative_state":"pre_compaction_context","post_tokens_recorded_as_success":false,"raw_context_copied":false}
+```
+
+## Subagent / manager boundary smoke
+
+For subagents, manager agents, or child workers, answer:
+
+- what task was delegated, by category and hashed objective;
+- what large output was captured by the child, as line/token buckets;
+- what bounded summary returned to the parent;
+- whether raw child output, tool results, or MCP schemas entered the parent context;
+- the remaining audit gap.
+
+Minimal event names:
+
+- `subagent.delegation.requested`
+- `subagent.tool_output.captured`
+- `subagent.summary.returned`
+- `parent.context_budget.evaluated`
+
+## Good receipt test
+
+A receipt is useful if a maintainer can debug one of these failures without seeing private content:
+
+- the agent never found the right tool/skill;
+- the full definition loaded too early;
+- too many definitions stayed in context;
+- a child/subagent saved no budget because raw output returned to the parent;
+- compaction/pruning happened but no one can prove what was changed, protected, backed up, summarized, or dropped.
+
+A receipt is not enough if it only says “Tool Search enabled” or “used subagent”. It must prove the boundary behavior.

package/docs/.well-known/agent-skills/index.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+  "skills": [
+    {
+      "name": "context-receipts",
+      "type": "skill-md",
+      "description": "Emit privacy-safe receipts for context selection, deferral, hydration, compaction, pruning, delegation, usage attribution, and boundary handoffs.",
+      "url": "context-receipts/SKILL.md",
+      "digest": "sha256:6d268a5ceac4afa87308ff4c79f01483e2785a8e9bb54e5d3147477e0bf724a1"
+    },
+    {
+      "name": "skill-policy-receipts",
+      "type": "skill-md",
+      "description": "Use when a task must obey a hard project policy, such as \"do not generate tests for internal services\", \"do not call production APIs\", or \"do not edit generated files\". Emits a privacy-safe receipt before writes and after guard checks.",
+      "url": "skill-policy-receipts/SKILL.md",
+      "digest": "sha256:633b4da097b56da8805476a69d0498602979b7f8c03c57996f886bb9e56ccca8"
+    }
+  ]
+}

package/docs/.well-known/agent-skills/skill-policy-receipts/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: skill-policy-receipts
+description: Use when a task must obey a hard project policy, such as "do not generate tests for internal services", "do not call production APIs", or "do not edit generated files". Emits a privacy-safe receipt before writes and after guard checks.
+---
+
+# Skill Policy Receipts
+
+This Skill turns natural-language guardrails into an inspectable policy receipt.
+
+## Preflight: decide before writing
+
+Before creating or editing files:
+
+1. List intended targets using coarse paths or globs.
+2. For each target, decide `allowed` or `refused`.
+3. Give a short reason.
+4. If any target is refused, stop before writing.
+5. Emit a receipt with `write_started=false` and `stopped_at="policy_refused"`.
+
+Receipt shape:
+
+```json
+{
+  "receipt_type": "skill.policy.v1",
+  "skill": "skill-policy-receipts",
+  "policy_scope": "<short policy name>",
+  "targets": [
+    {
+      "target": "<coarse path or glob>",
+      "decision": "allowed|refused",
+      "reason": "<short reason>"
+    }
+  ],
+  "write_started": false,
+  "post_write_guard": "not_run",
+  "stopped_at": "policy_refused|all_targets_allowed"
+}
+```
+
+Do not include raw prompts, code, secrets, customer data, stack traces, or full tool output.
+
+## Write only after all targets are allowed
+
+If every target is allowed:
+
+1. Emit or state `stopped_at="all_targets_allowed"`.
+2. Perform the write.
+3. Run the configured post-write guard.
+4. Emit whether the guard passed or failed.
+
+Post-write receipt shape:
+
+```json
+{
+  "receipt_type": "skill.policy.v1",
+  "skill": "skill-policy-receipts",
+  "policy_scope": "<short policy name>",
+  "write_started": true,
+  "post_write_guard": "passed|failed|not_configured",
+  "stopped_at": "guard_passed|guard_failed"
+}
+```
+
+## Example policy: no internal-service unit tests
+
+Policy:
+
+> Do not generate unit tests for internal services. If the requested test imports `internal/`, `@/internal`, or a known private service module, refuse before writing and explain the safer target.
+
+Example guard:
+
+```bash
+grep -R "from ['\"]\.\./\.\./internal\|from ['\"]@/internal\|require(['\"]@/internal" \
+  -- '*test.*' '*spec.*'
+```
+
+If the grep finds a match in generated tests, stop and report `post_write_guard="failed"`.

package/docs/context-budget-receipts.md

@@ -8,6 +8,49 @@ This is different from generic token accounting. A context-budget receipt should
 
 If you want a copyable Agent Skill recipe instead of a spec-style guide, see [`skills/context-receipts/`](../skills/context-receipts/). It turns the receipt pattern into a 60-second smoke checklist for Tool Search, skills, and subagent boundaries.
 
+## If Tool Search already fixed the bloat
+
+Modern hosts can defer large MCP catalogs behind Tool Search or similar lazy discovery. That changes the receipt question; it does not remove it.
+
+Do not use a context-budget receipt to re-prove that every schema was smaller than before. Use it to prove the boundary that lazy loading promised:
+
+- the catalog/index was loaded instead of full definitions;
+- the selected query loaded only the matching tool definitions;
+- unselected tool groups stayed deferred or withheld;
+- a schema did not enter a side lane such as `messages`, subagent bootstrap, skill preamble, or memory hydration; and
+- the receipt records what evidence is missing when only fallback client telemetry exists.
+
+This makes the receipt useful in the common objection case: "MCP context bloat is solved by Tool Search." A good receipt should answer: **solved where, for this turn, through which lane, and with what proof?**
+
+Runnable fixture for the normal happy path:
+
+```bash
+node examples/context-input-evidence/convert-mcp-tool-search-log.mjs
+```
+
+Public trace:
+
+- `examples/context-input-evidence/mcp-tool-search-otel-trace.json`
+
+Minimum hidden-bypass fields for managed seats or gateways:
+
+```json
+{
+  "event.name": "mcp.deferral.evaluated",
+  "mcp.defer_loading.enabled": true,
+  "mcp.catalog.deferred": true,
+  "mcp.tool_search.selected_tool_count": 0,
+  "context.messages.remote_mcp_schema_count_bucket": "over_25",
+  "context.messages.delta_token_bucket": "under_100k",
+  "context.attribution": "remote_mcp_schema_in_messages",
+  "expected_behavior": "deferred_until_tool_search_match",
+  "verdict": "deferral_bypassed",
+  "privacy.raw_schema_included": false
+}
+```
+
+That shape deliberately avoids raw schema bodies, connector names, private URLs, and prompt text. It proves attribution, not whether the selected tool was semantically optimal.
+
 ## When to use this receipt
 
 Use a context-budget receipt when a coding agent looks lazy, fails with `prompt is too long`, or returns a tiny summary after a subagent/tool-heavy step and you need to distinguish:

package/docs/index.html

@@ -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, and CLAUDE.md rule-attention drift.</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>