@sandrinio/vbounce 1.7.0 → 1.9.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,...]
@@ -81,6 +82,8 @@ Usage:
   vbounce prep qa <storyId>            Generate QA context pack
   vbounce prep arch <storyId>          Generate Architect context pack
   vbounce prep sprint <sprintId>       Generate Sprint context pack
+  vbounce docs match --story <ID>      Match story scope against vdoc manifest
+  vbounce docs check <sprintId>        Detect stale vdocs and generate Scribe task
   vbounce trends                       Cross-sprint trend analysis
   vbounce suggest <sprintId>           Generate improvement suggestions
   vbounce doctor                       Validate all configs and state files
@@ -192,6 +195,20 @@ if (command === 'suggest') {
   runScript('suggest_improvements.mjs', args.slice(1));
 }
 
+// -- docs --
+if (command === 'docs') {
+  rl.close();
+  if (sub === 'match') {
+    runScript('vdoc_match.mjs', args.slice(2));
+  } else if (sub === 'check') {
+    runScript('vdoc_staleness.mjs', args.slice(2));
+  } else {
+    console.error(`Unknown docs subcommand: ${sub}`);
+    console.error('Usage: vbounce docs match --story <ID> | vbounce docs check <sprintId>');
+    process.exit(1);
+  }
+}
+
 // -- doctor --
 if (command === 'doctor') {
   rl.close();
@@ -211,6 +228,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 = {
@@ -271,34 +289,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('');
@@ -312,13 +504,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()) {
@@ -331,8 +533,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 {
@@ -364,7 +574,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,10 @@
-# 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 coding agent operating within **V-Bounce Engine** — 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 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.
 
@@ -106,7 +106,7 @@ Bouncing → Escalated (3+ failures)
 ## 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,4 +1,4 @@
-# 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.
@@ -21,7 +21,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).

package/brains/CLAUDE.md

@@ -1,10 +1,10 @@
-# V-Bounce OS — Agent Brain
+# V-Bounce Engine — Agent Brain
 
-> This file configures Claude Code to operate within the V-Bounce OS framework.
+> This file configures Claude Code 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 coding agent operating within **V-Bounce Engine** — 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 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.
 
@@ -127,7 +127,7 @@ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architec
 ## 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/GEMINI.md

@@ -1,11 +1,11 @@
-# V-Bounce OS — Agent Brain
+# V-Bounce Engine — Agent Brain
 
-> This file configures Gemini CLI and Antigravity to operate within the V-Bounce OS framework.
+> This file configures Gemini CLI and Antigravity to operate within the V-Bounce Engine framework.
 > Place at project root for Gemini CLI. For Antigravity, also copy skills to `.agents/skills/`.
 
 ## 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 coding agent operating within **V-Bounce Engine** — 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 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.
 
@@ -27,7 +27,7 @@ For Antigravity: copy skills to `.agents/skills/` for workspace-scoped discovery
 
 ## CLI Commands
 
-V-Bounce OS ships a CLI. Use these commands for state management instead of editing files manually:
+V-Bounce Engine ships a CLI. Use these commands for state management instead of editing files manually:
 
 ```bash
 # Sprint management
@@ -149,7 +149,7 @@ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architec
 ## 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/SETUP.md

@@ -1,13 +1,13 @@
-# Adding V-Bounce OS to Any Repo
+# Adding V-Bounce Engine to Any Repo
 
-Step-by-step guide to set up V-Bounce OS in an existing or new project.
+Step-by-step guide to set up V-Bounce Engine in an existing or new project.
 
 ## Prerequisites
 
-- A git repository (V-Bounce OS uses branches and worktrees)
+- A git repository (V-Bounce Engine uses branches and worktrees)
 - Node.js installed (for validation and semantic search scripts)
 - At least one supported AI coding tool installed
-- The V-Bounce OS folder (this repo)
+- The V-Bounce Engine folder (this repo)
 
 ## Step 1: Copy the Framework
 
@@ -15,11 +15,11 @@ Copy the `skills/` and `templates/` directories into your project root:
 
 ```bash
 # From your project root
-cp -r /path/to/V-Bounce-OS/skills/ ./skills/
-cp -r /path/to/V-Bounce-OS/templates/ ./templates/
+cp -r /path/to/V-Bounce-Engine/skills/ ./skills/
+cp -r /path/to/V-Bounce-Engine/templates/ ./templates/
 ```
 
-These are the core of V-Bounce OS — skills define agent behavior, templates define document structure.
+These are the core of V-Bounce Engine — skills define agent behavior, templates define document structure.
 
 ## Step 2: Deploy Brain File for Your AI Tool
 
@@ -27,32 +27,32 @@ Pick the tool you're using and deploy the corresponding brain file:
 
 ### Claude Code
 ```bash
-cp /path/to/V-Bounce-OS/brains/CLAUDE.md ./CLAUDE.md
+cp /path/to/V-Bounce-Engine/brains/CLAUDE.md ./CLAUDE.md
 
 # Deploy subagent configs
 mkdir -p .claude/agents
-cp /path/to/V-Bounce-OS/brains/claude-agents/*.md .claude/agents/
+cp /path/to/V-Bounce-Engine/brains/claude-agents/*.md .claude/agents/
 ```
 
 ### Codex CLI (OpenAI)
 ```bash
-cp /path/to/V-Bounce-OS/brains/AGENTS.md ./AGENTS.md
+cp /path/to/V-Bounce-Engine/brains/AGENTS.md ./AGENTS.md
 ```
 
 ### Cursor
 ```bash
 mkdir -p .cursor/rules
-cp /path/to/V-Bounce-OS/brains/cursor-rules/*.mdc .cursor/rules/
+cp /path/to/V-Bounce-Engine/brains/cursor-rules/*.mdc .cursor/rules/
 ```
 
 ### Gemini CLI
 ```bash
-cp /path/to/V-Bounce-OS/brains/GEMINI.md ./GEMINI.md
+cp /path/to/V-Bounce-Engine/brains/GEMINI.md ./GEMINI.md
 ```
 
 ### Antigravity
 ```bash
-cp /path/to/V-Bounce-OS/brains/GEMINI.md ./GEMINI.md
+cp /path/to/V-Bounce-Engine/brains/GEMINI.md ./GEMINI.md
 cp -r skills/ .agents/skills/
 ```
 
@@ -141,7 +141,7 @@ your-project/
 ├── CLAUDE.md                  ← brain file (or AGENTS.md / GEMINI.md)
 ├── LESSONS.md                 ← project-specific rules (grows over time)
 ├── .claude/agents/            ← subagent configs (Claude Code only)
-├── skills/                    ← V-Bounce OS skills
+├── skills/                    ← V-Bounce Engine skills
 │   ├── agent-team/
 │   ├── doc-manager/
 │   ├── lesson/
@@ -192,4 +192,4 @@ brains/
     └── vbounce-docs.mdc
 ```
 
-Each brain file is self-contained and authoritative for its tool. When updating V-Bounce OS rules, update each brain file directly and keep them in sync.
+Each brain file is self-contained and authoritative for its tool. When updating V-Bounce Engine rules, update each brain file directly and keep them in sync.

package/brains/claude-agents/architect.md

@@ -5,7 +5,7 @@ tools: Read, Glob, Grep, Bash
 disallowedTools: Edit, Write
 ---
 
-You are the **Architect Agent** in the V-Bounce OS framework.
+You are the **Architect Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 Audit the codebase for structural integrity, standards compliance, and long-term sustainability. You review — you do not implement. You are the last gate before human review.

package/brains/claude-agents/developer.md

@@ -5,7 +5,7 @@ tools: Read, Edit, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
-You are the **Developer Agent** in the V-Bounce OS framework.
+You are the **Developer Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 Implement features and fix bugs as specified in Story documents. You write code — nothing more, nothing less.

package/brains/claude-agents/devops.md

@@ -5,7 +5,7 @@ tools: Read, Edit, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
-You are the **DevOps Agent** in the V-Bounce OS framework.
+You are the **DevOps Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 

package/brains/claude-agents/qa.md

@@ -5,7 +5,7 @@ tools: Read, Bash, Glob, Grep
 disallowedTools: Edit, Write
 ---
 
-You are the **QA Agent** in the V-Bounce OS framework.
+You are the **QA Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 Validate that the Developer's implementation meets the Story's acceptance criteria. You test — you do not fix. If something fails, you write a detailed bug report and send it back.
@@ -15,6 +15,7 @@ Validate that the Developer's implementation meets the Story's acceptance criter
 1. **Read LESSONS.md**: Scan for failure patterns relevant to this story. Treat matching entries as known risk areas to probe first.
 2. **Read the Developer Implementation Report** (`.bounce/reports/STORY-{ID}-{StoryName}-dev.md`) to understand what was built.
 3. **Read Story §2 The Truth** — these are your pass/fail criteria. If the Gherkin scenarios don't pass, the bounce failed.
+4. **Check vdoc context**: If the QA context pack includes a `## vdoc Context` section, read the referenced product docs. Cross-reference the Developer's changes against documented behavior — if the implementation contradicts what a vdoc describes, flag it as a behavioral regression even if the Gherkin scenarios pass. Check the Blast Radius warnings for features that may be indirectly affected.
 
 ## Pre-Computed Scan Results
 

package/brains/claude-agents/scribe.md

@@ -5,7 +5,7 @@ tools: Read, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
-You are the **Scribe Agent** in the V-Bounce OS framework.
+You are the **Scribe Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 

package/brains/copilot/copilot-instructions.md

@@ -1,10 +1,10 @@
-# V-Bounce OS — GitHub Copilot Instructions
+# V-Bounce Engine — GitHub Copilot Instructions
 
-This project uses **V-Bounce OS** — a structured AI-agent development framework.
+This project uses **V-Bounce Engine** — a structured AI-agent development framework.
 
 ## What This Means for You
 
-You are operating in Tier 4 (Awareness) mode. You understand the project uses V-Bounce OS but you do not orchestrate agents.
+You are operating in Tier 4 (Awareness) mode. You understand the project uses V-Bounce Engine but you do not orchestrate agents.
 
 ## Key Behaviors
 

package/brains/cursor-rules/vbounce-docs.mdc

@@ -1,10 +1,10 @@
 ---
-description: V-Bounce OS document hierarchy — templates, locations, and report formats
+description: V-Bounce Engine document hierarchy — templates, locations, and report formats
 globs:
 alwaysApply: false
 ---
 
-# V-Bounce OS — Document & Report Reference
+# V-Bounce Engine — Document & Report Reference
 
 ## Document Locations
 

package/brains/cursor-rules/vbounce-process.mdc

@@ -1,12 +1,12 @@
 ---
-description: V-Bounce OS process rules — the core framework for AI-assisted software development
+description: V-Bounce Engine process rules — the core framework for AI-assisted software development
 globs:
 alwaysApply: true
 ---
 
-# V-Bounce OS — Process Rules
+# V-Bounce Engine — Process Rules
 
-You are an AI coding agent operating within **V-Bounce OS** — a structured system for planning, implementing, and validating software using AI agents.
+You are an AI coding agent operating within **V-Bounce Engine** — a structured system for planning, implementing, and validating software using AI agents.
 
 ## The V-Bounce Process
 

package/brains/cursor-rules/vbounce-rules.mdc

@@ -1,10 +1,10 @@
 ---
-description: V-Bounce OS critical rules — mandatory constraints for all implementation work
+description: V-Bounce Engine critical rules — mandatory constraints for all implementation work
 globs:
 alwaysApply: true
 ---
 
-# V-Bounce OS — Critical Rules
+# V-Bounce Engine — Critical Rules
 
 ## Before Writing Code
 1. **Read LESSONS.md** at the project root. Every time. No exceptions.

package/brains/windsurf/.windsurfrules

@@ -1,6 +1,6 @@
-# V-Bounce OS — Windsurf Rules
+# V-Bounce Engine — Windsurf Rules
 
-This project uses V-Bounce OS. You are operating in Tier 4 (Awareness) mode.
+This project uses V-Bounce Engine. You are operating in Tier 4 (Awareness) mode.
 
 ## Before Writing Code