pluribus-context 0.3.15 → 0.3.16

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 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

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

@@ -15,7 +15,7 @@ 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
+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:
@@ -23,7 +23,7 @@ For the npm release path, copy `examples/portability-fidelity/pluribus.md` into
 ```bash
 npx --yes pluribus-context@latest validate
 npx --yes pluribus-context@latest sync --dry-run
-npx --yes pluribus-context@latest audit --json
+npx --yes pluribus-context@latest audit --json --fidelity-report
 ```
 
 ## What a claim should say
@@ -75,7 +75,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` gives CI/reviewers a machine-readable check for missing or drifted outputs.
+- `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.
@@ -85,7 +85,7 @@ That does **not** prove runtime behavior. You still need tool-specific smoke tes
 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.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.15",
+  "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.15'
+export const VERSION = '0.3.16'