pluribus-context 0.3.34 → 0.3.36

package/examples/skill-use-rate-receipts/skill-use-rate-receipt.json

@@ -0,0 +1,79 @@
+{
+  "schema": "pluribus.skill_use_rate_receipt.v1",
+  "run_id": "skills-audit-2026-06-05T13:00Z",
+  "generated_at": "2026-06-05T13:00:00Z",
+  "installer": {
+    "name": "skills",
+    "version": "1.5.9",
+    "command_digest": "sha256:4c2b31d9f1e3a1a5f94c2c65d18f0a9b0c3d14a1c6a4f8cbb6e8f0b2a118f001"
+  },
+  "window": {
+    "started_at": "2026-05-22T00:00:00Z",
+    "ended_at": "2026-06-05T13:00:00Z"
+  },
+  "skills": [
+    {
+      "skill_id": "frontend-design",
+      "source_ref": "github:vercel-labs/agent-skills/skills/frontend-design@main",
+      "target_agent": "claude-code",
+      "scope": "project",
+      "install_method": "symlink",
+      "discovered": true,
+      "installed": true,
+      "attached": true,
+      "invoked_count": 7,
+      "acted_on_count": 3,
+      "last_invoked_at": "2026-06-05T10:12:08Z",
+      "unused_since_install": false,
+      "context_cost_bucket": "small",
+      "evidence": [
+        {
+          "kind": "session_log_digest",
+          "ref": "sha256:0b7d7a9f2950f5e4ab8d9ab2f93e71875a995ee3878d0d595c8a65f8d7bf0c4d"
+        }
+      ]
+    },
+    {
+      "skill_id": "rust-lsp-helper",
+      "source_ref": "github:example-org/agent-skills/skills/rust-lsp-helper@v1.2.0",
+      "target_agent": "claude-code",
+      "scope": "global",
+      "install_method": "copy",
+      "discovered": true,
+      "installed": true,
+      "attached": true,
+      "invoked_count": 0,
+      "acted_on_count": 0,
+      "last_invoked_at": null,
+      "unused_since_install": true,
+      "context_cost_bucket": "medium",
+      "evidence": [
+        {
+          "kind": "installer_lock_digest",
+          "ref": "sha256:d25b0ddca0d6b8ac8705cc1e845351f5f5a3971b982be9dc6eeb3aadc5a83a54"
+        }
+      ]
+    },
+    {
+      "skill_id": "code-review-xhigh",
+      "source_ref": "builtin:claude-code/code-review@2.1.152",
+      "target_agent": "claude-code",
+      "scope": "builtin",
+      "install_method": "builtin",
+      "discovered": true,
+      "installed": true,
+      "attached": true,
+      "invoked_count": 12,
+      "acted_on_count": 9,
+      "last_invoked_at": "2026-06-05T12:40:01Z",
+      "unused_since_install": false,
+      "context_cost_bucket": "unknown",
+      "evidence": [
+        {
+          "kind": "review_report_digest",
+          "ref": "sha256:8f489e2b0d3539b17f3d0b6ebc68bf1c9d68022c6ea086b6a3636b107a42f9f4"
+        }
+      ]
+    }
+  ]
+}

package/examples/subagent-role-receipts/README.md

@@ -0,0 +1,15 @@
+# Subagent role receipts example
+
+This directory contains a small `agents.toml` example for teams experimenting with project-local subagent roles.
+
+The important artifact is not the exact TOML dialect. The important artifact is the receipt that proves the role boundary:
+
+- requested role vs effective role;
+- role source and coarse hash/version;
+- whether role instructions loaded;
+- allowed/refused write and tool capabilities;
+- boundary decisions made by the role;
+- where the role stopped and the next safe action;
+- privacy flags excluding raw prompts, code, transcripts, secrets, customer data, and raw tool output.
+
+See [`../../docs/subagent-role-receipts.md`](../../docs/subagent-role-receipts.md) for the full recipe.

package/examples/subagent-role-receipts/agents.toml

@@ -0,0 +1,36 @@
+# Example only: adapt field names and location to the subagent runner you use.
+# The stable idea is the receipt, not this exact TOML dialect.
+
+[[agents]]
+name = "blast-radius-reviewer"
+description = "Reviews AI-generated PRs by operational blast radius before merge."
+model = "default"
+tools = ["read", "grep", "test-summary"]
+writes_allowed = false
+instructions = """
+Review by blast radius, not diff size.
+
+Require explicit evidence for:
+- schema or persisted data contracts;
+- live reader/writer compatibility;
+- async jobs, queues, cron, webhooks, and retries;
+- rollout gates, feature flags, or kill switches;
+- external side effects such as email, payments, auth, billing, analytics, or third-party APIs;
+- generated files, public APIs, plugin manifests, MCP/Skill/hook configuration.
+
+Do not approve merge when any high-risk boundary is ambiguous. Emit a privacy-safe review.blast_radius.v1 or subagent.role_boundary.v1 receipt instead of logging raw source, prompts, transcripts, or tool output.
+"""
+
+[[agents]]
+name = "temporal-authority-checker"
+description = "Checks whether matched docs/specs are current authority or historical citations before edits."
+model = "default"
+tools = ["read", "grep"]
+writes_allowed = false
+instructions = """
+Before code changes, identify the current authority source and any historical/superseded specs.
+
+Refuse writes when two sources conflict and neither one declares status, date, scope, or superseded_by metadata. Emit a privacy-safe context.temporal_authority.v1 or subagent.role_boundary.v1 receipt with coarse document names, status, decision, stopped_at, and next_safe_action.
+
+Do not log raw prompts, source code, private paths, transcripts, secrets, or customer data.
+"""

package/examples/temporal-context-receipts/CURRENT_STATE.md

@@ -0,0 +1,13 @@
+# Current state
+
+## checkout-flow
+
+- status: current
+- as_of: 2026-05-28
+- current authority: this section
+- scope: checkout-flow
+- related historical specs:
+  - `specs/2025-checkout-rewrite.md` — superseded; rationale only
+  - `specs/2026-checkout-risk-notes.md` — current supporting context
+
+Agents may cite superseded specs for rationale, but must not implement from them unless this file explicitly reactivates that behavior.

package/examples/temporal-context-receipts/specs/2025-checkout-rewrite.md

@@ -0,0 +1,10 @@
+---
+status: superseded
+scope: checkout-flow
+date: 2025-11-10
+superseded_by: ../CURRENT_STATE.md#checkout-flow
+---
+
+# 2025 checkout rewrite
+
+Historical note. This file is kept for rationale only and is not implementation authority.

package/examples/temporal-context-receipts/specs/2026-checkout-risk-notes.md

@@ -0,0 +1,10 @@
+---
+status: current
+scope: checkout-flow
+date: 2026-05-20
+superseded_by: null
+---
+
+# 2026 checkout risk notes
+
+Current supporting context for known risk areas. Use together with `CURRENT_STATE.md`.

package/examples/temporal-context-receipts/temporal-authority-receipt.json

@@ -0,0 +1,27 @@
+{
+  "receipt_type": "context.temporal_authority.v1",
+  "request_id": "local-run-2026-05-28T16:00Z",
+  "current_authority": {
+    "file": "CURRENT_STATE.md",
+    "status": "current",
+    "as_of": "2026-05-28",
+    "scope": "checkout-flow"
+  },
+  "sources_considered": [
+    {
+      "file": "specs/2025-checkout-rewrite.md",
+      "status": "superseded",
+      "superseded_by": "CURRENT_STATE.md#checkout-flow",
+      "decision": "historical_citation_only"
+    },
+    {
+      "file": "specs/2026-checkout-risk-notes.md",
+      "status": "current",
+      "scope": "checkout-flow",
+      "decision": "allowed_as_supporting_context"
+    }
+  ],
+  "ambiguous_sources": [],
+  "write_started": true,
+  "stopped_at": "temporal_authority_resolved"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.34",
+  "version": "0.3.36",
   "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

@@ -0,0 +1,155 @@
+/**
+ * pluribus demo — run tiny packaged demos from npm without cloning the repo.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { fileURLToPath } from 'url'
+
+const DEFAULT_DEMO = 'skill-use-rate'
+const SKILL_USE_RATE_SCHEMA = 'pluribus.skill_use_rate_receipt.v1'
+
+/**
+ * @param {Record<string, string | boolean>} args
+ * @param {string[]} positional
+ */
+export async function runDemo(args, positional = []) {
+  const demoName = positional[0] || DEFAULT_DEMO
+
+  if (demoName !== DEFAULT_DEMO) {
+    console.error(`❌ Unknown demo: ${demoName}`)
+    console.error('   Available demos: skill-use-rate')
+    process.exit(1)
+  }
+
+  const receiptPath = typeof args.receipt === 'string' && args.receipt.trim()
+    ? path.resolve(process.cwd(), args.receipt)
+    : bundledSkillUseRateReceiptPath()
+
+  let receipt
+  try {
+    receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
+  } catch (err) {
+    console.error(`❌ Could not read skill use-rate receipt at ${receiptPath}: ${err.message}`)
+    process.exit(1)
+  }
+
+  const result = validateSkillUseRateReceipt(receipt)
+  if (Boolean(args.json)) {
+    console.log(JSON.stringify({
+      ok: result.errors.length === 0,
+      demo: DEFAULT_DEMO,
+      receipt: path.relative(process.cwd(), receiptPath) || receiptPath,
+      summary: result.summary,
+      warnings: result.warnings,
+      errors: result.errors,
+    }, null, 2))
+  } else {
+    console.log('🧪 Pluribus demo: skill use-rate receipt')
+    console.log(`   Receipt: ${path.relative(process.cwd(), receiptPath) || receiptPath}`)
+    console.log('')
+
+    if (result.errors.length === 0) {
+      const warningLabel = result.warnings.length === 1 ? 'warning' : 'warnings'
+      console.log(`✅ skill use-rate receipt ok: ${result.summary.skillCount} skills checked, ${result.warnings.length} unused install ${warningLabel}`)
+      for (const warning of result.warnings) console.log(`   • ${warning}`)
+      console.log('')
+      console.log('Why this matters: installed is not used. Track discovered → installed/attached → invoked → acted-on before paying context cost for dormant skills.')
+      console.log('Try your own receipt: pluribus demo skill-use-rate --receipt path/to/skill-use-rate-receipt.json')
+    } else {
+      console.error('❌ skill use-rate receipt invalid:')
+      for (const error of result.errors) console.error(`   • ${error}`)
+    }
+  }
+
+  if (result.errors.length > 0) process.exit(1)
+}
+
+function bundledSkillUseRateReceiptPath() {
+  return fileURLToPath(new URL('../../examples/skill-use-rate-receipts/skill-use-rate-receipt.json', import.meta.url))
+}
+
+export function validateSkillUseRateReceipt(receipt) {
+  const errors = []
+  const warnings = []
+
+  function requireString(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+      errors.push(`${field} must be a non-empty string`)
+    }
+  }
+
+  function requireBoolean(value, field) {
+    if (typeof value !== 'boolean') {
+      errors.push(`${field} must be boolean`)
+    }
+  }
+
+  function requireNonNegativeInteger(value, field) {
+    if (!Number.isInteger(value) || value < 0) {
+      errors.push(`${field} must be a non-negative integer`)
+    }
+  }
+
+  if (receipt.schema !== SKILL_USE_RATE_SCHEMA) {
+    errors.push(`schema must be ${SKILL_USE_RATE_SCHEMA}`)
+  }
+
+  requireString(receipt.run_id, 'run_id')
+  requireString(receipt.generated_at, 'generated_at')
+  requireString(receipt.installer?.name, 'installer.name')
+  requireString(receipt.window?.started_at, 'window.started_at')
+  requireString(receipt.window?.ended_at, 'window.ended_at')
+
+  if (!Array.isArray(receipt.skills) || receipt.skills.length === 0) {
+    errors.push('skills must be a non-empty array')
+  }
+
+  for (const [index, skill] of (receipt.skills || []).entries()) {
+    const prefix = `skills[${index}]`
+    requireString(skill.skill_id, `${prefix}.skill_id`)
+    requireString(skill.source_ref, `${prefix}.source_ref`)
+    requireString(skill.target_agent, `${prefix}.target_agent`)
+    requireString(skill.scope, `${prefix}.scope`)
+    requireString(skill.install_method, `${prefix}.install_method`)
+    requireBoolean(skill.discovered, `${prefix}.discovered`)
+    requireBoolean(skill.installed, `${prefix}.installed`)
+    requireBoolean(skill.attached, `${prefix}.attached`)
+    requireBoolean(skill.unused_since_install, `${prefix}.unused_since_install`)
+    requireNonNegativeInteger(skill.invoked_count, `${prefix}.invoked_count`)
+    requireNonNegativeInteger(skill.acted_on_count, `${prefix}.acted_on_count`)
+
+    if (Number.isInteger(skill.acted_on_count) && Number.isInteger(skill.invoked_count) && skill.acted_on_count > skill.invoked_count) {
+      errors.push(`${prefix}.acted_on_count cannot exceed invoked_count`)
+    }
+
+    if (skill.installed && skill.attached && skill.invoked_count === 0) {
+      if (skill.unused_since_install !== true) {
+        errors.push(`${prefix}.unused_since_install must be true when installed/attached but never invoked`)
+      }
+      warnings.push(`${skill.skill_id || prefix} is installed/attached but has 0 invocations in this window`)
+    }
+
+    if (skill.invoked_count > 0) {
+      if (skill.unused_since_install !== false) {
+        errors.push(`${prefix}.unused_since_install must be false when invoked_count > 0`)
+      }
+      if (typeof skill.last_invoked_at !== 'string' || skill.last_invoked_at.trim() === '') {
+        errors.push(`${prefix}.last_invoked_at must be set when invoked_count > 0`)
+      }
+    }
+
+    if (!Array.isArray(skill.evidence) || skill.evidence.length === 0) {
+      errors.push(`${prefix}.evidence must include at least one privacy-safe evidence ref`)
+    }
+  }
+
+  return {
+    errors,
+    warnings,
+    summary: {
+      skillCount: Array.isArray(receipt.skills) ? receipt.skills.length : 0,
+      unusedInstallCount: warnings.length,
+    },
+  }
+}

package/src/index.js

@@ -7,6 +7,7 @@ export { runSync } from './commands/sync.js'
 export { runValidate } from './commands/validate.js'
 export { runWatch } from './commands/watch.js'
 export { runAudit } from './commands/audit.js'
+export { runDemo, validateSkillUseRateReceipt } from './commands/demo.js'
 export { parsePluribusFile, validateSections } from './utils/parser.js'
 export { renderTemplate } from './utils/renderer.js'
 export { BUILT_IN_SKILLS, SUPPORTED_TOOLS } from './skills/built-in.js'

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.34'
+export const VERSION = '0.3.36'