pluribus-context 0.3.12 → 0.3.15

package/CHANGELOG.md

@@ -4,6 +4,26 @@
 
 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
+
+- Add a multi-session coordination contract guide and example for teams experimenting with Claude Code event logs, `.coordination/` ledgers, MCP/A2A relays, or parallel agent worktrees.
+- Document authority handoff topics (`authority.claimed`, `authority.delegated`, `authority.released`) so shared schemas, generated clients, release branches, and infra config have explicit owners instead of silent conflict.
+
+## 0.3.13 — external memory docs tracking
+
+### Changed
+
+- Track the MemoryGraph docs PR in `discovery:smoke` so adjacent MCP memory feedback is measured alongside awesome-list distribution attempts.
+
 ## 0.3.12 — MCP memory handoff 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). 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/coordination-contract.md

@@ -0,0 +1,160 @@
+# Coordination contract for multi-session agents
+
+Use this when several Claude Code, Cursor, Copilot, OpenClaw, or terminal-agent sessions work on the same project and you need them to follow the same coordination rules.
+
+Pluribus is not an event bus, queue, memory server, or orchestrator. It can hold the **coordination contract**: the small, reviewable protocol that tells every session what shared state exists, which events matter, who owns what, and when stale context must be invalidated.
+
+The pattern pairs well with tools that provide the runtime substrate: MCP memory servers, append-only JSONL logs, Discord/channel plugins, SQLite queues, task ledgers, dashboards, or custom schedulers. Those tools move messages; Pluribus keeps the rules for reading and writing those messages consistent across AI tools.
+
+## Audience
+
+This guide is for developers who:
+
+- run multiple AI coding sessions on the same repo or related repos;
+- use one tool for planning and other sessions for implementation;
+- keep hitting the "human as message bus" problem;
+- already use, or are considering, an event log, scratchpad, memory server, task ledger, or channel plugin;
+- want every agent/session to validate the same protocol before acting.
+
+If you need real-time wake, pub/sub delivery, session discovery, locks, or durable retrieval, use a coordination/memory tool. If you need the instruction contract for those tools to stay aligned across Claude Code, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed, use Pluribus.
+
+## 60-second disposable test
+
+```bash
+mkdir coordination-contract-demo
+cd coordination-contract-demo
+curl -fsSL https://raw.githubusercontent.com/caioribeiroclw-pixel/pluribus/main/examples/coordination-contract/pluribus.md -o pluribus.md
+
+npx --yes pluribus-context@latest validate
+npx --yes pluribus-context@latest sync --dry-run
+```
+
+The dry run previews the tool-specific instructions before writing files:
+
+| Tool/session surface | Generated file |
+| --- | --- |
+| Claude Code | `CLAUDE.md` |
+| Cursor | `.cursorrules` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| OpenClaw / agent runners | `AGENTS.md` |
+
+If the preview is correct:
+
+```bash
+npx --yes pluribus-context@latest sync
+npx --yes pluribus-context@latest audit
+```
+
+Commit `pluribus.md` as the reviewed source of truth. Commit generated files if you want each tool to pick up the contract immediately after clone.
+
+## What belongs in a coordination contract
+
+A useful contract is small and operational. Keep it explicit enough that a fresh session can follow it without reading the whole project history.
+
+```markdown
+<!-- pluribus:tools: claude,cursor,copilot,openclaw -->
+
+# Identity
+I am working on Acme Platform, a repo edited by multiple AI sessions.
+
+# Context
+The runtime coordination substrate is an append-only event log at `.coordination/events.jsonl` plus one owned status file per session under `.coordination/sessions/`.
+
+# Workflow
+1. Before planning, read `.coordination/events.jsonl` from your last processed offset.
+2. Before editing files, check session status files for active ownership of the same area.
+3. When you change a shared contract, append an event before continuing implementation.
+4. If an event invalidates your current plan, stop and re-plan before the next tool call.
+
+# Constraints
+- Do not paste secrets or private chat logs into coordination files.
+- Do not rewrite the append-only event log.
+- Do not edit another session's owned status file.
+```
+
+The important point is not the exact file names. The important point is that all sessions agree on the same protocol: event schema, ownership model, invalidation rules, and safety boundaries.
+
+## Authority is part of the contract
+
+Multi-session workflows usually fail before the transport fails. Two sessions can both receive the same event and still drift if they disagree about who owns a shared definition.
+
+Make authority explicit:
+
+- which role owns each shared contract: API schema, database migration, deployment config, design token, generated client, release branch;
+- whether ownership is exclusive, delegated, or review-only;
+- which event transfers ownership or requests a handoff;
+- what a session must do when it sees another active owner for the same area;
+- how cross-repo or cross-machine sessions identify the same project/version.
+
+For example:
+
+```json
+{"schemaVersion":"coordination.v1","eventId":"2026-05-17T22:10:00Z-api-owner-1","topic":"authority.claimed","producer":"api-session","createdAt":"2026-05-17T22:10:00Z","projectVersion":"a1b2c3d","payload":{"domain":"api.schema","owner":"api-session","scope":["openapi.yaml","packages/client/src/generated/**"],"expiresAt":"2026-05-17T23:10:00Z"},"invalidates":["dashboard-session.plan","worker-session.plan"]}
+```
+
+A session that sees this event should not edit the same schema or generated client until it either receives an `authority.released` event, gets explicit delegation, or replans around a read-only dependency.
+
+## Suggested contract fields
+
+For an append-only project event log, define at least:
+
+- `schemaVersion`: version of the event schema;
+- `eventId`: stable unique id for deduplication;
+- `topic`: machine-readable topic such as `infra.endpoint.changed`, `db.migration.completed`, or `authority.claimed`;
+- `producer`: session id or role that emitted the event;
+- `createdAt`: timestamp;
+- `projectVersion`: git SHA, package version, or config revision when emitted;
+- `payload`: structured data, excluding secrets;
+- `invalidates`: optional list of plans, files, or roles that must re-check state.
+
+For each session role, define:
+
+- topics it **must read before planning**;
+- topics it **may write**;
+- files, domains, schemas, or contracts it owns;
+- events that claim, delegate, release, or revoke authority;
+- when it must pause and ask the coordinator/human;
+- whether event delivery is `at-least-once`, `replay from offset`, or best effort;
+- how to record the last processed offset.
+
+## Example: migration updates an endpoint
+
+Bad handoff:
+
+> Session A changed the database endpoint. The user copy-pastes that fact into four other terminals.
+
+Better handoff:
+
+```json
+{"schemaVersion":"coordination.v1","eventId":"2026-05-17T21:10:00Z-infra-1","topic":"infra.endpoint.changed","producer":"infra-session","createdAt":"2026-05-17T21:10:00Z","projectVersion":"a1b2c3d","payload":{"service":"postgres","endpointRef":"POSTGRES_ENDPOINT"},"invalidates":["api-session.plan","worker-session.plan","dashboard-session.plan"]}
+```
+
+The contract then tells API, worker, and dashboard sessions: before the next plan/tool call, read events from your offset; if `infra.endpoint.changed` appears, invalidate cached assumptions about database endpoint configuration and re-check the canonical env/config source.
+
+## Why this is separate from memory
+
+Memory tools store facts and retrieve relevant history. Coordination tools deliver events and track state. The contract is the layer that says **how sessions are allowed to use those tools**.
+
+Separating those layers prevents a common failure mode: five sessions use the same memory/event substrate with five subtly different conventions. The result looks like flaky coordination, but the root cause is protocol drift.
+
+## What this deliberately does not solve
+
+- It does not wake sleeping sessions.
+- It does not provide pub/sub, locks, or a queue.
+- It does not read another session's private reasoning or transcript.
+- It does not replace MCP memory, task systems, dashboards, or event logs.
+- It does not make multi-agent coordination safe by itself.
+
+That boundary is intentional. Pluribus keeps the coordination protocol reviewable and synced; runtime systems execute it.
+
+## Feedback wanted
+
+If this breaks in a real multi-session workflow, the most useful feedback is concrete:
+
+- which tools/sessions were involved;
+- what runtime substrate you used: event log, memory server, channel, task ledger, or custom queue;
+- which contract rule drifted or was ignored;
+- whether `pluribus audit` caught stale generated instructions;
+- what field should be added to make the contract more executable.
+
+Open feedback here: https://github.com/caioribeiroclw-pixel/pluribus/discussions/13

package/docs/cursor-claude-context-handoff.md

@@ -0,0 +1,111 @@
+# Cursor ↔ Claude Code context handoff
+
+Use this when you switch between Cursor, Claude Code, Copilot/Codex-style assistants, and terminal agents and keep re-explaining the same project facts.
+
+Pluribus is not a chat transcript mover and not a memory database. It is the small, reviewable layer for **intentional project context**: architecture notes, conventions, constraints, workflow rules, and safety boundaries that should survive tool switches.
+
+## Audience
+
+This guide is for developers who:
+
+- use Cursor for IDE work and Claude Code or a terminal agent for larger changes;
+- also keep Copilot instructions, `AGENTS.md`, Windsurf/Continue/Zed rules, or similar files;
+- want a repo-local source of truth instead of manually copying context between tools;
+- do not want a background service or MCP server just to keep instruction files aligned.
+
+If you need semantic recall over notes, use a memory/MCP/RAG tool. If you need the same project instructions available to several tools, use a versioned context file and sync it.
+
+## 60-second disposable test
+
+```bash
+mkdir ai-context-handoff-demo
+cd ai-context-handoff-demo
+
+npx --yes pluribus-context@latest init \
+  --name "Handoff Demo" \
+  --description "A repo used from Cursor, Claude Code, and Copilot" \
+  --tools claude,cursor,copilot,openclaw
+
+npx --yes pluribus-context@latest validate
+npx --yes pluribus-context@latest sync --dry-run
+```
+
+The dry run shows the generated outputs before writing tool files:
+
+| Tool | File |
+| --- | --- |
+| Claude Code | `CLAUDE.md` |
+| Cursor | `.cursorrules` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| OpenClaw / agent runners | `AGENTS.md` |
+
+If the preview looks right:
+
+```bash
+npx --yes pluribus-context@latest sync
+npx --yes pluribus-context@latest audit
+```
+
+Commit `pluribus.md` as the source of truth. Commit generated files if you want each tool to work immediately after clone.
+
+## What to put in `pluribus.md`
+
+Keep only context that should be stable enough to review in git:
+
+```markdown
+<!-- pluribus:tools: claude,cursor,copilot,openclaw -->
+
+# Identity
+I am building Acme Billing, a TypeScript service used by finance operators.
+
+# Stack
+- Node.js 22
+- PostgreSQL
+- Vitest
+
+# Conventions
+- Prefer small, reviewed changes over large rewrites.
+- Do not change database migrations without adding a rollback note.
+- Keep API compatibility unless an issue explicitly approves a breaking change.
+
+# Goals
+1. Make billing changes safe to review.
+2. Keep AI tool behavior consistent across IDE and terminal workflows.
+
+# Constraints
+- Never paste secrets, customer data, tokens, or private chat logs into context files.
+- Repository code and tests override stale generated context.
+
+# Workflow
+1. Read the relevant code and this project context before proposing changes.
+2. Run the smallest meaningful test before claiming a fix.
+3. Update `pluribus.md` when project conventions change, then run `pluribus sync`.
+```
+
+## Handoff pattern
+
+1. **Before switching tools:** put durable project facts in `pluribus.md`, not in a one-off chat.
+2. **Preview:** run `pluribus sync --dry-run` to see what each tool will receive.
+3. **Sync:** generate native files when the preview is correct.
+4. **Audit:** run `pluribus audit` locally or in CI to catch drift when someone edits generated files directly.
+5. **Use memory separately:** if you also run an MCP memory server, keep the recall/store protocol in `pluribus.md` and let the memory server store durable facts.
+
+## What this deliberately does not solve
+
+- It does not move active chat state from Cursor to Claude Code.
+- It does not summarize your current conversation automatically.
+- It does not store or retrieve memories.
+- It does not replace MCP tools, RAG over notes, or agent memory.
+
+That boundary is the point: project instructions should be boring, reviewable, and easy to diff. Runtime memory can stay specialized.
+
+## Feedback wanted
+
+If this fails on a real multi-tool repo, the useful feedback is specific:
+
+- which tools you use together;
+- which context files already existed;
+- whether `audit` found the right missing/stale file;
+- which generated file felt semantically wrong for that tool.
+
+Open feedback here: https://github.com/caioribeiroclw-pixel/pluribus/discussions/13

package/docs/discovery-smoke.md

@@ -33,7 +33,7 @@ As of 2026-05-17 01:01 UTC, public npm is still `pluribus-context@0.3.9` while t
 - `pendingNpmPublish` is expected to be `true` until npm auth/2FA allows publishing `0.3.10`; generic search results still measure the public `0.3.9` metadata, not the sharpened local `0.3.10` description/keywords.
 - npm downloads are visible through the same smoke report (`last-day`, `last-week`, `last-month`), but current values still include likely noise from release/publish/smoke activity.
 - GitHub adoption signals are visible in the same report: stars/forks/watchers, latest release, open issues, open pull requests, discussion activity, and recent external discussion-comment count.
-- External distribution tracking covers the contextual `awesome-ai-coding-tools` and `awesome-claude-code` PRs and records whether each remains open, mergeable, commented on, or merged.
+- External distribution tracking covers the contextual `awesome-ai-coding-tools`, `awesome-claude-code`, and adjacent `memory-graph` PRs and records whether each remains open, mergeable, commented on, or merged.
 - Generic npm queries still favor adjacent packages such as `sync-ai-context`, `ai-rules-sync`, `cursor2claude`, and `@intellectronica/ruler`.
 - That means exact-name discovery works, but problem-query discovery is still weak and should be treated as a lagging adoption metric, especially while `pendingNpmPublish` is true.
 

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/context-handoff/pluribus.md

@@ -0,0 +1,48 @@
+<!-- pluribus:tools: claude,cursor,copilot,openclaw -->
+
+# Identity
+
+I am building **Acme Billing**, a TypeScript service used by finance operators to review invoices, payments, and reconciliation exceptions.
+
+This repository is edited with Cursor for IDE work, Claude Code for larger terminal tasks, GitHub Copilot for inline assistance, and OpenClaw-style agents for automation.
+
+# Stack
+
+- TypeScript strict mode
+- Node.js 22 LTS
+- PostgreSQL
+- Vitest for unit tests
+- GitHub Actions for CI
+
+# Conventions
+
+- Prefer small, reviewable changes over broad rewrites.
+- Keep generated AI context files in sync from `pluribus.md`; do not edit `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md` by hand.
+- Add or update tests for billing logic changes.
+- For database changes, include migration intent and rollback notes in the PR.
+- Treat repository code, tests, and migrations as the source of truth when generated context is stale.
+
+# Goals
+
+1. Make AI-assisted billing changes safe to review.
+2. Keep Cursor, Claude Code, Copilot, and terminal agents aligned on the same project boundaries.
+3. Avoid re-explaining stable project context in every new tool session.
+
+# Constraints
+
+- Never place secrets, tokens, credentials, private customer data, or full chat transcripts in `pluribus.md` or generated context files.
+- Do not let AI tools invent billing policy, pricing, legal commitments, or customer-facing promises.
+- Do not change migrations, payment semantics, or reconciliation rules without tests and explicit review context.
+- If tool-specific generated files drift from `pluribus.md`, update the source file first and regenerate.
+
+# Workflow
+
+1. Before meaningful changes, read this context and inspect the relevant code.
+2. If a project convention changes, edit `pluribus.md` and run `npx --yes pluribus-context@latest sync --dry-run`.
+3. When the preview looks right, run `npx --yes pluribus-context@latest sync`.
+4. Run `npx --yes pluribus-context@latest audit` before opening a PR so generated context files do not drift.
+5. Use memory/MCP/RAG tools only for durable recall; keep the cross-tool instruction protocol here in git.
+
+# Context
+
+This example demonstrates a boring but useful handoff: one reviewed project context file feeds the native instruction files used by Cursor, Claude Code, Copilot, and agent runners. It is intentionally not a memory server and not a transcript migration tool.

package/examples/coordination-contract/pluribus.md

@@ -0,0 +1,136 @@
+<!-- pluribus:tools: claude,cursor,copilot,openclaw -->
+
+# Identity
+
+I am working on **Acme Platform**, a TypeScript/PostgreSQL product maintained by several AI coding sessions at the same time.
+
+This repository may be edited from Claude Code, Cursor, GitHub Copilot, and OpenClaw-style terminal agents. Each session keeps its own context window, but all sessions must follow the same coordination contract.
+
+# Stack
+
+- TypeScript strict mode
+- Node.js 22 LTS
+- PostgreSQL
+- Vitest for unit tests
+- GitHub Actions for CI
+- Runtime coordination substrate: append-only JSONL event log plus per-session status files
+
+# Context
+
+The runtime substrate is intentionally simple and inspectable:
+
+- `.coordination/events.jsonl` is an append-only project event log.
+- `.coordination/sessions/<session-role>.md` is the owned status file for one session role.
+- `.coordination/offsets/<session-role>.json` records the last processed event offset for one session role.
+
+Pluribus does not implement the event log, queue, wake mechanism, locks, or memory server. This file is the reviewed coordination contract that every generated AI instruction file receives.
+
+# Conventions
+
+- Treat `pluribus.md` as the source of truth for coordination rules.
+- Do not edit generated `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md` by hand.
+- The event log is append-only. Never rewrite, reorder, truncate, or silently redact past events.
+- Each session may update only its own `.coordination/sessions/<session-role>.md` file.
+- Prefer typed events over prose handoffs when a change affects another session.
+- Keep event payloads small and structured. Put detailed work notes in the owning session status file or issue/PR.
+- Use git, tests, and code review as final authority when AI context conflicts with source code.
+
+# Coordination Contract
+
+## Event schema
+
+Every event appended to `.coordination/events.jsonl` should be one JSON object per line with:
+
+- `schemaVersion`: currently `coordination.v1`.
+- `eventId`: unique and stable for deduplication.
+- `topic`: machine-readable topic such as `infra.endpoint.changed`, `db.migration.completed`, `api.contract.changed`, `authority.claimed`, `authority.released`, `worker.blocked`, or `release.published`.
+- `producer`: session role that emitted the event.
+- `createdAt`: UTC ISO timestamp.
+- `projectVersion`: git SHA, package version, or config revision when emitted.
+- `payload`: structured data with no secrets.
+- `invalidates`: optional list of roles, plans, files, or assumptions that must be re-checked.
+
+Example:
+
+```json
+{"schemaVersion":"coordination.v1","eventId":"2026-05-17T21:10:00Z-infra-1","topic":"infra.endpoint.changed","producer":"infra-session","createdAt":"2026-05-17T21:10:00Z","projectVersion":"a1b2c3d","payload":{"service":"postgres","endpointRef":"POSTGRES_ENDPOINT"},"invalidates":["api-session.plan","worker-session.plan","dashboard-session.plan"]}
+```
+
+## Required read topics
+
+Before making or continuing a plan, every session must read from its last processed offset and check these topics:
+
+- `infra.endpoint.changed`
+- `db.migration.completed`
+- `api.contract.changed`
+- `authority.claimed`
+- `authority.delegated`
+- `authority.released`
+- `release.published`
+- `security.constraint.changed`
+- `session.blocked`
+
+If one of those topics invalidates the current plan, stop and re-plan before the next tool call.
+
+## Authority and ownership
+
+Shared definitions must have an explicit owner before parallel sessions edit them:
+
+- `api-session` owns `openapi.yaml`, generated API clients, and API compatibility notes while an `authority.claimed` event for `api.schema` is active.
+- `db-session` owns migrations and schema docs while an `authority.claimed` event for `db.schema` is active.
+- `infra-session` owns deployment endpoints, secrets references, and runtime config names while an `authority.claimed` event for `infra.config` is active.
+- Consumer sessions may read those files and adapt local code, but must not rewrite the shared contract unless authority is delegated.
+- Authority should include `domain`, `owner`, `scope`, optional `expiresAt`, and optional `handoffTo` in the event payload.
+
+Example:
+
+```json
+{"schemaVersion":"coordination.v1","eventId":"2026-05-17T22:10:00Z-api-owner-1","topic":"authority.claimed","producer":"api-session","createdAt":"2026-05-17T22:10:00Z","projectVersion":"a1b2c3d","payload":{"domain":"api.schema","owner":"api-session","scope":["openapi.yaml","packages/client/src/generated/**"],"expiresAt":"2026-05-17T23:10:00Z"},"invalidates":["dashboard-session.plan","worker-session.plan"]}
+```
+
+If two sessions claim the same authority domain, pause edits in that domain and resolve ownership before continuing.
+
+## Allowed write topics
+
+- `infra-session` may write `infra.*` and `release.*` topics.
+- `db-session` may write `db.*` topics.
+- `api-session` may write `api.*` topics.
+- Any owner may write `authority.claimed`, `authority.delegated`, and `authority.released` for its own domain.
+- `worker-session` may write `worker.*` topics.
+- `dashboard-session` may write `dashboard.*` topics.
+- Any session may write `session.blocked`, `session.unblocked`, and `session.question` for its own role.
+
+Do not write events for another session role unless explicitly delegated in a ticket or coordinator message.
+
+## Delivery semantics
+
+- Treat event delivery as at-least-once.
+- Deduplicate by `eventId`.
+- Replay from the recorded offset when a session starts, resumes, or finishes compaction.
+- If the offset file is missing or corrupt, replay from the start of the current day's events and summarize anything relevant before acting.
+- If two events conflict, prefer the newer event only after checking whether both producers had authority over the topic.
+- If two active authority claims overlap, stop editing the overlapping domain until ownership is resolved.
+
+# Workflow
+
+1. At session start or resume, read this contract and then read `.coordination/events.jsonl` from your recorded offset.
+2. Before planning, process required read topics and update your session status file with current assumptions.
+3. Before editing files, check whether another session status file claims the same area.
+4. When you change a shared contract, endpoint, migration, API, release, or security constraint, append an event before continuing implementation.
+5. When blocked, write `session.blocked` with a structured reason and the smallest question needed to unblock.
+6. Before claiming completion, run the smallest meaningful test and `npx --yes pluribus-context@latest audit` if AI context files may have drifted.
+
+# Goals
+
+1. Remove the human as the message bus between parallel AI sessions.
+2. Keep every session aligned on the same coordination protocol without exposing private reasoning or full transcripts.
+3. Make stale assumptions visible before they cause conflicting edits or incorrect plans.
+4. Keep the coordination layer boring, inspectable, and reviewable in git.
+
+# Constraints
+
+- Never put secrets, credentials, tokens, private customer data, or full chat transcripts in coordination files.
+- Never paste raw chain-of-thought or private reasoning from another session.
+- Do not use the event log as a durable memory database; store long-lived decisions in docs, issues, PRs, or an explicit memory tool.
+- Do not continue implementation after receiving an invalidating event until the plan is refreshed.
+- Do not assume every AI tool represents these rules identically; run `pluribus sync --dry-run` and review generated files when changing this contract.

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.12",
+  "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.12'
+export const VERSION = '0.3.15'