@sandrinio/vbounce 1.0.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
@@ -130,6 +144,24 @@ When the Team Lead asks for a **Sprint Integration Audit** (after all stories pa
 - Check for emergent coupling that wasn't visible in individual story reviews
 - Write the integration audit to `.bounce/reports/sprint-integration-audit.md`
 
+## Checkpointing
+
+After completing each major phase of your audit (e.g., Deep Audit done, Trend Check done, ADR compliance checked), write a progress checkpoint to `.bounce/reports/STORY-{ID}-arch-checkpoint.md`:
+
+```markdown
+# Architect Checkpoint: STORY-{ID}
+## Completed
+- {Which audit phases are done}
+## Remaining
+- {Which phases are left}
+## Preliminary Findings
+- {Key issues or observations so far}
+## Current Verdict
+- {Leaning PASS/FAIL and why}
+```
+
+This enables recovery if your session is interrupted. A re-spawned Architect agent reads the checkpoint to continue without re-running completed audit phases. Overwrite the checkpoint file each time — only the latest state matters.
+
 ## Critical Rules
 
 - You NEVER fix code. You only report what needs fixing.

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
@@ -61,6 +71,24 @@ Write a **Developer Implementation Report** to `.bounce/reports/STORY-{ID}-dev.m
 - [ ] No new patterns or libraries introduced
 ```
 
+## Checkpointing
+
+After completing each major phase of your work (e.g., initial implementation done, tests written, bug fixes applied), write a progress checkpoint to `.bounce/reports/STORY-{ID}-dev-checkpoint.md`:
+
+```markdown
+# Developer Checkpoint: STORY-{ID}
+## Completed
+- {What's done so far}
+## Remaining
+- {What's left to do}
+## Key Decisions
+- {Important choices made during implementation}
+## Files Modified
+- {List of files changed so far}
+```
+
+This enables recovery if your session is interrupted. A re-spawned Developer agent reads the checkpoint to continue without restarting from scratch. Overwrite the checkpoint file each time — only the latest state matters.
+
 ## Critical Rules
 
 - You NEVER communicate with QA or Architect directly. Your report is your only output.

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.
 
@@ -41,6 +41,14 @@ Run Story §2.1 Gherkin scenarios against the implementation:
 - Each scenario is a binary pass/fail
 - Document exact failure conditions (input, expected, actual)
 
+### Spec Fidelity Check
+After running scenarios, verify:
+- Test count matches the number of Gherkin scenarios in §2 (not fewer, not more)
+- Fixture data matches spec examples (if spec says "5 items", test uses 5 items)
+- API contracts match §3 exactly (methods, parameters, return types)
+
+If there's a mismatch, flag it — even if the tests pass. Passing tests with wrong fixture counts means the tests aren't validating what the spec intended.
+
 ### Gold-Plating Audit
 Check for unnecessary complexity the Developer added beyond the Story spec:
 - Features not in the requirements
@@ -50,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
@@ -74,12 +90,31 @@ Write a **QA Validation Report** to `.bounce/reports/STORY-{ID}-qa.md`:
 ## Gold-Plating Audit
 - {Findings or "No gold-plating detected"}
 
+## Scrutiny Log
+- **Hardest scenario tested**: {Which scenario was closest to failing and why}
+- **Boundary probed**: {What edge case did you push hardest on}
+- **Observation**: {Anything that passed but felt fragile — worth watching in future sprints}
+
+## Spec Fidelity
+- Test count matches Gherkin scenarios: {Yes/No — if No, list discrepancies}
+- Fixture data matches spec examples: {Yes/No}
+- API contracts match §3: {Yes/No}
+
 ## Recommendation
 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
@@ -103,6 +138,24 @@ Every finding must include a non-coder analogy. Examples:
 - "High coupling" → "Pulling one wire takes down the whole electrical system"
 - "Duplication" → "Three departments each built their own payroll system"
 
+## Checkpointing
+
+After completing each major phase of your testing (e.g., Quick Scan done, PR Review done, scenarios validated), write a progress checkpoint to `.bounce/reports/STORY-{ID}-qa-checkpoint.md`:
+
+```markdown
+# QA Checkpoint: STORY-{ID}
+## Completed
+- {Which testing phases are done}
+## Remaining
+- {Which phases are left}
+## Preliminary Findings
+- {Issues found so far, scenarios passed/failed}
+## Current Verdict
+- {Leaning PASS/FAIL and why}
+```
+
+This enables recovery if your session is interrupted. A re-spawned QA agent reads the checkpoint to continue without re-running completed test phases. Overwrite the checkpoint file each time — only the latest state matters.
+
 ## Critical Rules
 
 - You NEVER fix code. You only report what's broken.

package/docs/HOTFIX_EDGE_CASES.md

@@ -0,0 +1,37 @@
+# Hotfix Workflow: Edge Cases & Mitigations
+
+This document outlines the critical edge cases, failure modes, and required mitigations for the **V-Bounce OS Hotfix (L1 Trivial)** workflow.
+
+---
+
+## 1. Scope Creep (The "Just one more file" Fallacy)
+
+*   **The Edge Case**: A request triaged as a Hotfix (e.g., "Fix button color") turns out to be more complex (e.g., the component is shared across 5 views, requires updating global CSS variables, and affects existing tests).
+*   **The Mitigation**: 
+    *   **Mitigation — Developer Hard-Stop**: The Developer agent must stop if a fix requires touching >2 files or introduces new logic patterns.
+*   **Mitigation — Escalation to Human**: The Team Lead must escalate the issue back to the Human, providing suggestions and recommendations on how to proceed (e.g., converting to a standard Epic/Story).
+
+## 2. The "Silent Regression" (Bypassing QA)
+
+*   **The Edge Case**: Bypassing the QA and Architect agents allows a "quick fix" to inadvertently break a downstream component that a human might miss during manual verification.
+*   **The Mitigation**:
+    *   **Mitigation — Automated Validation**: Mandate in `hotfix.md` that the Developer must run localized tests (`npm test`) before submission.
+*   **Mitigation — Manual Human Testing**: Because the hotfix bypasses the QA agent, the Human MUST test the fix manually. This includes verifying surrounding features and the overall context, not just the isolated fix.
+
+## 3. Architectural Drift (The "Death by a Thousand Papercuts")
+
+*   **The Edge Case**: A series of un-audited hotfixes introduces minor anti-patterns (e.g., inline styles instead of Tailwind classes), degrading codebase integrity over time.
+*   **The Mitigation**:
+    *   **Mitigation — Scripted Trend Check (`hotfix-manager audit`)**: To save tokens, an automated bash script runs static analysis (grepping for inline styles, `console.log`, and bypasses) on Hotfix commits before Sprint Integration, raising flags only if anti-patterns are detected.
+
+## 4. Merge Conflicts with Active Worktrees
+
+*   **The Edge Case**: A hotfix merged directly to the `sprint` branch causes a collision when other agents try to merge their isolated `.worktrees/`.
+*   **The Mitigation**:
+    *   **Mitigation — Scripted Worktree Sync (`hotfix-manager sync`)**: After a Hotfix merge, a script safely detects all active `.worktrees/` and runs a `git pull --rebase` to ensure parallel agents are building on the latest code.
+
+## 5. Invisible Deliverables (The Ghost Fix)
+
+*   **The Edge Case**: Hotfixes bypass the `DELIVERY_PLAN.md`, so they are excluded from the Sprint Report and user-facing documentation.
+*   **The Mitigation**:
+    *   **Mitigation — Scripted Ledger (`hotfix-manager ledger`)**: An automated script appends a new row (Title and Brief Description) to the **"§8 Applied Hotfixes"** table in the `DELIVERY_PLAN.md` specifically for Scribe integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrinio/vbounce",
-  "version": "1.0.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": {
@@ -35,6 +35,15 @@
     "bin",
     "brains",
     "templates",
-    "skills"
-  ]
-}
+    "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"
+  }
+}