pluribus-context 0.3.21 → 0.3.22

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.22 - 2026-05-19
+
+- Extended `pluribus audit --fidelity-report` with `loadEvidence` receipts so reviewers can see whether generated context is expected to enter through native file discovery or a generic agent fallback.
+- Added explicit runtime dedupe uncertainty via `load-dedupe-not-proven` warnings and `runtime-load-dedupe-not-proven` semantic markers, making native-vs-hook-vs-manual duplication an evidence question.
+- Updated the audit JSON schema, community review packet, README shortcut, and portability fidelity docs with `loadedBy`, `effectiveSource`, hook/session-start flags, resume behavior, and dedupe risk.
+
 ## 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.

package/README.md

@@ -14,7 +14,7 @@ It shows where instructions keep their semantics, where they are downgraded to a
 
 It is **not** a persistent memory layer, retrieval system, agent orchestrator, or agent-merging framework. Think `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `AGENTS.md` — one intentional context, multiple generated outputs.
 
-**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and a disposable 60-second smoke test. If you only run one command, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, manual activation requirements, and semantic differences.
+**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and a disposable 60-second smoke test. If you only run one command, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, load evidence, manual activation requirements, effective context scope, and semantic differences.
 
 ---
 

package/docs/community-review-packet.md

@@ -100,7 +100,7 @@ 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 })))"
+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, loadedBy: t.loadEvidence?.loadedBy, dedupeRisk: t.loadEvidence?.dedupeRisk })))"
 ```
 
 Expected result:
@@ -108,7 +108,8 @@ 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.
+- Both targets include `loadEvidence`: Bob is `loadedBy: "native-file-discovery"`; OpenClaw is `loadedBy: "generic-agent-file"`; both currently report `dedupeRisk: "unknown"` because Pluribus does not prove runtime deduplication across native files, hooks, generated imports, or manual injection.
+- 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, how the context is expected to be loaded, and what effective context scope has actually been proven.
 
 ## Useful links
 

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, effective context scope, 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, load evidence, 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,10 +90,11 @@ 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.
-- `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.”
+- `loadEvidence` — how the generated context is expected to enter the agent session. Built-in targets currently report `loadedBy` (`native-file-discovery` or `generic-agent-file`), `effectiveSource`, `deliveryMechanism`, `hookInstalled: false`, `injectedOnSessionStart: false`, `resumeBehavior: not-proven`, and `dedupeRisk: unknown`; this makes native-vs-hook-vs-manual duplication an explicit evidence question instead of an assumption.
+- `effectiveContext` — what Pluribus can prove about the context a target receives. Built-in targets currently report `scope: repo-root`, `pathScoped: false`, `inheritance: none-modeled`, `overrideBehavior: none-modeled`, plus the inferred `loadedBy` and `effectiveSource`; 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`, `generic-agent-file`, or `runtime-load-dedupe-not-proven` 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,” “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/`.”
+These fields are intentionally boring. They help reviewers catch cases like “installed files exist but the agent will not discover them,” “a hook injects the same context already loaded natively,” “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
 
@@ -101,8 +102,9 @@ 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. 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.
+5. For hook/native/manual mixes, treat `loadEvidence.dedupeRisk: unknown` as a warning, not proof. Add a target-specific receipt for `loadedBy`, `hookInstalled`, `injectedOnSessionStart`, and resume behavior before claiming deduplication.
+6. 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.
+7. Update the claim whenever a new target is added, a tool changes capability names, a subdirectory context is introduced, a hook/manual injection path changes, or a permission/security default changes.
 
 ## Feedback wanted
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.21",
+  "version": "0.3.22",
   "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/schemas/audit-result.schema.json

@@ -129,14 +129,37 @@
     },
     "fidelityTarget": {
       "type": "object",
-      "required": ["toolId", "files", "activation", "representedSections", "unsupportedSections"],
+      "required": [
+        "toolId",
+        "files",
+        "nativeDiscoverySurface",
+        "resolutionAnchor",
+        "genericFallback",
+        "manualActivationRequired",
+        "activation",
+        "loadEvidence",
+        "effectiveContext",
+        "semanticDifference",
+        "representedSections",
+        "unsupportedSections"
+      ],
       "properties": {
         "toolId": { "type": "string" },
         "files": {
           "type": "array",
           "items": { "type": "string" }
         },
+        "nativeDiscoverySurface": { "type": ["string", "null"] },
+        "resolutionAnchor": { "type": "string" },
+        "genericFallback": { "type": "boolean" },
+        "manualActivationRequired": { "type": "boolean" },
         "activation": { "$ref": "#/$defs/fidelityActivation" },
+        "loadEvidence": { "$ref": "#/$defs/loadEvidence" },
+        "effectiveContext": { "$ref": "#/$defs/effectiveContext" },
+        "semanticDifference": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
         "representedSections": {
           "type": "array",
           "items": { "type": "string" }
@@ -148,6 +171,70 @@
       },
       "additionalProperties": false
     },
+    "loadEvidence": {
+      "type": "object",
+      "required": [
+        "loadedBy",
+        "effectiveSource",
+        "deliveryPath",
+        "deliveryMechanism",
+        "hookInstalled",
+        "injectedOnSessionStart",
+        "manualInjectionRequired",
+        "resumeBehavior",
+        "dedupeKey",
+        "dedupeRisk",
+        "evidence",
+        "note"
+      ],
+      "properties": {
+        "loadedBy": { "type": "string" },
+        "effectiveSource": { "type": ["string", "null"] },
+        "deliveryPath": { "type": ["string", "null"] },
+        "deliveryMechanism": { "type": "string" },
+        "hookInstalled": { "type": "boolean" },
+        "injectedOnSessionStart": { "type": "boolean" },
+        "manualInjectionRequired": { "type": "boolean" },
+        "resumeBehavior": { "type": "string" },
+        "dedupeKey": { "type": "string" },
+        "dedupeRisk": { "type": "string" },
+        "evidence": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "note": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "effectiveContext": {
+      "type": "object",
+      "required": [
+        "scope",
+        "pathScoped",
+        "inheritance",
+        "overrideBehavior",
+        "isolationEvidence",
+        "entrypoints",
+        "loadedBy",
+        "effectiveSource",
+        "note"
+      ],
+      "properties": {
+        "scope": { "type": "string" },
+        "pathScoped": { "type": "boolean" },
+        "inheritance": { "type": "string" },
+        "overrideBehavior": { "type": "string" },
+        "isolationEvidence": { "type": "string" },
+        "entrypoints": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "loadedBy": { "type": "string" },
+        "effectiveSource": { "type": ["string", "null"] },
+        "note": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
     "fidelityActivation": {
       "type": "object",
       "required": ["kind", "evidence"],

package/src/commands/audit.js

@@ -294,7 +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)
+    const loadEvidence = inferLoadEvidence(toolId, outputFiles, discovery, activation)
+    const effectiveContext = inferEffectiveContext(toolId, outputFiles, loadEvidence)
 
     return {
       toolId,
@@ -304,8 +305,9 @@ function buildFidelityReport({ cwd, sections, tools, loadSkill }) {
       genericFallback: discovery.genericFallback,
       manualActivationRequired: discovery.manualActivationRequired,
       activation,
+      loadEvidence,
       effectiveContext,
-      semanticDifference: summarizeSemanticDifference({ unsupportedSections, activation, discovery, effectiveContext }),
+      semanticDifference: summarizeSemanticDifference({ unsupportedSections, activation, discovery, effectiveContext, loadEvidence }),
       representedSections: represented,
       unsupportedSections,
     }
@@ -338,6 +340,14 @@ function buildFidelityReport({ cwd, sections, tools, loadSkill }) {
     })
   }
 
+  if (targets.some((target) => target.loadEvidence?.dedupeRisk === 'unknown')) {
+    warnings.push({
+      code: 'load-dedupe-not-proven',
+      target: '*',
+      message: 'Load evidence records the expected delivery path, but Pluribus does not currently prove runtime deduplication across native files, hooks, generated imports, or manual injection.',
+    })
+  }
+
   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({
@@ -398,7 +408,27 @@ function inferDiscovery(toolId, outputFiles) {
   }
 }
 
-function inferEffectiveContext(toolId, outputFiles) {
+function inferLoadEvidence(toolId, outputFiles, discovery, activation) {
+  const primaryFile = outputFiles[0] || null
+  const loadedBy = discovery.genericFallback ? 'generic-agent-file' : 'native-file-discovery'
+
+  return {
+    loadedBy,
+    effectiveSource: primaryFile,
+    deliveryPath: primaryFile,
+    deliveryMechanism: discovery.genericFallback ? 'generated-generic-fallback' : 'generated-native-surface',
+    hookInstalled: false,
+    injectedOnSessionStart: false,
+    manualInjectionRequired: discovery.manualActivationRequired,
+    resumeBehavior: 'not-proven',
+    dedupeKey: primaryFile ? `${toolId}:${loadedBy}:${primaryFile}` : `${toolId}:${loadedBy}:unknown`,
+    dedupeRisk: 'unknown',
+    evidence: outputFiles,
+    note: `${toolId} load path is inferred from generated files and known discovery surfaces; verify runtime loading/deduplication in the target agent when hooks, imports, or manual injection are also used.`,
+  }
+}
+
+function inferEffectiveContext(toolId, outputFiles, loadEvidence) {
   return {
     scope: 'repo-root',
     pathScoped: false,
@@ -406,11 +436,13 @@ function inferEffectiveContext(toolId, outputFiles) {
     overrideBehavior: 'none-modeled',
     isolationEvidence: 'not-modeled',
     entrypoints: outputFiles,
+    loadedBy: loadEvidence.loadedBy,
+    effectiveSource: loadEvidence.effectiveSource,
     note: `${toolId} output is audited as repo-root context only; verify subdirectory load order separately in monorepos.`,
   }
 }
 
-function summarizeSemanticDifference({ unsupportedSections, activation, discovery, effectiveContext }) {
+function summarizeSemanticDifference({ unsupportedSections, activation, discovery, effectiveContext, loadEvidence }) {
   const differences = []
 
   if (unsupportedSections.length > 0) {
@@ -433,6 +465,10 @@ function summarizeSemanticDifference({ unsupportedSections, activation, discover
     differences.push('manual-activation-required')
   }
 
+  if (loadEvidence?.dedupeRisk === 'unknown') {
+    differences.push('runtime-load-dedupe-not-proven')
+  }
+
   return differences.length > 0 ? differences : ['no-known-template-loss']
 }
 
@@ -452,10 +488,13 @@ function printFidelityReport(report) {
     const scope = target.effectiveContext?.scope
       ? `; effective context: ${target.effectiveContext.scope}`
       : ''
+    const loadedBy = target.loadEvidence?.loadedBy
+      ? `; loaded by: ${target.loadEvidence.loadedBy}`
+      : ''
     const semantics = target.semanticDifference?.length
       ? `; semantic: ${target.semanticDifference.join(', ')}`
       : ''
-    console.log(`   • ${target.toolId}: ${target.activation.kind}${discovery}${scope}${unsupported}${semantics}`)
+    console.log(`   • ${target.toolId}: ${target.activation.kind}${discovery}${scope}${loadedBy}${unsupported}${semantics}`)
   }
 
   for (const warning of report.warnings) {

package/src/utils/version.js

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