@sandrinio/vbounce 1.0.0 → 1.3.0

package/scripts/hotfix_manager.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+
+# V-Bounce OS: Hotfix Manager
+# Handles edge cases for L1 Trivial tasks to save tokens and ensure framework integrity.
+
+set -euo pipefail
+
+# Ensure we're in a git repository
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
+    echo "❌ Error: Not inside a git repository."
+    exit 1
+}
+
+COMMAND="${1:-}"
+
+function show_help {
+    echo "V-Bounce OS — Hotfix Manager"
+    echo ""
+    echo "Usage: ./scripts/hotfix_manager.sh <command> [args]"
+    echo ""
+    echo "Commands:"
+    echo "  audit               Run a lightweight static analysis on recent commits to detect architectural drift."
+    echo "  sync                Rebase all active git worktrees against the current sprint branch."
+    echo "  ledger <title> <desc>  Append a Hotfix entry to §8 Applied Hotfixes in the active DELIVERY_PLAN.md."
+    echo ""
+    echo "Examples:"
+    echo "  ./scripts/hotfix_manager.sh audit"
+    echo "  ./scripts/hotfix_manager.sh sync"
+    echo "  ./scripts/hotfix_manager.sh ledger \"Fix Header\" \"Aligned the logo to the left\""
+    exit 1
+}
+
+if [ -z "$COMMAND" ]; then
+    show_help
+fi
+
+case "$COMMAND" in
+    audit)
+        echo "🔍 Running Token-Saving Hotfix Audit..."
+
+        # Determine how many commits exist on the branch so we don't overshoot
+        TOTAL_COMMITS=$(git rev-list --count HEAD 2>/dev/null || echo "0")
+        LOOKBACK=5
+        if [ "$TOTAL_COMMITS" -lt "$LOOKBACK" ]; then
+            LOOKBACK="$TOTAL_COMMITS"
+        fi
+
+        if [ "$LOOKBACK" -eq 0 ]; then
+            echo "✅ No commits to audit."
+            exit 0
+        fi
+
+        SUSPICIOUS=$(git diff "HEAD~${LOOKBACK}" HEAD -G'style=|console\.log|// TODO' --name-only 2>/dev/null || true)
+
+        if [ -n "$SUSPICIOUS" ]; then
+            echo "⚠️  WARNING: Potential architectural drift detected in recent commits."
+            echo "The following files contain inline styles, console.logs, or TODOs:"
+            echo "$SUSPICIOUS"
+            echo ""
+            echo "Action Required: The Architect agent MUST perform a Deep Audit on these files."
+            exit 1
+        else
+            echo "✅ No obvious architectural drift detected in recent commits."
+            exit 0
+        fi
+        ;;
+
+    sync)
+        echo "🔄 Syncing active worktrees with the latest changes..."
+
+        WORKTREE_DIR="${REPO_ROOT}/.worktrees"
+
+        if [ ! -d "$WORKTREE_DIR" ]; then
+            echo "✅ No active worktrees found at ${WORKTREE_DIR}. Nothing to sync."
+            exit 0
+        fi
+
+        CURRENT_BRANCH=$(git branch --show-current)
+
+        if [ -z "$CURRENT_BRANCH" ]; then
+            echo "❌ Error: Detached HEAD state. Cannot determine sprint branch for sync."
+            exit 1
+        fi
+
+        SYNC_COUNT=0
+        FAIL_COUNT=0
+
+        for dir in "${WORKTREE_DIR}"/*/; do
+            if [ -d "$dir" ]; then
+                WORKTREE_NAME=$(basename "$dir")
+                echo "Syncing worktree: $WORKTREE_NAME..."
+
+                if (cd "$dir" && git fetch origin && git rebase "origin/$CURRENT_BRANCH"); then
+                    echo "  ✅ Successfully synced $WORKTREE_NAME."
+                    SYNC_COUNT=$((SYNC_COUNT + 1))
+                else
+                    echo "  ❌ Failed to sync $WORKTREE_NAME. Manual intervention required."
+                    FAIL_COUNT=$((FAIL_COUNT + 1))
+                fi
+            fi
+        done
+
+        echo ""
+        echo "Sync complete: $SYNC_COUNT succeeded, $FAIL_COUNT failed."
+        [ "$FAIL_COUNT" -gt 0 ] && exit 1 || exit 0
+        ;;
+
+    ledger)
+        TITLE="${2:-}"
+        DESC="${3:-}"
+
+        if [ -z "$TITLE" ] || [ -z "$DESC" ]; then
+            echo "❌ Error: Missing title or description for the ledger."
+            echo "Usage: ./scripts/hotfix_manager.sh ledger \"Fix Header\" \"Aligned the logo to the left\""
+            exit 1
+        fi
+
+        # Find the active delivery plan (search from repo root)
+        DELIVERY_PLAN=$(find "${REPO_ROOT}/product_plans" -name "DELIVERY_PLAN.md" 2>/dev/null | head -n 1)
+
+        if [ -z "$DELIVERY_PLAN" ]; then
+            echo "❌ Error: No DELIVERY_PLAN.md found in product_plans/."
+            exit 1
+        fi
+
+        echo "📝 Updating Hotfix Ledger in $DELIVERY_PLAN..."
+
+        # Check if §8 Applied Hotfixes exists, if not, create it
+        if ! grep -q "## 8. Applied Hotfixes" "$DELIVERY_PLAN"; then
+            echo "" >> "$DELIVERY_PLAN"
+            echo "---" >> "$DELIVERY_PLAN"
+            echo "" >> "$DELIVERY_PLAN"
+            echo "## 8. Applied Hotfixes" >> "$DELIVERY_PLAN"
+            echo "" >> "$DELIVERY_PLAN"
+            echo "> L1 Trivial fixes that bypassed the Epic/Story hierarchy. Auto-appended by \`hotfix_manager.sh ledger\`." >> "$DELIVERY_PLAN"
+            echo "" >> "$DELIVERY_PLAN"
+            echo "| Date | Title | Brief Description |" >> "$DELIVERY_PLAN"
+            echo "|------|-------|-------------------|" >> "$DELIVERY_PLAN"
+        fi
+
+        # Append the new row
+        DATE=$(date "+%Y-%m-%d")
+        echo "| $DATE | $TITLE | $DESC |" >> "$DELIVERY_PLAN"
+
+        echo "✅ Ledger updated: \"$TITLE\" added to §8 Applied Hotfixes."
+        ;;
+
+    --help|-h|help)
+        show_help
+        ;;
+
+    *)
+        echo "❌ Unknown command: $COMMAND"
+        echo ""
+        show_help
+        ;;
+esac

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);