chati-dev 4.2.1 → 4.3.0

package/framework/migrations/v4.2-to-v4.3.yaml

@@ -0,0 +1,29 @@
+migration:
+  from: "4.2.0"
+  to: "4.3.0"
+  description: "Framework/user separation hardening: comprehensive .gitignore, tracked-file detection, runtime boundary fixes"
+  breaking: false
+
+# This migration ensures users upgrading from any v4.2.x to v4.3.0 get:
+#   1. The new comprehensive .gitignore (covers .chati.dev/, .chati/, providers, etc.)
+#   2. Detection + warning if framework files are already tracked in git
+#   3. New 4.3.0 runtime boundary fixes (delivered via copyFrameworkFiles, this is a no-op step)
+#
+# Step types `update_gitignore` and `warn_tracked_files` are introduced in 4.3.0
+# and require src/upgrade/migrator.js >= the corresponding feature.
+
+steps:
+  # Step 1: Update .gitignore to the comprehensive 4.3.0 template.
+  # Idempotent: detects old marker (pre-4.3.0) and replaces; detects new marker and replaces.
+  # Merges with user's existing .gitignore (does not overwrite user content outside the chati block).
+  - type: update_gitignore
+    description: "Replace minimal pre-4.3.0 .gitignore block with comprehensive framework exclusions"
+
+  # Step 2: Detect framework files already tracked in git history (pre-4.3.0 leaks).
+  # Non-blocking: prints a warning with exact `git rm --cached` commands.
+  # User decides when/whether to clean up history.
+  - type: warn_tracked_files
+    description: "Warn if framework files were committed before .gitignore was fixed"
+
+# Validation: nothing critical to verify (gitignore content is variable per user).
+# The warn_tracked_files step itself acts as observability.

package/framework/orchestrator/chati-router.js

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+/**
+ * chati-router.js — Deterministic Pipeline Router
+ *
+ * Runs ALL deterministic logic BEFORE Claude processes anything:
+ *   1. License validation + integrity check
+ *   2. Session state read
+ *   3. Pipeline routing (orchestrate next)
+ *   4. Team registration (orchestrate spawn-team) if needed
+ *
+ * Outputs a single JSON object that Claude consumes. Claude cannot skip
+ * any of these steps because they already ran as code.
+ *
+ * Usage (from .claude/commands/chati.md):
+ *   node chati.dev/orchestrator/chati-router.js
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const PROJECT_DIR = process.cwd();
+const ROUTER_ARGS = process.argv.slice(2);
+
+/**
+ * Find the chati-dev CLI module. Tries local node_modules first (fast),
+ * then monorepo dev layout. Returns the module or null.
+ */
+async function findCliModule(projectDir) {
+  // Resolve framework dir (.chati.dev/ or chati.dev/ for legacy)
+  const fwDir = existsSync(join(projectDir, '.chati.dev')) ? '.chati.dev' : 'chati.dev';
+  const candidates = [
+    // PRIMARY: bundled CLI inside framework dir (self-contained install — no npx needed)
+    join(projectDir, fwDir, '_cli', 'orchestrator', 'cli.js'),
+    // Fallback: node_modules inside .chati.dev/
+    join(projectDir, fwDir, 'node_modules', 'chati-dev', 'src', 'orchestrator', 'cli.js'),
+    // Fallback: legacy node_modules at project root
+    join(projectDir, 'node_modules', 'chati-dev', 'src', 'orchestrator', 'cli.js'),
+    // Fallback: monorepo dev layout
+    join(projectDir, '..', '..', 'packages', 'chati-dev', 'src', 'orchestrator', 'cli.js'),
+    join(projectDir, '..', '..', '..', 'packages', 'chati-dev', 'src', 'orchestrator', 'cli.js'),
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try { return await import(p); } catch { /* continue */ }
+    }
+  }
+  // Last resort: Node module resolution (global install)
+  try {
+    const { createRequire } = await import('module');
+    const require = createRequire(join(projectDir, 'package.json'));
+    const cliPath = require.resolve('chati-dev/src/orchestrator/cli.js');
+    return await import(cliPath);
+  } catch { /* not installed globally */ }
+  return null;
+}
+
+/**
+ * Call runOrchestrate and capture its stdout JSON output.
+ */
+async function captureOrchestrate(mod, subCommand, args, projectDir) {
+  const chunks = [];
+  const origWrite = process.stdout.write;
+  process.stdout.write = (c) => { chunks.push(c); return true; };
+  try {
+    await mod.runOrchestrate(subCommand, args, projectDir);
+  } finally {
+    process.stdout.write = origWrite;
+  }
+  try {
+    return JSON.parse(chunks.join(''));
+  } catch (e) {
+    return { action: 'error', error: `invalid_json: ${e.message}` };
+  }
+}
+
+/**
+ * Route `advance` command deterministically — same reliability as `next`.
+ * Called as: node chati-router.js advance --agent {name} --score {score}
+ */
+async function routeAdvance(agentName, score) {
+  const result = {
+    ok: true,
+    advanced: false,
+    agent: agentName,
+    score: parseInt(score, 10),
+    next: null,
+    team: null,
+    error: null,
+  };
+
+  try {
+    const cliMod = await findCliModule(PROJECT_DIR);
+    if (!cliMod) {
+      result.ok = false;
+      result.error = 'cli_module_not_found';
+      return result;
+    }
+
+    const advanceResult = await captureOrchestrate(cliMod, 'advance',
+      ['--agent', agentName, '--score', String(score)], PROJECT_DIR);
+
+    result.advanced = advanceResult.advanced || false;
+    result.already_advanced = advanceResult.already_advanced || false;
+    if (advanceResult.status_summary) result.status_summary = advanceResult.status_summary;
+    result.next = advanceResult.next || advanceResult;
+
+    // If next action is spawn_team, register team immediately (deterministic)
+    if (result.next && result.next.action === 'spawn_team') {
+      const teamType = result.next.team_type || 'build';
+      const prevAgent = agentName;
+      try {
+        const teamResult = await captureOrchestrate(cliMod, 'spawn-team',
+          ['--team-type', teamType, '--previous-agent', prevAgent], PROJECT_DIR);
+
+        if (teamResult.fallback_required) {
+          result.next.action = 'spawn_parallel';
+          result.team = null;
+        } else {
+          result.team = {
+            team_id: teamResult.team_id,
+            team_type: teamResult.team_type,
+            members: teamResult.members,
+            task_list_path: teamResult.task_list_path,
+            mailbox_path: teamResult.mailbox_path,
+          };
+        }
+      } catch (err) {
+        result.next.action = 'spawn_parallel';
+        result.team = null;
+        result.error = `team_registration_failed: ${err.message?.slice(0, 200)}`;
+      }
+    }
+  } catch (err) {
+    result.ok = false;
+    result.error = `advance_failed: ${err.message?.slice(0, 200)}`;
+  }
+
+  return result;
+}
+
+// All orchestrate subcommands the router can dispatch locally
+const VALID_ORCHESTRATE_SUBS = new Set([
+  'next', 'advance', 'init', 'status', 'validate-handoff',
+  'deviation', 'exit', 'providers', 'detect-flow', 'backlog',
+  'qa-plan-score', 'qa-impl-score', 'qa-visual-score', 'scan',
+  'spawn-team', 'team-status', 'team-dissolve',
+  'wait-for-capture', 'wave-status', 'assess-coverage',
+  'wait-for-license', 'doctor',
+]);
+
+/**
+ * Parse --flag value pairs and standalone --flag bools from argv.
+ */
+function parseFlagArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      args[key] = next;
+      i++;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+/**
+ * Dispatch ANY orchestrate subcommand through the bundled local CLI.
+ * Returns the JSON result. Never falls back to npx.
+ */
+async function dispatchOrchestrate(subCommand, argv) {
+  const cliMod = await findCliModule(PROJECT_DIR);
+  if (!cliMod) {
+    return {
+      ok: false,
+      action: 'error',
+      error: 'cli_module_not_found',
+      reason: 'Bundled CLI not found in .chati.dev/_cli/. Reinstall with: npx chati-dev init',
+    };
+  }
+  try {
+    return await captureOrchestrate(cliMod, subCommand, argv, PROJECT_DIR);
+  } catch (err) {
+    return {
+      ok: false,
+      action: 'error',
+      error: `dispatch_failed: ${err.message?.slice(0, 200)}`,
+    };
+  }
+}
+
+async function main() {
+  const subCommand = ROUTER_ARGS[0];
+
+  // Sub-command mode: `node chati-router.js <subcommand> [--flags...]`
+  // Routes to the local CLI for ANY orchestrate subcommand. No npx, no network.
+  if (subCommand && VALID_ORCHESTRATE_SUBS.has(subCommand)) {
+    if (subCommand === 'advance') {
+      // advance also needs team registration, kept as a special case
+      const flags = parseFlagArgs(ROUTER_ARGS.slice(1));
+      if (!flags.agent || !flags.score) {
+        console.log(JSON.stringify({ ok: false, error: 'Missing --agent or --score' }));
+        return;
+      }
+      const advResult = await routeAdvance(flags.agent, flags.score);
+      console.log(JSON.stringify(advResult));
+      return;
+    }
+    // Generic dispatch for init, status, detect-flow, etc.
+    const result = await dispatchOrchestrate(subCommand, ROUTER_ARGS.slice(1));
+    console.log(JSON.stringify(result));
+    return;
+  }
+
+  // No-subcommand mode (default): full router pipeline (license + integrity + session + next)
+  const result = {
+    ok: true,
+    license: null,
+    integrity: true,
+    session: null,
+    action: null,
+    pipeline: null,
+    team: null,
+    error: null,
+  };
+
+  // -----------------------------------------------------------------------
+  // 1. License validation
+  // -----------------------------------------------------------------------
+  try {
+    const fwDir = existsSync(join(PROJECT_DIR, '.chati.dev')) ? '.chati.dev' : 'chati.dev';
+    const hookPath = join(PROJECT_DIR, fwDir, 'hooks', 'license-guard.js');
+    if (!existsSync(hookPath)) {
+      result.ok = false;
+      result.error = 'license_guard_missing';
+      result.license = { valid: false, reason: 'License enforcement file missing. Reinstall with: npx chati-dev init' };
+      console.log(JSON.stringify(result));
+      return;
+    }
+
+    const mod = await import(hookPath);
+    const license = await mod.checkLicense();
+    result.license = license;
+
+    if (!license.valid) {
+      result.ok = false;
+      result.error = 'license_invalid';
+      console.log(JSON.stringify(result));
+      return;
+    }
+  } catch (err) {
+    // Fail-closed on license check errors
+    result.license = { valid: false, error: 'license_check_error' };
+    result.ok = false;
+  }
+
+  // -----------------------------------------------------------------------
+  // 2. Integrity check — are all required hooks registered in settings.json?
+  // Note: license-guard is registered under UserPromptSubmit (not PreToolUse).
+  // mode-governance, constitution-guard, and read-protection are in PreToolUse.
+  // -----------------------------------------------------------------------
+  try {
+    const settingsPath = join(PROJECT_DIR, '.claude', 'settings.json');
+    if (existsSync(settingsPath)) {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+      const ptu = settings.hooks?.PreToolUse || [];
+      const ups = settings.hooks?.UserPromptSubmit || [];
+      const ptuCmds = ptu.flatMap(g => (g.hooks || []).map(h => h.command || ''));
+      const upsCmds = ups.flatMap(g => (g.hooks || []).map(h => h.command || ''));
+      // license-guard lives in UserPromptSubmit; others live in PreToolUse
+      const missingHooks = [
+        ...(['mode-governance', 'constitution-guard', 'read-protection'].filter(h => !ptuCmds.some(c => c.includes(h)))),
+        ...(['license-guard'].filter(h => !upsCmds.some(c => c.includes(h)) && !ptuCmds.some(c => c.includes(h)))),
+      ];
+      result.integrity = missingHooks.length === 0;
+      if (missingHooks.length > 0) {
+        result.error = `integrity_failed: missing hooks: ${missingHooks.join(', ')}`;
+      }
+    } else {
+      result.integrity = false;
+    }
+
+    if (!result.integrity) {
+      result.ok = false;
+      result.error = 'integrity_failed';
+      console.log(JSON.stringify(result));
+      return;
+    }
+  } catch {
+    // Fail-closed on integrity check
+    result.integrity = false;
+    result.ok = false;
+  }
+
+  // -----------------------------------------------------------------------
+  // 3. Session state
+  // -----------------------------------------------------------------------
+  try {
+    const sessionPath = join(PROJECT_DIR, '.chati', 'session.yaml');
+    if (existsSync(sessionPath)) {
+      const raw = readFileSync(sessionPath, 'utf-8');
+      const extract = (key) => {
+        const m = raw.match(new RegExp(`^\\s*${key}:\\s*(.+)$`, 'm'));
+        return m ? m[1].trim().replace(/^["']|["']$/g, '') : null;
+      };
+      result.session = {
+        language: extract('language') || 'en',
+        project_name: extract('name') || '',
+        project_type: extract('type') || 'greenfield',
+        state: extract('state') || 'discover',
+        current_agent: extract('current_agent') || '',
+        workflow: extract('workflow') || 'full',
+      };
+    }
+  } catch {
+    result.session = null;
+  }
+
+  // -----------------------------------------------------------------------
+  // 4. Pipeline routing — orchestrate next
+  // Calls bundled local CLI ONLY. No npx/network dependency: every install
+  // is self-contained via the bundled .chati.dev/_cli/ source.
+  // -----------------------------------------------------------------------
+  try {
+    const cliMod = await findCliModule(PROJECT_DIR);
+    if (!cliMod) {
+      result.action = 'error';
+      result.error = 'cli_module_not_found: bundled CLI missing in .chati.dev/_cli/. Reinstall with: npx chati-dev init';
+    } else {
+      result.pipeline = await captureOrchestrate(cliMod, 'next', [], PROJECT_DIR);
+      result.action = result.pipeline.action;
+    }
+  } catch (err) {
+    result.action = 'error';
+    result.error = `pipeline_routing_failed: ${err.message?.slice(0, 200)}`;
+  }
+
+  // -----------------------------------------------------------------------
+  // 5. If spawn_team → register team (deterministic, MUST happen before Claude)
+  // -----------------------------------------------------------------------
+  if (result.action === 'spawn_team' && result.pipeline) {
+    try {
+      const teamType = result.pipeline.team_type || 'planning';
+      const prevAgent = result.pipeline.agent || 'brief';
+      const cliMod = await findCliModule(PROJECT_DIR);
+
+      let teamResult;
+      if (cliMod) {
+        teamResult = await captureOrchestrate(cliMod, 'spawn-team',
+          ['--team-type', teamType, '--previous-agent', prevAgent], PROJECT_DIR);
+      } else {
+        // No CLI module → cannot spawn team. Don't fall back to npx (version drift risk).
+        result.action = 'spawn_parallel';
+        result.team = null;
+        result.error = 'cli_module_not_found: cannot spawn team without bundled CLI. Reinstall.';
+        return console.log(JSON.stringify(result));
+      }
+
+      if (teamResult.fallback_required) {
+        result.action = 'spawn_parallel';
+        result.team = null;
+      } else {
+        result.team = {
+          team_id: teamResult.team_id,
+          team_type: teamResult.team_type,
+          members: teamResult.members,
+          task_list_path: teamResult.task_list_path,
+          mailbox_path: teamResult.mailbox_path,
+        };
+      }
+    } catch (err) {
+      result.action = 'spawn_parallel';
+      result.team = null;
+      result.error = `team_registration_failed: ${err.message?.slice(0, 200)}`;
+    }
+  }
+
+  console.log(JSON.stringify(result));
+}
+
+main().catch(err => {
+  console.log(JSON.stringify({ ok: false, error: err.message }));
+});

package/framework/orchestrator/chati-update.md

@@ -1,4 +1,4 @@
-# /chati-update — Evolution Advisor with Self-Validated Implementation
+# /chati-update - Evolution Advisor with Self-Validated Implementation
 
 You are the **Chati Update Agent**, a specialized evolution advisor for the chati.dev framework. Your mission is to analyze an external repo/project, perform exhaustive cross-comparison with chati.dev's current state, propose improvements, and implement approved changes with ralph-wiggum self-validation at 95% threshold.
 
@@ -8,17 +8,17 @@ You are the **Chati Update Agent**, a specialized evolution advisor for the chat
 
 ## CRITICAL RULES
 
-1. **NEVER copy blindly** — Adapt concepts to chati.dev's identity and patterns
-2. **NEVER break existing tests** — All 989+ tests must continue passing
-3. **NEVER violate the constitution** — 19 articles are sacred
-4. **NEVER skip comparison** — Every finding MUST be validated against current state
-5. **ALWAYS present options** — Numbered 1, 2, 3 format before any implementation
-6. **ALWAYS use sub-agents** — Parallelize SCAN and COMPARE for throughput
-7. **ORIGINALITY 100%** — Zero copies, zero external framework references in code/docs
+1. **NEVER copy blindly** - Adapt concepts to chati.dev's identity and patterns
+2. **NEVER break existing tests** - All tests must continue passing (run `npm test` to verify)
+3. **NEVER violate the constitution** - 23 articles are sacred
+4. **NEVER skip comparison** - Every finding MUST be validated against current state
+5. **ALWAYS present options** - Numbered 1, 2, 3 format before any implementation
+6. **ALWAYS use sub-agents** - Parallelize SCAN and COMPARE for throughput
+7. **ORIGINALITY 100%** - Zero copies, zero external framework references in code/docs
 
 ---
 
-## Phase 0: PREPARE — Resolve Input
+## Phase 0: PREPARE - Resolve Input
 
 ```
 IF $ARGUMENTS is empty:
@@ -40,7 +40,7 @@ IF $ARGUMENTS is a GitHub shorthand (owner/repo):
 
 ---
 
-## Phase 1: SCAN — Deep Analysis of Reference Repo (Sub-Agent)
+## Phase 1: SCAN - Deep Analysis of Reference Repo (Sub-Agent)
 
 Launch a **Task agent (subagent_type=Explore, thoroughness=very thorough)** to analyze the reference repo at REF_PATH.
 
@@ -61,7 +61,7 @@ Analyze the repo at <REF_PATH> exhaustively. You must produce a comprehensive re
    - Configuration patterns (YAML, JSON, env)
    - CLI patterns and entry points
 
-3. **INTERESTING CONCEPTS** (the gold — be thorough)
+3. **INTERESTING CONCEPTS** (the gold - be thorough)
    - Novel patterns not commonly seen
    - Quality gates, validation systems
    - Context management strategies
@@ -80,19 +80,19 @@ Analyze the repo at <REF_PATH> exhaustively. You must produce a comprehensive re
    - Type safety patterns
    - Security patterns
 
-5. **SPECIFIC ARTIFACTS** — For each interesting file/pattern:
+5. **SPECIFIC ARTIFACTS** - For each interesting file/pattern:
    - File path
    - What it does
    - Why it's interesting
    - Key code snippets (actual content, not summaries)
 
-Be EXHAUSTIVE. Read every important file. Don't summarize — extract actual patterns with code.
+Be EXHAUSTIVE. Read every important file. Don't summarize - extract actual patterns with code.
 Minimum 30 files analyzed. No laziness.
 ```
 
 ---
 
-## Phase 2: COMPARE — Cross-Reference with Chati.dev (Sub-Agent)
+## Phase 2: COMPARE - Cross-Reference with Chati.dev (Sub-Agent)
 
 Launch **in parallel** with Phase 1 a **Task agent (subagent_type=Explore, thoroughness=very thorough)** to map chati.dev's current state.
 
@@ -101,44 +101,44 @@ Launch **in parallel** with Phase 1 a **Task agent (subagent_type=Explore, thoro
 ```
 Map the COMPLETE current state of chati.dev. Analyze:
 
-1. **CONSTITUTION** — Read chati.dev/constitution.md fully. Extract:
-   - All 19 articles with key rules
+1. **CONSTITUTION** - Read chati.dev/constitution.md fully. Extract:
+   - All 23 articles with key rules
    - Quality thresholds
    - Governance patterns
 
-2. **ALL AGENTS** — Read every file in chati.dev/agents/**/*.md:
+2. **ALL AGENTS** - Read every file in chati.dev/agents/**/*.md:
    - Agent identity, role, pipeline position
    - Input/output contracts
    - Acceptance criteria
    - Key patterns each agent uses
 
-3. **ORCHESTRATOR** — Read chati.dev/orchestrator/chati.md fully:
+3. **ORCHESTRATOR** - Read chati.dev/orchestrator/chati.md fully:
    - Routing logic
    - Session management
    - Deviation handling
 
-4. **WORKFLOWS** — Read chati.dev/workflows/*.yaml:
+4. **WORKFLOWS** - Read chati.dev/workflows/*.yaml:
    - Workflow definitions
    - Step sequences
    - Gate conditions
 
-5. **SCHEMAS** — Read chati.dev/schemas/*.json:
+5. **SCHEMAS** - Read chati.dev/schemas/*.json:
    - Session schema
    - Handoff schema
    - Config schema
 
-6. **HOOKS** — Read packages/chati-dev/src/**/*:
+6. **HOOKS** - Read packages/chati-dev/src/**/*:
    - All 6 hooks
    - PRISM engine
    - Mode governance
    - Build loop / autonomy system
 
-7. **TESTS** — Map test structure:
+7. **TESTS** - Map test structure:
    - Test organization
    - Coverage patterns
    - Key test utilities
 
-8. **CONFIG** — Read chati.dev/config.yaml, package.json:
+8. **CONFIG** - Read chati.dev/config.yaml, package.json:
    - Version info
    - Dependencies
    - Scripts
@@ -149,7 +149,7 @@ This is the baseline for comparison. Be thorough.
 
 ---
 
-## Phase 3: CROSS-ANALYZE — Merge Findings
+## Phase 3: CROSS-ANALYZE - Merge Findings
 
 Once both sub-agents complete, YOU (main agent) perform the cross-analysis:
 
@@ -177,7 +177,7 @@ constitution_check: <which articles are relevant, any conflicts>
 
 ---
 
-## Phase 4: PROPOSE — Present to User
+## Phase 4: PROPOSE - Present to User
 
 Generate a structured report for the user:
 
@@ -193,7 +193,7 @@ Generate a structured report for the user:
 
 ## Recommendations (sorted by priority_score desc)
 
-### ADOPT — New Concepts Worth Adding
+### ADOPT - New Concepts Worth Adding
 
 1. **<Finding Name>** (Priority: X/10)
    - **What**: <description>
@@ -204,7 +204,7 @@ Generate a structured report for the user:
 
 2. ...
 
-### ADAPT — Existing Concepts Worth Improving
+### ADAPT - Existing Concepts Worth Improving
 
 1. **<Finding Name>** (Priority: X/10)
    - **Current**: <how chati.dev does it today>
@@ -214,10 +214,10 @@ Generate a structured report for the user:
 
 2. ...
 
-### ALREADY_EXISTS — Chati.dev Already Has This
+### ALREADY_EXISTS - Chati.dev Already Has This
 (brief list for transparency)
 
-### IGNORE — Not Applicable
+### IGNORE - Not Applicable
 (brief list with reasons)
 ```
 
@@ -226,14 +226,14 @@ Then ask the user:
 
 ---
 
-## Phase 5: APPLY + RALPH — Self-Validated Implementation
+## Phase 5: APPLY + RALPH - Self-Validated Implementation
 
 For the approved changes, enter ralph-wiggum mode:
 
 ### Pre-Ralph Checklist:
-1. Run current tests: `npm test` — record baseline (must be green)
-2. Run lint: `npm run lint` — record baseline
-3. Git status — ensure clean working directory
+1. Run current tests: `npm test` - record baseline (must be green)
+2. Run lint: `npm run lint` - record baseline
+3. Git status - ensure clean working directory
 4. Create branch: `git checkout -b chati-update/<repo-name>-<date>`
 
 ### Ralph Loop Activation:
@@ -247,15 +247,15 @@ Use `/ralph-loop` with the following prompt structure:
 
 REQUIREMENTS:
 1. Implement each change following chati.dev patterns and conventions
-2. Respect the constitution (19 articles) — especially originality
+2. Respect the constitution (23 articles) - especially originality
 3. Update relevant tests for each change
-4. Run full test suite after each change — ALL must pass
-5. Run lint after each change — must be clean
+4. Run full test suite after each change - ALL must pass
+5. Run lint after each change - must be clean
 6. Validate against constitution rules
 7. Each change must score >= 95% on self-validation
 
 SELF-VALIDATION CHECKLIST (must ALL be true):
-- [ ] All existing tests pass (989+)
+- [ ] All existing tests pass (run `npm test` to verify)
 - [ ] New tests added for new functionality
 - [ ] Lint passes with zero errors
 - [ ] No external framework references (originality 100%)
@@ -272,7 +272,7 @@ When ALL items are validated at >= 95%, output:
 
 ---
 
-## Phase 6: REPORT — Final Summary
+## Phase 6: REPORT - Final Summary
 
 After ralph-wiggum completes, generate final report:
 
@@ -303,7 +303,7 @@ After ralph-wiggum completes, generate final report:
 ## Error Handling
 
 - **Clone fails**: Ask user for correct URL/path, suggest alternatives
-- **Tests fail at baseline**: STOP — do not proceed with changes on a broken baseline. Report to user.
+- **Tests fail at baseline**: STOP - do not proceed with changes on a broken baseline. Report to user.
 - **Ralph stuck (> 10 iterations without progress)**: Break loop, report what was achieved, ask user for guidance
 - **Constitution conflict detected**: STOP that specific change, report conflict, ask user for deviation approval
 - **Sub-agent returns incomplete data**: Re-run that specific sub-agent with more specific instructions
@@ -318,4 +318,4 @@ After ralph-wiggum completes, generate final report:
 - Don't modify the constitution
 - Don't skip the comparison phase ("it looks good, let's just add it")
 - Don't implement without user approval of the proposal
-- Don't rush — thoroughness > speed
+- Don't rush - thoroughness > speed