@sandrinio/vbounce 1.8.0 → 2.0.0

package/bin/vbounce.mjs

@@ -2,6 +2,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import crypto from 'crypto';
 import { fileURLToPath } from 'url';
 import readline from 'readline';
 
@@ -65,10 +66,10 @@ const askQuestion = (query) => new Promise(resolve => rl.question(query, resolve
 
 function displayHelp() {
   console.log(`
-V-Bounce OS CLI
+V-Bounce Engine CLI
 
 Usage:
-  vbounce install <platform>           Install V-Bounce OS into a project
+  vbounce install <platform>           Install V-Bounce Engine into a project
   vbounce state show                   Show current sprint state
   vbounce state update <storyId> <state|--qa-bounce>
   vbounce sprint init <sprintId> <deliveryId> [--stories STORY-001,...]
@@ -85,6 +86,7 @@ Usage:
   vbounce docs check <sprintId>        Detect stale vdocs and generate Scribe task
   vbounce trends                       Cross-sprint trend analysis
   vbounce suggest <sprintId>           Generate improvement suggestions
+  vbounce improve <sprintId>           Run full self-improvement pipeline
   vbounce doctor                       Validate all configs and state files
 
 Install Platforms:
@@ -194,6 +196,26 @@ if (command === 'suggest') {
   runScript('suggest_improvements.mjs', args.slice(1));
 }
 
+// -- improve --
+if (command === 'improve') {
+  rl.close();
+  // Full pipeline: analyze → trends → suggest
+  const sprintArg = args[1];
+  if (!sprintArg) {
+    console.error('Usage: vbounce improve S-XX');
+    process.exit(1);
+  }
+  // Run trends first
+  const trendsPath = path.join(pkgRoot, 'scripts', 'sprint_trends.mjs');
+  if (fs.existsSync(trendsPath)) {
+    console.log('Step 1/2: Running cross-sprint trend analysis...');
+    spawnSync(process.execPath, [trendsPath], { stdio: 'inherit', cwd: process.cwd() });
+  }
+  // Run suggest (which internally runs post_sprint_improve.mjs)
+  console.log('\nStep 2/2: Running improvement analyzer + suggestions...');
+  runScript('suggest_improvements.mjs', [sprintArg]);
+}
+
 // -- docs --
 if (command === 'docs') {
   rl.close();
@@ -227,6 +249,7 @@ if (command === 'install') {
   }
 
   const CWD = process.cwd();
+  const pkgVersion = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version;
 
   // Map vbounce platform names to vdoc platform names
   const vdocPlatformMap = {
@@ -287,34 +310,208 @@ if (command === 'install') {
     displayHelp();
   }
 
-  console.log(`\n🚀 Preparing to install V-Bounce OS for \x1b[36m${targetPlatform}\x1b[0m...\n`);
+  // ---------------------------------------------------------------------------
+  // Upgrade-safe install helpers
+  // ---------------------------------------------------------------------------
 
-  const toCopy = [];
-  const toOverwrite = [];
+  const META_PATH = path.join(CWD, '.bounce', 'install-meta.json');
+  const BACKUPS_DIR = path.join(CWD, '.bounce', 'backups');
 
-  mapping.forEach(rule => {
-    const sourcePath = path.join(pkgRoot, rule.src);
-    const destPath = path.join(CWD, rule.dest);
+  /** Compute MD5 hash of a single file's contents. */
+  function computeFileHash(filePath) {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash('md5').update(content).digest('hex');
+  }
 
-    if (!fs.existsSync(sourcePath)) {
-      return; // Source does not exist internally, skip
+  /** Compute a combined hash for a directory by hashing all files sorted by relative path. */
+  function computeDirHash(dirPath) {
+    const hash = crypto.createHash('md5');
+    const entries = [];
+
+    function walk(dir, rel) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        const relPath = path.join(rel, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath, relPath);
+        } else {
+          entries.push({ relPath, fullPath });
+        }
+      }
     }
 
-    if (fs.existsSync(destPath)) {
-      toOverwrite.push(rule.dest);
-    } else {
-      toCopy.push(rule.dest);
+    walk(dirPath, '');
+    entries.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    for (const e of entries) {
+      hash.update(e.relPath);
+      hash.update(fs.readFileSync(e.fullPath));
     }
-  });
+    return hash.digest('hex');
+  }
+
+  /** Compute hash for a path (file or directory). */
+  function computeHash(p) {
+    const stats = fs.statSync(p);
+    return stats.isDirectory() ? computeDirHash(p) : computeFileHash(p);
+  }
+
+  /** Count files in a path (1 for a file, recursive count for a directory). */
+  function countFiles(p) {
+    const stats = fs.statSync(p);
+    if (!stats.isDirectory()) return 1;
+    let count = 0;
+    function walk(dir) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) walk(path.join(dir, entry.name));
+        else count++;
+      }
+    }
+    walk(p);
+    return count;
+  }
+
+  /** Read install-meta.json, returns null if missing. */
+  function readInstallMeta() {
+    if (!fs.existsSync(META_PATH)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(META_PATH, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  /** Write install-meta.json. */
+  function writeInstallMeta(version, platform, files, hashes) {
+    const meta = {
+      version,
+      platform,
+      installed_at: new Date().toISOString(),
+      files,
+      hashes
+    };
+    fs.mkdirSync(path.dirname(META_PATH), { recursive: true });
+    fs.writeFileSync(META_PATH, JSON.stringify(meta, null, 2) + '\n');
+  }
+
+  /** Backup files to .bounce/backups/<version>/. Removes previous backup first. */
+  function backupFiles(version, paths) {
+    // Remove previous backup (keep only one)
+    if (fs.existsSync(BACKUPS_DIR)) {
+      for (const entry of fs.readdirSync(BACKUPS_DIR, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          fs.rmSync(path.join(BACKUPS_DIR, entry.name), { recursive: true, force: true });
+        }
+      }
+    }
+
+    const backupDir = path.join(BACKUPS_DIR, version);
+    fs.mkdirSync(backupDir, { recursive: true });
+
+    for (const relPath of paths) {
+      const src = path.join(CWD, relPath);
+      const dest = path.join(backupDir, relPath);
+
+      if (!fs.existsSync(src)) continue;
+
+      const stats = fs.statSync(src);
+      if (stats.isDirectory()) {
+        fs.mkdirSync(dest, { recursive: true });
+        fs.cpSync(src, dest, { recursive: true });
+      } else {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+      }
+    }
+
+    return backupDir;
+  }
+
+  /**
+   * Classify files into unchanged, modified, and newFiles.
+   * - unchanged: dest exists and matches what was installed (safe to overwrite)
+   * - modified: dest exists but differs from what was installed (user changed it)
+   * - newFiles: dest does not exist
+   */
+  function classifyFiles(mappingRules, meta) {
+    const unchanged = [];
+    const modified = [];
+    const newFiles = [];
+
+    for (const rule of mappingRules) {
+      const sourcePath = path.join(pkgRoot, rule.src);
+      const destPath = path.join(CWD, rule.dest);
+
+      if (!fs.existsSync(sourcePath)) continue;
+
+      if (!fs.existsSync(destPath)) {
+        newFiles.push(rule);
+        continue;
+      }
+
+      // Dest exists — classify as unchanged or modified
+      if (!meta || !meta.hashes || !meta.hashes[rule.dest]) {
+        // No metadata (first upgrade) — treat as modified to be safe
+        modified.push(rule);
+        continue;
+      }
+
+      const currentHash = computeHash(destPath);
+      const installedHash = meta.hashes[rule.dest];
+
+      if (currentHash === installedHash) {
+        unchanged.push(rule);
+      } else {
+        modified.push(rule);
+      }
+    }
+
+    return { unchanged, modified, newFiles };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Begin install flow
+  // ---------------------------------------------------------------------------
 
-  if (toCopy.length > 0) {
-    console.log('The following will be \x1b[32mCREATED\x1b[0m:');
-    toCopy.forEach(f => console.log(`  + ${f}`));
+  const meta = readInstallMeta();
+  const isUpgrade = meta !== null;
+
+  if (isUpgrade) {
+    console.log(`\n🚀 V-Bounce Engine \x1b[36m${pkgVersion}\x1b[0m (upgrading from \x1b[33m${meta.version}\x1b[0m)\n`);
+  } else {
+    console.log(`\n🚀 Preparing to install V-Bounce Engine \x1b[36m${pkgVersion}\x1b[0m for \x1b[36m${targetPlatform}\x1b[0m...\n`);
   }
 
-  if (toOverwrite.length > 0) {
-    console.log('\nThe following will be \x1b[33mOVERWRITTEN\x1b[0m:');
-    toOverwrite.forEach(f => console.log(`  ! ${f}`));
+  const { unchanged, modified, newFiles } = classifyFiles(mapping, meta);
+
+  if (unchanged.length > 0) {
+    console.log('Will update (unchanged by you):');
+    for (const rule of unchanged) {
+      const destPath = path.join(CWD, rule.dest);
+      const n = countFiles(destPath);
+      const label = n > 1 ? `(${n} files)` : '';
+      console.log(`  \x1b[32m✓\x1b[0m ${rule.dest} ${label}`);
+    }
+  }
+
+  if (modified.length > 0) {
+    const backupLabel = isUpgrade ? `.bounce/backups/${meta.version}/` : '.bounce/backups/pre-install/';
+    console.log(`\nModified by you (backed up to ${backupLabel}):`);
+    for (const rule of modified) {
+      console.log(`  \x1b[33m⚠\x1b[0m ${rule.dest}`);
+    }
+  }
+
+  if (newFiles.length > 0) {
+    console.log('\nNew in this version:');
+    for (const rule of newFiles) {
+      console.log(`  \x1b[32m+\x1b[0m ${rule.dest}`);
+    }
+  }
+
+  if (unchanged.length === 0 && modified.length === 0 && newFiles.length === 0) {
+    rl.close();
+    console.log('Nothing to install — all source files are missing from the package.');
+    process.exit(0);
   }
 
   console.log('');
@@ -328,13 +525,23 @@ if (command === 'install') {
       process.exit(0);
     }
 
+    // Backup modified files before overwriting
+    if (modified.length > 0) {
+      const backupVersion = isUpgrade ? meta.version : 'pre-install';
+      const backupDir = backupFiles(backupVersion, modified.map(r => r.dest));
+      console.log(`\n📂 Backed up modified files to ${path.relative(CWD, backupDir)}/`);
+    }
+
     console.log('\n📦 Installing files...');
 
-    mapping.forEach(rule => {
+    const installedFiles = [];
+    const hashes = {};
+
+    for (const rule of [...unchanged, ...modified, ...newFiles]) {
       const sourcePath = path.join(pkgRoot, rule.src);
       const destPath = path.join(CWD, rule.dest);
 
-      if (!fs.existsSync(sourcePath)) return;
+      if (!fs.existsSync(sourcePath)) continue;
 
       const stats = fs.statSync(sourcePath);
       if (stats.isDirectory()) {
@@ -347,8 +554,16 @@ if (command === 'install') {
         }
         fs.copyFileSync(sourcePath, destPath);
       }
+
+      // Record hash of what we just installed (from source)
+      hashes[rule.dest] = computeHash(sourcePath);
+      installedFiles.push(rule.dest);
       console.log(`  \x1b[32m✓\x1b[0m ${rule.dest}`);
-    });
+    }
+
+    // Write install metadata
+    writeInstallMeta(pkgVersion, targetPlatform, installedFiles, hashes);
+    console.log(`  \x1b[32m✓\x1b[0m .bounce/install-meta.json`);
 
     console.log('\n⚙️  Installing dependencies...');
     try {
@@ -380,7 +595,22 @@ if (command === 'install') {
       }
     }
 
-    console.log('\n✅ V-Bounce OS successfully installed! Welcome to the team.\n');
+    // Auto-run doctor to verify installation
+    console.log('\n🩺 Running doctor to verify installation...');
+    const doctorPath = path.join(CWD, 'scripts', 'doctor.mjs');
+    if (fs.existsSync(doctorPath)) {
+      const result = spawnSync(process.execPath, [doctorPath], {
+        stdio: 'inherit',
+        cwd: CWD
+      });
+      if (result.status !== 0) {
+        console.error('\n  \x1b[33m⚠\x1b[0m Doctor reported issues. Review the output above.');
+      }
+    } else {
+      console.log('  \x1b[33m⚠\x1b[0m Doctor script not found — skipping verification.');
+    }
+
+    console.log('\n✅ V-Bounce Engine successfully installed! Welcome to the team.\n');
   });
 
 } else {

package/brains/AGENTS.md

@@ -1,10 +1,14 @@
-# V-Bounce OS — Agent Brain (Codex CLI)
+# V-Bounce Engine — Agent Brain (Codex CLI)
 
-> This file configures OpenAI Codex CLI to operate within the V-Bounce OS framework.
+> This file configures OpenAI Codex CLI to operate within the V-Bounce Engine framework.
 
 ## Identity
 
-You are an AI coding agent operating within **V-Bounce OS** — a structured system for planning, implementing, and validating software using AI agents. You work as part of a team: Team Lead, Developer, QA, Architect, DevOps, and Scribe agents collaborate through structured reports.
+You are an AI operating within **V-Bounce Engine** — a structured system for planning, implementing, and validating software.
+
+You have two roles depending on the phase:
+- **During Planning (Phase 1 & 2):** You work directly with the human. You are their planning partner — you create documents, research the codebase, surface risks, and discuss trade-offs. No subagents are involved.
+- **During Execution (Phase 3):** You are the Team Lead orchestrating specialist agents (Developer, QA, Architect, DevOps, Scribe) through structured reports.
 
 You MUST follow the V-Bounce process. Deviating from it — skipping validation, ignoring LESSONS.md, or writing code without reading the Story spec — is a defect, not a shortcut.
 
@@ -24,34 +28,51 @@ Skills are in the `skills/` directory. Each skill has a `SKILL.md` with instruct
 
 ## The V-Bounce Process
 
-### Phase 1: Verification (Planning)
-Documents are created in strict hierarchy — no level can be skipped:
+The process has four phases. You determine which phase to operate in based on what the human is asking for.
+
+### Phase 1: Planning (AI + Human — No Subagents)
+
+**When to enter:** The human talks about what to build, asks to create or modify planning documents, discusses features, priorities, or asks about work status. This is a direct conversation — no subagents.
+
+Read `skills/doc-manager/SKILL.md` and follow its workflows.
+
+**Document hierarchy** — no level can be skipped:
 Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → Risk Registry (risks)
 
-### Pre-Bounce Checks
-Before starting any sprint, the Team Lead MUST:
-- **Triage the Request**: Is this an L1 Trivial change (1-2 files, cosmetic/minor)?
-  - If YES → Use the **Hotfix Path** (create a Hotfix document, bypass Epic/Story).
-  - If NO → Use the **Standard Path** (create/find Epic, Story).
-- **Determine Execution Mode**: Full Bounce vs Fast Track.
-- **Dependency Check**: Stories with `Depends On:` must execute sequentially.
-- Read RISK_REGISTRY.md — flag high-severity risks that affect planned stories.
-- Read `sprint-{XX}.md` §2 Sprint Open Questions — do not bounce stories with unresolved blocking questions.
-- If `vdocs/_manifest.json` exists, read it.
-- **Strategic Freeze**: Charter/Roadmap frozen during sprints. Use **Impact Analysis Protocol** if emergency changes occur. Evaluate active stories against new strategy. Pause until human approval.
-
-### Phase 2: The Bounce (Implementation)
+**Your responsibilities during planning:**
+1. **Creating documents:** Read upstream documents, research the codebase, draft the document. Follow doc-manager's CREATE and DECOMPOSE workflows.
+2. **Surfacing problems:** Assess ambiguity, open questions, edge cases, and risks. Present these clearly to the human — this is collaborative.
+3. **Answering status questions:** Read `product_plans/` to understand current state (backlog/, sprints/, archive/, strategy/).
+4. **Triaging requests:** L1 Trivial → Hotfix Path. Everything else → Standard Path (Epic → Story → Sprint).
+
+### Phase 2: Sprint Planning (AI + Human — Collaborative Gate)
+
+**When to enter:** The human wants to start executing work — "let's start a sprint", "what should we work on next?"
+
+**Hard rule: No bounce can start without a finalized, human-confirmed Sprint Plan.**
+
+1. Read backlog, archive, Risk Registry, vdocs manifest
+2. Propose sprint scope based on priority, dependencies, complexity
+3. Surface blockers: open questions, 🔴 ambiguity, missing prerequisites, risks, edge cases
+4. Discuss and refine with human
+5. Create Sprint Plan from `templates/sprint.md` — fill §0 Readiness Gate, §1 Active Scope, §2 Execution Strategy, §3 Open Questions
+6. **Gate:** Human confirms the Sprint Plan. Only then set status to "Active"
+
+**Strategic Freeze:** Charter/Roadmap frozen during sprints. Use **Impact Analysis Protocol** if emergency changes occur. Pause until human approval.
+
+### Phase 3: The Bounce (Execution)
 **Standard Path (L2-L4 Stories):**
 0. **Orient via state**: Read `.bounce/state.json` (`vbounce state show`) for instant context. Run `vbounce prep sprint S-{XX}` to generate a fresh context pack.
 1. Team Lead sends Story context pack to Developer.
 2. Developer reads LESSONS.md and the Story context pack, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
 3. **Pre-QA Gate Scan:** Team Lead runs `./scripts/pre_gate_runner.sh qa` to catch mechanical failures before spawning QA. If trivial issues → return to Dev.
 4. QA runs Quick Scan + PR Review (skipping pre-scanned checks), validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report.
-5. Dev fixes and resubmits. 3+ failures → Escalated.
+5. Dev fixes and resubmits. 3+ failures → Escalated (see Escalation Recovery below).
 6. **Pre-Architect Gate Scan:** Team Lead runs `./scripts/pre_gate_runner.sh arch` to catch structural issues before spawning Architect. If mechanical failures → return to Dev.
 7. Architect runs Deep Audit + Trend Check (skipping pre-scanned checks), validates Safe Zone compliance and ADR adherence.
 8. DevOps merges story branch into sprint branch, validates post-merge (tests + lint + build), handles release tagging.
-9. Team Lead consolidates reports into Sprint Report.
+9. **Record lessons immediately**: After DevOps merge, check Dev and QA reports for `lessons_flagged`. Record to LESSONS.md now — do not wait for sprint close.
+10. Team Lead consolidates reports into Sprint Report.
 
 **Hotfix Path (L1 Trivial Tasks):**
 1. Team Lead evaluates request and creates `HOTFIX-{Date}-{Name}.md`.
@@ -61,10 +82,27 @@ Before starting any sprint, the Team Lead MUST:
 5. Hotfix is merged directly into the active branch.
 6. DevOps (or Team Lead) runs `./scripts/hotfix_manager.sh sync` to update active worktrees.
 
-### Phase 3: Review
-Sprint Report → Human review → Delivery Plan updated → Lessons recorded → Next sprint.
+**Escalation Recovery (3+ bounce failures):**
+1. Mark story as "Escalated" in Sprint Plan
+2. Present to human: what failed, root causes from bounce reports, pattern analysis
+3. Propose options: re-scope the story, split into smaller stories, create a spike, or remove from sprint
+4. Human decides. Execute the decision.
+
+### Phase 4: Review
+Sprint Report → Human review → Delivery Plan updated (at boundary only) → Lessons recorded → Next sprint.
 If sprint delivered new features or Dev reports flagged stale product docs → spawn Scribe agent to generate/update vdocs/ via vdoc.
 
+**Self-Improvement Pipeline** (auto-runs on `vbounce sprint close`):
+1. `sprint_trends.mjs` → cross-sprint trend analysis → `.bounce/trends.md`
+2. `post_sprint_improve.mjs` → parses §5 retro tables + LESSONS.md automation candidates + recurring patterns + effectiveness checks → `.bounce/improvement-manifest.json`
+3. `suggest_improvements.mjs` → generates human-readable suggestions with impact levels → `.bounce/improvement-suggestions.md`
+4. Human reviews suggestions → approve/reject/defer each item
+5. Run `/improve` to apply approved changes with brain-file sync
+
+**Impact Levels:** P0 Critical (blocks agents), P1 High (causes rework), P2 Medium (friction), P3 Low (polish). See `/improve` skill for details.
+
+On-demand: `vbounce improve S-{XX}` runs the full pipeline.
+
 ## Story States
 
 Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architect Passed → Sprint Review → Done
@@ -101,12 +139,12 @@ Bouncing → Escalated (3+ failures)
 10. One source of truth. Reference upstream documents, don't duplicate.
 11. Change Logs are mandatory on every document modification.
 12. Agent Reports MUST use YAML Frontmatter. Every `.bounce/report/` generated must start with a strict `---` YAML block containing the core status and metrics before the Markdown body.
-13. Framework Integrity. Any modification to a `brains/` or `skills/` file MUST be recorded in `brains/CHANGELOG.md`.
+13. Framework Integrity. Any modification to a `brains/`, `skills/`, `templates/`, or `scripts/` file MUST be recorded in `brains/CHANGELOG.md` and reflected in `MANIFEST.md`.
 
 ## Framework Structure
 
 ```
-V-Bounce OS/
+V-Bounce Engine/
 ├── brains/          — Agent brain files (this file)
 ├── templates/       — Document templates (immutable)
 ├── skills/          — Agent skills (SKILL.md files)

package/brains/CHANGELOG.md

@@ -1,8 +1,30 @@
-# V-Bounce OS Brains & Skills Changelog
+# V-Bounce Engine Brains & Skills Changelog
 
 This log tracks modifications to the core agentic framework (e.g., `brains/`, `skills/`). 
 Per **Rule 13: Framework Integrity**, anytime an entry is made here, all tool-specific brain files must be reviewed for consistency.
 
+## [2026-03-13] — Discovery Phase: Structured Spike System
+
+### Spike Template (New)
+- **Added**: `templates/spike.md` — spike document template with YAML frontmatter (spike_id, parent_epic_ref, status, ambiguity_before, time_box), 8 sections (Question, Constraints, Approach, Findings, Decision, Residual Risk, Affected Documents checklist, Change Log). Hierarchy Level 3.5 — child of Epic, sibling of Story. Output location: `product_plans/backlog/EPIC-{NNN}_{name}/SPIKE-{EpicID}-{NNN}-{topic}.md`.
+
+### Discovery Reference (New)
+- **Added**: `skills/agent-team/references/discovery.md` — spike execution protocol. Covers: when discovery triggers, spike lifecycle (Open → Investigating → Findings Ready → Validated → Closed), 4-step execution protocol (Create → Investigate → Validate → Close & Propagate), timing rules, integration with bounce sequence.
+
+### Doc-Manager Skill (Modified)
+- **Modified**: `skills/doc-manager/SKILL.md` — added Spike row to Template Locations table; added spike file to folder structure diagram; added spike information flows (Epic §8 → Spike §1, Spike §4 → Epic §4, Spike §5 → Roadmap §3, Spike §6 → Risk Registry); added Spike pre-read requirements; added spike cascade rules; added spike transition gates (Probing/Spiking → Refinement, Spike → Validated, Spike → Closed); updated Developer and Architect agent integration rows with spike ownership; added Ambiguity Assessment Rubric section with 🔴/🟡/🟢 signal definitions and spike creation trigger.
+
+### Agent-Team Skill (Modified)
+- **Modified**: `skills/agent-team/SKILL.md` — added Step 0.5: Discovery Check between Sprint Setup and Story Initialization; added critical rule "Resolve discovery before bouncing" requiring L4/🔴 stories to complete spikes before entering bounce sequence.
+
+### Claude Brain (Modified)
+- **Modified**: `brains/CLAUDE.md` — added Discovery Check to Pre-Bounce Checks; expanded L4 complexity label with spike creation and validation requirements; updated Story States diagram to show spike sub-flow (Dev investigates → Arch validates → docs updated).
+
+### Sync Notes
+- Other brain files (`GEMINI.md`, `AGENTS.md`, `cursor-rules/`) not yet updated — should be synced in a follow-up change.
+
+---
+
 ## [2026-03-12] — LanceDB Removal
 
 - **Removed**: `scripts/vbounce_ask.mjs` — LanceDB semantic query tool. Replaced by direct `LESSONS.md` reads.
@@ -21,7 +43,7 @@ Per **Rule 13: Framework Integrity**, anytime an entry is made here, all tool-sp
 - **Modified**: `.gitignore` — Removed `.bounce/.lancedb/` entry.
 - **Rationale**: Modern LLMs have 200K+ token context windows. The prep scripts (`vbounce prep sprint/qa/arch`) + LESSONS.md graduation provide targeted, deterministic context without embedding models, sync steps, or heavy dependencies. Removes ~50MB of node_modules and eliminates the most common setup failure point.
 
-## [2026-03-12] — V-Bounce OS Optimization Plan (12-Change Batch)
+## [2026-03-12] — V-Bounce Engine Optimization Plan (12-Change Batch)
 
 ### State Management (Change #1)
 - **Added**: `.bounce/state.json` — machine-readable sprint state snapshot for crash recovery. Tracks sprint_id, delivery_id, current_phase, last_action, and per-story state (V-Bounce state, bounce counts, worktree path, updated_at).