worclaude 2.2.6 → 2.4.0

package/src/commands/init.js

@@ -1,7 +1,13 @@
 import path from 'node:path';
 import inquirer from 'inquirer';
 import ora from 'ora';
-import { scaffoldFile, updateGitignore } from '../core/scaffolder.js';
+import {
+  scaffoldFile,
+  updateGitignore,
+  scaffoldHooks,
+  scaffoldPluginJson,
+  scaffoldMemoryDocs,
+} from '../core/scaffolder.js';
 import {
   computeFileHashes,
   createWorkflowMeta,
@@ -211,11 +217,30 @@ async function runAgents(selections) {
   return { ...selections, selectedAgents };
 }
 
+async function runOptionalExtras(selections) {
+  const { generatePluginJson, scaffoldGtdMemory } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'generatePluginJson',
+      message: 'Generate .claude-plugin/plugin.json for marketplace compatibility?',
+      default: selections.generatePluginJson || false,
+    },
+    {
+      type: 'confirm',
+      name: 'scaffoldGtdMemory',
+      message: 'Scaffold structured memory files (decisions.md, preferences.md)?',
+      default: selections.scaffoldGtdMemory || false,
+    },
+  ]);
+  return { ...selections, generatePluginJson, scaffoldGtdMemory };
+}
+
 const STEP_RUNNERS = {
   projectInfo: runProjectInfo,
   projectType: runProjectType,
   techStack: runTechStack,
   agents: runAgents,
+  optionalExtras: runOptionalExtras,
 };
 
 // --- Confirmation ---
@@ -251,6 +276,14 @@ async function showConfirmation(selections) {
   console.log(
     `  ${'Agents'.padEnd(10)}${display.white(`${universalCount} universal + ${optionalCount} optional`)} ${display.dimColor(`(${totalCount} total)`)}`
   );
+
+  const extrasLabels = [];
+  if (selections.generatePluginJson) extrasLabels.push('plugin.json');
+  if (selections.scaffoldGtdMemory) extrasLabels.push('memory docs');
+  if (extrasLabels.length > 0) {
+    console.log(`  ${'Extras'.padEnd(10)}${display.white(extrasLabels.join(', '))}`);
+  }
+
   display.newline();
 
   const { confirmation } = await inquirer.prompt([
@@ -271,25 +304,37 @@ async function showConfirmation(selections) {
 
 // --- Shared functions ---
 
-async function runInteractivePrompts(projectRoot) {
-  let selections = {
+function createInitialSelections(projectRoot) {
+  return {
     projectName: path.basename(projectRoot),
     description: '',
     projectTypes: [],
     languages: [],
     useDocker: false,
     selectedAgents: [],
+    generatePluginJson: false,
+    scaffoldGtdMemory: false,
   };
+}
+
+async function runAllSteps(selections) {
+  selections = await runProjectInfo(selections);
+  selections = await runProjectType(selections);
+  selections = await runTechStack(selections);
+  selections = await runAgents(selections);
+  selections = await runOptionalExtras(selections);
+  return selections;
+}
+
+async function runInteractivePrompts(projectRoot) {
+  let selections = createInitialSelections(projectRoot);
 
   let confirmed = false;
   let firstRun = true;
 
   while (!confirmed) {
     if (firstRun) {
-      selections = await runProjectInfo(selections);
-      selections = await runProjectType(selections);
-      selections = await runTechStack(selections);
-      selections = await runAgents(selections);
+      selections = await runAllSteps(selections);
       firstRun = false;
     }
 
@@ -298,21 +343,11 @@ async function runInteractivePrompts(projectRoot) {
     if (confirmation === 'yes') {
       confirmed = true;
     } else if (confirmation === 'restart') {
-      selections = {
-        projectName: path.basename(projectRoot),
-        description: '',
-        projectTypes: [],
-        languages: [],
-        useDocker: false,
-        selectedAgents: [],
-      };
+      selections = createInitialSelections(projectRoot);
       display.newline();
       display.info('Starting over...');
       display.newline();
-      selections = await runProjectInfo(selections);
-      selections = await runProjectType(selections);
-      selections = await runTechStack(selections);
-      selections = await runAgents(selections);
+      selections = await runAllSteps(selections);
     } else if (confirmation === 'adjust') {
       const { step } = await inquirer.prompt([
         {
@@ -363,6 +398,10 @@ function buildTemplateVariables(selections) {
   );
   const skillsText = skillsLines.join('\n');
 
+  const memoryArchitectureExtras = selections.scaffoldGtdMemory
+    ? '\n- Team decisions: `docs/memory/decisions.md` (version-controlled, shared).\n- Team preferences: `docs/memory/preferences.md` (version-controlled, shared).'
+    : '';
+
   return {
     project_name: projectName,
     description: description || 'A project scaffolded with Worclaude',
@@ -372,6 +411,7 @@ function buildTemplateVariables(selections) {
     docker_row: dockerRow,
     commands_filled_during_init: commandsText,
     project_specific_skills: skillsText,
+    memory_architecture_extras: memoryArchitectureExtras,
     timestamp: new Date().toISOString(),
   };
 }
@@ -401,6 +441,9 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
     await scaffoldFile('core/claude-md.md', 'CLAUDE.md', variables, projectRoot);
     spinner.text = 'Created CLAUDE.md';
 
+    await scaffoldFile('core/agents-md.md', 'AGENTS.md', variables, projectRoot);
+    spinner.text = 'Created AGENTS.md';
+
     await writeFile(path.join(projectRoot, '.claude', 'settings.json'), settingsStr);
     spinner.text = 'Created .claude/settings.json';
 
@@ -500,6 +543,26 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
     await writeFile(path.join(projectRoot, '.claude', 'sessions', '.gitkeep'), '');
     spinner.text = 'Created .claude/sessions/';
 
+    // Copy hook scripts (.claude/hooks/)
+    await scaffoldHooks(projectRoot);
+    spinner.text = 'Created .claude/hooks/';
+
+    // Create learnings directory for correction capture
+    await writeFile(path.join(projectRoot, '.claude', 'learnings', '.gitkeep'), '');
+    spinner.text = 'Created .claude/learnings/';
+
+    // Opt-in: plugin.json for Claude Code marketplace compatibility
+    if (selections.generatePluginJson) {
+      await scaffoldPluginJson(projectRoot, selections);
+      spinner.text = 'Created .claude-plugin/plugin.json';
+    }
+
+    // Opt-in: GTD memory scaffold (docs/memory/decisions.md, preferences.md)
+    if (selections.scaffoldGtdMemory) {
+      await scaffoldMemoryDocs(projectRoot);
+      spinner.text = 'Created docs/memory/';
+    }
+
     await computeAndWriteWorkflowMeta(projectRoot, selections, version);
     spinner.text = 'Created .claude/workflow-meta.json';
 
@@ -518,12 +581,20 @@ function displayFreshSuccess(selections, skipped) {
 
   display.newline();
   display.success('CLAUDE.md');
+  display.success('AGENTS.md');
   display.success('.claude/settings.json');
   display.success('.claude/workflow-meta.json');
   display.success(`.claude/agents/${display.dimColor(`        ${totalAgents} agents`)}`);
   display.success(`.claude/commands/${display.dimColor(`      ${COMMAND_FILES.length} commands`)}`);
   display.success(`.claude/skills/${display.dimColor(`        ${totalSkills} skills`)}`);
   display.success('.claude/sessions/');
+  display.success('.claude/hooks/');
+  if (selections.generatePluginJson) {
+    display.success('.claude-plugin/plugin.json');
+  }
+  if (selections.scaffoldGtdMemory) {
+    display.success('docs/memory/' + display.dimColor('           decisions.md, preferences.md'));
+  }
   display.success('.mcp.json');
   display.success('.gitignore');
   if (skipped.progressMd) {
@@ -648,6 +719,19 @@ function displayMergeReport(report, backupPath) {
     display.success('CLAUDE.md created');
   }
 
+  // Memory Architecture Tier 3 notice
+  if (report.memoryArchitectureSectionExists) {
+    display.newline();
+    display.info(
+      'docs/memory/ scaffolded, but your CLAUDE.md already has a Memory Architecture section.'
+    );
+    display.dim('  Add these lines manually if you want pointer bullets:');
+    display.dim('    - Team decisions: `docs/memory/decisions.md` (version-controlled, shared).');
+    display.dim(
+      '    - Team preferences: `docs/memory/preferences.md` (version-controlled, shared).'
+    );
+  }
+
   // Skipped
   if (report.skipped.progressMd) {
     display.dim('  docs/spec/PROGRESS.md — already exists, skipped');

package/src/core/detector.js

@@ -19,8 +19,31 @@ export async function detectScenario(projectRoot) {
 }
 
 export async function scanExistingSetup(projectRoot) {
-  const hasClaudeDir = await dirExists(path.join(projectRoot, '.claude'));
-  const hasClaudeMd = await fileExists(path.join(projectRoot, 'CLAUDE.md'));
+  const [
+    hasClaudeDir,
+    hasClaudeMd,
+    hasSettingsJson,
+    hasMcpJson,
+    existingSkills,
+    existingSkillDirs,
+    existingAgents,
+    existingCommands,
+    hasAgentsMd,
+    hasProgressMd,
+    hasSpecMd,
+  ] = await Promise.all([
+    dirExists(path.join(projectRoot, '.claude')),
+    fileExists(path.join(projectRoot, 'CLAUDE.md')),
+    fileExists(path.join(projectRoot, '.claude', 'settings.json')),
+    fileExists(path.join(projectRoot, '.mcp.json')),
+    listFiles(path.join(projectRoot, '.claude', 'skills')),
+    listSkillDirs(path.join(projectRoot, '.claude', 'skills')),
+    listFiles(path.join(projectRoot, '.claude', 'agents')),
+    listFiles(path.join(projectRoot, '.claude', 'commands')),
+    fileExists(path.join(projectRoot, 'AGENTS.md')),
+    fileExists(path.join(projectRoot, 'docs', 'spec', 'PROGRESS.md')),
+    fileExists(path.join(projectRoot, 'docs', 'spec', 'SPEC.md')),
+  ]);
 
   let claudeMdLineCount = 0;
   if (hasClaudeMd) {
@@ -32,13 +55,14 @@ export async function scanExistingSetup(projectRoot) {
     hasClaudeDir,
     hasClaudeMd,
     claudeMdLineCount,
-    hasSettingsJson: await fileExists(path.join(projectRoot, '.claude', 'settings.json')),
-    hasMcpJson: await fileExists(path.join(projectRoot, '.mcp.json')),
-    existingSkills: await listFiles(path.join(projectRoot, '.claude', 'skills')),
-    existingSkillDirs: await listSkillDirs(path.join(projectRoot, '.claude', 'skills')),
-    existingAgents: await listFiles(path.join(projectRoot, '.claude', 'agents')),
-    existingCommands: await listFiles(path.join(projectRoot, '.claude', 'commands')),
-    hasProgressMd: await fileExists(path.join(projectRoot, 'docs', 'spec', 'PROGRESS.md')),
-    hasSpecMd: await fileExists(path.join(projectRoot, 'docs', 'spec', 'SPEC.md')),
+    hasSettingsJson,
+    hasMcpJson,
+    existingSkills,
+    existingSkillDirs,
+    existingAgents,
+    existingCommands,
+    hasAgentsMd,
+    hasProgressMd,
+    hasSpecMd,
   };
 }

package/src/core/merger.js

@@ -1,7 +1,15 @@
 import path from 'node:path';
 import os from 'node:os';
 import { readFile, writeFile } from '../utils/file.js';
-import { readTemplate, substituteVariables, scaffoldFile, mergeSettings } from './scaffolder.js';
+import {
+  readTemplate,
+  substituteVariables,
+  scaffoldFile,
+  mergeSettings,
+  scaffoldHooks,
+  scaffoldPluginJson,
+  scaffoldMemoryDocs,
+} from './scaffolder.js';
 import { promptHookConflict } from '../prompts/conflict-resolution.js';
 import {
   detectMissingSections,
@@ -374,7 +382,7 @@ async function mergeDocSpecs(projectRoot, existingScan, variables, selections, r
   report.skipped.specMd = existingScan.hasSpecMd;
 }
 
-async function handleClaudeMd(projectRoot, existingScan, variables, report) {
+async function handleClaudeMd(projectRoot, existingScan, variables, selections, report) {
   if (!existingScan.hasClaudeMd) {
     // No CLAUDE.md — scaffold fresh
     await scaffoldFile('core/claude-md.md', 'CLAUDE.md', variables, projectRoot);
@@ -386,6 +394,13 @@ async function handleClaudeMd(projectRoot, existingScan, variables, report) {
   const renderedTemplate = substituteVariables(await readTemplate('core/claude-md.md'), variables);
   const missingSections = detectMissingSections(existingContent);
 
+  // Tier 3 notice: if user opted into GTD memory AND their CLAUDE.md already has
+  // a Memory Architecture section, the pointer bullets from the rendered template
+  // won't be merged in automatically. Surface this so the user can add them manually.
+  if (selections.scaffoldGtdMemory && !missingSections.includes('Memory Architecture')) {
+    report.memoryArchitectureSectionExists = true;
+  }
+
   if (missingSections.length === 0) {
     display.newline();
     display.info(`Your CLAUDE.md (${existingContent.split(/\r?\n/).length} lines) was detected.`);
@@ -411,6 +426,16 @@ async function handleClaudeMd(projectRoot, existingScan, variables, report) {
   }
 }
 
+async function mergeAgentsMd(projectRoot, existingScan, variables, report) {
+  if (!existingScan.hasAgentsMd) {
+    await scaffoldFile('core/agents-md.md', 'AGENTS.md', variables, projectRoot);
+    report.agentsMdHandling = 'created';
+  } else {
+    await scaffoldFile('core/agents-md.md', 'AGENTS.md.workflow-ref', variables, projectRoot);
+    report.agentsMdHandling = 'saved-alongside';
+  }
+}
+
 // --- Main merge function ---
 
 export async function performMerge(
@@ -425,6 +450,7 @@ export async function performMerge(
     conflicts: { skills: [], agents: [], commands: [] },
     skipped: { progressMd: false, specMd: false },
     claudeMdHandling: 'kept',
+    agentsMdHandling: 'kept',
     hookConflicts: [],
   };
 
@@ -442,11 +468,30 @@ export async function performMerge(
   // Ensure sessions directory exists for session persistence
   await writeFile(path.join(projectRoot, '.claude', 'sessions', '.gitkeep'), '');
 
+  // Copy hook scripts (preserves existing user modifications)
+  await scaffoldHooks(projectRoot);
+
+  // Create learnings directory for correction capture
+  await writeFile(path.join(projectRoot, '.claude', 'learnings', '.gitkeep'), '');
+
+  // Opt-in: plugin.json (idempotent — scaffolder skips if file exists)
+  if (selections.generatePluginJson) {
+    await scaffoldPluginJson(projectRoot, selections);
+  }
+
+  // Opt-in: GTD memory scaffold (idempotent per-file). Tier 3 notice for
+  // existing Memory Architecture section is handled inside handleClaudeMd,
+  // which already reads CLAUDE.md and runs section detection.
+  if (selections.scaffoldGtdMemory) {
+    await scaffoldMemoryDocs(projectRoot);
+  }
+
   await mergeDocSpecs(projectRoot, existingScan, variables, selections, report);
 
   // Stop spinner before CLAUDE.md merge — interactive prompts for section selection
   if (spinner) spinner.stop();
-  await handleClaudeMd(projectRoot, existingScan, variables, report);
+  await handleClaudeMd(projectRoot, existingScan, variables, selections, report);
+  await mergeAgentsMd(projectRoot, existingScan, variables, report);
   if (spinner) spinner.start();
 
   return report;

package/src/core/scaffolder.js

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import fs from 'fs-extra';
-import { readFile, writeFile } from '../utils/file.js';
+import { fileExists, readFile, writeFile } from '../utils/file.js';
+import { UNIVERSAL_AGENTS } from '../data/agents.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -52,6 +53,7 @@ export async function updateGitignore(projectDir) {
     '.claude/workflow-meta.json',
     '.claude/worktrees/',
     '.claude-backup-*/',
+    '.claude/learnings/',
   ];
   const header = '# Worclaude (generated workflow files)';
 
@@ -86,6 +88,61 @@ export async function updateGitignore(projectDir) {
   return true;
 }
 
+export async function scaffoldHooks(projectRoot) {
+  const hooksTemplateDir = path.join(getTemplatesDir(), 'hooks');
+  const destDir = path.join(projectRoot, '.claude', 'hooks');
+  await fs.ensureDir(destDir);
+
+  const entries = await fs.readdir(hooksTemplateDir);
+  for (const entry of entries) {
+    if (!entry.endsWith('.cjs') && !entry.endsWith('.js')) continue;
+    await fs.copy(path.join(hooksTemplateDir, entry), path.join(destDir, entry), {
+      overwrite: false,
+      errorOnExist: false,
+    });
+  }
+}
+
+export function slugifyPluginName(projectName) {
+  const slug = String(projectName || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'worclaude-plugin';
+}
+
+export async function scaffoldPluginJson(projectRoot, selections) {
+  const destPath = path.join(projectRoot, '.claude-plugin', 'plugin.json');
+  if (await fileExists(destPath)) return;
+
+  const agents = [...UNIVERSAL_AGENTS, ...(selections.selectedAgents || [])].map(
+    (a) => `./.claude/agents/${a}.md`
+  );
+
+  const plugin = {
+    name: `${slugifyPluginName(selections.projectName)}-workflow`,
+    version: '0.1.0',
+    description: selections.description || `Claude Code workflow for ${selections.projectName}`,
+    keywords: ['claude-code', 'workflow', 'worclaude'],
+    agents,
+    skills: ['./.claude/skills/'],
+    commands: ['./.claude/commands/'],
+  };
+
+  await writeFile(destPath, JSON.stringify(plugin, null, 2) + '\n');
+}
+
+export async function scaffoldMemoryDocs(projectRoot) {
+  const destDir = path.join(projectRoot, 'docs', 'memory');
+  await fs.ensureDir(destDir);
+  for (const file of ['decisions.md', 'preferences.md']) {
+    const destPath = path.join(destDir, file);
+    if (await fileExists(destPath)) continue;
+    const content = await readTemplate(`memory/${file}`);
+    await writeFile(destPath, content);
+  }
+}
+
 export function mergeSettings(base, ...stacks) {
   const merged = JSON.parse(JSON.stringify(base));
   const baseAllow = merged.permissions?.allow || [];

package/src/data/agent-registry.js

@@ -1,11 +1,11 @@
 /**
- * Agent routing metadata for all 25 agents.
+ * Agent routing metadata for every agent in the registry.
  * Used by the agent-routing generator to produce the routing skill file.
  * Separate from agents.js because this data is only consumed by the generator,
  * not by CLI prompts or display logic.
  */
 export const AGENT_REGISTRY = {
-  // --- Universal agents (5) ---
+  // --- Universal agents ---
 
   'plan-reviewer': {
     category: 'universal',
@@ -73,6 +73,21 @@ export const AGENT_REGISTRY = {
     expectBack: 'Detailed verification report. Blocking issues listed.',
     situationLabel: 'Finished a task, ready for PR',
   },
+  'upstream-watcher': {
+    category: 'universal',
+    model: 'Sonnet',
+    isolation: 'none',
+    pipelineStage: 'Stage 1: Context',
+    triggerType: 'manual',
+    triggerCommand: '/upstream-check',
+    whenToUse:
+      'At the start of a session to check for upstream Claude Code changes. After Claude Code updates. When behavior seems different from last session.',
+    whatItDoes:
+      "Fetches anthropic-watch feeds, cross-references upstream changes against the project's scaffolded agents/commands/hooks/skills, and produces an impact report.",
+    expectBack:
+      'Impact report: which upstream changes affect this project, which are informational, and recommended actions.',
+    situationLabel: 'Want to check for upstream Claude Code changes',
+  },
 
   // --- Frontend agents (2) ---
 

package/src/data/agents.js

@@ -4,6 +4,7 @@ export const UNIVERSAL_AGENTS = [
   'test-writer',
   'build-validator',
   'verify-app',
+  'upstream-watcher',
 ];
 
 export const AGENT_CATALOG = {
@@ -194,6 +195,8 @@ export const COMMAND_FILES = [
   'build-fix',
   'refactor-clean',
   'test-coverage',
+  'learn',
+  'upstream-check',
 ];
 
 export const UNIVERSAL_SKILLS = [
@@ -205,6 +208,7 @@ export const UNIVERSAL_SKILLS = [
   'verification',
   'testing',
   'claude-md-maintenance',
+  'coding-principles',
   'subagent-usage',
   'security-checklist',
   'coordinator-mode',
@@ -216,6 +220,8 @@ export const TEMPLATE_SKILLS = [
   'project-patterns',
 ];
 
+export const HOOK_FILES = ['pre-compact-save', 'correction-detect', 'learn-capture', 'skill-hint'];
+
 export const PROJECT_TYPES = [
   'Full-stack web application',
   'Backend / API',
@@ -315,6 +321,7 @@ export const CONFIRMATION_STEPS = [
   { name: 'Project type', value: 'projectType' },
   { name: 'Tech stack', value: 'techStack' },
   { name: 'Agent selection', value: 'agents' },
+  { name: 'Optional extras (plugin.json, memory)', value: 'optionalExtras' },
 ];
 
 export const NOTIFICATION_COMMANDS = {

package/src/index.js

@@ -56,6 +56,7 @@ program
 program
   .command('doctor')
   .description('Validate workflow installation health')
-  .action(doctorCommand);
+  .option('--json', 'Output results as JSON')
+  .action((options) => doctorCommand(options));
 
 program.parse();

package/src/prompts/claude-md-merge.js

@@ -28,6 +28,11 @@ const SECTION_DETECTORS = [
     heading: '## Gotchas',
     test: (c) => /Gotchas/i.test(c),
   },
+  {
+    name: 'Memory Architecture',
+    heading: '## Memory Architecture',
+    test: (c) => /Memory Architecture/i.test(c) || /\.claude\/learnings\//i.test(c),
+  },
 ];
 
 export function detectMissingSections(existingContent) {

package/templates/agents/universal/build-validator.md

@@ -48,6 +48,29 @@ End with a clear verdict:
 - **WARNINGS**: Non-blocking issues (formatting, deprecation warnings) — can commit with caution
 - **BLOCKED**: Tests fail or build broken — must fix before committing
 
+## Severity Classification
+
+Classify each finding:
+
+| Severity | Meaning | Action |
+|----------|---------|--------|
+| CRITICAL | Build fails, tests fail, app won't start | BLOCKED — must fix |
+| WARNING | Deprecation warnings, formatting issues, lint warnings | Can commit with caution |
+| INFO | Performance suggestions, optional improvements | Note for later |
+
+Report CRITICAL issues first. If no CRITICAL but some WARNINGS, verdict is WARNINGS.
+
+## Common False Positives
+
+Do not report these as failures:
+- **Optional peer dependencies** missing — only a failure if the feature is used
+- **Platform-specific warnings** — warnings for platforms not targeted
+- **Dev dependency deprecation** — note but don't block
+- **Test timeouts in CI vs local** — environmental, not bugs
+- **Snapshot updates needed** — expected after intentional visual changes
+
+When in doubt, report as INFO, not CRITICAL.
+
 ## Rules
 - Run checks in the listed order — if build fails, still run the rest
 - Report ALL failures, not just the first one

package/templates/agents/universal/code-simplifier.md

@@ -65,6 +65,17 @@ After completing improvements, provide a summary:
 | 2 | src/api.js | Early return for null check | Reduced nesting from 4→2 levels |
 | 3 | src/config.js | Removed 12 unused imports | Dead code |
 
+## When NOT to Simplify
+
+Do not refactor:
+- **Hot paths** with performance-sensitive code — profiling data overrules readability
+- **Stable legacy code** that works and has no active bugs — risk exceeds benefit
+- **Framework boilerplate** — generated patterns that look verbose but are idiomatic
+- **Security-critical code** — verbose explicit validation is safer than clever abstraction
+- **Code you don't fully understand** — if you can't explain what it does, don't touch it
+
+When in doubt: leave it. A working system is more valuable than a clean system.
+
 ## Rules
 - Never change behavior — if tests break, you changed behavior, revert
 - Never refactor code you don't understand — read the full context first

package/templates/agents/universal/plan-reviewer.md

@@ -74,6 +74,45 @@ Structure your review as:
 
 **What's Good** (1-2 sentences — acknowledge strengths briefly):
 
+## Confidence Threshold
+
+Only flag issues you are >80% confident are real problems.
+If uncertain, phrase it as a question, not a finding.
+"This might cause issues with X" wastes the planner's time.
+"Will this handle concurrent requests? I see no locking in step 3." is actionable.
+
+## Must-Haves Verification
+
+Every plan must define must-haves:
+- **Truths**: Observable behaviors that must be true when done
+- **Artifacts**: Files that must exist with real implementation
+- **Key Links**: Connections between artifacts (imports, routes, configs)
+
+If must-haves are missing, verdict is NEEDS REVISION regardless of other quality.
+
+## Bounded Revision
+
+Maximum 3 revision cycles between reviewer and author:
+- Round 1: All issues surfaced. Author addresses them.
+- Round 2: Verify fixes, catch anything missed. Author addresses.
+- Round 3: Final check. If issues remain, escalate to user.
+
+If critical issues do not decrease between rounds, stop reviewing
+and escalate: "This plan needs human architectural input because..."
+
+## Worked Example
+
+**Plan:** "Add password reset feature"
+**Step 1:** "Create reset endpoint in src/routes/auth.js"
+
+**Review finding:** NEEDS REVISION
+- Missing: exact HTTP method and path (POST /api/auth/reset-password?)
+- Missing: what parameters does the request body accept?
+- Missing: verification step — how do you confirm the endpoint works?
+- Missing: how does the reset token get sent to the user?
+
+This level of specificity is what you're checking for.
+
 ## Review Principles
 - Be direct — flag problems, suggest solutions, don't hedge
 - Be specific — "this could fail" is useless; "step 3 will fail if the users table has existing rows because of the NOT NULL constraint" is actionable