pluribus-context 0.3.41 → 0.3.42

package/examples/semantic-anchor-receipts/check-semantic-anchors.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const args = { out: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    const value = argv[i + 1];
+    if (key === '--original') { args.original = value; i += 1; continue; }
+    if (key === '--cleaned') { args.cleaned = value; i += 1; continue; }
+    if (key === '--out') { args.out = value; i += 1; continue; }
+    if (key === '--help' || key === '-h') { args.help = true; continue; }
+    throw new Error(`Unknown argument: ${key}`);
+  }
+  return args;
+}
+
+function usage() {
+  return `Usage: node check-semantic-anchors.mjs --original original-paste.md --cleaned cleaned-paste.md [--out receipt.json]\n`;
+}
+
+function normalize(value) {
+  return value
+    .replace(/`+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function approxTokens(value) {
+  const chunks = value.trim().split(/\s+/).filter(Boolean).length;
+  return Math.max(1, Math.ceil(chunks * 1.33));
+}
+
+function extractAnchors(markdown) {
+  const anchors = [];
+  const lines = markdown.split(/\r?\n/);
+  let inFence = false;
+  let fenceLang = '';
+  let fenceLines = [];
+
+  function push(type, text, extra = {}) {
+    const canonical = normalize(text);
+    if (!canonical) return;
+    anchors.push({ type, text: text.trim(), canonical, ...extra });
+  }
+
+  for (const line of lines) {
+    const fence = line.match(/^```\s*([\w-]*)/);
+    if (fence) {
+      if (!inFence) {
+        inFence = true;
+        fenceLang = fence[1] || 'plain';
+        fenceLines = [];
+      } else {
+        const body = fenceLines.join('\n').trim();
+        if (body) push('code_fence', body, { language: fenceLang });
+        inFence = false;
+        fenceLang = '';
+        fenceLines = [];
+      }
+      continue;
+    }
+
+    if (inFence) {
+      fenceLines.push(line);
+      const sig = line.match(/\b(export\s+)?(async\s+)?(function|class|interface|type|def)\s+[A-Za-z0-9_]+[^;{]*/);
+      if (sig) push('api_signature', sig[0]);
+      continue;
+    }
+
+    if (/^#{1,4}\s+\S/.test(line)) push('heading', line.replace(/^#{1,4}\s+/, ''));
+    if (/\b(v?\d+\.\d+(?:\.\d+)?)\b/.test(line) && /\b(version|v\d|deprecated|removed|migration|upgrade|breaking|changed)\b/i.test(line)) {
+      push('version_or_migration_note', line);
+    }
+    if (/\b(never|must|do not|required|preserve|security|constraint)\b/i.test(line)) {
+      push('must_keep_policy', line.replace(/^[-*]\s+/, ''));
+    }
+    const sig = line.match(/\b(export\s+)?(async\s+)?(function|class|interface|type|def)\s+[A-Za-z0-9_]+[^;{]*/);
+    if (sig) push('api_signature', sig[0]);
+  }
+
+  const seen = new Set();
+  return anchors.filter((anchor) => {
+    const key = `${anchor.type}:${anchor.canonical}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { process.stdout.write(usage()); return; }
+  if (!args.original || !args.cleaned) throw new Error(usage().trim());
+
+  const originalPath = path.resolve(args.original);
+  const cleanedPath = path.resolve(args.cleaned);
+  const original = fs.readFileSync(originalPath, 'utf8');
+  const cleaned = fs.readFileSync(cleanedPath, 'utf8');
+  const cleanedCanonical = normalize(cleaned);
+  const anchors = extractAnchors(original);
+  const preserved = [];
+  const missing = [];
+
+  for (const anchor of anchors) {
+    const keep = cleanedCanonical.includes(anchor.canonical);
+    const compactAnchor = { type: anchor.type, text: anchor.text };
+    if (anchor.language) compactAnchor.language = anchor.language;
+    (keep ? preserved : missing).push(compactAnchor);
+  }
+
+  const before = approxTokens(original);
+  const after = approxTokens(cleaned);
+  const reduction = Number((((before - after) / before) * 100).toFixed(1));
+  const receipt = {
+    schema: 'pluribus.semantic_anchor_preservation_receipt.v1',
+    source_type: 'paste-cleaning-skill-or-cli-output',
+    original_ref: path.basename(originalPath),
+    cleaned_ref: path.basename(cleanedPath),
+    approximate_tokens_before: before,
+    approximate_tokens_after: after,
+    approximate_reduction_percent: reduction,
+    raw_source_logged: false,
+    anchor_detection_policy: [
+      'headings',
+      'code_fences',
+      'api_signatures',
+      'version_or_migration_notes',
+      'must_keep_policy_lines'
+    ],
+    anchors_total: anchors.length,
+    anchors_preserved: preserved.length,
+    anchors_missing: missing.length,
+    preserved_anchors: preserved,
+    missing_anchors: missing,
+    semantic_loss_check_passed: missing.length === 0,
+    token_savings_claim_allowed: missing.length === 0 && after < before
+  };
+
+  const serialized = `${JSON.stringify(receipt, null, 2)}\n`;
+  if (args.out) fs.writeFileSync(path.resolve(args.out), serialized);
+  process.stdout.write(serialized);
+  if (!receipt.semantic_loss_check_passed) process.exitCode = 1;
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/examples/semantic-anchor-receipts/cleaned-paste.md

@@ -0,0 +1,17 @@
+# Upload API v2 migration notes
+
+The `uploadFile` helper changed in v2.4.0. Keep this version note because older snippets still use v1.
+
+```ts
+export async function uploadFile(input: UploadInput): Promise<UploadResult> {
+  return client.files.upload(input)
+}
+```
+
+## Required behavior
+
+- Preserve the retry policy: max 3 attempts with exponential backoff.
+- Do not strip the security constraint: never log raw file contents.
+- Deprecated: `uploadLegacy(path)` is removed after v2.5.0.
+
+Most verbose examples were removed, but the API signature, version notes, and security constraint survive.

package/examples/semantic-anchor-receipts/original-paste.md

@@ -0,0 +1,19 @@
+# Upload API v2 migration notes
+
+The `uploadFile` helper changed in v2.4.0. Keep this version note because older snippets still use v1.
+
+```ts
+export async function uploadFile(input: UploadInput): Promise<UploadResult> {
+  return client.files.upload(input)
+}
+```
+
+## Required behavior
+
+- Preserve the retry policy: max 3 attempts with exponential backoff.
+- Do not strip the security constraint: never log raw file contents.
+- Deprecated: `uploadLegacy(path)` is removed after v2.5.0.
+
+Most examples below are verbose and can be compressed before pasting into Claude Code once the important anchors are checked.
+
+Long example narrative: in staging we saw several users retry uploads manually after a network timeout, then paste screenshots and unrelated logs into the issue. The cleaned context does not need every anecdote, every repeated stack frame, or every copy of the same explanatory paragraph. It only needs enough surrounding language for the agent to understand the migration target after the anchors above are preserved. Remove repeated examples, duplicated support notes, and verbose operational chatter before the paste enters the session.

package/examples/semantic-anchor-receipts/sample-receipt.json

@@ -0,0 +1,62 @@
+{
+  "schema": "pluribus.semantic_anchor_preservation_receipt.v1",
+  "source_type": "paste-cleaning-skill-or-cli-output",
+  "original_ref": "original-paste.md",
+  "cleaned_ref": "cleaned-paste.md",
+  "approximate_tokens_before": 224,
+  "approximate_tokens_after": 110,
+  "approximate_reduction_percent": 50.9,
+  "raw_source_logged": false,
+  "anchor_detection_policy": [
+    "headings",
+    "code_fences",
+    "api_signatures",
+    "version_or_migration_notes",
+    "must_keep_policy_lines"
+  ],
+  "anchors_total": 9,
+  "anchors_preserved": 9,
+  "anchors_missing": 0,
+  "preserved_anchors": [
+    {
+      "type": "heading",
+      "text": "Upload API v2 migration notes"
+    },
+    {
+      "type": "version_or_migration_note",
+      "text": "The `uploadFile` helper changed in v2.4.0. Keep this version note because older snippets still use v1."
+    },
+    {
+      "type": "api_signature",
+      "text": "export async function uploadFile(input: UploadInput): Promise<UploadResult>"
+    },
+    {
+      "type": "code_fence",
+      "text": "export async function uploadFile(input: UploadInput): Promise<UploadResult> {\n  return client.files.upload(input)\n}",
+      "language": "ts"
+    },
+    {
+      "type": "heading",
+      "text": "Required behavior"
+    },
+    {
+      "type": "must_keep_policy",
+      "text": "## Required behavior"
+    },
+    {
+      "type": "must_keep_policy",
+      "text": "Preserve the retry policy: max 3 attempts with exponential backoff."
+    },
+    {
+      "type": "must_keep_policy",
+      "text": "Do not strip the security constraint: never log raw file contents."
+    },
+    {
+      "type": "version_or_migration_note",
+      "text": "- Deprecated: `uploadLegacy(path)` is removed after v2.5.0."
+    }
+  ],
+  "missing_anchors": [],
+  "semantic_loss_check_passed": true,
+  "token_savings_claim_allowed": true
+}

package/examples/session-preflight-receipts/README.md

@@ -0,0 +1,25 @@
+# Session preflight receipt example
+
+This example is for Cursor/Claude Code/MCP workflows where a project wants a required first step before agent work, such as `session_guard.session_init` or reading `MEMORY.md`.
+
+It turns a behavioral instruction into a reviewable artifact:
+
+1. The rule says the agent must initialize context first.
+2. The receipt records whether the required context was loaded.
+3. The decision says whether the run may proceed, must stay read-only, or should stop.
+
+Copy the sample rule into `.cursor/rules/session-preflight.mdc` and adapt the JSON fields to your local guard/MCP server.
+
+## Try it
+
+```bash
+node -e "const fs=require('fs'); const r=JSON.parse(fs.readFileSync('examples/session-preflight-receipts/session-preflight-receipt.json','utf8')); if (!r.decision.allowed_to_start_work) process.exit(1); console.log(r.schema, r.decision.mode)"
+```
+
+Expected output:
+
+```text
+pluribus.session_preflight_receipt.v1 read_then_patch
+```
+
+This does not enforce Cursor's tool calls by itself. It gives teams a concrete evidence object to ask for when evaluating required-first-tool or pre-tool-hook workflows.

package/examples/session-preflight-receipts/session-preflight-receipt.json

@@ -0,0 +1,39 @@
+{
+  "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:replace-with-non-secret-digest"
+    },
+    {
+      "id": "project-rules",
+      "path": ".cursor/rules/session-preflight.mdc",
+      "status": "loaded",
+      "fingerprint": "sha256:replace-with-non-secret-digest"
+    }
+  ],
+  "tool_surface": {
+    "mcp_servers_seen": ["session-guard", "playwright"],
+    "side_effecting_tools_blocked_until_preflight": ["Shell", "Write"],
+    "read_only_tools_allowed_before_preflight": ["Read"]
+  },
+  "decision": {
+    "allowed_to_start_work": true,
+    "mode": "read_then_patch",
+    "reason": "required project memory and rules were checked before side-effecting tool use"
+  },
+  "privacy": {
+    "raw_context_logged": false,
+    "secrets_logged": false,
+    "fingerprints_only": true
+  }
+}

package/examples/session-preflight-receipts/session-preflight.mdc

@@ -0,0 +1,18 @@
+---
+description: Require a visible session preflight before side-effecting agent work.
+alwaysApply: true
+---
+
+Before using Shell, Write, Apply Patch, or external MCP tools, produce a session preflight receipt.
+
+The receipt must state:
+
+- required first step: `session_guard.session_init` or the local equivalent
+- required context files checked, such as `MEMORY.md`, `AGENTS.md`, `.cursor/rules/*.mdc`, or `CLAUDE.md`
+- whether only read-only tools are allowed before preflight
+- proceed mode: `read_only`, `read_then_patch`, `stop`, or `ask_human`
+- reason for the mode
+
+Do not paste raw memory or secrets into the receipt. Use status and non-secret fingerprints instead.
+
+If the preflight is missing or required context is unavailable, stay in `read_only` mode and ask for the missing context before edits.

package/examples/task-scoped-mcp-config/README.md

@@ -0,0 +1,60 @@
+# Task-scoped MCP config receipt
+
+A tiny demo for the Claude Code / MCP context-bloat complaint: MCP tools can consume context before they are used. One practical workaround is to keep a catalog of MCP server configs and start the agent with a task-specific `--mcp-config` instead of loading every server every time.
+
+This example makes that workaround auditable. It produces:
+
+1. a minimal Claude Code-compatible MCP config for one task; and
+2. a privacy-safe receipt showing which servers were selected, which were withheld, and why.
+
+It deliberately does **not** claim adoption. A selected MCP server is only agent-visible; a later tool-adoption receipt would still be needed to prove the agent called it.
+
+## Run it
+
+```bash
+cd examples/task-scoped-mcp-config
+node select-mcp-config.mjs \
+  --task tasks/browser-debug.json \
+  --out /tmp/browser-debug.mcp.json \
+  --receipt /tmp/browser-debug.receipt.json
+```
+
+Use the generated config with Claude Code or a compatible client:
+
+```bash
+claude --mcp-config /tmp/browser-debug.mcp.json
+```
+
+The demo catalog includes five plausible MCP servers. The `browser-debug` task selects only `playwright` and `context7`, withholding memory, observability, and repo-operation servers for the first pass.
+
+## Receipt shape
+
+The receipt is intentionally low-cardinality:
+
+```json
+{
+  "schema": "pluribus.task_scoped_mcp_config_receipt.v1",
+  "task_id": "browser-debug",
+  "selected_server_ids": ["playwright", "context7"],
+  "withheld_server_ids": ["sentry", "openmemory", "github"],
+  "selected_estimated_schema_tokens": 20000,
+  "withheld_estimated_schema_tokens": 24000,
+  "raw_tool_schemas_logged": false,
+  "adoption_claim_allowed": false
+}
+```
+
+Use it to review the initial context surface:
+
+- Did this task need every MCP server, or only a small subset?
+- Which server descriptions were kept out of the first context window?
+- Are we accidentally claiming “the agent used the tool” when we only proved “the tool was selected into the config”?
+
+## Why this exists
+
+The market signal is not “MCP is bad.” It is that large tool catalogs need two separate proofs:
+
+- **Surface proof:** which tools/servers were made visible for this task?
+- **Adoption proof:** which visible tools were actually called, cited, or used before claims/edits?
+
+This demo covers only the first proof. Pair it with a tool-adoption receipt when you need the second.

package/examples/task-scoped-mcp-config/mcp-catalog.json

@@ -0,0 +1,46 @@
+{
+  "schema": "pluribus.mcp_catalog.v1",
+  "catalogId": "demo-claude-code-mcp-catalog",
+  "servers": [
+    {
+      "id": "playwright",
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"],
+      "category": "browser_automation",
+      "estimatedSchemaTokens": 11800,
+      "taskTags": ["browser", "web-debug", "e2e"]
+    },
+    {
+      "id": "context7",
+      "command": "npx",
+      "args": ["@upstash/context7-mcp@latest"],
+      "category": "docs_lookup",
+      "estimatedSchemaTokens": 8200,
+      "taskTags": ["docs", "api-reference"]
+    },
+    {
+      "id": "sentry",
+      "command": "npx",
+      "args": ["@sentry/mcp-server@latest"],
+      "category": "observability",
+      "estimatedSchemaTokens": 9700,
+      "taskTags": ["errors", "production-debug"]
+    },
+    {
+      "id": "openmemory",
+      "command": "npx",
+      "args": ["openmemory-mcp@latest"],
+      "category": "memory",
+      "estimatedSchemaTokens": 6900,
+      "taskTags": ["memory", "recall"]
+    },
+    {
+      "id": "github",
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-github@latest"],
+      "category": "repo_ops",
+      "estimatedSchemaTokens": 7400,
+      "taskTags": ["issues", "pull-requests", "repo"]
+    }
+  ]
+}

package/examples/task-scoped-mcp-config/select-mcp-config.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const args = new Map();
+for (let i = 2; i < process.argv.length; i += 1) {
+  const key = process.argv[i];
+  const value = process.argv[i + 1];
+  if (!key.startsWith('--') || value === undefined || value.startsWith('--')) {
+    throw new Error(`Expected --key value, got ${key}`);
+  }
+  args.set(key.slice(2), value);
+  i += 1;
+}
+
+const taskPath = args.has('task') ? resolve(process.cwd(), args.get('task')) : resolve(here, 'tasks/browser-debug.json');
+const catalogPath = args.has('catalog') ? resolve(process.cwd(), args.get('catalog')) : resolve(here, 'mcp-catalog.json');
+const outPath = args.has('out') ? resolve(process.cwd(), args.get('out')) : null;
+const receiptPath = args.has('receipt') ? resolve(process.cwd(), args.get('receipt')) : null;
+
+const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
+const task = JSON.parse(readFileSync(taskPath, 'utf8'));
+const servers = new Map(catalog.servers.map((server) => [server.id, server]));
+const missing = task.includeServerIds.filter((id) => !servers.has(id));
+if (missing.length) {
+  throw new Error(`Task references unknown server ids: ${missing.join(', ')}`);
+}
+
+const selected = task.includeServerIds.map((id) => servers.get(id));
+const withheld = catalog.servers.filter((server) => !task.includeServerIds.includes(server.id));
+const mcpServers = Object.fromEntries(
+  selected.map((server) => [
+    server.id,
+    {
+      command: server.command,
+      args: server.args,
+    },
+  ]),
+);
+
+const config = { mcpServers };
+const receipt = {
+  schema: 'pluribus.task_scoped_mcp_config_receipt.v1',
+  task_id: task.taskId,
+  catalog_id: catalog.catalogId,
+  selected_server_ids: selected.map((server) => server.id),
+  withheld_server_ids: withheld.map((server) => server.id),
+  selected_estimated_schema_tokens: selected.reduce((sum, server) => sum + server.estimatedSchemaTokens, 0),
+  withheld_estimated_schema_tokens: withheld.reduce((sum, server) => sum + server.estimatedSchemaTokens, 0),
+  selection_reason: task.description,
+  withheld_reason: task.excludeReason,
+  raw_tool_schemas_logged: false,
+  raw_prompts_logged: false,
+  raw_tool_outputs_logged: false,
+  adoption_claim_allowed: false,
+  note: 'This proves only the task-scoped MCP config surface. It does not prove that the agent later called or adopted the selected tools.',
+};
+
+if (outPath) writeFileSync(outPath, `${JSON.stringify(config, null, 2)}\n`);
+if (receiptPath) writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+
+console.log(JSON.stringify({ ok: true, config, receipt }, null, 2));

package/examples/task-scoped-mcp-config/tasks/browser-debug.json

@@ -0,0 +1,7 @@
+{
+  "schema": "pluribus.mcp_task_profile.v1",
+  "taskId": "browser-debug",
+  "description": "Debug a failing browser flow and look up one library API while keeping unrelated memory/observability/repo tools out of the initial context.",
+  "includeServerIds": ["playwright", "context7"],
+  "excludeReason": "Not needed for this task's first pass; load a different --mcp-config if the task changes."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.41",
+  "version": "0.3.42",
   "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/commands/demo.js

@@ -12,7 +12,8 @@ const SKILL_USE_RATE_DEMO = 'skill-use-rate'
 const MCP_AUDIT_RECEIPT_DEMO = 'mcp-audit-receipt'
 const MCP_TELEMETRY_IMPORT_DEMO = 'mcp-telemetry-import'
 const TOOL_SURFACE_DIFF_DEMO = 'tool-surface-diff'
-const AVAILABLE_DEMOS = [SKILL_USE_RATE_DEMO, MCP_AUDIT_RECEIPT_DEMO, MCP_TELEMETRY_IMPORT_DEMO, TOOL_SURFACE_DIFF_DEMO]
+const CONTEXT_SUFFICIENCY_TRACE_DEMO = 'context-sufficiency-trace'
+const AVAILABLE_DEMOS = [SKILL_USE_RATE_DEMO, MCP_AUDIT_RECEIPT_DEMO, MCP_TELEMETRY_IMPORT_DEMO, TOOL_SURFACE_DIFF_DEMO, CONTEXT_SUFFICIENCY_TRACE_DEMO]
 const SKILL_USE_RATE_SCHEMA = 'pluribus.skill_use_rate_receipt.v1'
 const MCP_AUDIT_RECEIPT_SCHEMA = 'pluribus.mcp_tool_call_audit_receipt.v1'
 const TOOL_SURFACE_DIFF_SCHEMA = 'pluribus.mcp_tool_surface_diff_receipt.v1'
@@ -33,6 +34,8 @@ export async function runDemo(args, positional = []) {
       return runMcpTelemetryImportDemo(args)
     case TOOL_SURFACE_DIFF_DEMO:
       return runToolSurfaceDiffDemo(args)
+    case CONTEXT_SUFFICIENCY_TRACE_DEMO:
+      return runContextSufficiencyTraceDemo(args)
     default:
       console.error(`❌ Unknown demo: ${demoName}`)
       console.error(`   Available demos: ${AVAILABLE_DEMOS.join(', ')}`)
@@ -196,6 +199,18 @@ function bundledToolSurfaceDiffReceiptPath() {
   return fileURLToPath(new URL('../../examples/tool-surface-diff-receipts/tool-surface-diff-receipt.json', import.meta.url))
 }
 
+function bundledContextSufficiencyGroundTruthPath() {
+  return fileURLToPath(new URL('../../examples/context-sufficiency-trace/ground-truth.json', import.meta.url))
+}
+
+function bundledContextSufficiencyTracePath() {
+  return fileURLToPath(new URL('../../examples/context-sufficiency-trace/context-trace.json', import.meta.url))
+}
+
+function bundledContextSufficiencyPassTracePath() {
+  return fileURLToPath(new URL('../../examples/context-sufficiency-trace/context-trace-pass.json', import.meta.url))
+}
+
 function runToolSurfaceDiffDemo(args) {
   const receiptPath = selectedReceiptPath(args, bundledToolSurfaceDiffReceiptPath())
   const receipt = readReceipt(receiptPath, 'tool-surface diff')
@@ -230,6 +245,71 @@ function runToolSurfaceDiffDemo(args) {
   if (result.errors.length > 0) process.exit(1)
 }
 
+function runContextSufficiencyTraceDemo(args) {
+  const truthPath = typeof args.receipt === 'string' && args.receipt.trim()
+    ? path.resolve(process.cwd(), args.receipt)
+    : bundledContextSufficiencyGroundTruthPath()
+  const tracePath = typeof args.input === 'string' && args.input.trim()
+    ? path.resolve(process.cwd(), args.input)
+    : (Boolean(args.pass) ? bundledContextSufficiencyPassTracePath() : bundledContextSufficiencyTracePath())
+
+  const truth = readReceipt(truthPath, 'context sufficiency ground-truth')
+  const trace = readReceipt(tracePath, 'context trace')
+  const result = validateContextSufficiencyTrace(truth, trace)
+
+  if (Boolean(args.json)) {
+    console.log(JSON.stringify({
+      ok: result.verdict === 'pass',
+      demo: CONTEXT_SUFFICIENCY_TRACE_DEMO,
+      groundTruth: path.relative(process.cwd(), truthPath) || truthPath,
+      trace: path.relative(process.cwd(), tracePath) || tracePath,
+      summary: result,
+    }, null, 2))
+  } else {
+    console.log('🧪 Pluribus demo: context sufficiency trace')
+    console.log(`   Ground truth: ${path.relative(process.cwd(), truthPath) || truthPath}`)
+    console.log(`   Trace: ${path.relative(process.cwd(), tracePath) || tracePath}`)
+    console.log('')
+
+    const mark = result.verdict === 'pass' ? '✅' : '❌'
+    console.log(`${mark} context sufficiency ${result.verdict}: gold_context_recall=${result.gold_context_recall}, missed_required_file_rate=${result.missed_required_file_rate}, late_context_rate=${result.late_context_rate}`)
+    if (result.missed_required_files.length > 0) console.log(`   • missed_required_files: ${result.missed_required_files.join(', ')}`)
+    if (result.frontier_cut_misses.length > 0) console.log(`   • frontier_cut_misses: ${result.frontier_cut_misses.join(', ')}`)
+    console.log('')
+    console.log('Why this matters: context compression is only safe if the reduced bundle still contains the files/symbols the task ground truth requires before editing starts.')
+    console.log('Try your own trace: pluribus demo context-sufficiency-trace --receipt ground-truth.json --input context-trace.json --json')
+  }
+
+  if (result.verdict !== 'pass') process.exit(1)
+}
+
+export function validateContextSufficiencyTrace(truth, trace) {
+  const required = new Set(Array.isArray(truth.required_files) ? truth.required_files : [])
+  const returned = new Set((Array.isArray(trace.returned_files) ? trace.returned_files : []).map((file) => file.path).filter(Boolean))
+  const frontierCut = new Set((Array.isArray(trace.frontier_cut) ? trace.frontier_cut : []).map((file) => file.path).filter(Boolean))
+  const late = new Set((Array.isArray(trace.late_files) ? trace.late_files : []).map((file) => file.path).filter(Boolean))
+
+  const requiredList = [...required]
+  const returnedRequired = requiredList.filter((filePath) => returned.has(filePath))
+  const missedRequired = requiredList.filter((filePath) => !returned.has(filePath))
+  const frontierCutMisses = missedRequired.filter((filePath) => frontierCut.has(filePath))
+  const lateMisses = missedRequired.filter((filePath) => late.has(filePath))
+
+  const ratio = (count, total) => (total === 0 ? 0 : Number((count / total).toFixed(4)))
+  return {
+    task_id: truth.task_id || 'unknown-task',
+    trace_id: trace.trace_id || 'unknown-trace',
+    required_files: requiredList.length,
+    returned_files: returned.size,
+    gold_context_recall: ratio(returnedRequired.length, requiredList.length),
+    missed_required_file_rate: ratio(missedRequired.length, requiredList.length),
+    late_context_rate: ratio(lateMisses.length, requiredList.length),
+    missed_required_files: missedRequired,
+    frontier_cut_misses: frontierCutMisses,
+    verdict: missedRequired.length === 0 ? 'pass' : 'fail',
+  }
+}
+
 export function validateSkillUseRateReceipt(receipt) {
   const errors = []
   const warnings = []

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.41'
+export const VERSION = '0.3.42'