pluribus-context 0.3.14 → 0.3.16

package/CHANGELOG.md

@@ -4,6 +4,20 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.16 — audit fidelity evidence
+
+### Added
+
+- Add `pluribus audit --fidelity-report` so maintainers can emit target-by-target portability evidence in JSON or human output: represented sections, unsupported sections, activation shape, warnings, and the next step before claiming a rule/skill bundle is universal.
+- Update the portability fidelity report guide to use `audit --json --fidelity-report` as the reproducible evidence artifact for directory reviewers and rule/skill bundle maintainers.
+
+## 0.3.15 — portability fidelity report demo
+
+### Added
+
+- Add a portability fidelity report guide and example for AI rule/skill bundle maintainers who need evidence-based compatibility claims across `CLAUDE.md`, Cursor, Copilot, and `AGENTS.md` outputs.
+- Link the new report from the README so directory reviewers and skill/rule authors can test portability claims without treating `universal` as a self-attested boolean.
+
 ## 0.3.14 — coordination contract demo
 
 ### Added

package/README.md

@@ -152,7 +152,7 @@ npx --yes pluribus-context@latest sync --dry-run
 
 If the preview looks right, run `npx --yes pluribus-context@latest sync` to write the tool-specific files.
 
-For a fuller walkthrough, see the [Quickstart](docs/quickstart.md). To enforce generated context files in pull requests, use the [CI audit example](docs/ci-audit-example.md); to catch drift before commits leave your machine, use the [Pre-commit Audit Hook](docs/pre-commit-audit.md). If your repo already has `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, run a [Context Drift Audit](docs/context-drift-audit.md) first, try the intentionally drifted [audit example](examples/context-drift-audit/), then follow [Migrate Existing AI Context Files](docs/migrate-existing-context.md). If you switch between Cursor, Claude Code, Copilot, and terminal agents, try the [Cursor ↔ Claude Code context handoff guide](docs/cursor-claude-context-handoff.md) and its [example source file](examples/context-handoff/pluribus.md). If you run multiple AI sessions on the same project, try the [Coordination Contract guide](docs/coordination-contract.md) and its [example source file](examples/coordination-contract/pluribus.md) to keep event-log/scratchpad protocol rules aligned without turning Pluribus into an orchestrator. Before committing shared or generated AI instructions, use the [Context File Review Checklist](docs/context-file-review.md). If you're deciding between Pluribus and a one-way rules converter, see [When to use Pluribus](docs/when-to-use-pluribus.md). If you are debugging "context drift" after compaction or long sessions, start with the [Context Drift Taxonomy](docs/context-drift-taxonomy.md) to separate file drift from runtime precedence drift. If you use MCP memory or knowledge-graph tools, try the [MCP memory handoff demo](docs/memory-mcp-handoff.md) to keep recall/store protocols aligned across AI coding tools without turning Pluribus into a memory server. If you are reviewing Pluribus for a list, newsletter, or tool directory, use the [Community Review Packet](docs/community-review-packet.md) for directory submission fields, a one-line description, safety notes, and a disposable 60-second smoke test. Maintainers can track package/repo discovery with the [Discovery Smoke Checks](docs/discovery-smoke.md).
+For a fuller walkthrough, see the [Quickstart](docs/quickstart.md). To enforce generated context files in pull requests, use the [CI audit example](docs/ci-audit-example.md); to catch drift before commits leave your machine, use the [Pre-commit Audit Hook](docs/pre-commit-audit.md). If your repo already has `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, run a [Context Drift Audit](docs/context-drift-audit.md) first, try the intentionally drifted [audit example](examples/context-drift-audit/), then follow [Migrate Existing AI Context Files](docs/migrate-existing-context.md). If you switch between Cursor, Claude Code, Copilot, and terminal agents, try the [Cursor ↔ Claude Code context handoff guide](docs/cursor-claude-context-handoff.md) and its [example source file](examples/context-handoff/pluribus.md). If you run multiple AI sessions on the same project, try the [Coordination Contract guide](docs/coordination-contract.md) and its [example source file](examples/coordination-contract/pluribus.md) to keep event-log/scratchpad protocol rules aligned without turning Pluribus into an orchestrator. If you publish AI rules, skills, or instruction bundles as "portable", use the [Portability Fidelity Report](docs/portability-fidelity-report.md) and its [example source file](examples/portability-fidelity/pluribus.md) to make compatibility claims evidence-based instead of self-attested. Before committing shared or generated AI instructions, use the [Context File Review Checklist](docs/context-file-review.md). If you're deciding between Pluribus and a one-way rules converter, see [When to use Pluribus](docs/when-to-use-pluribus.md). If you are debugging "context drift" after compaction or long sessions, start with the [Context Drift Taxonomy](docs/context-drift-taxonomy.md) to separate file drift from runtime precedence drift. If you use MCP memory or knowledge-graph tools, try the [MCP memory handoff demo](docs/memory-mcp-handoff.md) to keep recall/store protocols aligned across AI coding tools without turning Pluribus into a memory server. If you are reviewing Pluribus for a list, newsletter, or tool directory, use the [Community Review Packet](docs/community-review-packet.md) for directory submission fields, a one-line description, safety notes, and a disposable 60-second smoke test. Maintainers can track package/repo discovery with the [Discovery Smoke Checks](docs/discovery-smoke.md).
 
 ### Usage
 

package/bin/pluribus.js

@@ -55,6 +55,7 @@ OPTIONS (audit)
   --json          Print machine-readable audit results
   --output        Write --json results to a file instead of stdout
   --github-annotations  Print GitHub Actions annotations for drift/missing outputs
+  --fidelity-report  Include portability/fidelity evidence for selected targets
 
 OPTIONS (watch)
   --source        Path to pluribus.md (default: ./pluribus.md)
@@ -78,6 +79,7 @@ EXAMPLES
   pluribus audit --json
   pluribus audit --strict --json --output pluribus-audit.json
   pluribus audit --strict --github-annotations
+  pluribus audit --json --fidelity-report
   pluribus watch --tools claude,cursor
 
 DOCS
@@ -88,7 +90,7 @@ const COMMAND_FLAGS = {
   init: new Set(['name', 'description', 'tools', 'dry-run']),
   sync: new Set(['dry-run', 'tools', 'source', 'update-imports']),
   validate: new Set(['source', 'update-imports']),
-  audit: new Set(['source', 'tools', 'update-imports', 'strict', 'ci', 'json', 'output', 'github-annotations']),
+  audit: new Set(['source', 'tools', 'update-imports', 'strict', 'ci', 'json', 'output', 'github-annotations', 'fidelity-report']),
   watch: new Set(['source', 'tools', 'update-imports', 'dry-run', 'once', 'debounce']),
 }
 

package/docs/portability-fidelity-report.md

@@ -0,0 +1,95 @@
+# Portability Fidelity Report
+
+Use this when a rule pack, skill bundle, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or Copilot instruction file claims to be portable across AI coding tools.
+
+The goal is not to prove that every tool behaves identically. The goal is to make portability claims falsifiable: which tools were tested, which capabilities are required, where semantics are lossy, and what evidence a reviewer can inspect.
+
+This pattern came from live market signals around AI skills and rule bundles: authors want to mark instructions as "universal", but tool capabilities, file loading rules, write APIs, glob semantics, and security defaults differ enough that a boolean label can hide silent semantic loss.
+
+## 60-second disposable check
+
+Try the example without touching a real repo:
+
+```bash
+git clone https://github.com/caioribeiroclw-pixel/pluribus.git
+cd pluribus/examples/portability-fidelity
+node ../../bin/pluribus.js validate
+node ../../bin/pluribus.js sync --dry-run
+node ../../bin/pluribus.js audit --json --fidelity-report
+```
+
+For the npm release path, copy `examples/portability-fidelity/pluribus.md` into a temporary directory as `pluribus.md`, then run:
+
+```bash
+npx --yes pluribus-context@latest validate
+npx --yes pluribus-context@latest sync --dry-run
+npx --yes pluribus-context@latest audit --json --fidelity-report
+```
+
+## What a claim should say
+
+Avoid this:
+
+```yaml
+portable: true
+```
+
+Prefer claims that include evidence and known loss:
+
+```yaml
+portability:
+  tier: portable-with-adapters
+  testedOn:
+    - target: claude-code
+      evidence: generated CLAUDE.md smoke-reviewed on 2026-05-18
+    - target: cursor
+      evidence: generated .cursorrules smoke-reviewed on 2026-05-18
+    - target: github-copilot
+      evidence: generated .github/copilot-instructions.md smoke-reviewed on 2026-05-18
+  requiredCapabilities:
+    - read repository instructions before planning
+    - preserve generated-file warning
+    - respect security constraints before edits
+  knownLossyTargets:
+    - target: flat-markdown-targets
+      loss: cannot represent Cursor-style path/glob activation; keep scoped rules tool-native or annotate the loss
+```
+
+In Pluribus, keep that claim inside the source file so every generated output carries the same reviewable contract.
+
+## Decision rule
+
+A rule/skill/context bundle is portable only when a maintainer can answer four questions from the repo:
+
+1. **Capability:** what does the instruction require from the target tool?
+2. **Evidence:** where was that target actually rendered or smoke-tested?
+3. **Loss:** which semantics are degraded, flattened, or unsupported?
+4. **Fallback:** what should a user do when a target lacks the capability?
+
+If any answer is missing, use a narrower label such as `project-local`, `target-native`, or `portable-with-loss` instead of `universal`.
+
+## How Pluribus helps
+
+Pluribus is intentionally narrower than a skill registry or memory layer:
+
+- `pluribus.md` keeps the claim in one reviewed source of truth.
+- `sync --dry-run` previews target-specific outputs before writing files.
+- generated files carry a warning header so manual edits are visible.
+- `audit --json --fidelity-report` gives CI/reviewers a machine-readable check for missing/drifted outputs plus target-by-target section loss, activation shape, and portability warnings.
+- remote imports are opt-in, locked, cached, and digest-checked before becoming shared context.
+
+That does **not** prove runtime behavior. You still need tool-specific smoke tests for load order, path/glob activation, available tools, MCP servers, and permission semantics.
+
+## Suggested workflow for maintainers
+
+1. Put the portability claim in the canonical source.
+2. Generate target outputs with `sync --dry-run` and inspect semantic loss.
+3. Keep target-native instructions when a semantic cannot be represented everywhere.
+4. Commit a small audit artifact (`pluribus audit --json --fidelity-report --output reports/pluribus-audit.json`) when you want CI/review evidence.
+5. Update the claim whenever a new target is added, a tool changes capability names, or a permission/security default changes.
+
+## Feedback wanted
+
+If your rule pack, skill bundle, or instruction manifest needs a different evidence shape, open a focused issue: https://github.com/caioribeiroclw-pixel/pluribus/issues/new
+
+Do not paste private instructions, secrets, tokens, customer data, or proprietary source in public feedback.

package/examples/portability-fidelity/pluribus.md

@@ -0,0 +1,56 @@
+<!-- pluribus:tools: claude,cursor,copilot,openclaw -->
+
+# Identity
+This repository publishes an AI rule or skill bundle that claims portability across Claude Code, Cursor, GitHub Copilot, and AGENTS.md-compatible coding agents.
+
+The bundle should be treated as portable only when its required capabilities, tested targets, known lossy targets, and fallback behavior are visible in review.
+
+# Stack
+- Source format: Markdown rules/skills maintained in git.
+- Generated targets: `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, and `AGENTS.md`.
+- Review command: `npx --yes pluribus-context@latest sync --dry-run`.
+- Drift command: `npx --yes pluribus-context@latest audit --json`.
+
+# Conventions
+- Do not use `universal` as a boolean portability claim.
+- Describe portability as claims with evidence: tier, tested targets, required capabilities, project assumptions, known lossy targets, and fallback behavior.
+- Treat `project-local` and `portable-with-loss` as honest labels, not failures.
+- Keep target-native rules when a target has semantics that flat Markdown cannot preserve, such as path/glob activation or manual attachment behavior.
+- When converting between tool formats, never silently drop security constraints, generated-file warnings, required read-before-plan steps, or scoped-rule metadata.
+
+## Portability claim
+
+```yaml
+portability:
+  tier: portable-with-adapters
+  testedOn:
+    - target: claude-code
+      evidence: generated CLAUDE.md smoke-reviewed
+    - target: cursor
+      evidence: generated .cursorrules smoke-reviewed
+    - target: github-copilot
+      evidence: generated .github/copilot-instructions.md smoke-reviewed
+    - target: agents-md
+      evidence: generated AGENTS.md smoke-reviewed
+  requiredCapabilities:
+    - load repository instructions before planning
+    - preserve generated-file warning
+    - expose security constraints before edits
+  knownLossyTargets:
+    - target: flat-markdown-targets
+      loss: cannot express Cursor-style path/glob activation without annotation
+  fallback:
+    - if a target cannot represent scoped activation, keep that scoped rule in the target-native file and document the loss
+```
+
+# Goals
+1. Make portability claims falsifiable before users copy a rule pack into production.
+2. Give maintainers a reviewable report of which targets were generated and where semantics may be lossy.
+3. Help directory/list reviewers distinguish real multi-tool support from self-attested compatibility.
+4. Keep one canonical source for shared claims while preserving target-native files for semantics that do not round-trip.
+
+# Constraints
+- Do not expose tokens, private instructions, customer data, internal paths, or proprietary source when reporting portability evidence.
+- Do not claim that generated Markdown proves runtime load order, model behavior, permission mapping, MCP availability, or path/glob precedence.
+- Do not flatten tool-specific security or activation semantics into a generic target without a visible fidelity warning.
+- Do not replace human review of rule/skill substance with a passing sync or audit check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "AI context/rules sync for CLAUDE.md, Claude Code, Cursor rules, Copilot instructions, OpenClaw, Windsurf, Continue, and Zed.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",

package/schemas/audit-result.schema.json

@@ -68,6 +68,10 @@
       "type": "string",
       "format": "uri",
       "description": "Issue template URL for reporting audit false positives, noisy output, or confusing next steps."
+    },
+    "fidelityReport": {
+      "$ref": "#/$defs/fidelityReport",
+      "description": "Optional portability/fidelity evidence emitted by `pluribus audit --fidelity-report`."
     }
   },
   "allOf": [
@@ -92,6 +96,80 @@
   ],
   "additionalProperties": false,
   "$defs": {
+    "fidelityReport": {
+      "type": "object",
+      "required": ["claim", "sourceSections", "targets", "summary", "warnings", "nextStep"],
+      "properties": {
+        "claim": { "type": "string" },
+        "sourceSections": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "targets": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/fidelityTarget" }
+        },
+        "summary": {
+          "type": "object",
+          "required": ["targetCount", "targetsWithUnsupportedSections", "warningCount"],
+          "properties": {
+            "targetCount": { "type": "integer", "minimum": 0 },
+            "targetsWithUnsupportedSections": { "type": "integer", "minimum": 0 },
+            "warningCount": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/fidelityWarning" }
+        },
+        "nextStep": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "fidelityTarget": {
+      "type": "object",
+      "required": ["toolId", "files", "activation", "representedSections", "unsupportedSections"],
+      "properties": {
+        "toolId": { "type": "string" },
+        "files": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "activation": { "$ref": "#/$defs/fidelityActivation" },
+        "representedSections": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "unsupportedSections": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "fidelityActivation": {
+      "type": "object",
+      "required": ["kind", "evidence"],
+      "properties": {
+        "kind": { "type": "string" },
+        "evidence": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "fidelityWarning": {
+      "type": "object",
+      "required": ["code", "target", "message"],
+      "properties": {
+        "code": { "type": "string" },
+        "target": { "type": "string" },
+        "message": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
     "result": {
       "type": "object",
       "required": ["toolId", "status", "file"],

package/src/commands/audit.js

@@ -38,6 +38,7 @@ export async function runAudit(args) {
   const strict = Boolean(args.strict || ci)
   const json = Boolean(args.json)
   const githubAnnotations = Boolean(args['github-annotations'] || ci)
+  const fidelityReportEnabled = Boolean(args['fidelity-report'])
   const hasJsonOutput = Object.prototype.hasOwnProperty.call(args, 'output')
   const jsonOutput = typeof args.output === 'string' && args.output.trim() ? args.output : null
   const cwd = process.cwd()
@@ -225,12 +226,18 @@ export async function runAudit(args) {
   }, {})
 
   const hasProblem = (summary.drift || 0) + (summary.missing || 0) + (summary.error || 0) > 0
+  const fidelityReport = fidelityReportEnabled ? buildFidelityReport({ cwd, sections, tools, loadSkill }) : null
+
+  if (!json && fidelityReport) {
+    printFidelityReport(fidelityReport)
+  }
+
   if (githubAnnotations) {
     writeGitHubAnnotations(results, { strict })
   }
 
   if (json) {
-    writeJson({
+    const payload = {
       ok: !hasProblem,
       source: displaySource,
       sourceFound: true,
@@ -246,7 +253,13 @@ export async function runAudit(args) {
         ? 'Run pluribus sync --dry-run to preview fixes, then pluribus sync to update generated files.'
         : 'Generated context files are in sync.',
       feedback: AUDIT_FEEDBACK_URL,
-    }, jsonOutput)
+    }
+
+    if (fidelityReport) {
+      payload.fidelityReport = fidelityReport
+    }
+
+    writeJson(payload, jsonOutput)
   } else {
     console.log('')
     console.log(`Summary: ${summary.current || 0} current, ${summary.drift || 0} drifted, ${summary.missing || 0} missing, ${summary.error || 0} error(s).`)
@@ -264,6 +277,105 @@ export async function runAudit(args) {
   }
 }
 
+function buildFidelityReport({ cwd, sections, tools, loadSkill }) {
+  const presentSections = Object.entries(sections)
+    .filter(([, value]) => String(value || '').trim())
+    .map(([name]) => name)
+    .sort((a, b) => a.localeCompare(b))
+
+  const lowerPresentSections = new Set(presentSections.map((name) => name.toLowerCase()))
+  const targets = tools.map((toolId) => {
+    const skill = loadSkill(cwd, toolId)
+    const representedSections = new Set([...(skill?.required || []), ...(skill?.optional || [])].map((name) => name.toLowerCase()))
+    const unsupportedSections = presentSections.filter((name) => !representedSections.has(name.toLowerCase()))
+
+    return {
+      toolId,
+      files: skill?.outputFiles || [],
+      activation: inferActivation(toolId, skill?.outputFiles || []),
+      representedSections: presentSections.filter((name) => representedSections.has(name.toLowerCase())),
+      unsupportedSections,
+    }
+  })
+
+  const warnings = []
+  for (const target of targets) {
+    if (target.unsupportedSections.length > 0) {
+      warnings.push({
+        code: 'section-not-rendered-by-target',
+        target: target.toolId,
+        message: `${target.toolId} template does not render section(s): ${target.unsupportedSections.join(', ')}`,
+      })
+    }
+  }
+
+  if (targets.some((target) => target.activation.kind === 'flat-project-wide')) {
+    warnings.push({
+      code: 'project-wide-activation-only',
+      target: '*',
+      message: 'Generated outputs are project-wide/always-on; Pluribus does not currently model path-scoped activation, manual attach, or progressive disclosure semantics.',
+    })
+  }
+
+  const advancedSections = ['workflow', 'context', 'examples', 'anti-patterns'].filter((name) => lowerPresentSections.has(name))
+  if (advancedSections.length > 0 && warnings.some((warning) => warning.code === 'section-not-rendered-by-target')) {
+    warnings.push({
+      code: 'portability-claim-needs-evidence',
+      target: '*',
+      message: `Do not claim universal portability without evidence: advanced section(s) ${advancedSections.join(', ')} are not represented equally by every selected target.`,
+    })
+  }
+
+  return {
+    claim: 'project-wide instruction portability evidence for selected targets',
+    sourceSections: presentSections,
+    targets,
+    summary: {
+      targetCount: targets.length,
+      targetsWithUnsupportedSections: targets.filter((target) => target.unsupportedSections.length > 0).length,
+      warningCount: warnings.length,
+    },
+    warnings,
+    nextStep: warnings.length > 0
+      ? 'Review unsupportedSections/warnings before calling this context universal; narrow the tools list, change the source, or document known lossy targets.'
+      : 'Selected targets render the current non-empty source sections with no known Pluribus template loss; still smoke-test behavior in each agent.',
+  }
+}
+
+function inferActivation(toolId, outputFiles) {
+  if (toolId === 'windsurf' || toolId === 'continue') {
+    return {
+      kind: 'project-wide-rule',
+      evidence: outputFiles,
+    }
+  }
+
+  return {
+    kind: 'flat-project-wide',
+    evidence: outputFiles,
+  }
+}
+
+function printFidelityReport(report) {
+  console.log('')
+  console.log('Fidelity report:')
+  console.log(`   Claim: ${report.claim}`)
+  console.log(`   Targets: ${report.targets.map((target) => target.toolId).join(', ')}`)
+
+  for (const target of report.targets) {
+    const unsupported = target.unsupportedSections.length > 0
+      ? `; unsupported sections: ${target.unsupportedSections.join(', ')}`
+      : '; no known section loss'
+    console.log(`   • ${target.toolId}: ${target.activation.kind}${unsupported}`)
+  }
+
+  for (const warning of report.warnings) {
+    console.log(`   ⚠️  ${warning.code}: ${warning.message}`)
+  }
+
+  console.log(`   Next: ${report.nextStep}`)
+}
+
 function getTools(rawContent, toolsArg) {
   if (toolsArg) {
     return splitTools(toolsArg)

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.14'
+export const VERSION = '0.3.16'