claude-prism 0.8.0 → 1.0.0

package/bin/cli.mjs

@@ -163,14 +163,81 @@ switch (command) {
     }
 
     console.log('🌈 claude-prism update\n');
-    await update(cwd);
-    console.log('✅ UDEC methodology updated');
+    const result = await update(cwd);
+    if (result?.sourceRepo) {
+      console.log('✅ UDEC methodology updated (from local templates)');
+    } else {
+      console.log('✅ UDEC methodology updated');
+    }
     console.log('✅ Commands updated');
     console.log('✅ Commit guard updated');
     console.log('\n🌈 Prism updated to latest.');
     break;
   }
 
+  case 'analytics': {
+    const { listSessions, getSessionSummary } = await import('../lib/session.mjs');
+    console.log('🌈 claude-prism analytics\n');
+
+    const sessions = listSessions();
+    if (sessions.length === 0) {
+      console.log('  No session data yet. Analytics will populate as hooks run.');
+      break;
+    }
+
+    let totalBlocks = 0;
+    let totalWarnings = 0;
+    let totalTestsRun = 0;
+    let totalTestsPassed = 0;
+    let totalTestsFailed = 0;
+    let totalFilesModified = 0;
+    let totalFilesCreated = 0;
+    let totalTurns = 0;
+    let sessionCount = 0;
+
+    for (const sid of sessions) {
+      const summary = getSessionSummary(sid);
+      if (!summary) continue;
+      sessionCount++;
+      totalBlocks += summary.blocks;
+      totalWarnings += summary.warnings;
+      totalTestsRun += summary.testsRun;
+      totalTestsPassed += summary.testsPassed;
+      totalTestsFailed += summary.testsFailed;
+      totalFilesModified += summary.filesModified;
+      totalFilesCreated += summary.filesCreated;
+      totalTurns += summary.turns;
+    }
+
+    console.log(`  Sessions:        ${sessionCount}`);
+    console.log(`  Total events:    ${totalTurns + totalBlocks + totalWarnings + totalTestsRun + totalFilesModified + totalFilesCreated}`);
+    console.log('');
+    console.log('  Hook Effectiveness:');
+    console.log(`    Blocks:        ${totalBlocks}`);
+    console.log(`    Warnings:      ${totalWarnings}`);
+    console.log('');
+    console.log('  Test Activity:');
+    console.log(`    Runs:          ${totalTestsRun}`);
+    console.log(`    Passed:        ${totalTestsPassed}`);
+    console.log(`    Failed:        ${totalTestsFailed}`);
+    console.log('');
+    console.log('  File Activity:');
+    console.log(`    Modified:      ${totalFilesModified}`);
+    console.log(`    Created:       ${totalFilesCreated}`);
+
+    if (hasFlag('detail')) {
+      console.log('\n  Recent Sessions:\n');
+      const recent = sessions.slice(-5);
+      for (const sid of recent) {
+        const s = getSessionSummary(sid);
+        if (!s) continue;
+        const date = new Date(s.startedAt).toISOString().slice(0, 19).replace('T', ' ');
+        console.log(`    ${date} | events: ${s.totalEvents} | blocks: ${s.blocks} | warns: ${s.warnings} | tests: ${s.testsRun}`);
+      }
+    }
+    break;
+  }
+
   default: {
     console.log(`🌈 claude-prism — UDEC methodology framework for AI coding agents
 
@@ -181,6 +248,7 @@ Usage:
   prism doctor                           Diagnose issues with fix suggestions
   prism stats                            Show installation summary
   prism reset                            Clear hook state
+  prism analytics [--detail]             Show usage analytics
   prism update                           Re-install using current config
   prism update --global                  Update global commands + OMC skill
   prism uninstall                        Remove prism from current project

package/lib/installer.mjs

@@ -28,7 +28,7 @@ export async function init(projectDir, options = {}) {
   const nsCommandsDir = join(claudeDir, 'commands', 'claude-prism');
   mkdirSync(nsCommandsDir, { recursive: true });
 
-  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md'];
+  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md', 'analytics.md'];
   for (const cmd of commandFiles) {
     copyFileSync(
       join(TEMPLATES_DIR, 'commands', 'claude-prism', cmd),
@@ -58,7 +58,7 @@ export async function init(projectDir, options = {}) {
     const libDestDir = join(claudeDir, 'lib');
     mkdirSync(libDestDir, { recursive: true });
     const libSourceDir = join(__dirname);
-    for (const file of ['state.mjs', 'config.mjs', 'utils.mjs', 'messages.mjs', 'pipeline.mjs']) {
+    for (const file of ['state.mjs', 'config.mjs', 'utils.mjs', 'messages.mjs', 'pipeline.mjs', 'session.mjs']) {
       copyFileSync(join(libSourceDir, file), join(libDestDir, file));
     }
 
@@ -73,6 +73,7 @@ export async function init(projectDir, options = {}) {
   const configPath = join(projectDir, '.claude-prism.json');
   if (!existsSync(configPath)) {
     writeFileSync(configPath, JSON.stringify({
+      version: 1,
       hooks: {
         'commit-guard': { enabled: true, maxTestAge: 300 },
         'test-tracker': { enabled: true },
@@ -198,6 +199,23 @@ export function uninstall(projectDir) {
  * @param {string} projectDir
  */
 export async function update(projectDir) {
+  // Self-update detection: if running inside the claude-prism source repo,
+  // use local templates instead of the npx-downloaded package templates
+  const localPkgPath = join(projectDir, 'package.json');
+  if (existsSync(localPkgPath)) {
+    try {
+      const localPkg = JSON.parse(readFileSync(localPkgPath, 'utf8'));
+      if (localPkg.name === 'claude-prism') {
+        // We're in the source repo — use local templates directly
+        const localRulesPath = join(projectDir, 'templates', 'rules.md');
+        if (existsSync(localRulesPath)) {
+          injectRules(projectDir, localRulesPath);
+          return { sourceRepo: true };
+        }
+      }
+    } catch { /* not our package, proceed normally */ }
+  }
+
   // Migration: rename .prism.json to .claude-prism.json
   const oldConfigPath = join(projectDir, '.prism.json');
   const newConfigPath = join(projectDir, '.claude-prism.json');
@@ -255,8 +273,17 @@ export async function update(projectDir) {
     }
   }
 
-  // Remove old config so init creates a fresh one
-  if (existsSync(configPath)) rmSync(configPath);
+  // Migrate config: add version field if missing
+  if (existsSync(configPath)) {
+    try {
+      const existingConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+      if (!existingConfig.version) {
+        existingConfig.version = 1;
+        writeFileSync(configPath, JSON.stringify(existingConfig, null, 2) + '\n');
+      }
+    } catch { /* proceed with fresh config */ }
+    rmSync(configPath);
+  }
 
   await init(projectDir, { hooks });
 }
@@ -275,7 +302,7 @@ export function doctor(projectDir, options = {}) {
 
   // Check namespaced commands
   const nsCommandsDir = join(claudeDir, 'commands', 'claude-prism');
-  const expectedCommands = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md'];
+  const expectedCommands = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md', 'analytics.md'];
   for (const cmd of expectedCommands) {
     if (!existsSync(join(nsCommandsDir, cmd))) {
       issues.push(`Missing command: claude-prism/${cmd}`);
@@ -422,7 +449,7 @@ export function initGlobal(options = {}) {
   const commandsDir = join(claudeDir, 'commands', 'claude-prism');
   mkdirSync(commandsDir, { recursive: true });
 
-  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md'];
+  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md', 'analytics.md'];
   for (const cmd of commandFiles) {
     copyFileSync(
       join(TEMPLATES_DIR, 'commands', 'claude-prism', cmd),
@@ -467,7 +494,7 @@ export function dryRun(projectDir, options = {}) {
 
   // Commands
   const nsCommandsDir = join(claudeDir, 'commands', 'claude-prism');
-  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md'];
+  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md', 'analytics.md'];
   for (const cmd of commandFiles) {
     const target = join(nsCommandsDir, cmd);
     actions.push({
@@ -497,7 +524,7 @@ export function dryRun(projectDir, options = {}) {
       });
     }
 
-    for (const lib of ['state.mjs', 'config.mjs', 'utils.mjs', 'messages.mjs', 'pipeline.mjs']) {
+    for (const lib of ['state.mjs', 'config.mjs', 'utils.mjs', 'messages.mjs', 'pipeline.mjs', 'session.mjs']) {
       const target = join(claudeDir, 'lib', lib);
       actions.push({
         type: 'lib',
@@ -526,9 +553,9 @@ export function dryRun(projectDir, options = {}) {
 
 // ─── internal helpers ───
 
-function injectRules(projectDir) {
+function injectRules(projectDir, overrideRulesPath) {
   const claudeMdPath = join(projectDir, 'CLAUDE.md');
-  const rulesPath = join(TEMPLATES_DIR, 'rules.md');
+  const rulesPath = overrideRulesPath || join(TEMPLATES_DIR, 'rules.md');
   if (!existsSync(rulesPath)) return;
 
   const rules = readFileSync(rulesPath, 'utf8');

package/lib/pipeline.mjs

@@ -8,6 +8,7 @@ import { join } from 'path';
 import { sanitizeId } from './utils.mjs';
 import { loadConfig } from './config.mjs';
 import { getStateDir } from './state.mjs';
+import { logEvent } from './session.mjs';
 
 const TOOL_ACTION_MAP = {
   'Edit': 'edit',
@@ -87,6 +88,18 @@ export function runPipeline(rules, hookEventName) {
 
     const result = rule.evaluate(ctx, hookConfig, stateDir);
 
+    // Log rule evaluation for analytics
+    if (ctx.sessionId && result.type !== 'pass') {
+      try {
+        logEvent(ctx.sessionId, {
+          type: result.type, // 'block', 'warn'
+          rule: name,
+          action: ctx.action,
+          file: ctx.filePath || undefined,
+        });
+      } catch { /* logging should never break the pipeline */ }
+    }
+
     if (result.type === 'block') {
       blocked = true;
       blockMessage = result.message || '🌈 Prism ✋ Action blocked.';
@@ -163,6 +176,18 @@ export async function runPipelineAsync(builtInRules, hookEventName) {
 
     const result = rule.evaluate(ctx, hookConfig, stateDir);
 
+    // Log rule evaluation for analytics
+    if (ctx.sessionId && result.type !== 'pass') {
+      try {
+        logEvent(ctx.sessionId, {
+          type: result.type, // 'block', 'warn'
+          rule: name,
+          action: ctx.action,
+          file: ctx.filePath || undefined,
+        });
+      } catch { /* logging should never break the pipeline */ }
+    }
+
     if (result.type === 'block') {
       blocked = true;
       blockMessage = result.message || '🌈 Prism ✋ Action blocked.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-prism",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "UDEC methodology framework for AI coding agents — Understand, Decompose, Execute, Checkpoint.",
   "type": "module",
   "bin": {

package/templates/commands/claude-prism/analytics.md

@@ -0,0 +1,35 @@
+# /claude-prism:analytics — Usage Analytics
+
+When this command is invoked, show aggregated statistics from session event logs:
+
+## Report
+
+1. **Read session data** using `listSessions()` and `getSessionSummary()` from session.mjs
+2. **Aggregate across all sessions**:
+   - Total sessions count
+   - Hook effectiveness: blocks and warnings by rule type
+   - Test activity: runs, passed, failed
+   - File activity: modified, created
+3. **Display using this format**:
+
+```
+🌈 claude-prism analytics
+
+  Sessions:        N
+  Total events:    N
+
+  Hook Effectiveness:
+    Blocks:        N
+    Warnings:      N
+
+  Test Activity:
+    Runs:          N
+    Passed:        N
+    Failed:        N
+
+  File Activity:
+    Modified:      N
+    Created:       N
+```
+
+4. **With --detail flag**, also show last 5 sessions with timestamps and per-session counts

package/templates/commands/claude-prism/checkpoint.md

@@ -7,7 +7,11 @@ When this command is invoked:
    - `grep -c '\- \[x\]' <plan-file>` → completed count
    - `grep -c '\- \[ \]' <plan-file>` → remaining count
    - Calculate percentage: completed / (completed + remaining)
-3. **Freshness check**: grep for plan's change targets to verify they still exist in codebase
+3. **Plan-Reality sync** (freshness check):
+   - Grep for plan's change targets (patterns, files, functions to modify) to verify they still exist in codebase
+   - If target no longer exists → mark task as "already completed (prior work)"
+   - If new targets discovered → add to plan's "Risks / Open Questions"
+   - Update plan file's `Codebase Audit` section with fresh counts if present
 4. **Report current status** using this standard format:
 
    ### Changes
@@ -20,7 +24,7 @@ When this command is invoked:
 
    | Check | Result |
    |-------|--------|
-   | TypeScript | ✅/❌ [details] |
+   | Build | ✅/❌ [details] |
    | Tests | ✅/❌ [pass count] |
    | Lint | ✅/❌ or N/A |
 
@@ -29,6 +33,7 @@ When this command is invoked:
    ```
    Phase: [current phase] | Batch: [N/M] | Tasks: [done/total] ([%])
    [████████░░] 80% — Next: [next batch name]
+   Plan freshness: verified [date] | Remaining targets: [N] confirmed in code
    ```
 
    - Batches complete: N/M
@@ -44,11 +49,11 @@ When this command is invoked:
    | [M] Medium | N | N |
    | [L] Large | N | N |
 
-4. **Show summary**:
+5. **Show summary**:
    - Files created/modified so far
    - Tests added and their status
    - Commits made
-5. **Checkpoint policy check**:
+6. **Checkpoint policy check**:
    - If 3+ consecutive approvals → suggest expanding batch size to 5-8
    - If phase boundary → always stop
-6. **Ask**: "Continue with the current plan, adjust, or stop?"
+7. **Ask**: "Continue with the current plan, adjust, or stop?"

package/templates/commands/claude-prism/doctor.md

@@ -7,15 +7,15 @@ When this command is invoked, check all components of the prism installation:
 1. **CLAUDE.md**: Does it contain `<!-- PRISM:START -->` marker?
 2. **Config**: Does `.claude-prism.json` exist? Is it valid JSON?
 3. **Commands**: Do these files exist in `.claude/commands/claude-prism/`?
-   - prism.md, checkpoint.md, plan.md, doctor.md, stats.md, help.md
+   - prism.md, checkpoint.md, plan.md, doctor.md, stats.md, help.md, update.md
 4. **Hooks**: Do these files exist in `.claude/hooks/`?
-   - commit-guard.mjs, debug-loop.mjs, test-tracker.mjs, scope-guard.mjs
+   - pre-tool.mjs, post-tool.mjs
 5. **Rules**: Do these files exist in `.claude/rules/`?
-   - commit-guard.mjs, debug-loop.mjs, test-tracker.mjs, scope-guard.mjs
+   - commit-guard.mjs, test-tracker.mjs, plan-enforcement.mjs
 6. **Lib**: Do these files exist in `.claude/lib/`?
-   - adapter.mjs, state.mjs, config.mjs, utils.mjs
+   - pipeline.mjs, state.mjs, config.mjs, utils.mjs, messages.mjs
 7. **Settings**: Does `.claude/settings.json` contain prism hook registrations?
-8. **Legacy**: Are there old flat commands (`/prism`, `/checkpoint`) that need migration?
+8. **Legacy**: Are there old flat commands (`/prism`, `/checkpoint`) or deprecated files (`debug-loop.mjs`, `scope-guard.mjs`, `adapter.mjs`) that need cleanup?
 
 ## Report Format
 
@@ -25,11 +25,11 @@ When this command is invoked, check all components of the prism installation:
   CLAUDE.md:   ✅ PRISM rules present
   Config:      ✅ .claude-prism.json valid
   Commands:    ✅ 7/7 installed
-  Hooks:       ✅ 4/4 installed
-  Rules:       ✅ 4/4 installed
-  Lib:         ✅ 4/4 installed
+  Hooks:       ✅ 2/2 installed
+  Rules:       ✅ 3/3 installed
+  Lib:         ✅ 5/5 installed
   Settings:    ✅ Hooks registered
-  Legacy:      ✅ No old commands found
+  Legacy:      ✅ No old files found
 
   Status: ✅ Healthy
 ```
@@ -40,3 +40,4 @@ For each issue found, suggest the fix:
 - Missing files → "Run `prism update` to restore"
 - Legacy commands → "Run `prism update` to migrate to namespaced commands"
 - Missing PRISM block → "Run `prism update` to re-inject rules"
+- Deprecated files → "Run `prism update` to clean up legacy files"

package/templates/commands/claude-prism/plan.md

@@ -18,26 +18,37 @@ If user requests a new plan:
 
 1. **Determine topic** from user's description
 2. **Create file** at `docs/plans/YYYY-MM-DD-<topic>.md`
-3. **Use UDEC template** (adapt language to project's `.claude-prism.json` language setting):
+3. **Use UDEC template**:
 
 ```
 ## Goal
-One sentence: what and why.
+One sentence: what we're building and why.
 
 ## Architecture
-Tech stack, key decisions, 2-3 sentences.
+Tech stack, key decisions, 2-3 sentences max.
 
-## Batch 1: [Name]
-- [ ] Task 1.1: [Description] → `path/to/file`
-  - Test: `path/to/test` — [what to verify]
-  - Pass criterion: [specific assertion]
-- [ ] Task 1.2: ...
+## 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
 
-## Batch 2: [Name]
-- [ ] Task 2.1: ...
+## 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 uncertainties or potential blockers]
+- [Known unknowns or potential blockers]
 ```
 
 4. **Announce**: "Plan file created. Use /claude-prism:prism to start execution."
@@ -49,4 +60,4 @@ If user specifies a plan file:
 1. **Read** the specified plan file
 2. **Show progress** with completion percentage
 3. **Highlight** current batch (first batch with incomplete tasks)
-4. **List blockers** from "리스크 / 미결 사항" section
+4. **List blockers** from "Risks / Open Questions" section

package/templates/commands/claude-prism/prism.md

@@ -54,23 +54,23 @@ When this command is invoked, follow the UDEC framework strictly:
 
 ## E — EXECUTE
 
-11. Execute in adaptive batches:
+14. Execute in adaptive batches:
     - Simple changes (imports, types, config): 5-8 per batch
     - Standard changes (feature add/modify): 3-4 per batch
     - Complex changes (new module, architecture): 1-2 per batch
-12. Apply context-aware verification:
+15. Apply context-aware verification:
     - `lib/`, `utils/`, `store/`, `hooks/`, `services/` → TDD (failing test → implement → verify)
     - `components/`, `pages/`, `views/` → Build verification (escalate to TDD if complex logic)
     - `config/`, `styles/`, `types/` → Build/lint only
-13. **Scope Guard**: Before each change, ask: "Was this requested?" If no → don't do it
-14. **Self-correction triggers**:
+16. **Scope Guard**: Before each change, ask: "Was this requested?" If no → don't do it
+17. **Self-correction triggers**:
     - Same file edited 3+ times **on the same region/logic** → stop, investigate root cause (progressive edits across different regions — imports, logic, JSX — are normal)
     - File not in plan → pause, ask about scope change
     - 3 consecutive test failures → stop, reconsider approach
     - New package needed → ask user first
     - Adding workarounds on workarounds → design problem, step back
-15. **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>"`
-16. **Agent failure recovery**: If a delegated agent partially fails or produces incomplete results:
+18. **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>"`
+19. **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
@@ -100,4 +100,4 @@ If oh-my-claudecode is detected in this environment:
 - Use `architect` agent for complex decomposition decisions
 - Use `executor` agents for parallel batch execution when tasks are independent
 - Use `verifier` agent for checkpoint verification
-- Scope Guard thresholds are automatically raised for sub-agents (8 warn / 12 block vs 4/7)
+- Scope Guard thresholds are automatically raised for sub-agents (8 warn / 12 block vs default 4 warn / 7 block for standalone mode)

package/templates/rules.md

@@ -62,7 +62,7 @@ Before moving to DECOMPOSE:
 - MVP scope defined
 - User confirmed "proceed"
 
-### 2-4. Assumption Detection (Red Flag Checklist)
+### 2-5. Assumption Detection (Red Flag Checklist)
 
 **If you think you understand fully on first read, you probably don't.**
 
@@ -109,7 +109,7 @@ Before moving to DECOMPOSE:
 **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-10 per batch)
+- Aligns with 4-1 adaptive batch size (simple/mechanical: 5-8 per batch)
 
 ### 3-3. Plan File Persistence
 
@@ -175,7 +175,7 @@ If any gate fails → resolve before executing. Do not start implementation on a
 ### 4-1. Batch Execution
 
 1. **Adaptive batch size**:
-   - Simple/mechanical changes (imports, types, config, migration): 5-10 per batch
+   - 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.

package/templates/skills/prism/SKILL.md

@@ -38,7 +38,8 @@ AI agents optimize for speed, not correctness. Without structure, they skip unde
    - [Sufficient] Specific file, function, symptom mentioned → skip to DECOMPOSE
    - [Partial] Direction clear but details missing → explore then ask 1-2 questions
    - [Insufficient] Abstract, vague, multiple interpretations → must ask questions first
-3. **Check for hidden assumptions** (Red Flag Detection):
+3. **Environment validation**: Verify project builds, dependencies match, env config identified. If any fail → resolve first.
+4. **Check for hidden assumptions** (Red Flag Detection):
 
    | Red Flag | Question to Ask Yourself |
    |----------|-------------------------|
@@ -50,63 +51,74 @@ AI agents optimize for speed, not correctness. Without structure, they skip unde
    | No file/function names | [Insufficient]. Must ask. |
    | "just", "simply" | Complexity being underestimated |
 
-4. **Question rules** (if questions needed):
+5. **Question rules** (if questions needed):
    - One question at a time
    - Multiple choice with 2-3 options + recommendation
    - Include reasoning based on code exploration
    - Maximum 3 rounds of questions
-5. **Confirm alignment**: Summarize goal in one sentence, get user approval
-6. **Analysis-only requests**: If no code change is needed, report findings and ask: "Further action needed?" Do NOT proceed to D/E/C unless the user requests implementation.
+6. **Confirm alignment**: Summarize goal in one sentence, get user approval
+7. **Analysis-only requests**: If no code change is needed, report findings and ask: "Further action needed?" Do NOT proceed to D/E/C unless the user requests implementation.
 
 ## D — DECOMPOSE
 
-7. **Assess complexity** (consider BOTH file count AND logic complexity):
+8. **Assess complexity** (consider BOTH file count AND logic complexity):
    - [Simple] 1-2 files, minor changes (<50 LOC) → execute directly, no decomposition needed
    - [Medium] 3-5 files, OR 1-2 files with significant logic changes (50-150 LOC) → 2-3 batches
    - [Complex] 6+ files, OR substantial architectural changes → 5+ batches, must create plan file
    - [Complex system] Unclear scope → reduce scope first, then decompose
-8. **Create batches** following the 5 principles:
+9. **Create batches** following the 5 principles:
    - Unit size: 2-5 minutes each (test/implement/verify as separate steps)
    - Test first: test before implementation in each unit
    - Independent verification: each unit has a pass criterion
    - Files specified: list files to create/modify per unit
    - Dependencies noted: mark if unit depends on a previous one
-9. **Assign size tags** to every task: [S] <30 LOC, [M] 30-100 LOC, [L] >100 LOC
-   - Batch composition: S+S+M = 1 batch, L = 1 batch alone
-10. **Assign verification strategy** per task: `| Verify: TDD` or `| Verify: Build` or `| Verify: Visual`
-11. **Pre-decomposition checklist**:
+10. **Assign size tags** to every task: [S] <30 LOC, [M] 30-100 LOC, [L] >100 LOC
+    - Batch composition: S+S+M = 1 batch, L = 1 batch alone
+11. **Assign verification strategy** per task: `| Verify: TDD` or `| Verify: Build` or `| Verify: Visual`
+12. **Pre-decomposition checklist**:
+    - **Codebase audit**: grep/search to verify targets actually exist in code
+    - **Cross-plan check**: if other plans exist in `docs/plans/`, identify overlapping files
     - Required types/interfaces have the necessary fields?
     - External package APIs behave as expected?
     - Cross-package dependencies identified and noted as prerequisites?
-12. **Save plan** to `docs/plans/YYYY-MM-DD-<topic>.md`
-13. **Get approval**: "Proceed with this plan?"
+13. **Quality gate**: Plan file exists and targets verified, project builds, dependencies resolved, environment validated. All must pass before execution.
+14. **Save plan** to `docs/plans/YYYY-MM-DD-<topic>.md`
+15. **Get approval**: "Proceed with this plan?"
 
 ## E — EXECUTE
 
-11. Execute in adaptive batches:
+16. Execute in adaptive batches:
     - Simple changes (imports, types, config): 5-8 per batch
     - Standard changes (feature add/modify): 3-4 per batch
     - Complex changes (new module, architecture): 1-2 per batch
-12. Apply context-aware verification:
-    - `lib/`, `utils/`, `store/`, `hooks/`, `services/` → TDD (failing test → implement → verify)
-    - `components/`, `pages/`, `views/` → Build verification (escalate to TDD if complex logic)
-    - `config/`, `styles/`, `types/` → Build/lint only
-13. **Scope Guard**: Before each change, ask: "Was this requested?" If no → don't do it
-14. **Self-correction triggers**:
-    - Same file edited 3+ times **on the same region/logic** → stop, investigate root cause (progressive edits across different regions — imports, logic, JSX — are normal)
+17. **Git-as-Memory**: commit after each completed batch as a rollback point. Use `git diff` summaries to maintain context in long sessions.
+18. Apply risk-based verification:
+    - **High risk** (business logic, auth, data mutation): TDD — failing test → implement → pass. Include negative tests.
+    - **Medium risk** (new components with logic, API integration): Build + lint pass
+    - **Low risk** (imports, types, style, renaming): Build/lint passes
+    - **No test infra** (legacy PHP, WordPress, etc.): Grep-based static check + syntax validation
+    - Use **Verification Fallback Ladder**: Automated Tests → Approval Testing → Build → Lint → Smoke Check → Manual Diff Review (use highest available level)
+19. **Scope Guard**: Before each change, ask: "Was this requested?" If no → don't do it
+20. **Goal Recitation**: At every batch boundary, re-read the plan and confirm: "Current work aligns with: [original goal]"
+21. **Self-correction triggers (Thrashing Detector)**:
+    - Same file edited 3+ times **on the same region/logic** → stop, investigate root cause
     - File not in plan → pause, ask about scope change
     - 3 consecutive test failures → stop, reconsider approach
     - New package needed → ask user first
     - Adding workarounds on workarounds → design problem, step back
-15. **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>"`
-16. **Agent failure recovery**: If a delegated agent partially fails or produces incomplete results:
+    - Successive edits reverting previous changes (oscillation) → wrong approach
+    - Scope expanding beyond plan → scope creep, return to DECOMPOSE
+    - Error messages changing type across fixes → chasing symptoms, back to UNDERSTAND
+22. **Verification scoping**: Filter build output to only changed files. Pre-existing errors are not your concern.
+23. **Agent failure recovery**: If a delegated agent partially fails:
     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
 
 ## C — CHECKPOINT
 
-20. After each batch, report using this format:
+24. **Quality gate**: All batch tasks terminal, build passes with zero new errors, no uncommitted changes, plan file updated with `[x]` status. If any fail → continue in EXECUTE.
+25. After each batch, report using this format:
 
     | Item | Before | After |
     |------|--------|-------|
@@ -115,12 +127,14 @@ AI agents optimize for speed, not correctness. Without structure, they skip unde
     ```
     Phase: [current] | Batch: [N/M] | Tasks: [done/total] ([%])
     [████████░░] 80% — Next: [next batch name]
+    Plan freshness: verified [date] | Remaining targets: [N] confirmed in code
     ```
 
-21. Include: verification results, files modified, tests status
-22. **Checkpoint policy**: after 3 consecutive approvals, increase batch size to 5-8 for the rest of the phase
-23. Ask: "Continue to next batch?"
-24. User can redirect, adjust scope, or stop at any checkpoint
+26. **Plan-Reality sync**: Grep for plan targets, mark vanished targets as "already completed", add newly discovered targets.
+27. Include: verification results, files modified, tests status
+28. **Checkpoint policy**: after 3 consecutive approvals, increase batch size to 5-8 for the rest of the phase
+29. Ask: "Continue to next batch?"
+30. User can redirect, adjust scope, or stop at any checkpoint
 
 ## OMC Integration
 
@@ -129,6 +143,6 @@ If oh-my-claudecode is detected in this environment:
 - Use `architect` agent for complex decomposition decisions
 - Use `executor` agents for parallel batch execution when tasks are independent
 - Use `verifier` agent for checkpoint verification
-- Scope Guard thresholds are automatically raised for sub-agents (8 warn / 12 block vs 4/7)
+- Scope Guard thresholds are automatically raised for sub-agents (8 warn / 12 block vs default 4 warn / 7 block for standalone mode)
 
 </Steps>