@sandrinio/vbounce 1.2.0 → 1.3.0

package/README.md

@@ -48,7 +48,9 @@ npx @sandrinio/vbounce install codex
 ### What gets installed?
 - **Agent Instructions:** The "Brain" file (e.g., `CLAUDE.md`, `.cursor/rules/`) that teaches your AI how to follow the V-Bounce process.
 - **Templates:** Markdown templates for your Charter, Roadmap, Epics, and Stories.
-- **vdoc Integration:** Fully bundled with [`@sandrinio/vdoc`](https://github.com/sandrinio/vdoc) to automatically construct the `vdocs/` semantic documentation folder.
+- **Bundled Scripts:** Our validation pipeline (`validate_report.mjs`) and RAG synchronization engine (`pre_bounce_sync.sh`).
+- **Autonomous RAG Setup:** The installer automatically runs `npm install` for required libraries and initializes your local LanceDB knowledge base (`.bounce/.lancedb/`).
+- **vdoc Integration:** Fully compatible with [`@sandrinio/vdoc`](https://github.com/sandrinio/vdoc) to automatically construct semantic product documentation.
 
 ### 🧰 The Bundled Skills
 V-Bounce OS installs a powerful suite of specialized markdown `skills/` directly into your workspace. These act as modular capabilities you can invoke dynamically or that the Team Lead agent will invoke automatically during the SDLC process:

package/bin/vbounce.mjs

@@ -5,6 +5,8 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import readline from 'readline';
 
+import { execSync } from 'child_process';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const pkgRoot = path.join(__dirname, '..');
@@ -61,33 +63,39 @@ const platformMappings = {
     { src: 'brains/CLAUDE.md', dest: 'CLAUDE.md' },
     { src: 'brains/claude-agents', dest: '.claude/agents' },
     { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' }
+    { src: 'skills', dest: 'skills' },
+    { src: 'scripts', dest: 'scripts' }
   ],
   cursor: [
     { src: 'brains/cursor-rules', dest: '.cursor/rules' },
     { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' }
+    { src: 'skills', dest: 'skills' },
+    { src: 'scripts', dest: 'scripts' }
   ],
   gemini: [
     { src: 'brains/GEMINI.md', dest: 'GEMINI.md' },
     { src: 'templates', dest: 'templates' },
     { src: 'skills', dest: 'skills' },
-    { src: 'skills', dest: '.agents/skills' }
+    { src: 'skills', dest: '.agents/skills' },
+    { src: 'scripts', dest: 'scripts' }
   ],
   codex: [
     { src: 'brains/AGENTS.md', dest: 'AGENTS.md' },
     { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' }
+    { src: 'skills', dest: 'skills' },
+    { src: 'scripts', dest: 'scripts' }
   ],
   vscode: [
     { src: 'brains/CLAUDE.md', dest: '.github/copilot-instructions.md' },
     { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' }
+    { src: 'skills', dest: 'skills' },
+    { src: 'scripts', dest: 'scripts' }
   ],
   copilot: [
     { src: 'brains/CLAUDE.md', dest: '.github/copilot-instructions.md' },
     { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' }
+    { src: 'skills', dest: 'skills' },
+    { src: 'scripts', dest: 'scripts' }
   ]
 };
 
@@ -130,7 +138,7 @@ if (toOverwrite.length > 0) {
 
 console.log('');
 
-askQuestion('Proceed with installation? [y/N] ').then(answer => {
+askQuestion('Proceed with installation? [y/N] ').then(async answer => {
   rl.close();
   const confirmation = answer.trim().toLowerCase();
 
@@ -161,5 +169,32 @@ askQuestion('Proceed with installation? [y/N] ').then(answer => {
     console.log(`  \x1b[32m✓\x1b[0m ${rule.dest}`);
   });
 
+  console.log('\n⚙️  Installing RAG dependencies...');
+  try {
+    const deps = [
+      '@lancedb/lancedb',
+      '@xenova/transformers',
+      'js-yaml',
+      'marked',
+      'commander'
+    ];
+    console.log(`  Running: npm install ${deps.join(' ')}`);
+    execSync(`npm install ${deps.join(' ')}`, { stdio: 'inherit', cwd: CWD });
+    console.log('  \x1b[32m✓\x1b[0m Dependencies installed.');
+  } catch (err) {
+    console.error('  \x1b[31m✖\x1b[0m Failed to install dependencies. You may need to run it manually.');
+  }
+
+  console.log('\n🧠 Initializing RAG Knowledge Base...');
+  try {
+    const syncScript = path.join(CWD, 'scripts', 'pre_bounce_sync.sh');
+    if (fs.existsSync(syncScript)) {
+      execSync(`chmod +x "${syncScript}" && "${syncScript}"`, { stdio: 'inherit', cwd: CWD });
+      console.log('  \x1b[32m✓\x1b[0m Knowledge base initialized.');
+    }
+  } catch (err) {
+    console.error('  \x1b[31m✖\x1b[0m Failed to initialize knowledge base. Run ./scripts/pre_bounce_sync.sh manually.');
+  }
+
   console.log('\n✅ V-Bounce OS successfully installed! Welcome to the team.\n');
 });

package/brains/AGENTS.md

@@ -38,9 +38,10 @@ Before starting any sprint, the Team Lead MUST:
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4 Stories):**
+0. Team Lead runs `./scripts/pre_bounce_sync.sh` to ensure LanceDB RAG context is fresh.
 1. Team Lead sends Story context pack to Developer.
-2. Developer reads LESSONS.md, implements code, writes Implementation Report.
-3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev.
+2. Developer queries LanceDB, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
+3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report before passing to Architect/Dev.
 4. Dev fixes and resubmits. 3+ failures → Escalated.
 5. Architect runs Deep Audit + Trend Check, validates Safe Zone compliance and ADR adherence.
 6. DevOps merges story branch into sprint branch, validates post-merge, handles release tagging.
@@ -92,6 +93,8 @@ Bouncing → Escalated (3+ failures)
 9. Reports are the only handoff. No direct agent-to-agent communication.
 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` and trigger `./scripts/pre_bounce_sync.sh`.
 
 ## Framework Structure
 

package/brains/CHANGELOG.md

@@ -0,0 +1,7 @@
+# V-Bounce OS 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, the orchestrator MUST trigger `./scripts/pre_bounce_sync.sh` to update the RAG embeddings globally.
+
+## [2026-03-02]
+- **Initialized**: Created strict Framework Integrity tracking, YAML context handoffs, and RAG validation pipeline.

package/brains/CLAUDE.md

@@ -50,9 +50,10 @@ Before starting any sprint, the Team Lead MUST:
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4 Stories):**
+0. Team Lead runs `./scripts/pre_bounce_sync.sh` to ensure LanceDB RAG context is fresh.
 1. Team Lead sends Story context pack to Developer.
-2. Developer reads LESSONS.md, implements code, writes Implementation Report.
-3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev.
+2. Developer queries LanceDB, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
+3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report before passing to Architect/Dev.
 4. Dev fixes and resubmits. 3+ failures → Escalated.
 5. Architect runs Deep Audit + Trend Check, validates Safe Zone compliance and ADR adherence.
 6. DevOps merges story branch into sprint branch, validates post-merge, handles release tagging.
@@ -106,6 +107,8 @@ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architec
 9. **Reports are the only handoff**. No direct agent-to-agent communication.
 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` and trigger `./scripts/pre_bounce_sync.sh`.
 
 ## Framework Structure
 

package/brains/GEMINI.md

@@ -41,9 +41,10 @@ Before starting any sprint, the Team Lead MUST:
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4 Stories):**
+0. Team Lead runs `./scripts/pre_bounce_sync.sh` to ensure LanceDB RAG context is fresh.
 1. Team Lead sends Story context pack to Developer.
-2. Developer reads LESSONS.md, implements code, writes Implementation Report.
-3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev.
+2. Developer queries LanceDB, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
+3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report before passing to Architect/Dev.
 4. Dev fixes and resubmits. 3+ failures → Escalated.
 5. Architect runs Deep Audit + Trend Check, validates Safe Zone compliance and ADR adherence.
 6. DevOps merges story branch into sprint branch, validates post-merge, handles release tagging.
@@ -97,6 +98,8 @@ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architec
 9. **Reports are the only handoff**. No direct agent-to-agent communication.
 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` and trigger `./scripts/pre_bounce_sync.sh`.
 
 ## Framework Structure
 

package/brains/SETUP.md

@@ -5,6 +5,7 @@ Step-by-step guide to set up V-Bounce OS in an existing or new project.
 ## Prerequisites
 
 - A git repository (V-Bounce OS 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)
 
@@ -116,6 +117,17 @@ The agent will:
 4. Merge completed stories
 5. Generate a Sprint Report for your review
 
+## Step 7: Automated RAG Initialization
+
+V-Bounce OS uses LanceDB to provide agents with targeted context. While the `npx @sandrinio/vbounce install` command handles this automatically, you can manually re-trigger a sync if you add new architectural rules or change your brains:
+
+```bash
+# Re-build your local knowledge base
+./scripts/pre_bounce_sync.sh
+```
+
+This updates your local embeddings in `.bounce/.lancedb/`. Agents use `./scripts/vbounce_ask.mjs` to fetch rules on demand, ensuring they are always aligned with your latest Roadmap and Lessons.
+
 ## Folder Structure After Setup
 
 ```

package/brains/claude-agents/architect.md

@@ -14,7 +14,7 @@ Audit the codebase for structural integrity, standards compliance, and long-term
 
 ## Before Auditing
 
-1. **Read LESSONS.md** at the project root. Check for historical architectural decisions and past mistakes.
+1. **Query Project Lessons**: Run `./scripts/vbounce_ask.mjs "architectural constraints and historical mistakes for <story summary>"` to retrieve relevant context from `LESSONS.md` and past reports.
 2. **Read all reports** for this story (`.bounce/reports/STORY-{ID}-*.md`) — Dev Report, QA Report.
 3. **Read the full Story spec** — especially §3 Implementation Guide and §3.1 ADR References.
 4. **Read Roadmap §3 ADRs** — every architecture decision the implementation must comply with.
@@ -65,10 +65,18 @@ Check that the changes don't break existing functionality:
 
 ## Your Output
 
-Write an **Architectural Audit Report** to `.bounce/reports/STORY-{ID}-arch.md`:
+Write an **Architectural Audit Report** to `.bounce/reports/STORY-{ID}-arch.md`.
+You MUST include the YAML frontmatter block exactly as shown below:
 
 ### If Audit PASSES:
 ```markdown
+---
+status: "PASS"
+safe_zone_score: {SCORE}
+ai_isms_detected: {count}
+regression_risk: "{Low/Medium/High}"
+---
+
 # Architectural Audit Report: STORY-{ID} — PASS
 
 ## Safe Zone Compliance: {SCORE}/10
@@ -108,6 +116,12 @@ PASS — Ready for Sprint Review.
 
 ### If Audit FAILS:
 ```markdown
+---
+status: "FAIL"
+bounce_count: {N}
+critical_failures: {count}
+---
+
 # Architectural Audit Report: STORY-{ID} — FAIL
 
 ## Critical Failures

package/brains/claude-agents/developer.md

@@ -12,8 +12,9 @@ Implement features and fix bugs as specified in Story documents. You write code
 
 ## Before Writing ANY Code
 
-1. **Read LESSONS.md** at the project root. Treat every recorded rule as a hard constraint. No exceptions.
-2. **Read the Story spec** — §1 The Spec for requirements, §3 Implementation Guide for technical approach.
+1. **Query Project Lessons**: Run `./scripts/vbounce_ask.mjs "<summarize your specific coding task here>"` to retrieve relevant constraints and gotchas from `LESSONS.md` and historical reports. Treat these as hard constraints. No exceptions.
+2. **Query Architectural Decisions**: If your task involves core systems (auth, db, state), run `./scripts/vbounce_ask.mjs "<system> decisions"` to get relevant ADRs from the Roadmap.
+3. **Read the Story spec** — §1 The Spec for requirements, §3 Implementation Guide for technical approach.
 3. **Check ADR references** in §3.1 — comply with all architecture decisions from the Roadmap.
 4. **Read relevant react-best-practices rules** — consult `skills/react-best-practices/` for patterns matching your task.
 5. **Check product documentation** — if the task file references product docs from `product_documentation/`, read them. Understand how the existing feature works before changing adjacent code. If your implementation changes behavior described in a product doc, flag it in your report.
@@ -33,9 +34,18 @@ Do NOT proceed with a broken spec. Instead:
 
 ## Your Output
 
-Write a **Developer Implementation Report** to `.bounce/reports/STORY-{ID}-dev.md`:
+Write a **Developer Implementation Report** to `.bounce/reports/STORY-{ID}-dev.md`. 
+You MUST include the YAML frontmatter block exactly as shown below:
 
 ```markdown
+---
+status: "implemented"
+correction_tax: {X}
+files_modified:
+  - "path/to/file.ts"
+lessons_flagged: {number of lessons}
+---
+
 # Developer Implementation Report: STORY-{ID}
 
 ## Files Modified

package/brains/claude-agents/devops.md

@@ -146,10 +146,17 @@ Before approving a deployment:
 
 ## Your Output
 
-Write a **DevOps Report** to `.bounce/reports/STORY-{ID}-devops.md` (for story merges) or `.bounce/reports/sprint-S-{XX}-devops.md` (for sprint releases):
+Write a **DevOps Report** to `.bounce/reports/STORY-{ID}-devops.md` (for story merges) or `.bounce/reports/sprint-S-{XX}-devops.md` (for sprint releases).
+You MUST include the YAML frontmatter block exactly as shown below:
 
 ### Story Merge Report
 ```markdown
+---
+type: "story-merge"
+status: "{Clean / Conflicts Resolved / Failed}"
+conflicts_detected: {true/false}
+---
+
 # DevOps Report: STORY-{ID} Merge
 
 ## Pre-Merge Checks
@@ -178,6 +185,12 @@ Write a **DevOps Report** to `.bounce/reports/STORY-{ID}-devops.md` (for story m
 
 ### Sprint Release Report
 ```markdown
+---
+type: "sprint-release"
+status: "{Deployed / Pending / Manual}"
+version: "{VERSION}"
+---
+
 # DevOps Report: Sprint S-{XX} Release
 
 ## Pre-Release Checks

package/brains/claude-agents/qa.md

@@ -12,7 +12,7 @@ Validate that the Developer's implementation meets the Story's acceptance criter
 
 ## Before Testing
 
-1. **Read LESSONS.md** at the project root. Check for known failure patterns relevant to this story.
+1. **Query Project Lessons**: Run `./scripts/vbounce_ask.mjs "<summarize the story spec here>"` to retrieve known failure patterns relevant to this story from `LESSONS.md` and past reports.
 2. **Read the Developer Implementation Report** (`.bounce/reports/STORY-{ID}-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.
 
@@ -58,10 +58,18 @@ Check for unnecessary complexity the Developer added beyond the Story spec:
 
 ## Your Output
 
-Write a **QA Validation Report** to `.bounce/reports/STORY-{ID}-qa.md`:
+Write a **QA Validation Report** to `.bounce/reports/STORY-{ID}-qa.md`.
+You MUST include the YAML frontmatter block exactly as shown below:
 
 ### If Tests PASS:
 ```markdown
+---
+status: "PASS"
+bounce_count: {N}
+bugs_found: 0
+gold_plating_detected: false
+---
+
 # QA Validation Report: STORY-{ID} — PASS
 
 ## Quick Scan Results
@@ -98,6 +106,15 @@ PASS — Ready for Architect review.
 
 ### If Tests FAIL:
 ```markdown
+---
+status: "FAIL"
+bounce_count: {N}
+bugs_found: {number of bugs}
+gold_plating_detected: {true/false}
+failed_scenarios:
+  - "{scenario name}"
+---
+
 # QA Validation Report: STORY-{ID} — FAIL (Bounce {N})
 
 ## Failures

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrinio/vbounce",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "V-Bounce OS: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
   "type": "module",
   "bin": {
@@ -38,5 +38,12 @@
     "skills",
     "scripts",
     "docs"
-  ]
-}
+  ],
+  "dependencies": {
+    "@lancedb/lancedb": "^0.26.2",
+    "@xenova/transformers": "^2.17.2",
+    "commander": "^14.0.3",
+    "js-yaml": "^4.1.1",
+    "marked": "^17.0.3"
+  }
+}

package/scripts/pre_bounce_sync.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+# pre_bounce_sync.sh
+# 
+# Run this before kicking off the Implementation Loop (Bounce).
+# This prevents the "Stale Context" edge case by forcing the LanceDB
+# index to refresh with the latest rules from LESSONS.md and ROADMAP.md.
+
+echo "==========================================="
+echo " V-Bounce OS: Pre-Bounce Sync Started"
+echo "==========================================="
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
+ROOT_DIR="$(dirname "$SCRIPT_DIR")"
+
+cd "$ROOT_DIR" || exit 1
+
+# 1. Check for Node Modules
+if [ ! -d "node_modules" ]; then
+    echo "Error: node_modules not found. Run 'npm install'."
+    exit 1
+fi
+
+# 2. Rebuild the semantic search index
+echo "Syncing V-Bounce Knowledge Base (LanceDB)..."
+node ./scripts/vbounce_index.mjs --all
+
+if [ $? -ne 0 ]; then
+    echo "Error: LanceDB index sync failed."
+    exit 1
+fi
+
+echo "==========================================="
+echo " Pre-Bounce Sync Complete. RAG is fresh."
+echo " Ready for Team Lead delegation."
+echo "==========================================="
+exit 0

package/scripts/validate_report.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * validate_report.mjs
+ * 
+ * Strict YAML Frontmatter validation for V-Bounce OS Agent Reports.
+ * Fails loudly if an agent hallucinates formatting or omits required fields,
+ * so the orchestrator can bounce the prompt back.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+// Defined schemas for each report type
+const SCHEMAS = {
+    dev: ['status', 'correction_tax', 'files_modified', 'lessons_flagged'],
+    qa: {
+        base: ['status', 'bounce_count', 'bugs_found', 'gold_plating_detected'],
+        conditional: { 'FAIL': ['failed_scenarios'] }
+    },
+    arch: {
+        base: ['status'],
+        conditional: { 'PASS': ['safe_zone_score', 'ai_isms_detected', 'regression_risk'], 'FAIL': ['bounce_count', 'critical_failures'] }
+    },
+    devops: {
+        base: ['type', 'status'],
+        conditional: { 'story-merge': ['conflicts_detected'], 'sprint-release': ['version'] }
+    }
+};
+
+function extractFrontmatter(content) {
+    // Matches "---" at the start of the file or after whitespace
+    const match = content.match(/^---\s*[\r\n]+([\s\S]*?)[\r\n]+---\s*/);
+    if (!match) {
+        throw new Error('NO_FRONTMATTER: Report missing strict YAML --- delimiters at the top of the file.');
+    }
+    return match[1];
+}
+
+function validateDev(data) {
+    const missing = SCHEMAS.dev.filter(k => !(k in data));
+    if (missing.length > 0) throw new Error(`DEV_SCHEMA_ERROR: Missing required keys: ${missing.join(', ')}`);
+    if (!Array.isArray(data.files_modified)) throw new Error(`DEV_SCHEMA_ERROR: 'files_modified' must be an array.`);
+}
+
+function validateQA(data) {
+    const missing = SCHEMAS.qa.base.filter(k => !(k in data));
+    if (missing.length > 0) throw new Error(`QA_SCHEMA_ERROR: Missing required keys: ${missing.join(', ')}`);
+
+    if (data.status === 'FAIL') {
+        const conditionalMissing = SCHEMAS.qa.conditional.FAIL.filter(k => !(k in data));
+        if (conditionalMissing.length > 0) throw new Error(`QA_SCHEMA_ERROR: 'FAIL' status requires keys: ${conditionalMissing.join(', ')}`);
+    }
+}
+
+function validateArch(data) {
+    const missing = SCHEMAS.arch.base.filter(k => !(k in data));
+    if (missing.length > 0) throw new Error(`ARCH_SCHEMA_ERROR: Missing required keys: ${missing.join(', ')}`);
+
+    const s = data.status === 'PASS' ? 'PASS' : 'FAIL';
+    const conditionalMissing = SCHEMAS.arch.conditional[s].filter(k => !(k in data));
+    if (conditionalMissing.length > 0) throw new Error(`ARCH_SCHEMA_ERROR: '${s}' status requires keys: ${conditionalMissing.join(', ')}`);
+}
+
+function validateDevops(data) {
+    const missing = SCHEMAS.devops.base.filter(k => !(k in data));
+    if (missing.length > 0) throw new Error(`DEVOPS_SCHEMA_ERROR: Missing required keys: ${missing.join(', ')}`);
+
+    const typeStr = String(data.type);
+    if (SCHEMAS.devops.conditional[typeStr]) {
+        const conditionalMissing = SCHEMAS.devops.conditional[typeStr].filter(k => !(k in data));
+        if (conditionalMissing.length > 0) throw new Error(`DEVOPS_SCHEMA_ERROR: '${typeStr}' type requires keys: ${conditionalMissing.join(', ')}`);
+    }
+}
+
+function main() {
+    const filePath = process.argv[2];
+    if (!filePath) {
+        console.error("Usage: validate_report.mjs <path-to-markdown-file>");
+        process.exit(1);
+    }
+
+    const filename = path.basename(filePath);
+
+    // Infer agent type from filename convention
+    let agentType = 'unknown';
+    if (filename.endsWith('-dev.md')) agentType = 'dev';
+    else if (filename.endsWith('-qa.md')) agentType = 'qa';
+    else if (filename.endsWith('-arch.md')) agentType = 'arch';
+    else if (filename.endsWith('-devops.md')) agentType = 'devops';
+
+    if (agentType === 'unknown') {
+        console.error(`WARNING: Unrecognized report type for ${filename}. Ensure filename ends in -dev.md, -qa.md, -arch.md, or -devops.md.`);
+        process.exit(0); // Soft pass, not an agent workflow report
+    }
+
+    try {
+        const rawContent = fs.readFileSync(filePath, 'utf8');
+        const yamlString = extractFrontmatter(rawContent);
+        const data = yaml.load(yamlString);
+
+        if (!data || typeof data !== 'object') {
+            throw new Error("YAML_PARSE_ERROR: Frontmatter parsed to an empty or invalid object.");
+        }
+
+        if (agentType === 'dev') validateDev(data);
+        if (agentType === 'qa') validateQA(data);
+        if (agentType === 'arch') validateArch(data);
+        if (agentType === 'devops') validateDevops(data);
+
+        console.log(`VALID: ${filename} matches the ${agentType.toUpperCase()} schema.`);
+        process.exit(0);
+
+    } catch (error) {
+        // We print specifically to stdout so automation scripts can capture the payload and bounce it back to the AI
+        console.log(`VALIDATION_FAILED\n${error.message}`);
+        process.exit(1);
+    }
+}
+
+main();

package/scripts/vbounce_ask.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { connect } from '@lancedb/lancedb';
+import { pipeline } from '@xenova/transformers';
+import { program } from 'commander';
+
+const LANCE_DIR = path.join(process.cwd(), '.bounce', '.lancedb');
+
+program
+    .name('vbounce_ask')
+    .description('Query V-Bounce OS LanceDB for relevant context')
+    .argument('<query>', 'The semantic query to search for')
+    .option('-f, --filter <field=value>', 'Filter by metadata (e.g., type=lesson)')
+    .option('-l, --limit <number>', 'Number of results to return', 3)
+    .parse(process.argv);
+
+const options = program.opts();
+const query = program.args[0];
+
+class LocalEmbeddingFunction {
+    constructor() {
+        this.modelName = 'Xenova/all-MiniLM-L6-v2';
+        this.extractor = null;
+    }
+
+    async init() {
+        if (!this.extractor) {
+            this.extractor = await pipeline('feature-extraction', this.modelName, {
+                quantized: true,
+            });
+        }
+    }
+
+    async embedQuery(text) {
+        await this.init();
+        const output = await this.extractor(text, { pooling: 'mean', normalize: true });
+        return Array.from(output.data);
+    }
+}
+
+async function main() {
+    if (!query) {
+        console.error("Error: Must provide a semantic query string.");
+        process.exit(1);
+    }
+
+    if (!fs.existsSync(LANCE_DIR)) {
+        console.error(`Error: LanceDB not found at ${LANCE_DIR}. Have you run vbounce_index yet?`);
+        process.exit(1);
+    }
+
+    const db = await connect(LANCE_DIR);
+    let table;
+    try {
+        table = await db.openTable('vbounce_context');
+    } catch (e) {
+        console.error("Error: Table 'vbounce_context' not found. Please index documents first.");
+        process.exit(1);
+    }
+
+    const embedder = new LocalEmbeddingFunction();
+    const queryVector = await embedder.embedQuery(query);
+
+    let search = table.vectorSearch(queryVector).limit(parseInt(options.limit));
+
+    if (options.filter) {
+        const [field, value] = options.filter.split('=');
+        // LanceDB JS uses SQL-like string criteria for filtering
+        if (field === "type") {
+            search = search.where(`\`type\` = '${value}'`);
+        } else if (field === "section") {
+            search = search.where(`\`section\` = '${value}'`);
+        }
+    }
+
+    const results = await search.toArray();
+
+    if (results.length === 0) {
+        console.log("No relevant context found.");
+        return;
+    }
+
+    console.log(`\n--- V-Bounce Semantic Retrieval ---`);
+    console.log(`Query: "${query}"`);
+    console.log(`Found ${results.length} relevant chunks.\n`);
+
+    results.forEach((r, idx) => {
+        console.log(`[Result ${idx + 1}] Source: ${r.file} (${r.type || 'unknown'} > ${r.section || 'General'})`);
+        console.log(`Distance: ${r._distance ? r._distance.toFixed(4) : 'N/A'}`);
+        console.log('-'.repeat(40));
+        console.log(r.text.trim());
+        console.log('\n');
+    });
+}
+
+main().catch(console.error);

package/scripts/vbounce_index.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { connect } from '@lancedb/lancedb';
+import { pipeline } from '@xenova/transformers';
+import { marked } from 'marked';
+import { program } from 'commander';
+
+const LANCE_DIR = path.join(process.cwd(), '.bounce', '.lancedb');
+
+program
+    .name('vbounce_index')
+    .description('Index V-Bounce OS documents into local LanceDB')
+    .argument('[path]', 'File or directory path to index (or use --all)')
+    .option('--all', 'Index all standard V-Bounce directories')
+    .parse(process.argv);
+
+const options = program.opts();
+const targetPath = program.args[0];
+
+// Initialize local embedding model wrapper
+class LocalEmbeddingFunction {
+    constructor() {
+        this.modelName = 'Xenova/all-MiniLM-L6-v2';
+        this.extractor = null;
+    }
+
+    async init() {
+        if (!this.extractor) {
+            console.log(`Loading embedding model (${this.modelName})...`);
+            this.extractor = await pipeline('feature-extraction', this.modelName, {
+                quantized: true,
+            });
+        }
+    }
+
+    async computeSourceEmbeddings(texts) {
+        await this.init();
+        const embeddings = [];
+        for (const text of texts) {
+            const output = await this.extractor(text, { pooling: 'mean', normalize: true });
+            embeddings.push(Array.from(output.data));
+        }
+        return embeddings;
+    }
+}
+
+// Function to chunk Markdown files semantically (simplified for MVP)
+function chunkMarkdown(content, metadata) {
+    const tokens = marked.lexer(content);
+    const chunks = [];
+    let currentHeader = 'General';
+    let buffer = '';
+
+    for (const token of tokens) {
+        if (token.type === 'heading') {
+            if (buffer.trim()) {
+                chunks.push({ text: buffer.trim(), section: currentHeader, ...metadata });
+            }
+            currentHeader = token.text;
+            buffer = `${token.raw}\n`;
+        } else {
+            buffer += `${token.raw}\n`;
+        }
+    }
+
+    if (buffer.trim()) {
+        chunks.push({ text: buffer.trim(), section: currentHeader, ...metadata });
+    }
+
+    return chunks;
+}
+
+async function indexFile(filePath, embedder) {
+    console.log(`Processing file: ${filePath}`);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const basename = path.basename(filePath);
+
+    let type = 'unknown';
+    if (filePath.includes('LESSONS.md')) type = 'lesson';
+    else if (filePath.includes('ROADMAP.md')) type = 'adr';
+    else if (filePath.includes('.bounce/reports')) type = 'report';
+    else if (filePath.includes('product_plans')) type = 'plan';
+    else if (filePath.includes('product_documentation')) type = 'documentation';
+
+    const metadata = { file: basename, type };
+    const chunks = chunkMarkdown(content, metadata);
+
+    if (chunks.length === 0) return [];
+
+    console.log(`  Extracted ${chunks.length} chunks. Generating embeddings...`);
+
+    const textsToEmbed = chunks.map(c => `[${c.type} - ${c.file} - ${c.section}]\n${c.text}`);
+    const vectors = await embedder.computeSourceEmbeddings(textsToEmbed);
+
+    return chunks.map((chunk, i) => ({
+        id: `${chunk.file}-${i}`,
+        file: chunk.file,
+        type: chunk.type,
+        section: chunk.section,
+        text: chunk.text,
+        vector: vectors[i]
+    }));
+}
+
+async function main() {
+    if (!targetPath && !options.all) {
+        console.error("Error: Must specify a path or use --all");
+        process.exit(1);
+    }
+
+    const embedder = new LocalEmbeddingFunction();
+
+    // Ensure table exists
+    if (!fs.existsSync(LANCE_DIR)) {
+        fs.mkdirSync(LANCE_DIR, { recursive: true });
+    }
+
+    const db = await connect(LANCE_DIR);
+    let table;
+
+    try {
+        table = await db.openTable('vbounce_context');
+    } catch (e) {
+        // Table doesn't exist, will create dynamically on first insert
+        console.log("Creating new vbounce_context table...");
+    }
+
+    const filesToIndex = [];
+
+    function walkDir(dir) {
+        if (!fs.existsSync(dir)) return;
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+            const fullPath = path.join(dir, file);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                walkDir(fullPath);
+            } else if (fullPath.endsWith('.md')) {
+                filesToIndex.push(fullPath);
+            }
+        }
+    }
+
+    if (options.all) {
+        if (fs.existsSync('LESSONS.md')) filesToIndex.push('LESSONS.md');
+        if (fs.existsSync('ROADMAP.md')) filesToIndex.push('ROADMAP.md');
+        walkDir('product_plans');
+        walkDir('product_documentation');
+        walkDir('.bounce/reports');
+    } else if (targetPath) {
+        const stat = fs.statSync(targetPath);
+        if (stat.isFile()) {
+            filesToIndex.push(targetPath);
+        } else if (stat.isDirectory()) {
+            walkDir(targetPath);
+        }
+    }
+
+    if (filesToIndex.length === 0) {
+        console.log("No files found to index.");
+        process.exit(0);
+    }
+
+    let allRecords = [];
+    for (const file of filesToIndex) {
+        const records = await indexFile(file, embedder);
+        allRecords = allRecords.concat(records);
+    }
+
+    if (allRecords.length > 0) {
+        if (table) {
+            console.log(`Adding ${allRecords.length} records to existing table...`);
+            await table.add(allRecords);
+        } else {
+            console.log(`Creating table with ${allRecords.length} records...`);
+            table = await db.createTable('vbounce_context', allRecords);
+        }
+        console.log(`Successfully indexed into LanceDB.`);
+    }
+}
+
+main().catch(console.error);

package/scripts/verify_framework.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * verify_framework.mjs
+ * 
+ * Tests the backward-compatibility of the AI agent prompts against
+ * the strict YAML parsing schemas in validate_report.mjs.
+ * 
+ * Triggered manually by humans or automatically by CI when updating brains/.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const AGENTS_DIR = path.join(process.cwd(), 'brains', 'claude-agents');
+
+// The exact substring signatures that MUST exist in the agent instructions
+// to ensure the LLM knows to output the correct YAML schema.
+const EXPECTED_PROMPT_SIGNATURES = {
+    'developer.md': [
+        'status:',
+        'correction_tax:',
+        'files_modified:',
+        'lessons_flagged:'
+    ],
+    'qa.md': [
+        'status: "PASS"',
+        'bugs_found: 0',
+        'status: "FAIL"',
+        'failed_scenarios:'
+    ],
+    'architect.md': [
+        'status: "PASS"',
+        'safe_zone_score:',
+        'regression_risk:',
+        'status: "FAIL"',
+        'critical_failures:'
+    ],
+    'devops.md': [
+        'type: "story-merge"',
+        'conflicts_detected:',
+        'type: "sprint-release"',
+        'version:'
+    ]
+};
+
+function main() {
+    console.log("===========================================");
+    console.log(" V-Bounce OS: Framework Integrity Check");
+    console.log("===========================================\n");
+
+    let hasErrors = false;
+
+    if (!fs.existsSync(AGENTS_DIR)) {
+        console.error(`ERROR: ${AGENTS_DIR} not found.`);
+        process.exit(1);
+    }
+
+    const files = fs.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.md'));
+
+    for (const file of files) {
+        const filePath = path.join(AGENTS_DIR, file);
+        const content = fs.readFileSync(filePath, 'utf-8');
+
+        const requiredSignatures = EXPECTED_PROMPT_SIGNATURES[file];
+        if (!requiredSignatures) {
+            console.log(`[PASS] ${file} (No strict YAML signatures required)`);
+            continue;
+        }
+
+        let filePassed = true;
+        for (const sig of requiredSignatures) {
+            if (!content.includes(sig)) {
+                console.error(`[FAIL] ${file} is missing required YAML instruction key: '${sig}'`);
+                filePassed = false;
+                hasErrors = true;
+            }
+        }
+
+        // Check for general Rule 12 presence
+        if (!content.includes('YAML frontmatter') && !content.includes('YAML Frontmatter')) {
+            console.error(`[FAIL] ${file} appears to be missing the Rule 12 YAML Frontmatter instruction.`);
+            filePassed = false;
+            hasErrors = true;
+        }
+
+        if (filePassed) {
+            console.log(`[PASS] ${file} contains all required YAML extraction signatures.`);
+        }
+    }
+
+    console.log("\n-------------------------------------------");
+    if (hasErrors) {
+        console.error("❌ INTEGRITY CHECK FAILED.");
+        console.error("Agent prompts have drifted from the validate_report.mjs schema.");
+        console.error("Please fix the agent templates in brains/claude-agents/ to restore pipeline integrity.");
+        process.exit(1);
+    } else {
+        console.log("✅ INTEGRITY CHECK PASSED.");
+        console.log("All agent prompts strictly map to the required pipeline metadata schemas.");
+        process.exit(0);
+    }
+}
+
+main();

package/scripts/verify_framework.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+# verify_framework.sh
+# 
+# Wrapper script to execute the Framework Integrity Check.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
+ROOT_DIR="$(dirname "$SCRIPT_DIR")"
+
+cd "$ROOT_DIR" || exit 1
+
+node ./scripts/verify_framework.mjs
+exit $?

package/templates/hotfix.md

@@ -56,4 +56,5 @@ Do NOT output these instructions.
 
 - [ ] {Simple step, e.g., "Open the settings modal and verify the button is aligned."}
 - [ ] Automated tests still pass (`npm test`).
+- [ ] **Framework Integrity**: If `brains/` or `skills/` were modified, log to `brains/CHANGELOG.md` and run `./scripts/pre_bounce_sync.sh`.
 - [ ] **Post-Fix Action**: Run `./scripts/hotfix_manager.sh ledger "HOTFIX: {Name}" "{Brief Fix Description}"`

package/templates/story.md

@@ -148,3 +148,4 @@ POST /api/resource
 - [ ] LESSONS.md consulted before implementation.
 - [ ] No violations of Roadmap ADRs.
 - [ ] Documentation (API/Tech Stack) updated.
+- [ ] **Framework Integrity**: If `brains/` or `skills/` were modified, log to `brains/CHANGELOG.md` and run `./scripts/pre_bounce_sync.sh`.