pluribus-context 0.3.19 → 0.3.21

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.21 - 2026-05-19
+
+- Extended `pluribus audit --fidelity-report` with `effectiveContext` evidence so monorepo reviewers can see that built-in targets currently prove repo-root context only, not root→subpath inheritance or path isolation.
+- Added an explicit `effective-context-is-repo-root` warning and `no-path-scope-evidence` semantic marker to avoid treating generated root instruction files as proof of subdirectory behavior.
+- Updated the community review packet and portability fidelity docs to frame monorepo path scope as an evidence question: what context does the agent actually load from `apps/client/`?
+
+## 0.3.20 - 2026-05-18
+
+- Added a 60-second native-vs-fallback smoke to the community review packet so directory/list reviewers can see Bob native `.bob/rules/*.md` differ from OpenClaw/AGENTS.md generic fallback.
+- Extended `npm run review:smoke` to execute that fidelity demo against the published npm package and assert `nativeDiscoverySurface`, `genericFallback`, and `manualActivationRequired` fields.
+
 ## [Unreleased]
 
 All notable changes to Pluribus are documented here.

package/docs/community-review-packet.md

@@ -91,6 +91,25 @@ Expected result:
 - `sync --dry-run` previews generated context files without writing them.
 - `audit --ci` may exit `1` before generated files are synced; that is expected when outputs are missing or drifted.
 
+## 60-second native-vs-fallback smoke
+
+Use this when reviewing the fidelity-audit positioning. It demonstrates the difference between a native tool discovery surface and a generic fallback in a clean directory:
+
+```bash
+mkdir pluribus-fidelity && cd pluribus-fidelity
+npx --yes pluribus-context@latest init --name "Fidelity review" --description "Native vs fallback smoke" --tools bob,openclaw
+npx --yes pluribus-context@latest sync
+npx --yes pluribus-context@latest audit --json --fidelity-report --output fidelity.json
+node -e "const r=require('./fidelity.json'); console.log(r.fidelityReport.targets.map(t => ({ toolId: t.toolId, file: t.files[0], nativeDiscoverySurface: t.nativeDiscoverySurface, genericFallback: t.genericFallback, manualActivationRequired: t.manualActivationRequired, effectiveContextScope: t.effectiveContext?.scope })))"
+```
+
+Expected result:
+
+- Bob writes `.bob/rules/pluribus.md` and reports `nativeDiscoverySurface: ".bob/rules/*.md"`, `genericFallback: false`, `manualActivationRequired: false`.
+- OpenClaw writes `AGENTS.md` and reports `nativeDiscoverySurface: "AGENTS.md"`, `genericFallback: true`, `manualActivationRequired: false`.
+- Both targets report `effectiveContext.scope: "repo-root"` and `pathScoped: false`; for monorepos this is a warning that subdirectory inheritance/isolation still needs a separate smoke.
+- This is the core Pluribus distinction for reviewers: generated file exists is not enough; the report should show whether the target uses native discovery or a generic fallback, and what effective context scope has actually been proven.
+
 ## Useful links
 
 - npm package: <https://www.npmjs.com/package/pluribus-context>

package/docs/portability-fidelity-report.md

@@ -77,7 +77,7 @@ 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, native discovery surface, resolution anchor, generic fallback status, and portability warnings.
+- `audit --json --fidelity-report` gives CI/reviewers a machine-readable check for missing/drifted outputs plus target-by-target section loss, activation shape, native discovery surface, resolution anchor, generic fallback status, effective context scope, 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.
@@ -90,9 +90,10 @@ For each selected target, the JSON report includes:
 - `resolutionAnchor` — where the generated surface is resolved from today (`repo-root` for built-in targets).
 - `genericFallback` — whether the output is a broad agent fallback surface rather than a target-specific native surface.
 - `manualActivationRequired` — whether Pluribus knows the output requires manual activation after generation. Built-in project-wide targets are currently `false`; future scoped/skill targets may differ.
-- `semanticDifference` — a compact list such as `section-loss`, `project-wide-only`, or `generic-agent-file` so reviewers can distinguish “file exists” from “same behavior is preserved.”
+- `effectiveContext` — what Pluribus can prove about the context a target receives. Built-in targets currently report `scope: repo-root`, `pathScoped: false`, `inheritance: none-modeled`, and `overrideBehavior: none-modeled`; this is explicit evidence that monorepo path inheritance/isolation still needs a separate smoke.
+- `semanticDifference` — a compact list such as `section-loss`, `project-wide-only`, `no-path-scope-evidence`, or `generic-agent-file` so reviewers can distinguish “file exists” from “same behavior is preserved.”
 
-These fields are intentionally boring. They help reviewers catch cases like “installed files exist but the agent will not discover them,” or “two targets share a generic file but do not actually have the same loading semantics.”
+These fields are intentionally boring. They help reviewers catch cases like “installed files exist but the agent will not discover them,” “two targets share a generic file but do not actually have the same loading semantics,” or “root and subfolder instruction files exist but nobody has proven the effective context for `apps/client/`.”
 
 ## Suggested workflow for maintainers
 
@@ -100,7 +101,8 @@ These fields are intentionally boring. They help reviewers catch cases like “i
 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.
+5. For monorepos, treat `effectiveContext.scope: repo-root` as a warning, not proof. Add a target-specific smoke for the path you care about, for example `apps/client/` should load root + client context but not `apps/auth/` rules.
+6. Update the claim whenever a new target is added, a tool changes capability names, a subdirectory context is introduced, or a permission/security default changes.
 
 ## Feedback wanted
 

package/package.json

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

package/src/commands/audit.js

@@ -294,6 +294,8 @@ function buildFidelityReport({ cwd, sections, tools, loadSkill }) {
     const discovery = inferDiscovery(toolId, outputFiles)
     const represented = presentSections.filter((name) => representedSections.has(name.toLowerCase()))
 
+    const effectiveContext = inferEffectiveContext(toolId, outputFiles)
+
     return {
       toolId,
       files: outputFiles,
@@ -302,7 +304,8 @@ function buildFidelityReport({ cwd, sections, tools, loadSkill }) {
       genericFallback: discovery.genericFallback,
       manualActivationRequired: discovery.manualActivationRequired,
       activation,
-      semanticDifference: summarizeSemanticDifference({ unsupportedSections, activation, discovery }),
+      effectiveContext,
+      semanticDifference: summarizeSemanticDifference({ unsupportedSections, activation, discovery, effectiveContext }),
       representedSections: represented,
       unsupportedSections,
     }
@@ -327,6 +330,14 @@ function buildFidelityReport({ cwd, sections, tools, loadSkill }) {
     })
   }
 
+  if (targets.some((target) => target.effectiveContext?.scope === 'repo-root')) {
+    warnings.push({
+      code: 'effective-context-is-repo-root',
+      target: '*',
+      message: 'Effective context evidence is repo-root only; Pluribus does not currently prove root→subpath inheritance, overrides, or path isolation for monorepos.',
+    })
+  }
+
   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({
@@ -387,7 +398,19 @@ function inferDiscovery(toolId, outputFiles) {
   }
 }
 
-function summarizeSemanticDifference({ unsupportedSections, activation, discovery }) {
+function inferEffectiveContext(toolId, outputFiles) {
+  return {
+    scope: 'repo-root',
+    pathScoped: false,
+    inheritance: 'none-modeled',
+    overrideBehavior: 'none-modeled',
+    isolationEvidence: 'not-modeled',
+    entrypoints: outputFiles,
+    note: `${toolId} output is audited as repo-root context only; verify subdirectory load order separately in monorepos.`,
+  }
+}
+
+function summarizeSemanticDifference({ unsupportedSections, activation, discovery, effectiveContext }) {
   const differences = []
 
   if (unsupportedSections.length > 0) {
@@ -398,6 +421,10 @@ function summarizeSemanticDifference({ unsupportedSections, activation, discover
     differences.push('project-wide-only')
   }
 
+  if (effectiveContext?.pathScoped === false) {
+    differences.push('no-path-scope-evidence')
+  }
+
   if (discovery.genericFallback) {
     differences.push('generic-agent-file')
   }
@@ -422,10 +449,13 @@ function printFidelityReport(report) {
     const discovery = target.nativeDiscoverySurface
       ? `; surface: ${target.nativeDiscoverySurface}`
       : ''
+    const scope = target.effectiveContext?.scope
+      ? `; effective context: ${target.effectiveContext.scope}`
+      : ''
     const semantics = target.semanticDifference?.length
       ? `; semantic: ${target.semanticDifference.join(', ')}`
       : ''
-    console.log(`   • ${target.toolId}: ${target.activation.kind}${discovery}${unsupported}${semantics}`)
+    console.log(`   • ${target.toolId}: ${target.activation.kind}${discovery}${scope}${unsupported}${semantics}`)
   }
 
   for (const warning of report.warnings) {

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.19'
+export const VERSION = '0.3.21'