claude-prism 1.8.0 → 1.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-prism",
-  "version": "1.8.0",
+  "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,27 @@ 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.9.0] — 2026-03-18
+
+### Added
+- **Modular protocol files** — EUDEC methodology split into 6 on-demand protocol files (`essence.md`, `understand.md`, `decompose.md`, `execute.md`, `checkpoint.md`, `handoff.md`)
+- `copyProtocols()` in installer — copies protocol files to `.claude/protocols/prism/` during `init` and `update`
+- Protocol file verification tests
+
+### Changed
+- **Default `rulesMode` changed from `full` to `lean`** — CLAUDE.md injection reduced from 586 lines (26KB) to 114 lines (4.5KB), an 82% reduction
+- `rules-lean.md` now references `.claude/protocols/prism/*.md` for on-demand reading instead of `/claude-prism:prism` slash command
+- `preservedRulesMode` logic updated to preserve `full` mode for users who explicitly opted in
+- Existing users get lean mode automatically on `prism update` (marker-based replacement)
+
+## [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

package/README.md

@@ -23,7 +23,7 @@ the infrastructure that channels AI coding agents toward correct, verified outpu
 It combines a behavioral methodology (EUDEC), deterministic hooks for enforcement,
 session lifecycle automation, and adaptive process weight that scales with task complexity.
 
-Installs the EUDEC methodology — **Essence, Understand, Decompose, Execute, Checkpoint** — directly into your project's Claude Code environment. Includes a session transition protocol (Handoff) that bookends the core cycle. Seven hooks enforce the methodology and automate session management.
+Installs the EUDEC methodology — **Essence, Understand, Decompose, Execute, Checkpoint** — directly into your project's Claude Code environment. Includes a session transition protocol (Handoff) that bookends the core cycle. Eight hooks enforce the methodology and automate session management.
 
 ## The Problem
 
@@ -52,8 +52,8 @@ Injected into `CLAUDE.md`, EUDEC is a behavioral framework that corrects how AI
 
 ```
 ┌──────────────────── EUDEC Core Cycle ───────────────────┐
-│ ESSENCE ── Extract core problem → simplify → expand      │
-│   │        Task type derivation from essence             │
+│ ESSENCE ── Entry Judgment → extract core → simplify      │
+│   │        → expand · Scope Classification               │
 │ UNDERSTAND ── Sufficiency assessment → ask → align       │
 │   │          Environment validation                      │
 │   │          Analysis-only branch (skip D/E/C if no code │
@@ -90,7 +90,18 @@ Injected into `CLAUDE.md`, EUDEC is a behavioral framework that corrects how AI
 - **Streamlined verification**: 3-level fallback ladder (Tests → Build → Diff)
 - **Adaptive checkpoints**: no pause for small tasks, summary for medium, full for large
 
-**New in v1.7.0:**
+**New in v1.8.1:**
+- **ESSENCE phase expanded** — Entry Judgment (Top-down/Bottom-up/Hybrid approach selection), Top-Down Removal Method with Counterexample test, Bottom-Up Competitive Exploration for novel problems
+- **Scope Classification** — Core/Support/Out of Scope concentric circle model; "Out of Scope must not be empty" constraint prevents unbounded work
+- **Self-Correction Fallbacks** — each trigger now specifies an explicit fallback phase (→ ESSENCE/UNDERSTAND/DECOMPOSE) instead of generic "stop"
+
+**v1.8.0:**
+- **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
+- **Auto-backfill frontmatter** — plans without frontmatter get status auto-derived from checkbox progress
+- **mergeSettings() fix** — `prism update` now correctly adds new matchers for existing hook commands
+
+**v1.7.0:**
 - **Plan Lifecycle Management** — 6 states (`draft` → `active` → `completed` → `archived`, plus `blocked` and `abandoned`) with validated state machine transitions
 - **Auto-transitions** — plans auto-activate on first task check, auto-complete when all tasks done, with progress milestones (25/50/75%) logged
 - **Plan History** — `.prism/plans/.history.jsonl` records all status changes and milestones as timestamped events
@@ -119,7 +130,7 @@ Injected into `CLAUDE.md`, EUDEC is a behavioral framework that corrects how AI
 - **Verification scoping**: Build check output filtered to changed files only — pre-existing errors are ignored
 - **Agent failure recovery**: 3-step protocol when delegated agents produce incomplete results
 
-### 2. Seven Focused Hooks
+### 2. Eight Focused Hooks
 
 Hooks enforce the methodology at critical points:
 
@@ -132,8 +143,9 @@ Hooks enforce the methodology at critical points:
 | **session-end-handler** | SessionEnd | Saves HANDOFF + appends to `docs/PROJECT-MEMORY.md` |
 | **scope-injector** | SubagentStart | Injects current plan batch context into subagent |
 | **plan-sync** | TaskCompleted | Auto-updates plan file checkboxes on task completion |
+| **plan-progress** | PostToolUse | Tracks file-level progress against active plan's "Files in Scope" |
 
-The original three hooks (commit-guard, test-tracker, plan-enforcement) are deterministic enforcers. The four new hooks (v1.4.0) are **session lifecycle automations** — they don't block or warn, they auto-save context and sync plan state.
+The original three hooks (commit-guard, test-tracker, plan-enforcement) are deterministic enforcers. The four v1.4.0 hooks are **session lifecycle automations** — they auto-save context and sync plan state. The v1.8.0 **plan-progress** hook bridges the gap by tracking real-time file edits against the plan.
 
 ### 3. Slash Commands
 
@@ -221,7 +233,7 @@ your-project/
 │   ├── commands/claude-prism/   # 9 slash commands
 │   ├── hooks/                   # 6 runners (pre-tool, post-tool, precompact,
 │   │                            #   session-end, subagent-start, task-completed)
-│   ├── rules/                   # 7 rule modules
+│   ├── rules/                   # 8 rule modules
 │   ├── lib/                     # 9 shared dependencies
 │   └── settings.json            # Hook registration (6 events)
 
@@ -245,7 +257,8 @@ Edit `.prism/config.json`:
     "precompact-handler": { "enabled": true },
     "session-end-handler": { "enabled": true },
     "subagent-scope-injector": { "enabled": true },
-    "task-plan-sync": { "enabled": true, "matchThreshold": 0.3 }
+    "task-plan-sync": { "enabled": true, "matchThreshold": 0.3 },
+    "plan-progress-tracker": { "enabled": true }
   },
   "webhooks": [
     {
@@ -320,6 +333,18 @@ Prism auto-detects [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claud
 
 ## Upgrading
 
+### To v1.8.x
+
+```bash
+npx claude-prism update
+```
+
+v1.8.0 adds real-time plan progress tracking via `PostToolUse [Edit|Write]` hooks. The new `plan-progress-tracker` rule matches file edits against your plan's "Files in Scope" section and auto-tracks progress (25/50/75% milestones). Plans auto-transition from `draft` to `active` on the first scoped file edit.
+
+v1.8.1 expands the ESSENCE phase with Entry Judgment (approach selection), Scope Classification, and explicit fallback phases for self-correction triggers.
+
+`prism update` installs the new rule and adds the `Edit|Write` matcher to `settings.json` automatically. Existing hooks and configuration are preserved.
+
 ### To v1.7.0
 
 ```bash

package/lib/config.mjs

@@ -7,7 +7,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 
 const DEFAULTS = {
-  rulesMode: 'full',
+  rulesMode: 'lean',
   sourceExtensions: ['ts', 'tsx', 'js', 'jsx', 'py', 'go', 'rs', 'java', 'c', 'cpp', 'h', 'svelte', 'vue', 'rb', 'kt', 'swift', 'php', 'cs', 'scala', 'ex', 'clj', 'zig', 'lua', 'dart'],
   testPatterns: ['test', 'spec', '_test'],
   customRules: [],

package/lib/installer.mjs

@@ -83,6 +83,9 @@ export async function init(projectDir, options = {}) {
   // 4. Inject rules into CLAUDE.md
   injectRules(projectDir);
 
+  // 4b. Copy protocol reference files (on-demand EUDEC methodology)
+  copyProtocols(projectDir);
+
   // 5. Create .prism/ directory with config.json
   const prismDir = join(projectDir, '.prism');
   mkdirSync(prismDir, { recursive: true });
@@ -409,8 +412,8 @@ export async function update(projectDir) {
 
   await init(projectDir, { hooks });
 
-  // Restore rulesMode if it was set before migration
-  if (preservedRulesMode && preservedRulesMode !== 'full') {
+  // Restore rulesMode if it was explicitly set to non-default (default is now 'lean')
+  if (preservedRulesMode && preservedRulesMode !== 'lean') {
     const newConfig = JSON.parse(readFileSync(configPath, 'utf8'));
     newConfig.rulesMode = preservedRulesMode;
     writeFileSync(configPath, JSON.stringify(newConfig, null, 2) + '\n');
@@ -418,7 +421,7 @@ export async function update(projectDir) {
     injectRules(projectDir);
   }
 
-  // Source repo: re-inject rules from local templates (overrides the npx version)
+  // Source repo: re-inject rules and protocols from local templates (overrides the npx version)
   if (sourceRepo) {
     const mode = getRulesMode(projectDir);
     const fileName = mode === 'lean' ? 'rules-lean.md' : 'rules.md';
@@ -426,6 +429,10 @@ export async function update(projectDir) {
     if (existsSync(localRulesPath)) {
       injectRules(projectDir, localRulesPath);
     }
+    const localProtocolsDir = join(projectDir, 'templates', 'protocols');
+    if (existsSync(localProtocolsDir)) {
+      copyProtocols(projectDir, localProtocolsDir);
+    }
   }
 
   return sourceRepo ? { sourceRepo: true } : undefined;
@@ -856,6 +863,19 @@ function createRegistry(projectDir) {
 
 // ─── internal helpers ───
 
+function copyProtocols(projectDir, overrideDir) {
+  const protocolsSrcDir = overrideDir || join(TEMPLATES_DIR, 'protocols');
+  if (!existsSync(protocolsSrcDir)) return;
+
+  const protocolsDestDir = join(projectDir, '.claude', 'protocols', 'prism');
+  mkdirSync(protocolsDestDir, { recursive: true });
+
+  const protocolFiles = readdirSync(protocolsSrcDir).filter(f => f.endsWith('.md'));
+  for (const file of protocolFiles) {
+    copyFileSync(join(protocolsSrcDir, file), join(protocolsDestDir, file));
+  }
+}
+
 function injectRules(projectDir, overrideRulesPath) {
   const claudeMdPath = join(projectDir, 'CLAUDE.md');
   let rulesPath;

package/package.json

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

package/templates/protocols/checkpoint.md

@@ -0,0 +1,46 @@
+# EUDEC 5. CHECKPOINT — Confirmation Protocol
+
+## Quality Gate: EXECUTE → CHECKPOINT
+
+Before reporting completion of a phase:
+- [ ] All batch tasks reach terminal state (done or explicitly skipped with reason)
+- [ ] Build passes with zero new errors
+- [ ] No uncommitted changes left unstaged
+- [ ] Plan file updated with current `[x]` status
+
+If any gate fails → continue in EXECUTE, do not report completion.
+
+## 5-1. Batch Checkpoint
+
+After each batch:
+- Report what was completed
+- Report verification results (with evidence)
+- **Freshness check**: verify remaining plan targets still exist in codebase (quick grep)
+- Update plan file: mark completed tasks `[x]`, note any targets already done
+- Preview next batch
+- "Continue?"
+
+**Plan-Reality sync** (run at every checkpoint):
+1. Grep for plan's change targets (patterns, files, functions to modify)
+2. If target no longer exists → mark task as "already completed (prior work)"
+3. If new targets discovered → add to plan's "Risks / Open Questions"
+4. Update plan file's `Codebase Audit` section with fresh counts
+
+**Checkpoint frequency** (proportional to task weight):
+- **Lightweight tasks**: no checkpoint pause — report completion with evidence
+- **Standard tasks**: summary checkpoint (1-2 lines: what done, verification result, next)
+- **Full tasks**: full checkpoint with progress dashboard + "Continue?"
+- **Phase boundary**: always stop (mandatory, all weights)
+- **Blocker encountered**: always stop (mandatory, all weights)
+
+**Progress dashboard:**
+```
+Phase: [phase] | Batch: [N/M] | Tasks: [done/total] ([%])
+[████████░░] 80% — Next: [next batch name]
+Plan freshness: verified [date] | Remaining targets: [N] confirmed in code
+```
+
+## 5-2. Direction Change
+
+User says "change direction" → return to ESSENCE (re-examine from the core)
+User says "stop here" → clean exit

package/templates/protocols/decompose.md

@@ -0,0 +1,106 @@
+# EUDEC 3. DECOMPOSE — Planning Protocol
+
+## 3-1. Decomposition Trigger
+
+| Task Type | Trigger | Action |
+|-----------|---------|--------|
+| **Bugfix** | — | Skip decomposition. Go straight to locate → fix → verify. |
+| **Feature** | 3+ files affected (advisory: 2+ in tightly-coupled legacy, 5+ in well-tested modular) | Decompose into batches. Plan file if 6+ files or 3+ modules. |
+| **Migration** | — | Define pattern + file list. No per-file decomposition. |
+| **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. 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
+3. **Dependencies noted**: mark if a unit depends on a previous one
+4. **Test first**: tests come before implementation when tests exist for the area
+
+**Size Tags:**
+- **[S]** Small: <30 LOC, config/style/single-function changes
+- **[M]** Medium: 30-100 LOC, feature implementation, component creation
+- **[L]** Large: >100 LOC, multi-file rewrite, new module/architecture
+
+**Batch composition**:
+- Mixed: S+S+M = 1 batch, L = 1 batch alone
+- **[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-4. Plan File Persistence
+
+Save multi-step plans (6+ files) as markdown:
+- **Path**: `.prism/plans/YYYY-MM-DD-<topic>.md`
+
+```markdown
+---
+status: draft
+created: YYYY-MM-DD
+---
+
+## Goal
+One sentence: what we're building and why.
+
+## Architecture
+Tech stack, key decisions, 2-3 sentences max.
+
+## Related Plans
+- Depends on: `YYYY-MM-DD-<prior-plan>.md` (status: complete/in-progress)
+- Shared files: list files that overlap with other active plans
+- (Omit this section if no other plans exist)
+
+## Codebase Audit
+- Audit date: YYYY-MM-DD
+- Targets remaining: N files (verified by grep/search)
+- Already completed: N items (by prior work or other branches)
+- Evidence: `grep -r "pattern" --include="*.ext" | wc -l` → N
+
+## Files in Scope
+- `path/to/file1.ts` — [what changes]
+- `path/to/file2.ts` — [what changes]
+
+## Batch 1: [Name]
+- [ ] Task 1.1: [S] [description] | Verify: [auto: build/test/lint]
+- [ ] Task 1.2: [M] [description] | Verify: [auto: test] [manual: visual check]
+  - Prerequisite: Task 1.1
+
+## Risks / Open Questions
+- [Known unknowns or potential blockers]
+```
+
+## 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)
+- [ ] **Cross-plan check**: if other plans exist in `.prism/plans/`, identify overlapping files and note dependencies
+- [ ] Required types/interfaces have the necessary fields?
+- [ ] External package APIs behave as expected?
+- [ ] Cross-package dependencies identified?
+
+**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-6. Quality Gate: DECOMPOSE → EXECUTE
+
+Before starting execution, all must pass:
+- [ ] Plan file exists and targets verified against codebase
+- [ ] Project builds from current state (no pre-existing failures)
+- [ ] Dependencies resolved (lock file matches, no missing packages)
+- [ ] Environment validated (required env vars, services, configs present)
+
+If any gate fails → resolve before executing. Do not start implementation on a broken baseline.

package/templates/protocols/essence.md

@@ -0,0 +1,122 @@
+# EUDEC 1. ESSENCE — Essence Extraction Protocol
+
+Starting point for all work. Strip down to the core of the problem before implementation.
+
+Essence = "the thing without which it ceases to be what it is."
+
+## 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:**
+```
+## ESSENCE
+- Essence: [one sentence — no technology/tool names]
+- Minimal case: [simplest working form]
+- Expansion path: minimal → [step1] → [step2] → [complete]
+```
+
+## 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:
+
+| Essence Character | Type | Path |
+|-------------------|------|------|
+| "X is broken" | Bugfix | Fast Path (1-5) |
+| "X should be possible" | Feature | UNDERSTAND → DECOMPOSE → EXECUTE → CHECKPOINT |
+| "All X must become Y" | Migration | UNDERSTAND → pattern → batch apply → verify |
+| "X's structure must change" | Refactor | UNDERSTAND → DECOMPOSE → EXECUTE → CHECKPOINT |
+| "Why does X happen?" | Investigation | explore → analyze → report |
+
+**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-5. Essence Validation (Error Prevention)
+
+| Trap | Response |
+|------|----------|
+| Mistaking symptom for essence | "Is this the cause, or a consequence?" |
+| Mistaking solution for essence | "Add caching" is not the essence. "Eliminate redundant computation" is. |
+| Too abstract | "Can I write even one line of code from this?" |
+| Too specific | "What's the real problem one level up?" |
+
+**Core test**: If the essence statement contains specific technology/tool names → it's still at solution level, not essence. Go one level higher.
+
+## 1-6. Adaptive Weight (Task Size Routing)
+
+After extracting essence and task type, assess task weight to select the appropriate EUDEC path:
+
+| Weight | Criteria | Path |
+|--------|----------|------|
+| **Lightweight** | 1-2 files, <50 LOC, clear scope | Essence (1 line) → Execute → Verify → Done |
+| **Standard** | 3-5 files, 50-200 LOC | Full EUDEC, summary checkpoints |
+| **Full** | 6+ files, 200+ LOC, or unclear scope | Full EUDEC with plan file + full checkpoints |
+
+**Lightweight path** skips formal UNDERSTAND (sufficiency assessment, question rounds, alignment confirmation) and DECOMPOSE. The essence statement still grounds the work but takes one line, not a full section. Record: append 1-line summary to `docs/PROJECT-MEMORY.md` (what was changed and why).
+
+**Bugfix fast path** (regardless of file count):
+1. Reproduce the symptom
+2. Trace to root cause
+3. Minimal fix (smallest change that resolves the cause)
+4. Verify (test/build/diff)
+
+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)

package/templates/protocols/execute.md

@@ -0,0 +1,125 @@
+# EUDEC 4. EXECUTE — Execution Protocol
+
+## 4-1. Batch Execution
+
+1. **Adaptive batch size**:
+   - Simple/mechanical changes (imports, types, config, migration): 5-8 per batch
+   - Standard changes (feature add/modify): 3-4 per batch
+   - Complex changes (new module, architecture): 1-2 per batch
+2. **Git-as-Memory**: commit after each completed batch as a rollback point. Use `git diff` summaries to maintain context in long sessions.
+3. **Checkpoint**: report results after each batch + wait for user feedback
+4. **Report content**: what was done / verification results / next batch preview
+5. **On blockers**: stop immediately and report (do not guess)
+
+## 4-2. Verification Strategy (Risk-Based)
+
+Choose verification proportional to the **risk of the change**, not the file path:
+
+| Risk Level | When | Auto Verification | Manual (recommend only) |
+|------------|------|-------------------|----------------------|
+| **High** | Business logic, data mutation, auth, state machines, calculations | TDD: failing test → implement → pass | — |
+| **Medium** | New components with logic, API integration, config that affects behavior | Build + lint pass | Visual/runtime spot-check |
+| **Low** | Imports, types, style/layout, renaming, mechanical migration | Build/lint passes | — |
+| **No test infra** | No test framework, no CI/CD, manual deploy (legacy PHP, WordPress, etc.) | Grep-based static check + syntax validation | Browser/manual verification |
+
+**Auto vs Manual separation:**
+- **Auto** (required): build, test, lint — must pass before claiming completion
+- **Manual** (recommended, not required): visual checks, browser testing, UX review — note as "manual check recommended" in plan, don't list as a gate
+
+**Verifiability modifier**: Some changes are hard to verify automatically (UI layout, business rule nuances, security boundaries). For hard-to-verify + high-risk changes, require **human approval before commit** regardless of test results.
+
+**Verification Fallback Ladder** (use highest available level):
+
+| Level | Method | When |
+|-------|--------|------|
+| 1. Tests | Automated tests (unit, integration, e2e) | Test infrastructure exists |
+| 2. Build | Compiles + lint without new errors | No tests for this area |
+| 3. Diff | `git diff` reviewed for regressions | No build tooling |
+
+**Every change must have SOME verification.** If no tooling exists, `git diff` review is the minimum.
+
+**Verification scoping**: When running build checks (tsc, lint, etc.), filter output to only changed files. Pre-existing errors in other files are not your concern. Example: `tsc --noEmit 2>&1 | grep -i "<changed-file>"`
+
+**Core Rules:**
+1. Never claim completion without fresh **auto** verification evidence
+2. Never commit code that doesn't build
+3. For high-risk: write failing test first → minimal code to pass → verify
+4. For high-risk: write at least one **negative test** (what should this code NOT do? what input should it reject?)
+5. For medium/low: run build/lint after changes → confirm no regressions
+6. Never list manual verification as a pass criterion — it won't be enforced consistently
+
+## 4-3. Systematic Debugging (Bugfix path)
+
+| Step | Action | Output |
+|------|--------|--------|
+| 1. Root cause | Read error → reproduce → check recent changes → trace data flow | Hypothesis |
+| 2. Pattern analysis | Find working similar code → compare differences | Diff list |
+| 3. Hypothesis test | Single hypothesis → minimal change → test one at a time | Result |
+| 4. Fix | Write failing test → single fix → verify | Fix complete |
+
+**After 3 failed fixes: STOP. The problem is likely architectural, not local. Discuss with user.**
+
+## 4-4. Self-Correction Triggers
+
+- 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." → **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." → **Fallback: ESSENCE**
+
+## 4-5. Scope Guard
+
+**Only change what was requested. Nothing more, nothing less.**
+
+1. **Was this change explicitly requested?** → proceed
+2. **Is it required to make the requested change work?** → proceed
+3. **Is it an improvement I noticed while working?** → STOP. Note it, don't do it.
+4. **Is it "while I'm here" cleanup?** → STOP. Not your job right now.
+
+**If tempted:** Note it for the user. Ask: "I noticed X could be improved. Want me to address it after the current task?"
+
+## 4-6. Agent Delegation Verification
+
+When delegating work to sub-agents:
+
+1. **Clear instructions**: specify inputs, expected outputs, invariants, and pass criteria
+2. **Resource ownership**: each file/module has exactly one agent writing at a time — define non-overlapping scopes upfront
+3. **Read actual files** after agent completes — never trust the agent's report alone
+4. **Run build/test** to verify the agent's changes work
+5. **Fix or retry** if incomplete
+
+**Agent failure recovery**: If a delegated agent partially fails or produces incomplete results:
+1. Verify actual file state (read the file, not just the agent's report)
+2. If partially correct → complete the remaining work directly
+3. If fully wrong → retry with clearer instructions or execute directly
+
+**Never mark a delegated task as complete without reading the actual file state.**
+
+## 4-7. Project-Type Verification Examples
+
+| Project Type | Syntax Check | Smoke Test | Approval Test |
+|-------------|-------------|------------|---------------|
+| **PHP/WordPress** | `php -l file.php` | `curl` key pages, `wp-cli` commands | Capture page output before/after, diff |
+| **Static Sites** | Build completes | Link checker, visual diff of HTML | Compare output directory before/after |
+| **Scripts/CLI** | Language syntax check | Run with known inputs, compare outputs | Capture stdout before/after |
+| **Infra/Config** | `terraform plan`, `docker build` | Dry-run deploy | Compare plan output before/after |
+
+## 4-8. Checkpoint Integration
+
+Claude Code creates automatic checkpoints on every edit. Use `Esc+Esc` or `/rewind` to restore.
+- Before risky changes: checkpoint exists automatically
+- After failed batch: consider `/rewind` to restore clean state before retry
+- Checkpoints complement Git-as-Memory: git for cross-session, checkpoints for intra-session

package/templates/protocols/handoff.md

@@ -0,0 +1,63 @@
+# EUDEC 6. HANDOFF — Session Transition Protocol
+
+## 6-1. When to Handoff
+
+- Context window approaching limit (compaction warnings appearing)
+- Task is multi-session by nature (multi-day refactor, large migration)
+- Switching to a different task mid-session
+
+**Auto-triggers (via Prism hooks):**
+- PreCompact hook → auto-generates `docs/HANDOFF.md`
+- SessionEnd hook → auto-generates `docs/HANDOFF.md` + appends to `docs/PROJECT-MEMORY.md`
+
+## 6-2. Handoff Document
+
+Create `docs/HANDOFF.md` with:
+
+```markdown
+## Status
+[What's done, what's remaining]
+
+## Current State
+[Branch name, last commit, any uncommitted changes]
+
+## Next Steps
+[Exact next action to take, with file paths]
+
+## Decisions Made
+[Key choices and why, so they don't get re-debated]
+
+## Known Issues
+[Anything broken or incomplete]
+```
+
+## 6-3. Project Memory (persistent across all sessions)
+
+Maintain `docs/PROJECT-MEMORY.md` — cumulative knowledge that survives session transitions:
+
+```markdown
+## Architectural Decisions
+- [date] [decision] — [rationale]
+
+## Conventions
+- [naming, patterns, file structure rules discovered/established]
+
+## Environment Gotchas
+- [quirks, workarounds, version constraints and why]
+
+## Package Constraints
+- [package@version — why pinned, what breaks if upgraded]
+```
+
+**Rules:**
+- HANDOFF.md is session-scoped (overwritten each session transition)
+- PROJECT-MEMORY.md is permanent (append-only, never overwrite)
+- On session start: read PROJECT-MEMORY.md first, then HANDOFF.md if it exists
+
+## 6-4. Resuming from Handoff
+
+When a session starts:
+1. Read `docs/PROJECT-MEMORY.md` if it exists (persistent context)
+2. Read `docs/HANDOFF.md` if it exists (session context)
+3. Verify the described state matches reality (git status, file contents)
+4. Continue from "Next Steps"

package/templates/protocols/understand.md

@@ -0,0 +1,56 @@
+# EUDEC 2. UNDERSTAND — Understanding Protocol
+
+## 2-1. Information Sufficiency Assessment (MANDATORY)
+
+Before acting on any request, assess first:
+
+- **[Sufficient]** Specific file, function, symptom mentioned → skip to PLAN/DECOMPOSE
+- **[Partial]** Direction clear but details missing → explore code, then ask 1-2 questions
+- **[Insufficient]** Abstract, vague, multiple interpretations → must ask questions first
+
+## 2-2. Question Rules
+
+1. **One question at a time** — never ask multiple questions simultaneously
+2. **Multiple choice first** — 2-3 options with a recommendation
+3. **Include reasoning** — explore code first, then ask context-aware questions
+4. **Maximum 3 rounds** — Round 1: direction (what) / Round 2: constraints (how) / Round 3: scope
+5. **Explore first** — check package.json, existing structure before asking
+
+## 2-3. Environment Validation
+
+Before any implementation, verify:
+- Project builds from current state (no pre-existing failures)
+- Declared dependencies match lock file versions
+- Environment-specific config identified (env vars, local services, deploy targets)
+
+If any of these fail → resolve first. Do not implement on a broken baseline.
+
+## 2-4. Alignment Confirmation
+
+Before moving to DECOMPOSE:
+- Goal summarized in one sentence
+- Tech stack/approach agreed
+- MVP scope defined
+- User confirmed "proceed"
+
+## 2-5. Assumption Detection (Red Flag Checklist)
+
+**If you think you understand fully on first read, you probably don't.**
+
+| Red Flag | Question to Ask Yourself |
+|----------|------------------------|
+| "Obviously they want X" | Did they actually say X? Or am I inferring? |
+| "This is similar to Y" | What are the differences? Similar ≠ identical |
+| "The standard approach is..." | Is that what the user wants, or what I default to? |
+| "I know how this codebase works" | When did I last verify? Has it changed? |
+| "This is a simple fix" | Have I read the surrounding code? What might break? |
+| "They didn't mention Z, so it's not needed" | Or did they assume Z was obvious? |
+
+**Triggers:**
+- User request < 2 sentences → likely missing context. Explore first.
+- No file/function names mentioned → [Insufficient]. Must ask.
+- Words like "just", "simply", "quickly" → complexity is being underestimated.
+
+## 2-6. Analysis-Only Requests
+
+If no code change is needed (architecture review, cause analysis, investigation), report findings and ask: "Further action needed?" Do NOT proceed to DECOMPOSE/EXECUTE/CHECKPOINT unless the user requests implementation.

package/templates/rules-lean.md

@@ -12,13 +12,24 @@ On session start, read in order:
 After reading, verify described state matches reality (git status, file contents).
 <!-- PRISM:BOOT:END -->
 
-# Prism — EUDEC Methodology (Lean Mode)
+# Prism — EUDEC Methodology Framework
 
 **EUDEC = Essence, Understand, Decompose, Execute, Checkpoint** — the core cycle.
 
 > **Never implement what you haven't understood. Never understand what you haven't distilled to its essence.**
 
-For the full methodology, run `/claude-prism:prism`.
+## Protocol Reference (Read on demand)
+
+When entering an EUDEC phase, read the corresponding protocol file:
+
+| Phase | When to Read | File |
+|-------|-------------|------|
+| **Essence** | New feature, refactor, or unclear task | `.claude/protocols/prism/essence.md` |
+| **Understand** | Need to clarify requirements or assumptions | `.claude/protocols/prism/understand.md` |
+| **Decompose** | 3+ files affected, need batch plan | `.claude/protocols/prism/decompose.md` |
+| **Execute** | During implementation (batch execution, verification) | `.claude/protocols/prism/execute.md` |
+| **Checkpoint** | Reporting batch/phase completion | `.claude/protocols/prism/checkpoint.md` |
+| **Handoff** | Session ending, context limit, or task transition | `.claude/protocols/prism/handoff.md` |
 
 ---
 
@@ -27,17 +38,24 @@ For the full methodology, run `/claude-prism:prism`.
 | Weight | Criteria | Path |
 |--------|----------|------|
 | **Lightweight** | 1-2 files, <50 LOC, clear scope | Essence (1 line) → Execute → Verify → Record (1-line to `docs/PROJECT-MEMORY.md`) → Done |
-| **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 |
+| **Standard** | 3-5 files, 50-200 LOC | Full EUDEC (read protocols as needed) |
+| **Full** | 6+ files, 200+ LOC, or unclear scope | Full EUDEC with plan file + full checkpoints |
+
+## 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 |
 |-------------------|------|------|
 | "X is broken" | Bugfix | Fast Path (below) |
-| "X should be possible" | Feature | `/claude-prism:prism` |
+| "X should be possible" | Feature | Read `essence.md` → full EUDEC |
 | "All X must become Y" | Migration | Pattern → batch apply → verify |
-| "X's structure must change" | Refactor | `/claude-prism:prism` |
+| "X's structure must change" | Refactor | Read `essence.md` → full EUDEC |
 
 ## Bugfix Fast Path
 
@@ -69,11 +87,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
 
@@ -87,14 +106,14 @@ After 3 failed fixes: STOP. Discuss with user.
 ## Checkpoint Frequency
 
 - **Lightweight**: report completion with evidence, no pause
-- **Standard/Full**: run `/claude-prism:prism` for guided checkpoints
+- **Standard/Full**: read `.claude/protocols/prism/checkpoint.md` for guided checkpoints
 - **Blocker encountered**: always stop
 
 ## Session Handoff
 
 Prism hooks auto-generate `docs/HANDOFF.md` on compaction and session end.
 `docs/PROJECT-MEMORY.md` is auto-appended on session end.
-For manual handoff: Status, Current State, Next Steps, Decisions Made, Known Issues.
+For manual handoff: read `.claude/protocols/prism/handoff.md`.
 
 ## Completion Declaration
 

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,24 +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