getprismo 0.1.31 → 0.1.32

package/README.md

@@ -622,9 +622,10 @@ it surfaces recurring waste patterns such as the same lockfile leaking into many
 
 ```bash
 npx getprismo instructions audit
+npx getprismo instructions ablate --dry-run
 ```
 
-it scores rules in `CLAUDE.md`, `AGENTS.md`, `.codex/AGENTS.md`, `.codex/instructions.md`, and `.openai/instructions.md`, then flags duplicated rules, low-signal rules, trim candidates, and rules that appear ineffective based on recent session evidence.
+it scores rules in `CLAUDE.md`, `AGENTS.md`, `.codex/AGENTS.md`, `.codex/instructions.md`, and `.openai/instructions.md`, then separates observable violations, partial compliance, duplicated rules, trim candidates, and influence-unknown rules. `instructions ablate --dry-run` creates a conservative ablation plan with candidates, sample-count guidance, rollback notes, and variance warnings; it does not edit files.
 
 `boundaries` checks parallel-agent isolation:
 
@@ -720,6 +721,7 @@ no install needed. npx runs it directly.
 | `replay` | incident replay with root cause and recovery prompt |
 | `timeline` | recurring context-waste patterns across recent sessions |
 | `instructions audit` | instruction ROI audit for CLAUDE.md / AGENTS.md violations, partial compliance, duplicates, and influence-unknown rules |
+| `instructions ablate --dry-run` | conservative ablation plan for instruction candidates without editing files |
 | `boundaries` | multi-agent boundary check for shared files/artifacts and worktree overlap |
 | `scan --usage` | full repo scan with local usage data |
 | `scan --optimizer-fit` | recommend which token-optimization path fits your repo/session |
@@ -810,6 +812,7 @@ npx getprismo mcp /path/to/repo
 - `prismo_cursor_sessions`
 - `prismo_receipt`
 - `prismo_instructions_audit`
+- `prismo_instructions_ablate`
 - `prismo_timeline`
 - `prismo_replay`
 - `prismo_boundaries`
@@ -990,7 +993,7 @@ lib/prismo-dev/context-optimize.js  context packs, scoped prompts
 lib/prismo-dev/boundaries.js     multi-agent boundary and worktree overlap checks
 lib/prismo-dev/doctor.js         doctor/dev/init orchestration
 lib/prismo-dev/fixes.js          safe ignore/template generation
-lib/prismo-dev/instructions.js   instruction ROI and dead-rule analysis
+lib/prismo-dev/instructions.js   instruction ROI, partial-compliance, and ablation planning
 lib/prismo-dev/mcp.js            local MCP server and Prismo tool bindings
 lib/prismo-dev/receipt.js        run receipts for reads, output, artifacts, and next scope
 lib/prismo-dev/report.js         terminal, markdown, ci reports

package/lib/prismo-dev/instructions.js

@@ -364,8 +364,147 @@ module.exports = function createInstructionsAudit(deps) {
     return lines.join("\n");
   }
 
+  function makeAblationCandidate(rule, mode, reason, expectedSignal) {
+    return {
+      id: rule.id,
+      file: rule.file,
+      line: rule.line,
+      text: rule.text,
+      status: rule.status,
+      tokens: rule.tokens,
+      mode,
+      reason,
+      expectedSignal,
+      rollback: `Restore ${rule.file}:${rule.line} if failures, context growth, or repeated reads increase during the ablation window.`,
+    };
+  }
+
+  function buildInstructionsAblationPlan(options = {}) {
+    const root = options.cwd || process.cwd();
+    const samples = Math.max(3, Number(options.samples || 10));
+    const audit = buildInstructionsAudit(options);
+    const duplicateCandidates = audit.prunable
+      .filter((rule) => rule.status === "duplicate")
+      .map((rule) => makeAblationCandidate(
+        rule,
+        "dedupe",
+        "Duplicate rule appears more than once; remove or consolidate the repeated copy first.",
+        "No regression in repeated reads, artifact leaks, or task failures after dedupe."
+      ));
+    const trimCandidates = audit.prunable
+      .filter((rule) => rule.status === "trim-candidate")
+      .map((rule) => makeAblationCandidate(
+        rule,
+        "trim",
+        "Verbose persistent rule adds recurring context weight; test a shorter equivalent.",
+        "Similar session outcomes with fewer persistent-instruction tokens."
+      ));
+    const violationCandidates = audit.prunable
+      .filter((rule) => rule.status === "observably-violated")
+      .map((rule) => makeAblationCandidate(
+        rule,
+        "rewrite-as-guardrail",
+        "The rule maps to measurable session violations; do not simply delete the intent.",
+        "Violation count falls after moving the rule into a live guardrail/firewall or making it more enforceable."
+      ));
+    const partialCandidates = audit.partialCompliance.map((rule) => makeAblationCandidate(
+      rule,
+      "rewrite-as-acceptance-check",
+      "The session appears to perform the visible ritual, but noisy/failing evidence suggests weak follow-through.",
+      "The agent reports how the referenced file constrained the edit, and related failures/retries decrease."
+    ));
+    const influenceCandidates = audit.influenceUnknown.map((rule) => makeAblationCandidate(
+      rule,
+      "ablate",
+      "Influence is not directly observable; remove only for a controlled sample window.",
+      "No worse outcome across matched task runs, with stable decoding settings and similar task mix."
+    ));
+
+    const candidates = [
+      ...duplicateCandidates,
+      ...trimCandidates,
+      ...violationCandidates,
+      ...partialCandidates,
+      ...influenceCandidates,
+    ].slice(0, options.limit || 20);
+
+    const groups = {
+      cheapWins: duplicateCandidates.length + trimCandidates.length,
+      rewriteFirst: violationCandidates.length + partialCandidates.length,
+      controlledAblation: influenceCandidates.length,
+    };
+
+    return {
+      schemaVersion: 1,
+      command: "instructions ablate",
+      dryRun: true,
+      generatedAt: new Date().toISOString(),
+      scannedPath: root,
+      confidence: audit.confidence,
+      samples,
+      auditSummary: audit.summary,
+      groups,
+      candidates,
+      protocol: [
+        "Change one instruction candidate at a time; do not rewrite the whole file during the same window.",
+        `Collect at least ${samples} comparable sessions before trusting an influence-unknown ablation.`,
+        "Keep model, decoding temperature, tools, and task type as stable as possible.",
+        "Track repeated reads, generated artifact leaks, command loops, failures, and task completion quality.",
+        "Prefer dedupe/trim and scoped guardrail rewrites before removing aspirational rules.",
+      ],
+      warnings: [
+        "Ablation is noisy: removing one rule can re-weight attention across the remaining instruction file.",
+        "Influence-unknown does not mean dead; it means local logs do not expose a clean behavioral signal.",
+        "Observably violated and partial-compliance rules should usually be rewritten or scoped, not blindly deleted.",
+      ],
+      next: candidates.length
+        ? [
+            `Start with ${candidates[0].file}:${candidates[0].line} (${candidates[0].mode}).`,
+            "Run the next sessions with a receipt/timeline comparison.",
+            `${NPX_COMMAND} receipt --limit ${Math.min(samples, 10)}`,
+          ]
+        : [
+            "No ablation candidates found. Run instructions audit again after more sessions.",
+          ],
+    };
+  }
+
+  function renderInstructionsAblationTerminal(plan) {
+    const lines = [];
+    lines.push("");
+    lines.push("Prismo Instruction Ablation Plan");
+    lines.push("");
+    lines.push("Mode: dry run (no files changed)");
+    lines.push(`Candidates: ${plan.candidates.length}`);
+    lines.push(`Sample target: ${plan.samples} comparable sessions`);
+    lines.push(`Cheap wins: ${plan.groups.cheapWins}  |  Rewrite first: ${plan.groups.rewriteFirst}  |  Controlled ablation: ${plan.groups.controlledAblation}`);
+    lines.push("");
+    lines.push("Candidates");
+    if (plan.candidates.length) {
+      plan.candidates.slice(0, 10).forEach((candidate, index) => {
+        lines.push(`${index + 1}. ${candidate.file}:${candidate.line} [${candidate.mode}] ${candidate.text}`);
+        lines.push(`   Why: ${candidate.reason}`);
+        lines.push(`   Measure: ${candidate.expectedSignal}`);
+      });
+    } else {
+      lines.push("- No candidates found.");
+    }
+    lines.push("");
+    lines.push("Protocol");
+    plan.protocol.forEach((item, index) => lines.push(`${index + 1}. ${item}`));
+    lines.push("");
+    lines.push("Warnings");
+    plan.warnings.forEach((item) => lines.push(`- ${item}`));
+    lines.push("");
+    lines.push("Next");
+    plan.next.forEach((item, index) => lines.push(`${index + 1}. ${item}`));
+    return lines.join("\n");
+  }
+
   return {
+    buildInstructionsAblationPlan,
     buildInstructionsAudit,
+    renderInstructionsAblationTerminal,
     renderInstructionsAuditTerminal,
   };
 };

package/lib/prismo-dev/mcp.js

@@ -33,6 +33,7 @@ function createMcpTools(deps) {
     getClaudeCodeCostSummary,
     getCursorSessionSummary,
     buildBoundaryCheck,
+    buildInstructionsAblationPlan,
     buildInstructionsAudit,
     buildMultiSessionTimeline,
     buildReceipt,
@@ -126,6 +127,11 @@ function createMcpTools(deps) {
       path: pathProperty,
       limit: limitProperty,
     }),
+    makeTool("prismo_instructions_ablate", "Create a dry-run instruction ablation plan with candidates, protocol, and variance warnings.", {
+      path: pathProperty,
+      limit: limitProperty,
+      samples: { type: "number", description: "Comparable session sample target for controlled ablation." },
+    }),
     makeTool("prismo_timeline", "Return recurring context-waste patterns across recent sessions.", {
       path: pathProperty,
       tool: { type: "string", enum: ["all", "codex", "claude", "cursor"], description: "Which local session logs to inspect." },
@@ -254,6 +260,14 @@ function createMcpTools(deps) {
       }));
     }
 
+    if (name === "prismo_instructions_ablate") {
+      return createTextResult(buildInstructionsAblationPlan({
+        cwd: target,
+        limit: Number(args.limit) || 20,
+        samples: Number(args.samples) || 10,
+      }));
+    }
+
     if (name === "prismo_timeline") {
       return createTextResult(buildMultiSessionTimeline({
         cwd: target,
@@ -379,6 +393,7 @@ async function runMcpDoctor(deps) {
     "prismo_cursor_sessions",
     "prismo_receipt",
     "prismo_instructions_audit",
+    "prismo_instructions_ablate",
     "prismo_timeline",
     "prismo_replay",
     "prismo_boundaries",

package/lib/prismo-dev-scan.js

@@ -260,7 +260,9 @@ const {
 });
 
 const {
+  buildInstructionsAblationPlan,
   buildInstructionsAudit,
+  renderInstructionsAblationTerminal,
   renderInstructionsAuditTerminal,
 } = require("./prismo-dev/instructions")({
   fs,
@@ -334,6 +336,7 @@ Usage:
   prismo cursor [list|authorship|timeline|files|all] [--json] [--limit N] [path]
   prismo receipt [codex|claude|cursor|all] [--json] [--limit N] [path]
   prismo instructions audit [--json] [--limit N] [path]
+  prismo instructions ablate --dry-run [--json] [--limit N] [--samples N] [path]
   prismo timeline [codex|claude|cursor|all] [--json] [--last N] [path]
   prismo replay [codex|claude|cursor|all] [--json] [--limit N] [path]
   prismo boundaries [codex|claude|cursor|all] [--json] [--limit N] [path]
@@ -355,7 +358,7 @@ Commands:
   cc          Show Claude Code token cost, cache cost, and all-time totals.
   cursor      Show Cursor session data, AI authorship, and AI-generated file tracking.
   receipt     Generate a run receipt for reads, repeats, output, artifacts, and next-run scope.
-  instructions Audit CLAUDE.md / AGENTS.md rule ROI, violations, partial compliance, duplicates, and influence-unknown rules.
+  instructions Audit or ablate CLAUDE.md / AGENTS.md rule ROI, violations, partial compliance, duplicates, and influence-unknown rules.
   timeline    Show recurring context-waste patterns across recent sessions.
   replay      Reconstruct why a session went sideways and print a recovery prompt.
   boundaries  Check whether parallel agents are isolated or overlapping.
@@ -514,14 +517,18 @@ Output:
 
 Usage:
   prismo instructions audit [--json] [--limit N] [path]
+  prismo instructions ablate --dry-run [--json] [--limit N] [--samples N] [path]
 
 Examples:
   prismo instructions audit
   prismo instructions audit --json
+  prismo instructions ablate --dry-run
+  prismo instructions ablate --dry-run --json
 
 Output:
   Scores persistent instruction rules from CLAUDE.md, AGENTS.md, and Codex/OpenAI instruction files.
-  Highlights useful guardrails, duplicates, stale or low-signal lines, and rules that look ignored by recent session evidence.`,
+  Highlights useful guardrails, duplicates, partial compliance, influence-unknown lines, and conservative ablation candidates.
+  Ablation mode is dry-run only: it produces a protocol and candidate list without editing files.`,
     timeline: `Prismo Multi-Session Timeline
 
 Usage:
@@ -887,6 +894,7 @@ async function runCli(argv) {
       getClaudeCodeCostSummary,
       getCursorSessionSummary,
       buildBoundaryCheck,
+      buildInstructionsAblationPlan,
       buildInstructionsAudit,
       buildMultiSessionTimeline,
       buildReceipt,
@@ -1051,11 +1059,25 @@ async function runCli(argv) {
   if (command === "instructions") {
     const json = rest.includes("--json");
     const limitIndex = rest.indexOf("--limit");
-    const positional = getPositionals(rest, new Set(["--limit"]));
-    const subcommand = positional[0] && positional[0].toLowerCase() === "audit" ? "audit" : "audit";
-    const target = subcommand === "audit" && positional[0]?.toLowerCase() === "audit"
+    const samplesIndex = rest.indexOf("--samples");
+    const positional = getPositionals(rest, new Set(["--limit", "--samples"]));
+    const subcommand = ["audit", "ablate"].includes(positional[0]?.toLowerCase()) ? positional[0].toLowerCase() : "audit";
+    const target = ["audit", "ablate"].includes(positional[0]?.toLowerCase())
       ? positional[1] || process.cwd()
       : positional[0] || process.cwd();
+    if (subcommand === "ablate") {
+      const plan = buildInstructionsAblationPlan({
+        cwd: path.resolve(target),
+        limit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 20),
+        samples: parsePositiveInt(samplesIndex >= 0 ? rest[samplesIndex + 1] : null, 10),
+      });
+      if (json) {
+        console.log(JSON.stringify(plan, null, 2));
+        return;
+      }
+      console.log(renderInstructionsAblationTerminal(plan));
+      return;
+    }
     const audit = buildInstructionsAudit({
       cwd: path.resolve(target),
       limit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 20),
@@ -1317,6 +1339,7 @@ module.exports = {
   renderSimpleScanReport,
   renderClaudeCostTerminal,
   renderCursorTerminal,
+  renderInstructionsAblationTerminal,
   renderInstructionsAuditTerminal,
   renderMultiSessionTimelineTerminal,
   renderReceiptTerminal,
@@ -1342,6 +1365,7 @@ module.exports = {
   getClaudeCodeCostSummary,
   getCursorSessionSummary,
   buildBoundaryCheck,
+  buildInstructionsAblationPlan,
   buildReceipt,
   buildInstructionsAudit,
   buildMultiSessionTimeline,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getprismo",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "description": "Local AI coding workflow scanner for Codex, Claude Code, Cursor, and token-waste diagnostics.",
   "license": "MIT",
   "homepage": "https://github.com/shanirsh/prismodev#readme",