@sandrinio/vbounce 1.7.0 → 1.9.0

package/docs/HOTFIX_EDGE_CASES.md

@@ -1,6 +1,6 @@
 # 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.
+This document outlines the critical edge cases, failure modes, and required mitigations for the **V-Bounce Engine Hotfix (L1 Trivial)** workflow.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sandrinio/vbounce",
-  "version": "1.7.0",
-  "description": "V-Bounce OS: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
+  "version": "1.9.0",
+  "description": "V-Bounce Engine: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
   "type": "module",
   "bin": {
     "vbounce": "./bin/vbounce.mjs"
@@ -11,7 +11,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sandrinio/v-bounce-os.git"
+    "url": "git+https://github.com/sandrinio/v-bounce-engine.git"
   },
   "keywords": [
     "ai",
@@ -28,9 +28,9 @@
   "author": "sandrinio",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/sandrinio/v-bounce-os/issues"
+    "url": "https://github.com/sandrinio/v-bounce-engine/issues"
   },
-  "homepage": "https://github.com/sandrinio/v-bounce-os#readme",
+  "homepage": "https://github.com/sandrinio/v-bounce-engine#readme",
   "files": [
     "bin",
     "brains",

package/scripts/doctor.mjs

@@ -2,7 +2,7 @@
 
 /**
  * doctor.mjs
- * V-Bounce OS Health Check — validates all configs, templates, state files
+ * V-Bounce Engine Health Check — validates all configs, templates, state files
  * Usage: vbounce doctor
  */
 
@@ -42,7 +42,7 @@ const templatesDir = path.join(ROOT, 'templates');
 let templateCount = 0;
 for (const t of requiredTemplates) {
   if (fs.existsSync(path.join(templatesDir, t))) templateCount++;
-  else fail(`templates/${t} missing`, `Create from V-Bounce OS template`);
+  else fail(`templates/${t} missing`, `Create from V-Bounce Engine template`);
 }
 if (templateCount === requiredTemplates.length) pass(`templates/ complete (${templateCount}/${requiredTemplates.length})`);
 
@@ -130,7 +130,7 @@ if (fs.existsSync(path.join(ROOT, 'vbounce.config.json'))) {
 }
 
 // Print results
-console.log('\nV-Bounce OS Health Check');
+console.log('\nV-Bounce Engine Health Check');
 console.log('========================');
 checks.forEach(c => console.log(c));
 console.log('');

package/scripts/hotfix_manager.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# V-Bounce OS: Hotfix Manager
+# V-Bounce Engine: Hotfix Manager
 # Handles edge cases for L1 Trivial tasks to save tokens and ensure framework integrity.
 
 set -euo pipefail
@@ -14,7 +14,7 @@ REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
 COMMAND="${1:-}"
 
 function show_help {
-    echo "V-Bounce OS — Hotfix Manager"
+    echo "V-Bounce Engine — Hotfix Manager"
     echo ""
     echo "Usage: ./scripts/hotfix_manager.sh <command> [args]"
     echo ""

package/scripts/init_gate_config.sh

@@ -17,7 +17,7 @@ YELLOW='\033[1;33m'
 CYAN='\033[0;36m'
 NC='\033[0m'
 
-echo -e "${CYAN}V-Bounce OS Gate Config Initializer${NC}"
+echo -e "${CYAN}V-Bounce Engine Gate Config Initializer${NC}"
 echo -e "Project: ${PROJECT_PATH}"
 echo ""
 

package/scripts/pre_gate_common.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# pre_gate_common.sh — Shared gate check functions for V-Bounce OS
+# pre_gate_common.sh — Shared gate check functions for V-Bounce Engine
 # Sourced by pre_gate_runner.sh. Never run directly.
 
 set -euo pipefail

package/scripts/pre_gate_runner.sh

@@ -31,7 +31,7 @@ fi
 # Resolve to absolute path
 WORKTREE_PATH="$(cd "$WORKTREE_PATH" && pwd)"
 
-echo -e "${CYAN}V-Bounce OS Pre-Gate Scanner${NC}"
+echo -e "${CYAN}V-Bounce Engine Pre-Gate Scanner${NC}"
 echo -e "Gate: ${YELLOW}${GATE_TYPE}${NC}"
 echo -e "Target: ${WORKTREE_PATH}"
 echo ""

package/scripts/prep_qa_context.mjs

@@ -13,6 +13,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
 import yaml from 'js-yaml';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -96,7 +97,23 @@ const filesModified = Array.isArray(devFm.files_modified)
   ? devFm.files_modified.map(f => `- ${f}`).join('\n')
   : '_Not specified in dev report_';
 
-// 5. Assemble context pack
+// 5. vdoc context (optional — graceful skip if no manifest)
+let vdocSection = '';
+const vdocMatchScript = path.join(__dirname, 'vdoc_match.mjs');
+if (fs.existsSync(vdocMatchScript) && fs.existsSync(path.join(ROOT, 'vdocs', '_manifest.json'))) {
+  try {
+    const modifiedFiles = Array.isArray(devFm.files_modified) ? devFm.files_modified.join(',') : '';
+    const vdocArgs = [`--story`, storyId];
+    if (modifiedFiles) vdocArgs.push('--files', modifiedFiles);
+    vdocArgs.push('--context');
+    const vdocOutput = execSync(`node "${vdocMatchScript}" ${vdocArgs.map(a => `"${a}"`).join(' ')}`, { cwd: ROOT, encoding: 'utf8', timeout: 10000 }).trim();
+    if (vdocOutput && !vdocOutput.includes('No vdoc matches')) {
+      vdocSection = vdocOutput;
+    }
+  } catch { /* vdoc matching failed — skip silently */ }
+}
+
+// 6. Assemble context pack
 const lines = [
   `# QA Context: ${storyId}`,
   `> Generated: ${new Date().toISOString().split('T')[0]}`,
@@ -117,6 +134,7 @@ const lines = [
   `## Files Modified`,
   filesModified,
   '',
+  ...(vdocSection ? [vdocSection, ''] : []),
   `## Relevant Lessons`,
   lessonsExcerpt,
 ];

package/scripts/prep_sprint_context.mjs

@@ -13,6 +13,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -75,7 +76,28 @@ const storyRows = Object.entries(state.stories || {})
   .map(([id, s]) => `| ${id} | ${s.state} | ${s.qa_bounces} | ${s.arch_bounces} | ${s.worktree || '—'} |`)
   .join('\n');
 
-// 6. Assemble context pack
+// 6. vdoc summary (optional — graceful skip if no manifest)
+let vdocSummary = '';
+const manifestPath = path.join(ROOT, 'vdocs', '_manifest.json');
+if (fs.existsSync(manifestPath)) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const docCount = (manifest.documentation || []).length;
+    const docList = (manifest.documentation || []).slice(0, 10)
+      .map(d => `| ${d.filepath} | ${d.title} | ${(d.tags || []).slice(0, 4).join(', ')} | ${(d.deps || []).join(', ') || '—'} |`)
+      .join('\n');
+    vdocSummary = [
+      `## Product Documentation (vdoc)`,
+      `> ${docCount} feature doc(s) available in vdocs/`,
+      '',
+      `| Doc | Title | Tags | Dependencies |`,
+      `|-----|-------|------|-------------|`,
+      docList,
+    ].join('\n');
+  } catch { /* skip on parse error */ }
+}
+
+// 7. Assemble context pack
 const lines = [
   `# Sprint Context: ${sprintId}`,
   `> Generated: ${new Date().toISOString().split('T')[0]} | Sprint: ${sprintId} | Delivery: ${state.delivery_id}`,
@@ -91,6 +113,7 @@ const lines = [
   `|-------|-------|------------|--------------|----------|`,
   storyRows || '| (no stories) | — | — | — | — |',
   '',
+  ...(vdocSummary ? [vdocSummary, ''] : []),
   `## Relevant Lessons`,
   lessonsExcerpt,
   '',

package/scripts/suggest_improvements.mjs

@@ -159,7 +159,7 @@ suggestions.push({
   num: itemNum++,
   category: 'Health',
   title: 'Run vbounce doctor',
-  detail: 'Verify the V-Bounce OS installation is healthy after this sprint.',
+  detail: 'Verify the V-Bounce Engine installation is healthy after this sprint.',
   recommendation: 'Run: `vbounce doctor` — checks brain files, templates, scripts, state.json validity.',
   target: 'scripts/doctor.mjs',
   effort: 'Trivial',

package/scripts/validate_bounce_readiness.mjs

@@ -102,6 +102,33 @@ if (!fs.existsSync(worktreeDir)) {
   warnings.push(`.worktrees/${storyId}/ not found — create with: git worktree add .worktrees/${storyId} -b story/${storyId} sprint/S-XX`);
 }
 
+// 5. vdoc impact check (warning only — never blocks bounce)
+const manifestPath = path.join(ROOT, 'vdocs', '_manifest.json');
+if (fs.existsSync(manifestPath) && storyFile) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const docs = manifest.documentation || [];
+    const storyLower = fs.readFileSync(storyFile, 'utf8').toLowerCase();
+
+    // Extract file paths mentioned in the story
+    const storyFileRefs = storyLower.match(/(?:src|lib|app|pages|components|api|services|scripts)\/[^\s,)'"]+/g) || [];
+
+    for (const doc of docs) {
+      const docKeyFiles = (doc.keyFiles || []).map(f => f.toLowerCase());
+      const overlap = docKeyFiles.filter(kf =>
+        storyFileRefs.some(sf => sf.includes(kf) || kf.includes(sf))
+      );
+      if (overlap.length > 0) {
+        warnings.push(`vdoc impact: ${doc.filepath} — key files overlap with story scope (${overlap.slice(0, 3).join(', ')}). Doc may need updating post-sprint.`);
+        const deps = doc.deps || [];
+        if (deps.length > 0) {
+          warnings.push(`  ↳ Blast radius: ${deps.join(', ')} may also be affected`);
+        }
+      }
+    }
+  } catch { /* skip on manifest parse error */ }
+}
+
 // Print results
 console.log(`Bounce readiness check: ${storyId}`);
 console.log('');

package/scripts/validate_report.mjs

@@ -3,7 +3,7 @@
 /**
  * validate_report.mjs
  * 
- * Strict YAML Frontmatter validation for V-Bounce OS Agent Reports.
+ * Strict YAML Frontmatter validation for V-Bounce Engine Agent Reports.
  * Fails loudly if an agent hallucinates formatting or omits required fields,
  * so the orchestrator can bounce the prompt back.
  */

package/scripts/vdoc_match.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+/**
+ * vdoc_match.mjs
+ * Reads vdocs/_manifest.json and matches story scope against doc tags,
+ * descriptions, and key files. Returns relevant doc paths and blast radius.
+ *
+ * Usage:
+ *   ./scripts/vdoc_match.mjs --story STORY-005-02
+ *   ./scripts/vdoc_match.mjs --files "src/auth/index.ts,src/middleware/auth.ts"
+ *   ./scripts/vdoc_match.mjs --keywords "authentication,jwt,login"
+ *
+ * Output: JSON to stdout, human-readable to stderr
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+// ── Config ────────────────────────────────────────────────────────
+
+const configPath = path.join(ROOT, 'vbounce.config.json');
+const config = fs.existsSync(configPath)
+  ? JSON.parse(fs.readFileSync(configPath, 'utf8'))
+  : {};
+
+const MAX_MATCHES = config.vdocMaxMatches || 3;
+const VDOCS_DIR = path.join(ROOT, 'vdocs');
+const MANIFEST_PATH = path.join(VDOCS_DIR, '_manifest.json');
+const SLICES_DIR = path.join(VDOCS_DIR, '_slices');
+
+// ── Parse args ────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+let storyId = null;
+let inputFiles = [];
+let inputKeywords = [];
+let outputFormat = 'human'; // human | json | context
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case '--story':   storyId = args[++i]; break;
+    case '--files':   inputFiles = args[++i].split(',').map(f => f.trim()); break;
+    case '--keywords': inputKeywords = args[++i].split(',').map(k => k.trim().toLowerCase()); break;
+    case '--json':    outputFormat = 'json'; break;
+    case '--context': outputFormat = 'context'; break;
+  }
+}
+
+if (!storyId && inputFiles.length === 0 && inputKeywords.length === 0) {
+  console.error('Usage: vdoc_match.mjs --story STORY-ID | --files "f1,f2" | --keywords "k1,k2"');
+  console.error('  --json     Output JSON to stdout');
+  console.error('  --context  Output context-pack markdown to stdout');
+  process.exit(1);
+}
+
+// ── Load manifest ─────────────────────────────────────────────────
+
+if (!fs.existsSync(MANIFEST_PATH)) {
+  if (outputFormat === 'json') {
+    console.log(JSON.stringify({ matches: [], blastRadius: [], reason: 'no_manifest' }));
+  } else {
+    console.error('No vdocs/_manifest.json found — skipping vdoc matching');
+  }
+  process.exit(0); // Graceful no-op
+}
+
+const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+const docs = manifest.documentation || [];
+
+// ── Extract search terms from story ───────────────────────────────
+
+if (storyId) {
+  // Find story spec to extract keywords and file references
+  const storyPattern = new RegExp(storyId.replace(/[-]/g, '[-]'));
+  const storyFiles = findFiles(path.join(ROOT, 'product_plans'), storyPattern);
+
+  if (storyFiles.length > 0) {
+    const storyContent = fs.readFileSync(storyFiles[0], 'utf8').toLowerCase();
+
+    // Extract file paths mentioned in the story
+    const fileRefs = storyContent.match(/(?:src|lib|app|pages|components|api|services|scripts)\/[^\s,)'"]+/g) || [];
+    inputFiles.push(...fileRefs);
+
+    // Extract tags from story frontmatter
+    const tagMatch = storyContent.match(/tags:\s*\[([^\]]+)\]/);
+    if (tagMatch) {
+      inputKeywords.push(...tagMatch[1].split(',').map(t => t.trim().replace(/['"]/g, '')));
+    }
+
+    // Use story name parts as keywords
+    const nameParts = storyId.split('-').slice(3).join('-').replace(/_/g, ' ').split(/\s+/);
+    inputKeywords.push(...nameParts.filter(p => p.length > 2));
+  }
+}
+
+// ── Score each doc ────────────────────────────────────────────────
+
+const scored = docs.map(doc => {
+  let score = 0;
+  const reasons = [];
+
+  // 1. File path overlap (strongest signal)
+  const docKeyFiles = extractKeyFiles(doc);
+  const fileOverlap = inputFiles.filter(f => docKeyFiles.some(kf => kf.includes(f) || f.includes(kf)));
+  if (fileOverlap.length > 0) {
+    score += fileOverlap.length * 10;
+    reasons.push(`file overlap: ${fileOverlap.join(', ')}`);
+  }
+
+  // 2. Tag match
+  const docTags = (doc.tags || []).map(t => t.toLowerCase());
+  const tagOverlap = inputKeywords.filter(k => docTags.includes(k));
+  if (tagOverlap.length > 0) {
+    score += tagOverlap.length * 5;
+    reasons.push(`tag match: ${tagOverlap.join(', ')}`);
+  }
+
+  // 3. Description keyword match
+  const desc = (doc.description || '').toLowerCase();
+  const descMatches = inputKeywords.filter(k => desc.includes(k));
+  if (descMatches.length > 0) {
+    score += descMatches.length * 3;
+    reasons.push(`description match: ${descMatches.join(', ')}`);
+  }
+
+  // 4. Title keyword match
+  const title = (doc.title || '').toLowerCase();
+  const titleMatches = inputKeywords.filter(k => title.includes(k));
+  if (titleMatches.length > 0) {
+    score += titleMatches.length * 2;
+    reasons.push(`title match: ${titleMatches.join(', ')}`);
+  }
+
+  return { ...doc, score, reasons };
+}).filter(d => d.score > 0).sort((a, b) => b.score - a.score);
+
+// ── Top matches ───────────────────────────────────────────────────
+
+const topMatches = scored.slice(0, MAX_MATCHES);
+
+// ── Blast radius (deps of matched docs) ──────────────────────────
+
+const matchedFeatures = new Set(topMatches.map(d => d.title));
+const blastRadius = [];
+
+for (const match of topMatches) {
+  const deps = match.deps || [];
+  for (const dep of deps) {
+    if (!matchedFeatures.has(dep)) {
+      const depDoc = docs.find(d => d.title === dep || d.filepath.toLowerCase().includes(dep.toLowerCase().replace(/\s+/g, '_')));
+      if (depDoc) {
+        blastRadius.push({ feature: dep, doc: depDoc.filepath, triggeredBy: match.title });
+      } else {
+        blastRadius.push({ feature: dep, doc: null, triggeredBy: match.title });
+      }
+    }
+  }
+}
+
+// ── Output ────────────────────────────────────────────────────────
+
+const result = {
+  matches: topMatches.map(d => ({
+    filepath: d.filepath,
+    title: d.title,
+    score: d.score,
+    reasons: d.reasons,
+    deps: d.deps || [],
+  })),
+  blastRadius,
+};
+
+if (outputFormat === 'json') {
+  console.log(JSON.stringify(result, null, 2));
+} else if (outputFormat === 'context') {
+  // Output context-pack markdown using slices where available
+  if (topMatches.length === 0) {
+    console.log('<!-- No vdoc matches found -->');
+  } else {
+    console.log('## vdoc Context');
+    console.log('');
+    for (const match of topMatches) {
+      const sliceName = match.filepath.replace(/_DOC\.md$/, '_SLICE.md').replace(/\.md$/, '_SLICE.md');
+      const slicePath = path.join(SLICES_DIR, sliceName);
+      const fullPath = path.join(VDOCS_DIR, match.filepath);
+
+      if (fs.existsSync(slicePath)) {
+        console.log(fs.readFileSync(slicePath, 'utf8'));
+      } else if (fs.existsSync(fullPath)) {
+        // Fallback: extract Overview section from full doc
+        const content = fs.readFileSync(fullPath, 'utf8');
+        const overviewMatch = content.match(/## Overview\s*\n(?:<!--[^>]*-->\s*\n)?\s*([\s\S]*?)(?=\n---|\n##)/);
+        if (overviewMatch) {
+          console.log(`### ${match.title}`);
+          console.log(overviewMatch[1].trim().split('\n').slice(0, 5).join('\n'));
+          console.log('');
+        }
+      }
+      console.log('');
+    }
+
+    if (blastRadius.length > 0) {
+      console.log('### Blast Radius Warning');
+      console.log('Changes to matched features may also affect:');
+      for (const br of blastRadius) {
+        console.log(`- **${br.feature}** (triggered by ${br.triggeredBy})${br.doc ? ` — see ${br.doc}` : ''}`);
+      }
+      console.log('');
+    }
+  }
+} else {
+  // Human-readable to stderr
+  if (topMatches.length === 0) {
+    console.error('No vdoc matches found for the given scope.');
+  } else {
+    console.error(`\n✓ ${topMatches.length} vdoc match(es) found:\n`);
+    for (const match of topMatches) {
+      console.error(`  ${match.filepath} (score: ${match.score})`);
+      console.error(`    ${match.reasons.join(' | ')}`);
+    }
+    if (blastRadius.length > 0) {
+      console.error(`\n⚠ Blast radius — also affected:`);
+      for (const br of blastRadius) {
+        console.error(`  ${br.feature} (via ${br.triggeredBy})`);
+      }
+    }
+    console.error('');
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+function findFiles(dir, pattern) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) results.push(...findFiles(full, pattern));
+    else if (pattern.test(e.name)) results.push(full);
+  }
+  return results;
+}
+
+function extractKeyFiles(doc) {
+  // From manifest entry — check if keyFiles exist in frontmatter-style
+  const files = [];
+  if (doc.keyFiles) files.push(...doc.keyFiles);
+
+  // Also try reading the doc to get Key Files table
+  const docPath = path.join(VDOCS_DIR, doc.filepath);
+  if (fs.existsSync(docPath)) {
+    const content = fs.readFileSync(docPath, 'utf8');
+    const keyFilesMatch = content.match(/## Key Files[\s\S]*?\|[^|]+\|[^|]+\|[^|]+\|([\s\S]*?)(?=\n---|\n##)/);
+    if (keyFilesMatch) {
+      const rows = keyFilesMatch[1].split('\n').filter(r => r.includes('|'));
+      for (const row of rows) {
+        const cells = row.split('|').map(c => c.trim());
+        const filePath = cells[1]?.replace(/`/g, '');
+        if (filePath && filePath.includes('/')) files.push(filePath);
+      }
+    }
+  }
+  return files;
+}