pluribus-context 0.3.26 → 0.3.28

package/CHANGELOG.md

@@ -4,7 +4,15 @@
 
 All notable changes to Pluribus are documented here.
 
-- Added an executable subagent delegation receipt demo proving that large child command/tool output stayed isolated and only a bounded summary crossed back into the parent context.
+## 0.3.27 - 2026-05-25
+
+- Added a copyable Agent Skill recipe for privacy-safe context receipts, with 60-second smokes for Tool Search/lazy MCP, skill/prompt context, and subagent/manager boundaries.
+- Linked the recipe from the README and context-budget receipts guide so reviewers can install or inspect a concrete `SKILL.md` instead of reverse-engineering the receipt fixtures.
+
+## 0.3.26 - 2026-05-24
+
+- Added the public context-budget receipts guide, connecting subagent boot budget, delegation boundaries, MCP manager isolation, MCP gateway progressive disclosure, and CLI progressive disclosure under one diagnostic frame: what ate the agent's context before or after the task.
+- Published the GitHub release and npm catch-up so `pluribus-context@latest` includes the context-budget receipts docs and fixtures.
 
 ## 0.3.25 - 2026-05-23
 

package/README.md

@@ -14,7 +14,7 @@ It shows where instructions keep their semantics, where they are downgraded to a
 
 It is **not** a persistent memory layer, retrieval system, agent orchestrator, or agent-merging framework. Think `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `AGENTS.md` — one intentional context, multiple generated outputs.
 
-**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 a disposable 60-second smoke test. If you only run one command, 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 newer 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, or summaries actually crossed an agent boundary.
+**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 a disposable 60-second smoke test. If you only run one command, 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 newer 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, or summaries actually crossed an agent boundary. If you want the same idea as a copyable skill, use the [context-receipts Agent Skill recipe](examples/agent-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.
 
 ---
 
@@ -122,6 +122,13 @@ pluribus --help
 npm uninstall -g pluribus-context
 ```
 
+npm `latest` is currently aligned with the latest GitHub release. If you are reviewing a future GitHub release before npm `latest` catches up, run that release directly without a global install:
+
+```bash
+npm exec --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.26 -- pluribus --version
+npm exec --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.26 -- pluribus help
+```
+
 For local development:
 
 ```bash

package/docs/community-review-packet.md

@@ -82,9 +82,16 @@ npx --yes pluribus-context@latest sync --dry-run
 npx --yes pluribus-context@latest audit --ci --json --output pluribus-audit.json || test $? -eq 1
 ```
 
+npm `latest` is currently aligned with the latest GitHub release. If a future GitHub release is newer than npm `latest`, review that release directly instead of waiting for the npm dist-tag:
+
+```bash
+npm exec --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.26 -- pluribus --version
+npm exec --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.26 -- pluribus help
+```
+
 Expected result:
 
-- `--version` prints the current npm release.
+- `--version` prints the current npm release. During a future release-lag window, it prints the GitHub release version when using the `npm exec --package github:...` fallback.
 - `init --dry-run` previews `pluribus.md` without writing.
 - `init` writes `pluribus.md`.
 - `validate` succeeds.

package/docs/context-budget-receipts.md

@@ -6,6 +6,8 @@ Privacy-safe receipts for answering a narrow operational question:
 
 This is different from generic token accounting. A context-budget receipt should prove which context surfaces were available, which ones crossed the boundary, which ones stayed deferred or suppressed, and how much budget remained — without exporting raw prompts, tool schemas, tool outputs, memory bodies, file paths, ticket text, secrets, or customer data.
 
+If you want a copyable Agent Skill recipe instead of a spec-style guide, see [`examples/agent-skills/context-receipts/`](../examples/agent-skills/context-receipts/). It turns the receipt pattern into a 60-second smoke checklist for Tool Search, skills, and subagent boundaries.
+
 ## 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:
@@ -61,6 +63,22 @@ Public trace:
 
 - `examples/context-input-evidence/subagent-context-budget-otel-trace.json`
 
+## Per-agent MCP injection
+
+Role-specific subagents may need different MCP surfaces: a testing agent might need `testing` and `github`, while deployment, analytics, email, or browser servers should stay outside that boot context. The receipt should prove the policy boundary before the first task:
+
+- role/session id for the subagent without raw instructions;
+- available server count/hash for the role;
+- excluded server count/hash before boot;
+- loaded vs deferred tool-definition counts;
+- startup token bucket after the policy was applied; and
+- an explicit audit gap that this proves injection scope, not semantic tool quality.
+
+Minimal events:
+
+- `subagent.mcp_policy.applied`
+- `subagent.context_boot.evaluated`
+
 ## Delegation boundary
 
 A subagent can save parent context at boot and still lose the benefit if raw child output is pasted back into the parent. The receipt should prove:
@@ -144,7 +162,8 @@ Instead of “why is my subagent bad?”, ask for a receipt or debug JSON that c
 2. How many were loaded into the parent?
 3. How many were loaded into the subagent?
 4. How many were suppressed/deferred?
-5. What token bucket remained before the first tool call?
-6. Did raw child output return to the parent, or only a bounded summary?
+5. For a subagent, which MCP servers were allowed and which were excluded before boot?
+6. What token bucket remained before the first tool call?
+7. Did raw child output return to the parent, or only a bounded summary?
 
 That is the narrow wedge for Pluribus: context-budget evidence across agent boundaries, not another memory store or tool router.

package/examples/agent-skills/context-receipts/README.md

@@ -0,0 +1,22 @@
+# Context receipts Agent Skill recipe
+
+This is a small, copyable Agent Skill recipe for context-engineering users who are adopting Tool Search, lazy MCP loading, skills, memory, compaction, or subagents and need to verify what actually crossed the context boundary.
+
+It is intentionally markdown-only so it can be copied into a local skills directory such as:
+
+- `.claude/skills/context-receipts/SKILL.md`
+- `.opencode/skills/context-receipts/SKILL.md`
+- `.agents/skills/context-receipts/SKILL.md`
+
+## Quick smoke
+
+Ask an agent or harness using the skill to emit a receipt for one workflow and verify these constraints:
+
+```bash
+grep -E 'mcp\.tool_index\.loaded|context\.skill\.registry\.index\.loaded|subagent\.mcp_policy\.applied|subagent\.delegation\.requested' receipt.jsonl
+grep -E 'raw_(schema|query|args|result|output)_copied":false|raw.*CopiedToReceipt":false' receipt.jsonl
+```
+
+Then manually check that the receipt contains counts, hashes, ids, buckets, and `audit_gap`, but does **not** contain private prompts, raw schemas, tool args/results, skill bodies, memory bodies, customer names, secrets, or transcript text.
+
+For executable fixture examples, see [`../../context-input-evidence/`](../../context-input-evidence/).

package/examples/agent-skills/context-receipts/SKILL.md

@@ -0,0 +1,107 @@
+# Context Receipts
+
+Use this skill when an agent workflow claims to save context by selecting, deferring, hydrating, summarizing, compacting, delegating, 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"}
+```
+
+## 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 happened but no one can prove what was preserved, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "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.26'
+export const VERSION = '0.3.28'