claude-prism 1.7.2 → 1.8.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-prism",
-  "version": "1.7.2",
+  "version": "1.8.1",
   "description": "AI agent harness implementing the EUDEC methodology",
   "author": { "name": "lazysaturday91" },
   "repository": "https://github.com/lazysaturday91/claude-prism",

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.1] — 2026-03-09
+
+### Changed
+- **ESSENCE phase expanded** — Entry Judgment (Top-down/Bottom-up/Hybrid), Top-Down Removal Method with Counterexample test, Bottom-Up Competitive Exploration for novel problems
+- **Scope Classification** added to DECOMPOSE — Core/Support/Out of Scope concentric circle model; "Out of Scope must not be empty" constraint
+- **Self-Correction Triggers** — each trigger now specifies explicit fallback phase (→ ESSENCE/UNDERSTAND/DECOMPOSE); new triggers for scope expansion and error type oscillation
+- `rules-lean.md` synced with Entry Judgment summary and fallback annotations
+
+## [1.8.0] — 2026-03-06
+
+### Added
+- **Plan progress auto-tracking** — `PostToolUse [Edit|Write]` hook tracks file-level progress against active plan's "Files in Scope"
+- `plan-progress-tracker` rule: matches edited files to scoped files, records milestones (25/50/75%), auto-transitions `draft → active` on first edit
+- `PostToolUse [Edit|Write]` event matcher added to `settings.json` — enables hooks on file edits, not just Bash commands
+- `parseScopedFiles(content)` in `plan-lifecycle.mjs` — extracts file paths from "Files in Scope" section
+- `ensureFrontmatter(planPath, content)` in `plan-lifecycle.mjs` — auto-backfills frontmatter for plans without status (derives from checkbox progress)
+- Self-Correction Trigger: "Plan file checkboxes not updated after batch"
+- 27 new tests covering parseScopedFiles, ensureFrontmatter, plan-progress-tracker, and regression guards
+
+### Fixed
+- `mergeSettings()` now compares both command and matcher — prevents skipping new matchers for existing hook commands during `prism update`
+
 ## [1.7.2] — 2026-03-06
 
 ### Fixed

package/hooks/plan-progress-tracker.mjs

@@ -0,0 +1,121 @@
+/**
+ * claude-prism — Plan Progress Tracker
+ * PostToolUse rule: tracks file-level progress against active plan's "Files in Scope"
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, relative } from 'path';
+import { readJsonState, writeJsonState } from '../lib/state.mjs';
+import { parseScopedFiles, ensureFrontmatter, updatePlanStatus, appendHistory } from '../lib/plan-lifecycle.mjs';
+import { parseFrontmatter } from '../lib/handoff.mjs';
+
+export const planProgressTracker = {
+  name: 'plan-progress-tracker',
+
+  /**
+   * @param {Object} ctx - { action, filePath, ... }
+   * @param {Object} config - Prism config (projectRoot, hooks settings)
+   * @param {string} stateDir - Session state directory
+   * @returns {{ type: string, message?: string }}
+   */
+  evaluate(ctx, config, stateDir) {
+    // Only process Edit/Write actions
+    if (ctx.action !== 'edit' && ctx.action !== 'write') return { type: 'pass' };
+    if (!ctx.filePath) return { type: 'pass' };
+
+    const projectRoot = config.projectRoot || process.cwd();
+
+    // Find most recent active/draft plan
+    const plan = findActivePlan(projectRoot);
+    if (!plan) return { type: 'pass' };
+
+    // Parse "Files in Scope" → check if edited file is in scope
+    const scopedFiles = parseScopedFiles(plan.content);
+    if (scopedFiles.length === 0) return { type: 'pass' };
+
+    const relativePath = relative(projectRoot, ctx.filePath);
+    const inScope = scopedFiles.some(f =>
+      relativePath === f || relativePath.endsWith(f) || f.endsWith(relativePath)
+    );
+    if (!inScope) return { type: 'pass' };
+
+    // Accumulate touched files in session state
+    const state = readJsonState(stateDir, 'plan-progress') || { touched: [], recordedMilestones: [] };
+    if (!state.recordedMilestones) state.recordedMilestones = [];
+    if (!state.touched.includes(relativePath)) {
+      state.touched.push(relativePath);
+    }
+
+    // Ensure frontmatter exists (auto-backfill if missing)
+    try {
+      ensureFrontmatter(plan.path, plan.content);
+    } catch { /* should not break the hook */ }
+
+    // Calculate progress
+    const pct = Math.floor((state.touched.length / scopedFiles.length) * 100);
+    const fm = plan.frontmatter;
+    const planStatus = fm.status || 'active';
+
+    // draft → active (first scoped file edit)
+    if (planStatus === 'draft') {
+      try {
+        updatePlanStatus(plan.path, 'active');
+        appendHistory(projectRoot, {
+          plan: plan.name, event: 'status_change',
+          from: 'draft', to: 'active',
+          actor: 'hook:plan-progress-tracker',
+          detail: 'First scoped file edited'
+        });
+      } catch { /* lifecycle errors should not break the hook */ }
+    }
+
+    // Progress milestones (25%, 50%, 75%)
+    for (const m of [25, 50, 75]) {
+      if (pct >= m && !state.recordedMilestones.includes(m)) {
+        state.recordedMilestones.push(m);
+        try {
+          appendHistory(projectRoot, {
+            plan: plan.name, event: 'progress',
+            actor: 'hook:plan-progress-tracker',
+            detail: `Progress: ${state.touched.length}/${scopedFiles.length} (${pct}%)`
+          });
+        } catch { /* ignore */ }
+      }
+    }
+
+    // Save state
+    writeJsonState(stateDir, 'plan-progress', state);
+
+    return {
+      type: 'info',
+      message: `🌈 Plan progress: ${state.touched.length}/${scopedFiles.length} files (${pct}%) — ${plan.name}`
+    };
+  }
+};
+
+/**
+ * Find the most recent active or draft plan in .prism/plans/
+ * @param {string} projectRoot
+ * @returns {{ name: string, path: string, content: string, frontmatter: Object }|null}
+ */
+function findActivePlan(projectRoot) {
+  const plansDir = join(projectRoot, '.prism', 'plans');
+  if (!existsSync(plansDir)) return null;
+
+  let files;
+  try {
+    files = readdirSync(plansDir).filter(f => f.endsWith('.md')).sort().reverse();
+  } catch { return null; }
+
+  for (const f of files) {
+    const path = join(plansDir, f);
+    let content;
+    try { content = readFileSync(path, 'utf8'); } catch { continue; }
+    const fm = parseFrontmatter(content);
+    const status = fm.status || 'active';
+    if (status === 'active' || status === 'draft') {
+      return { name: f, path, content, frontmatter: fm };
+    }
+  }
+  return null;
+}

package/lib/installer.mjs

@@ -66,6 +66,7 @@ export async function init(projectDir, options = {}) {
     copyFileSync(join(hooksSourceDir, 'session-end-handler.mjs'), join(rulesDestDir, 'session-end-handler.mjs'));
     copyFileSync(join(hooksSourceDir, 'subagent-scope-injector.mjs'), join(rulesDestDir, 'subagent-scope-injector.mjs'));
     copyFileSync(join(hooksSourceDir, 'task-plan-sync.mjs'), join(rulesDestDir, 'task-plan-sync.mjs'));
+    copyFileSync(join(hooksSourceDir, 'plan-progress-tracker.mjs'), join(rulesDestDir, 'plan-progress-tracker.mjs'));
 
     // Copy lib dependencies
     const libDestDir = join(claudeDir, 'lib');
@@ -661,7 +662,7 @@ export function dryRun(projectDir, options = {}) {
       });
     }
 
-    for (const rule of ['commit-guard.mjs', 'test-tracker.mjs', 'plan-enforcement.mjs', 'precompact-handler.mjs', 'session-end-handler.mjs', 'subagent-scope-injector.mjs', 'task-plan-sync.mjs']) {
+    for (const rule of ['commit-guard.mjs', 'test-tracker.mjs', 'plan-enforcement.mjs', 'precompact-handler.mjs', 'session-end-handler.mjs', 'subagent-scope-injector.mjs', 'task-plan-sync.mjs', 'plan-progress-tracker.mjs']) {
       const target = join(claudeDir, 'rules', rule);
       actions.push({
         type: 'rule',
@@ -904,6 +905,7 @@ function mergeSettings(claudeDir) {
         for (const hook of hookList) {
           const alreadyExists = existing.hooks[event].some(
             h => h.hooks?.[0]?.command === hook.hooks?.[0]?.command
+              && (h.matcher || '') === (hook.matcher || '')
           );
           if (!alreadyExists) {
             existing.hooks[event].push(hook);

package/lib/plan-lifecycle.mjs

@@ -119,6 +119,49 @@ export function resolvePlan(projectRoot, planName) {
   return plans.find(p => (p.status || 'active') === 'active') || plans[0];
 }
 
+// ─── Scoped Files & Frontmatter Helpers ───
+
+/**
+ * Parse "Files in Scope" section from plan content
+ * Extracts backtick-wrapped file paths (e.g., `path/to/file.ts`)
+ * @param {string} content - Plan markdown content
+ * @returns {string[]} File paths extracted
+ */
+export function parseScopedFiles(content) {
+  const section = content.match(/##\s+Files\s+in\s+Scope\s*\n([\s\S]*?)(?=\n##|\n---|\s*$)/i);
+  if (!section) return [];
+  return [...section[1].matchAll(/`([^`]+\.[a-z]+)`/g)].map(m => m[1]);
+}
+
+/**
+ * Ensure a plan file has frontmatter; add if missing
+ * Derives status from checkbox progress (0/N → draft, M/N → active, N/N → completed)
+ * @param {string} planPath - Absolute path to plan file
+ * @param {string} content - Plan file content
+ */
+export function ensureFrontmatter(planPath, content) {
+  const fm = parseFrontmatter(content);
+  if (fm.status) return; // Already has frontmatter with status
+
+  // Derive status from checkbox state
+  let total = 0, done = 0;
+  for (const line of content.split('\n')) {
+    if (/^[-*]\s+\[x\]/i.test(line)) { total++; done++; }
+    else if (/^[-*]\s+\[ \]/.test(line)) { total++; }
+  }
+
+  let status = 'active';
+  if (total > 0 && done === 0) status = 'draft';
+  else if (total > 0 && done === total) status = 'completed';
+
+  // Extract date from filename (YYYY-MM-DD-topic.md)
+  const dateMatch = planPath.match(/(\d{4}-\d{2}-\d{2})/);
+  const created = dateMatch ? dateMatch[1] : new Date().toISOString().slice(0, 10);
+
+  const fmBlock = `---\nstatus: ${status}\ncreated: ${created}\n---\n\n`;
+  writeFileSync(planPath, fmBlock + content);
+}
+
 // ─── Plan Discovery & Import ───
 
 const PLAN_PATTERN = /^\d{4}-\d{2}-\d{2}-.+\.md$/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-prism",
-  "version": "1.7.2",
+  "version": "1.8.1",
   "description": "AI agent harness implementing the EUDEC methodology — Essence, Understand, Decompose, Execute, Checkpoint.",
   "type": "module",
   "bin": {

package/templates/rules-lean.md

@@ -30,6 +30,13 @@ For the full methodology, run `/claude-prism:prism`.
 | **Standard** | 3-5 files, 50-200 LOC | Run `/claude-prism:prism` for full EUDEC guidance |
 | **Full** | 6+ files, 200+ LOC, or unclear scope | Run `/claude-prism:prism` for full EUDEC with plan file |
 
+## Entry Judgment
+
+Before extracting essence: "Can existing elements be removed from this problem?"
+- **YES** (prior art exists) → Top-down: list components, remove one at a time, what remains is essence
+- **NO** (blank slate) → Bottom-up: collect broadly, score, compete 2-3 candidates, select survivor
+- **PARTIAL** → Split the problem, apply each path to its part
+
 ## Task Type Derivation
 
 | Essence Character | Type | Path |
@@ -69,11 +76,12 @@ After 3 failed fixes: STOP. Discuss with user.
 
 ## Self-Correction Triggers
 
-- Same file edited 3+ times → investigate root cause
-- Editing file not in plan → scope change needed?
-- 3 consecutive test failures → back to essence
+- Same file edited 3+ times → investigate root cause → **Fallback: UNDERSTAND**
+- Editing file not in plan → scope change needed? → **Fallback: DECOMPOSE**
+- 3 consecutive test failures → **Fallback: ESSENCE (was the essence wrong?)**
 - 5 turns autonomous → report progress before continuing
-- Adding workarounds to fix workarounds → design problem, step back
+- Adding workarounds to fix workarounds → **Fallback: ESSENCE (re-extract)**
+- Scope expanding beyond plan → **Fallback: DECOMPOSE (re-classify scope)**
 
 ## Rationalization Defense
 

package/templates/rules.md

@@ -29,13 +29,41 @@ The approach: **Essence → Simplify → Expand**. Strip down to the core of the
 
 Starting point for all work. Strip down to the core of the problem before implementation.
 
-### 1-1. Essence Extraction (3 Steps)
+Essence = "the thing without which it ceases to be what it is."
 
-| Step | Question | Output |
-|------|----------|--------|
-| **Extract** | "What do they actually want?" | Essence statement (1 sentence) |
-| **Simplify** | "What's the smallest working version?" | Minimal case |
-| **Expansion path** | "How do we grow from here?" | Expansion steps (2-4 steps) |
+### 1-1. Entry Judgment
+
+Before extracting essence, determine the approach:
+
+> "Can existing elements be removed from this problem?" (Are there references, prior art, existing solutions?)
+
+| Answer | Meaning | Path |
+|--------|---------|------|
+| **YES** | References, existing products, prior art exist | → Top-down (removal method) |
+| **NO** | No precedent, blank slate, novel domain | → Bottom-up (competitive exploration) |
+| **PARTIAL** | Some parts have references, some don't | → Hybrid (split, apply each path independently, merge in output) |
+
+Most coding tasks are **YES** (top-down). Bottom-up is for genuinely novel problems (new product direction, undefined feature space).
+
+### 1-2. Essence Extraction — Top-Down (Removal Method)
+
+The default path. Remove non-essential elements to reveal what remains.
+
+```
+Step 1. List all components of the problem/system
+Step 2. Remove one at a time, asking:
+        "Without this, is it still the thing?"
+          → YES (still the thing) → not essential, remove
+          → NO  (no longer the thing) → essence candidate
+Step 3. Validate remaining candidates:
+        "Do these alone justify the thing's existence?"
+          → YES → essence confirmed
+          → NO  → restore one removed item, re-test
+Step 4. Counterexample test:
+        "Can I name one scenario where this essence is wrong?"
+          → NO  → proceed
+          → YES → weaken confidence, document the counterexample, and verify the essence still holds from a different angle (e.g., different user persona, edge case, or opposing assumption)
+```
 
 **Output format:**
 ```
@@ -45,7 +73,28 @@ Starting point for all work. Strip down to the core of the problem before implem
 - Expansion path: minimal → [step1] → [step2] → [complete]
 ```
 
-### 1-2. Task Type Derivation
+### 1-3. Essence Extraction — Bottom-Up (Competitive Exploration)
+
+For novel problems with no prior art. Generate multiple essence candidates, compete them, select the survivor.
+
+```
+Step 1. Collect broadly (don't judge yet — quantity > quality)
+        Stop when: information saturates OR 3+ independent perspectives gathered OR time box hit
+Step 2. Filter (two-pass):
+        1st pass: gut feel — strong / moderate / weak (drop weak)
+        2nd pass: score remaining on frequency (1-3), impact (1-3), connectivity (1-3)
+        → 7-9 points: essence candidate
+        → 4-6 points: support element (reuse in DECOMPOSE)
+Step 3. Cluster similar candidates → select top 2-3
+        If only 1 candidate remains → create its opposite, compete them
+Step 4. Parallel exploration: "If this were the essence, what would we build?"
+        → Score difference ≤2 or irreversible decision → explore all equally
+        → Score difference >2 and reversible → staged elimination
+Step 5. Converge: which candidate solves the user's problem more directly?
+        Feasibility is NOT a factor here (that's DECOMPOSE's job)
+```
+
+### 1-4. Task Type Derivation
 
 The task type naturally emerges from the essence:
 
@@ -59,7 +108,7 @@ The task type naturally emerges from the essence:
 
 **Migration shortcut**: When applying the same transformation to 10+ files, don't decompose into individual file tasks. Define the pattern once, apply in batches of 5-10, verify after each batch. Scope guard thresholds are raised automatically when a plan file exists.
 
-### 1-3. Essence Validation (Error Prevention)
+### 1-5. Essence Validation (Error Prevention)
 
 | Trap | Response |
 |------|----------|
@@ -70,15 +119,7 @@ The task type naturally emerges from the essence:
 
 **Core test**: If the essence statement contains specific technology/tool names → it's still at solution level, not essence. Go one level higher.
 
-### 1-4. Quality Gate: ESSENCE → UNDERSTAND
-
-Before moving to UNDERSTAND, verify:
-- [ ] Essence statement is technology-neutral (holds without naming specific tools/libraries)
-- [ ] Minimal case is truly "minimal" (can it be reduced further?)
-- [ ] Each step in the expansion path works independently
-- [ ] Task type has been clearly derived
-
-### 1-5. Adaptive Weight (Task Size Routing)
+### 1-6. Adaptive Weight (Task Size Routing)
 
 After extracting essence and task type, assess task weight to select the appropriate EUDEC path:
 
@@ -98,6 +139,15 @@ After extracting essence and task type, assess task weight to select the appropr
 
 Bugfixes skip ESSENCE extraction, UNDERSTAND ceremony, and DECOMPOSE entirely. The 4-step debugging protocol (4-3) is the complete path.
 
+### 1-7. Quality Gate: ESSENCE → UNDERSTAND
+
+Before moving to UNDERSTAND, verify:
+- [ ] Essence statement is technology-neutral (holds without naming specific tools/libraries)
+- [ ] Minimal case is truly "minimal" (can it be reduced further?)
+- [ ] Each step in the expansion path works independently
+- [ ] Task type has been clearly derived
+- [ ] Counterexample test passed (no unresolved counterexamples)
+
 ---
 
 ## EUDEC 2. UNDERSTAND — Understanding Protocol
@@ -171,7 +221,23 @@ If no code change is needed (architecture review, cause analysis, investigation)
 | **Refactor** | 3+ files affected (same advisory as Feature) | Decompose into batches. Plan file if 6+ files or 3+ modules. |
 | **Investigation** | — | Skip decomposition. Define exploration scope. |
 
-### 3-2. Decomposition Principles (Feature/Refactor only)
+### 3-2. Scope Classification (before decomposing)
+
+Before breaking into batches, classify all changes using the concentric circle model:
+
+```
+"Is this required for the essence to work?"
+  → YES → Core (must be in scope)
+  → NO  → "Does this amplify the essence's value?"
+    → YES → Support (nice to have, lower priority)
+    → NO  → Out of Scope (explicitly excluded)
+```
+
+- Only **Core** items enter batch decomposition
+- **Support** items are noted for later (not in current plan)
+- **Out of Scope** must not be empty — if everything is "Core", scope classification has failed (return to ESSENCE)
+
+### 3-3. Decomposition Principles (Feature/Refactor only)
 
 1. **Independent verification**: each unit has a pass criterion
 2. **Files specified**: each task lists files to create/modify
@@ -188,7 +254,7 @@ If no code change is needed (architecture review, cause analysis, investigation)
 - **[S]-only: up to 8 per batch** (independent small changes can be batched aggressively)
 - Aligns with 4-1 adaptive batch size (simple/mechanical: 5-8 per batch)
 
-### 3-3. Plan File Persistence
+### 3-4. Plan File Persistence
 
 Save multi-step plans (6+ files) as markdown:
 - **Path**: `.prism/plans/YYYY-MM-DD-<topic>.md`
@@ -229,7 +295,7 @@ Tech stack, key decisions, 2-3 sentences max.
 - [Known unknowns or potential blockers]
 ```
 
-### 3-4. Pre-Decomposition Check
+### 3-5. Pre-Decomposition Check
 
 Before creating the plan:
 - [ ] **Codebase audit**: grep/search to verify targets actually exist in code (don't trust assumptions from prior sessions)
@@ -240,7 +306,7 @@ Before creating the plan:
 
 **Staleness prevention**: If plan targets (files to change, patterns to replace) no longer exist in the codebase, mark them as "already completed" before starting execution. Never start a plan without verifying its targets are real.
 
-### 3-5. Quality Gate: DECOMPOSE → EXECUTE
+### 3-6. Quality Gate: DECOMPOSE → EXECUTE
 
 Before starting execution, all must pass:
 - [ ] Plan file exists and targets verified against codebase
@@ -315,23 +381,24 @@ Choose verification proportional to the **risk of the change**, not the file pat
 
 ### 4-4. Self-Correction Triggers
 
-- Same file edited 3+ times → "Possible thrashing. Investigate root cause."
-- Editing file not in plan → "Scope change needed?"
-- 3 consecutive test failures → "Approach problem. Back to ESSENCE — did we get the essence wrong?"
+- Same file edited 3+ times → "Possible thrashing. Investigate root cause." → **Fallback: UNDERSTAND (re-examine the problem)**
+- Editing file not in plan → "Scope change needed?" → **Fallback: DECOMPOSE (re-classify scope)**
+- 3 consecutive test failures → "Approach problem." → **Fallback: ESSENCE (was the essence wrong?)**
 - New package needed → "Confirm with user"
 - 5 turns autonomous → "Report progress before continuing"
-- Adding workarounds to fix workarounds → "Design problem. Step back."
+- Adding workarounds to fix workarounds → "Design problem." → **Fallback: ESSENCE (re-extract)**
 - Copy-pasting similar code 3+ times → "Need abstraction? Ask user."
 - Dependency version mismatch detected → "Resolve before continuing."
+- Plan file checkboxes not updated after batch → "Update plan checkboxes and frontmatter before continuing"
+- Scope expanding beyond plan → "Scope creep." → **Fallback: DECOMPOSE (re-run scope classification)**
+- Error messages changing type across fixes → "Chasing symptoms, not root cause." → **Fallback: ESSENCE**
 
 **Goal Recitation** (prevents drift in long sessions):
 - At every batch boundary, re-read the plan file and confirm: "Current work aligns with: [original goal]"
 - If current work does not serve the original goal → STOP, report drift, return to plan
 
 **Thrashing Detector** (beyond simple edit counting):
-- Successive edits reverting previous changes (oscillation) → "Reverting own work. Wrong approach."
-- Scope of changes expanding beyond plan → "Scope creep. Return to DECOMPOSE."
-- Error messages changing type across fixes → "Chasing symptoms, not root cause. Back to ESSENCE."
+- Successive edits reverting previous changes (oscillation) → "Reverting own work. Wrong approach." → **Fallback: ESSENCE**
 
 ### 4-5. Scope Guard
 

package/templates/runners/post-tool.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { runPipelineAsync } from '../lib/pipeline.mjs';
 import { testTracker } from '../rules/test-tracker.mjs';
+import { planProgressTracker } from '../rules/plan-progress-tracker.mjs';
 
 await runPipelineAsync([
   { name: 'test-tracker', rule: testTracker },
+  { name: 'plan-progress-tracker', rule: planProgressTracker },
 ], 'PostToolUse');

package/templates/settings.json

@@ -32,6 +32,16 @@
             "timeout": 5000
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/post-tool.mjs",
+            "timeout": 5000
+          }
+        ]
       }
     ],
     "PreCompact": [