pluribus-context 0.3.14 → 0.3.15

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 All notable changes to Pluribus are documented here.
 
+## 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/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
+```
+
+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
+```
+
+## 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` gives CI/reviewers a machine-readable check for missing or drifted outputs.
+- 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 --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.15",
   "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/src/utils/version.js

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