vbounce-engine 2.5.1

package/scripts/hotfix_manager.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+
+# V-Bounce Engine: 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 Engine — Hotfix Manager"
+    echo ""
+    echo "Usage: ./.vbounce/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 "  ./.vbounce/scripts/hotfix_manager.sh audit"
+    echo "  ./.vbounce/scripts/hotfix_manager.sh sync"
+    echo "  ./.vbounce/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: ./.vbounce/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/init_gate_config.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# init_gate_config.sh — Auto-detect project stack and generate .vbounce/gate-checks.json
+# Usage: ./.vbounce/scripts/init_gate_config.sh [project-path]
+#
+# Run once during project setup or when the improve skill suggests new checks.
+# Safe to re-run — merges with existing config (preserves custom checks).
+
+set -euo pipefail
+
+PROJECT_PATH="${1:-.}"
+PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+CONFIG_PATH="${PROJECT_PATH}/.vbounce/gate-checks.json"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${CYAN}V-Bounce Engine Gate Config Initializer${NC}"
+echo -e "Project: ${PROJECT_PATH}"
+echo ""
+
+# ── Detect stack ─────────────────────────────────────────────────────
+
+LANGUAGE="unknown"
+FRAMEWORK="unknown"
+TEST_RUNNER="unknown"
+BUILD_CMD=""
+LINT_CMD=""
+TEST_CMD=""
+
+# Language detection
+if [[ -f "${PROJECT_PATH}/tsconfig.json" ]]; then
+  LANGUAGE="typescript"
+elif [[ -f "${PROJECT_PATH}/package.json" ]]; then
+  LANGUAGE="javascript"
+elif [[ -f "${PROJECT_PATH}/pyproject.toml" || -f "${PROJECT_PATH}/setup.py" || -f "${PROJECT_PATH}/requirements.txt" ]]; then
+  LANGUAGE="python"
+elif [[ -f "${PROJECT_PATH}/Cargo.toml" ]]; then
+  LANGUAGE="rust"
+elif [[ -f "${PROJECT_PATH}/go.mod" ]]; then
+  LANGUAGE="go"
+elif [[ -f "${PROJECT_PATH}/build.gradle" || -f "${PROJECT_PATH}/pom.xml" ]]; then
+  LANGUAGE="java"
+elif [[ -f "${PROJECT_PATH}/Package.swift" ]]; then
+  LANGUAGE="swift"
+fi
+
+echo -e "Language: ${GREEN}${LANGUAGE}${NC}"
+
+# Framework detection (JS/TS ecosystem)
+if [[ -f "${PROJECT_PATH}/package.json" ]]; then
+  PKG_CONTENT=$(cat "${PROJECT_PATH}/package.json")
+
+  if echo "$PKG_CONTENT" | grep -q '"next"'; then FRAMEWORK="nextjs"
+  elif echo "$PKG_CONTENT" | grep -q '"react"'; then FRAMEWORK="react"
+  elif echo "$PKG_CONTENT" | grep -q '"vue"'; then FRAMEWORK="vue"
+  elif echo "$PKG_CONTENT" | grep -q '"svelte"'; then FRAMEWORK="svelte"
+  elif echo "$PKG_CONTENT" | grep -q '"express"'; then FRAMEWORK="express"
+  elif echo "$PKG_CONTENT" | grep -q '"fastify"'; then FRAMEWORK="fastify"
+  elif echo "$PKG_CONTENT" | grep -q '"@angular/core"'; then FRAMEWORK="angular"
+  fi
+
+  # Test runner
+  if echo "$PKG_CONTENT" | grep -q '"vitest"'; then TEST_RUNNER="vitest"
+  elif echo "$PKG_CONTENT" | grep -q '"jest"'; then TEST_RUNNER="jest"
+  elif echo "$PKG_CONTENT" | grep -q '"mocha"'; then TEST_RUNNER="mocha"
+  elif echo "$PKG_CONTENT" | grep -q '"ava"'; then TEST_RUNNER="ava"
+  fi
+
+  # Commands from scripts
+  BUILD_CMD=$(node -e "try{const p=require('${PROJECT_PATH}/package.json');console.log(p.scripts&&p.scripts.build||'')}catch(e){}" 2>/dev/null || echo "")
+  LINT_CMD=$(node -e "try{const p=require('${PROJECT_PATH}/package.json');console.log(p.scripts&&p.scripts.lint||'')}catch(e){}" 2>/dev/null || echo "")
+  TEST_CMD=$(node -e "try{const p=require('${PROJECT_PATH}/package.json');const t=p.scripts&&p.scripts.test||'';if(t&&!t.includes('no test specified'))console.log(t);else console.log('')}catch(e){}" 2>/dev/null || echo "")
+elif [[ "$LANGUAGE" == "python" ]]; then
+  if command -v pytest &>/dev/null; then TEST_RUNNER="pytest"; fi
+  if command -v ruff &>/dev/null; then LINT_CMD="ruff check ."; fi
+elif [[ "$LANGUAGE" == "rust" ]]; then
+  TEST_RUNNER="cargo"
+  BUILD_CMD="cargo build"
+  LINT_CMD="cargo clippy"
+elif [[ "$LANGUAGE" == "go" ]]; then
+  TEST_RUNNER="go"
+  BUILD_CMD="go build ./..."
+  LINT_CMD="golangci-lint run"
+fi
+
+echo -e "Framework: ${GREEN}${FRAMEWORK}${NC}"
+echo -e "Test runner: ${GREEN}${TEST_RUNNER}${NC}"
+[[ -n "$BUILD_CMD" ]] && echo -e "Build: ${GREEN}${BUILD_CMD}${NC}"
+[[ -n "$LINT_CMD" ]] && echo -e "Lint: ${GREEN}${LINT_CMD}${NC}"
+echo ""
+
+# ── Generate config ──────────────────────────────────────────────────
+
+# Build QA checks array
+QA_CHECKS='[
+    { "id": "tests_exist", "enabled": true, "description": "Verify test files exist for modified source files" },
+    { "id": "tests_pass", "enabled": true, "description": "Run test suite" },
+    { "id": "build", "enabled": true, "description": "Run build command" },
+    { "id": "lint", "enabled": true, "description": "Run linter" },
+    { "id": "no_debug_output", "enabled": true, "description": "No debug statements in modified files" },
+    { "id": "no_todo_fixme", "enabled": true, "description": "No TODO/FIXME in modified files" },
+    { "id": "exports_have_docs", "enabled": true, "description": "Exported symbols have doc comments" }
+  ]'
+
+# Build Architect checks array
+ARCH_CHECKS='[
+    { "id": "tests_exist", "enabled": true, "description": "Verify test files exist for modified source files" },
+    { "id": "tests_pass", "enabled": true, "description": "Run test suite" },
+    { "id": "build", "enabled": true, "description": "Run build command" },
+    { "id": "lint", "enabled": true, "description": "Run linter" },
+    { "id": "no_debug_output", "enabled": true, "description": "No debug statements in modified files" },
+    { "id": "no_todo_fixme", "enabled": true, "description": "No TODO/FIXME in modified files" },
+    { "id": "exports_have_docs", "enabled": true, "description": "Exported symbols have doc comments" },
+    { "id": "no_new_deps", "enabled": true, "description": "No new dependencies without review" },
+    { "id": "file_size", "enabled": true, "max_lines": 500, "description": "Source files under 500 lines" }
+  ]'
+
+# Write config
+mkdir -p "$(dirname "$CONFIG_PATH")"
+
+cat > "$CONFIG_PATH" << HEREDOC
+{
+  "version": 1,
+  "detected_stack": {
+    "language": "${LANGUAGE}",
+    "framework": "${FRAMEWORK}",
+    "test_runner": "${TEST_RUNNER}",
+    "build_cmd": "${BUILD_CMD}",
+    "lint_cmd": "${LINT_CMD}",
+    "test_cmd": "${TEST_CMD}"
+  },
+  "qa_checks": ${QA_CHECKS},
+  "arch_checks": ${ARCH_CHECKS},
+  "custom_checks": []
+}
+HEREDOC
+
+echo -e "${GREEN}Generated: ${CONFIG_PATH}${NC}"
+echo ""
+echo "Universal checks enabled. To add project-specific checks:"
+echo "  1. Run sprints and let agents collect Process Feedback"
+echo "  2. Use the 'improve' skill to propose new checks"
+echo "  3. Or manually add entries to the custom_checks array"
+echo ""
+echo -e "Example custom check (add to custom_checks):"
+echo '  { "id": "custom_grep", "gate": "arch", "enabled": true,'
+echo '    "pattern": "var\\(--my-prefix-", "glob": "*.tsx",'
+echo '    "should_find": false, "description": "No raw CSS vars in components" }'

package/scripts/init_sprint.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+/**
+ * init_sprint.mjs
+ * Sprint setup automation — creates state.json, sprint plan dir, and prints git commands.
+ *
+ * Usage:
+ *   ./.vbounce/scripts/init_sprint.mjs S-06 D-02 --stories STORY-011-05,STORY-005-01,STORY-005-02
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '../..');
+
+const args = process.argv.slice(2);
+
+if (args.length < 2) {
+  console.error('Usage: init_sprint.mjs S-XX D-NN [--stories STORY-ID1,STORY-ID2,...]');
+  process.exit(1);
+}
+
+const sprintId = args[0]; // e.g. S-06
+const deliveryId = args[1]; // e.g. D-02
+
+if (!/^S-\d{2}$/.test(sprintId)) {
+  console.error(`ERROR: sprint_id "${sprintId}" must match S-XX format`);
+  process.exit(1);
+}
+if (!/^D-\d{2}$/.test(deliveryId)) {
+  console.error(`ERROR: delivery_id "${deliveryId}" must match D-NN format`);
+  process.exit(1);
+}
+
+const storiesArg = args.indexOf('--stories');
+const storyIds = storiesArg !== -1 ? args[storiesArg + 1].split(',') : [];
+
+// 1. Create .vbounce/ directory
+const bounceDir = path.join(ROOT, '.vbounce');
+fs.mkdirSync(bounceDir, { recursive: true });
+fs.mkdirSync(path.join(bounceDir, 'archive'), { recursive: true });
+fs.mkdirSync(path.join(bounceDir, 'reports'), { recursive: true });
+
+// 2. Create state.json
+const stateFile = path.join(bounceDir, 'state.json');
+if (fs.existsSync(stateFile)) {
+  console.warn(`⚠  state.json already exists. Overwriting...`);
+}
+
+const sprintNum = sprintId.replace('S-', '');
+const stories = {};
+for (const id of storyIds) {
+  stories[id.trim()] = {
+    state: 'Draft',
+    qa_bounces: 0,
+    arch_bounces: 0,
+    worktree: null
+  };
+}
+
+const state = {
+  sprint_id: sprintId,
+  delivery_id: deliveryId,
+  sprint_plan: `product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md`,
+  delivery_plan: `product_plans/strategy/${deliveryId}_DELIVERY_PLAN.md`,
+  stories,
+  phase: 'Phase 1',
+  last_action: `Sprint ${sprintId} initialized`,
+  updated_at: new Date().toISOString()
+};
+
+fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+console.log(`✓ Created .vbounce/state.json`);
+
+// 3. Create sprint plan directory
+const sprintDir = path.join(ROOT, 'product_plans', 'sprints', `sprint-${sprintNum}`);
+fs.mkdirSync(sprintDir, { recursive: true });
+
+const sprintPlanFile = path.join(sprintDir, `sprint-${sprintNum}.md`);
+if (!fs.existsSync(sprintPlanFile)) {
+  // Copy from template
+  const templateFile = path.join(ROOT, '.vbounce', 'templates', 'sprint.md');
+  if (fs.existsSync(templateFile)) {
+    let content = fs.readFileSync(templateFile, 'utf8');
+    // Replace placeholders
+    content = content.replace(/sprint-\{XX\}/g, `sprint-${sprintNum}`);
+    content = content.replace(/S-\{XX\}/g, sprintId);
+    content = content.replace(/D-\{NN\}/g, deliveryId);
+    content = content.replace(/status: "Planning \/ Active \/ Completed"/, 'status: "Planning"');
+    // Strip instructions block
+    content = content.replace(/<instructions>[\s\S]*?<\/instructions>\n\n/, '');
+    fs.writeFileSync(sprintPlanFile, content);
+    console.log(`✓ Created product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md`);
+  } else {
+    // Create minimal sprint plan
+    const minimal = `---\nsprint_id: "${sprintId}"\nsprint_goal: "TBD"\ndates: "TBD"\nstatus: "Planning"\ndelivery: "${deliveryId}"\n---\n\n# Sprint ${sprintId} Plan\n\n## 1. Active Scope\n\n| Priority | Story | Epic | Label | V-Bounce State | Blocker |\n|----------|-------|------|-------|----------------|---------|\n${storyIds.map((id, i) => `| ${i + 1} | ${id.trim()} | — | L2 | Draft | — |`).join('\n')}\n\n### Escalated / Parking Lot\n- (none)\n\n---\n\n## 2. Execution Strategy\n\n### Phase Plan\n- **Phase 1 (parallel)**: ${storyIds.join(', ')}\n\n### Risk Flags\n- (TBD)\n\n---\n\n## 3. Sprint Open Questions\n\n| Question | Options | Impact | Owner | Status |\n|----------|---------|--------|-------|--------|\n\n---\n\n<!-- EXECUTION_LOG_START -->\n## 4. Execution Log\n\n| Story | Final State | QA Bounces | Arch Bounces | Correction Tax | Notes |\n|-------|-------------|------------|--------------|----------------|-------|\n<!-- EXECUTION_LOG_END -->\n`;
+    fs.writeFileSync(sprintPlanFile, minimal);
+    console.log(`✓ Created product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md (minimal — template not found)`);
+  }
+} else {
+  console.log(`  Sprint plan already exists: product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md`);
+}
+
+// 4. Print git commands (don't execute)
+console.log('');
+console.log('Run these git commands to initialize the sprint branch:');
+console.log(`  git checkout -b sprint/${sprintId} main`);
+if (storyIds.length > 0) {
+  console.log('');
+  console.log('Then create worktrees for each story:');
+  storyIds.forEach(id => {
+    const trimmed = id.trim();
+    console.log(`  git worktree add .worktrees/${trimmed} -b story/${trimmed} sprint/${sprintId}`);
+    console.log(`  mkdir -p .worktrees/${trimmed}/.vbounce/{tasks,reports}`);
+  });
+}
+
+// 5. Regenerate product graph (non-blocking)
+const graphScript = path.join(__dirname, 'product_graph.mjs');
+if (fs.existsSync(graphScript)) {
+  const graphResult = spawnSync(process.execPath, [graphScript], { stdio: 'pipe', cwd: ROOT });
+  if (graphResult.status === 0) console.log('✓ Product graph regenerated');
+}
+
+console.log('');
+console.log(`✓ Sprint ${sprintId} initialized. Stories: ${storyIds.length > 0 ? storyIds.join(', ') : 'none (add manually)'}`);