vbounce-engine 2.5.1 → 2.5.3

package/README.md

@@ -5,7 +5,7 @@
 
   <p>
     <a href="https://github.com/sandrinio/v-bounce-engine/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
-    <a href="https://www.npmjs.com/package/vbounce"><img alt="NPM Version" src="https://img.shields.io/npm/v/vbounce"></a>
+    <a href="https://www.npmjs.com/package/vbounce-engine"><img alt="NPM Version" src="https://img.shields.io/npm/v/vbounce-engine"></a>
   </p>
   
   <p>
@@ -21,14 +21,14 @@ Get your new AI team up and running in seconds. No complex setup, no vector data
 
 ```bash
 # 1. Install the framework for your platform of choice
-npx vbounce install claude    # Claude Code (Full Orchestration)
-# Or: npx vbounce install cursor|gemini|codex|vscode
+npx vbounce-engine install claude    # Claude Code (Full Orchestration)
+# Or: npx vbounce-engine install cursor|gemini|codex|vscode
 
 # 2. Verify your installation
-npx vbounce doctor
+npx vbounce-engine doctor
 
 # 3. Initialize your first sprint!
-npx vbounce sprint init S-01 D-01
+npx vbounce-engine sprint init S-01 D-01
 ```
 
 > **Requirements**: Node.js and a project directory. That's it. One person to set the vision, the AI handles the execution.

package/VBOUNCE_MANIFEST.md

@@ -4,8 +4,8 @@
 > Any modification to `.claude/agents/`, `.vbounce/skills/`, `.vbounce/templates/`, or `.vbounce/scripts/` MUST also update this file.
 > Run `vbounce doctor` to validate file existence against this manifest.
 
-**Version:** 2.5.1
-**Last updated:** 2026-03-25
+**Version:** 2.5.3
+**Last updated:** 2026-03-26
 
 ---
 
@@ -185,6 +185,16 @@ Skills are modular instructions loaded by agents. Located in `.vbounce/skills/`.
 
 Scripts automate framework operations. Located in `.vbounce/scripts/`.
 
+### Script Execution Wrapper
+| Script | When | Input | Output |
+|--------|------|-------|--------|
+| `.vbounce/scripts/run_script.sh` | **Every script invocation** | Script name + args | Passthrough stdout/stderr, pre-flight checks, structured diagnostics on failure |
+
+### Shared Constants
+| Script | When | Input | Output |
+|--------|------|-------|--------|
+| `.vbounce/scripts/constants.mjs` | Imported by lifecycle scripts | — | `VALID_STATES`, `TERMINAL_STATES` (single source of truth) |
+
 ### Sprint Lifecycle
 | Script | When | Input | Output |
 |--------|------|-------|--------|
@@ -364,16 +374,21 @@ Regression suite for validating the engine after any path, script, or template c
 
 | File | Suite | What it checks |
 |------|-------|----------------|
-| `tests/harness.mjs` | — | Test primitives: `suite()`, `record()`, `assertFileExists()`, `assertNoMatch()`, `assertScriptRuns()`, `generateReport()` |
-| `tests/run.mjs` | — | Main runner: installs to temp dir, runs all suites, generates JSON + Markdown reports |
+| `tests/harness.mjs` | — | Test primitives: `suite()`, `record()`, `assertFileExists()`, `assertNoMatch()`, `assertScriptRuns()`, `assertBashRuns()`, `generateReport()` |
+| `tests/fixtures.mjs` | — | Shared fixture generator: `createSprintFixtures()`, `createSyntheticReport()`, `removeSprintFixtures()` |
+| `tests/run.mjs` | — | Main runner: installs to temp dir, runs all 12 suites, generates JSON + Markdown reports |
 | `tests/suites/install.mjs` | Install Integrity | 76+ file existence checks across all installed components |
 | `tests/suites/paths.mjs` | Path Integrity | 500+ stale path pattern scans across all shipped `.md`/`.mjs` files |
 | `tests/suites/doctor.mjs` | Doctor Accuracy | False positive and false negative detection |
-| `tests/suites/scripts.mjs` | Script Validation | Import checks, functional tests, ROOT resolution for all 22 `.mjs` scripts |
+| `tests/suites/scripts.mjs` | Script Validation | Import checks, functional tests, ROOT resolution for all `.mjs` scripts |
 | `tests/suites/brains.mjs` | Agent Contracts | Frontmatter, report YAML signatures, CLAUDE.md ↔ agents consistency |
 | `tests/suites/manifest.mjs` | Manifest Completeness | All backtick paths resolve, orphan file detection |
 | `tests/suites/templates.mjs` | Template/Skill Integrity | Structure validation, stale paths, CLAUDE.md ↔ skills cross-reference |
 | `tests/suites/lifecycle.mjs` | Full Lifecycle | 41-test simulation: fixtures → init → transitions → context prep → complete → close → analytics → edge cases |
+| `tests/suites/agent-errors.mjs` | Agent Error Paths | Scripts called in wrong order, wrong state, wrong/missing args — verifies actionable errors, not raw crashes |
+| `tests/suites/run-script-wrapper.mjs` | Script Wrapper | `run_script.sh` pre-flight checks, diagnostic block output, success/failure passthrough, bash script support |
+| `tests/suites/parallel-stories.mjs` | Parallel Stories | Concurrent state management: 3 stories transition independently, bounce counts isolated, re-init behavior |
+| `tests/suites/report-parsing.mjs` | Report Parsing | Malformed agent reports (no frontmatter, empty, truncated YAML, missing fields) handled gracefully |
 
 Reports output to `tests/reports/report-{timestamp}.{json,md}`.
 
@@ -396,9 +411,9 @@ Reports output to `tests/reports/report-{timestamp}.{json,md}`.
 | Templates | 13 |
 | Skills (SKILL.md + references) | 26 |
 | React rules | 57 |
-| Scripts | 27 |
-| Test suite | 10 |
+| Scripts | 29 |
+| Test suite | 16 |
 | Diagrams | 6 |
 | Docs + Visual Assets | 6 + ~15 icons/images |
 | CLI | 1 |
-| **Total** | **~185** |
+| **Total** | **~193** |

package/brains/CLAUDE.md

@@ -58,12 +58,12 @@ Determine which phase you're in from what the human is asking, then load the rig
 > - **Planning (Phase 1 & 2):** Load `@.vbounce/skills/doc-manager/SKILL.md` + `@.vbounce/skills/product-graph/SKILL.md`
 > - **Execution (Phase 3):** Load `@.vbounce/skills/agent-team/SKILL.md`
 
-> **On-demand skills:**
-> - `/doc` → `@.vbounce/skills/doc-manager/SKILL.md`
-> - `/review` → `@.vbounce/skills/vibe-code-review/SKILL.md` — code review
-> - `/write-skill` → `@.vbounce/skills/write-skill/SKILL.md` — skill authoring
-> - `/improve` → `@.vbounce/skills/improve/SKILL.md` — framework improvement
-> - `/react` → `@.vbounce/skills/react-best-practices/SKILL.md` — frontend patterns
+> **On-demand skills** (read the file directly when the user asks — these are NOT slash commands):
+> - "doc" → read `@.vbounce/skills/doc-manager/SKILL.md`
+> - "review" → read `@.vbounce/skills/vibe-code-review/SKILL.md` — code review
+> - "write-skill" → read `@.vbounce/skills/write-skill/SKILL.md` — skill authoring
+> - "improve" → read `@.vbounce/skills/improve/SKILL.md` — framework improvement
+> - "react" → read `@.vbounce/skills/react-best-practices/SKILL.md` — frontend patterns
 
 ## Subagents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vbounce-engine",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "description": "V-Bounce Engine: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
   "type": "module",
   "bin": {

package/scripts/close_sprint.mjs

@@ -12,6 +12,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import { TERMINAL_STATES } from './constants.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '../..');
@@ -37,7 +38,13 @@ if (!fs.existsSync(stateFile)) {
   process.exit(1);
 }
 
-const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+let state;
+try {
+  state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+} catch (e) {
+  console.error(`ERROR: state.json is not valid JSON — ${e.message}`);
+  process.exit(1);
+}
 
 if (state.sprint_id !== sprintId) {
   console.error(`ERROR: state.json is for sprint ${state.sprint_id}, not ${sprintId}`);
@@ -46,7 +53,7 @@ if (state.sprint_id !== sprintId) {
 
 // 2. Check all stories are terminal
 const activeStories = Object.entries(state.stories || {}).filter(
-  ([, s]) => !['Done', 'Escalated', 'Parking Lot'].includes(s.state)
+  ([, s]) => !TERMINAL_STATES.includes(s.state)
 );
 
 if (activeStories.length > 0) {

package/scripts/complete_story.mjs

@@ -42,7 +42,13 @@ if (!fs.existsSync(stateFile)) {
   console.error('ERROR: .vbounce/state.json not found');
   process.exit(1);
 }
-const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+let state;
+try {
+  state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+} catch (e) {
+  console.error(`ERROR: state.json is not valid JSON — ${e.message}`);
+  process.exit(1);
+}
 if (!state.stories[storyId]) {
   console.error(`ERROR: Story "${storyId}" not found in state.json`);
   process.exit(1);

package/scripts/constants.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+/**
+ * constants.mjs
+ * Shared constants for V-Bounce Engine scripts.
+ * Single source of truth for story states and terminal states.
+ */
+
+/** All valid story states in lifecycle order. */
+export const VALID_STATES = [
+  'Draft', 'Refinement', 'Ready to Bounce', 'Bouncing',
+  'QA Passed', 'Architect Passed', 'Done', 'Escalated', 'Parking Lot'
+];
+
+/** Terminal states — stories that are no longer active. */
+export const TERMINAL_STATES = ['Done', 'Escalated', 'Parking Lot'];

package/scripts/doctor.mjs

@@ -100,6 +100,7 @@ if (skillCount === requiredSkills.length) pass(`Skills: ${skillCount}/${required
 
 // Check scripts
 const requiredScripts = [
+  'run_script.sh',
   'validate_report.mjs', 'update_state.mjs', 'validate_state.mjs',
   'validate_sprint_plan.mjs', 'validate_bounce_readiness.mjs',
   'init_sprint.mjs', 'close_sprint.mjs', 'complete_story.mjs',

package/scripts/pre_gate_common.sh

@@ -536,6 +536,53 @@ check_file_size_limit() {
   fi
 }
 
+# ── Pre-merge report verification ────────────────────────────────────
+
+check_gate_reports_exist() {
+  local dir="$1" story_id="$2"
+  local reports_dir="${dir}/.vbounce/reports"
+  local missing=0
+  local details=""
+
+  if [[ ! -d "$reports_dir" ]]; then
+    record_result "gate_reports" "FAIL" ".vbounce/reports/ directory not found in worktree"
+    record_result_plain "gate_reports" "FAIL" ".vbounce/reports/ directory not found in worktree"
+    return
+  fi
+
+  # Check for QA report (any bounce)
+  local qa_report
+  qa_report=$(find "$reports_dir" -name "${story_id}-qa*" -o -name "${story_id}*-qa*" 2>/dev/null | head -1)
+  if [[ -z "$qa_report" ]]; then
+    missing=$((missing + 1))
+    details="${details}QA report missing. "
+  fi
+
+  # Check for Architect report (any bounce)
+  local arch_report
+  arch_report=$(find "$reports_dir" -name "${story_id}-arch*" -o -name "${story_id}*-arch*" 2>/dev/null | head -1)
+  if [[ -z "$arch_report" ]]; then
+    missing=$((missing + 1))
+    details="${details}Architect report missing. "
+  fi
+
+  # Check for Dev report
+  local dev_report
+  dev_report=$(find "$reports_dir" -name "${story_id}-dev*" -o -name "${story_id}*-dev*" 2>/dev/null | head -1)
+  if [[ -z "$dev_report" ]]; then
+    missing=$((missing + 1))
+    details="${details}Dev report missing. "
+  fi
+
+  if [[ $missing -eq 0 ]]; then
+    record_result "gate_reports" "PASS" "Dev, QA, and Architect reports present"
+    record_result_plain "gate_reports" "PASS" "Dev, QA, and Architect reports present"
+  else
+    record_result "gate_reports" "FAIL" "${details}"
+    record_result_plain "gate_reports" "FAIL" "${details}"
+  fi
+}
+
 # ── Custom check runner ──────────────────────────────────────────────
 
 run_custom_check() {

package/scripts/run_script.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# run_script.sh — Safe wrapper for V-Bounce script execution
+# Usage: ./.vbounce/scripts/run_script.sh <script> [args...]
+#
+# All agents MUST invoke .vbounce scripts through this wrapper.
+# Captures exit code, stdout, stderr. On failure, prints a structured
+# diagnostic block that agents can parse and act on.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+# ── Arguments ────────────────────────────────────────────────────────
+
+SCRIPT_NAME="${1:-}"
+
+if [[ -z "$SCRIPT_NAME" ]]; then
+  echo "Usage: ./.vbounce/scripts/run_script.sh <script> [args...]"
+  echo ""
+  echo "Examples:"
+  echo "  ./.vbounce/scripts/run_script.sh validate_state.mjs"
+  echo "  ./.vbounce/scripts/run_script.sh pre_gate_runner.sh qa .worktrees/STORY-001-01/"
+  echo "  ./.vbounce/scripts/run_script.sh complete_story.mjs STORY-001-01"
+  exit 1
+fi
+
+shift
+SCRIPT_ARGS=("$@")
+
+# ── Resolve script path ─────────────────────────────────────────────
+
+SCRIPT_PATH="${SCRIPT_DIR}/${SCRIPT_NAME}"
+
+if [[ ! -f "$SCRIPT_PATH" ]]; then
+  echo ""
+  echo -e "${RED}┌─ SCRIPT FAILURE ─────────────────────────────────────────┐${NC}"
+  echo -e "${RED}│ Script:    ${SCRIPT_NAME}${NC}"
+  echo -e "${RED}│ Exit Code: 127 (not found)${NC}"
+  echo -e "${RED}│ Error:     ${SCRIPT_PATH} does not exist${NC}"
+  echo -e "${RED}│${NC}"
+  echo -e "${RED}│ Available scripts:${NC}"
+  for f in "${SCRIPT_DIR}"/*.{mjs,sh}; do
+    [[ -f "$f" ]] && [[ "$(basename "$f")" != "run_script.sh" ]] && echo -e "${RED}│   $(basename "$f")${NC}"
+  done
+  echo -e "${RED}│${NC}"
+  echo -e "${RED}│ Action:    Check script name for typos${NC}"
+  echo -e "${RED}└──────────────────────────────────────────────────────────┘${NC}"
+  exit 127
+fi
+
+# ── Pre-flight checks ───────────────────────────────────────────────
+
+PREFLIGHT_WARNINGS=""
+
+# Check state.json for scripts that need it
+NEEDS_STATE=(
+  "update_state.mjs" "validate_state.mjs" "complete_story.mjs"
+  "close_sprint.mjs" "prep_sprint_context.mjs" "validate_bounce_readiness.mjs"
+)
+
+for s in "${NEEDS_STATE[@]}"; do
+  if [[ "$SCRIPT_NAME" == "$s" ]]; then
+    if [[ ! -f "${ROOT}/.vbounce/state.json" ]]; then
+      PREFLIGHT_WARNINGS="${PREFLIGHT_WARNINGS}\n  ⚠ state.json missing — ${SCRIPT_NAME} will fail"
+    elif ! node -e "JSON.parse(require('fs').readFileSync('${ROOT}/.vbounce/state.json','utf8'))" 2>/dev/null; then
+      PREFLIGHT_WARNINGS="${PREFLIGHT_WARNINGS}\n  ⚠ state.json is invalid JSON — ${SCRIPT_NAME} will fail"
+    fi
+    break
+  fi
+done
+
+# Check .vbounce directory exists
+if [[ ! -d "${ROOT}/.vbounce" ]]; then
+  PREFLIGHT_WARNINGS="${PREFLIGHT_WARNINGS}\n  ⚠ .vbounce/ directory missing"
+fi
+
+if [[ -n "$PREFLIGHT_WARNINGS" ]]; then
+  echo -e "${YELLOW}Pre-flight warnings:${PREFLIGHT_WARNINGS}${NC}"
+  echo ""
+fi
+
+# ── Execute ──────────────────────────────────────────────────────────
+
+STDOUT_FILE=$(mktemp)
+STDERR_FILE=$(mktemp)
+trap 'rm -f "$STDOUT_FILE" "$STDERR_FILE"' EXIT
+
+# Determine runner
+RUNNER=""
+case "$SCRIPT_NAME" in
+  *.mjs) RUNNER="node" ;;
+  *.sh)  RUNNER="bash" ;;
+  *)     RUNNER="" ;;
+esac
+
+if [[ -n "$RUNNER" ]]; then
+  $RUNNER "$SCRIPT_PATH" ${SCRIPT_ARGS[@]+"${SCRIPT_ARGS[@]}"} > "$STDOUT_FILE" 2> "$STDERR_FILE"
+else
+  "$SCRIPT_PATH" ${SCRIPT_ARGS[@]+"${SCRIPT_ARGS[@]}"} > "$STDOUT_FILE" 2> "$STDERR_FILE"
+fi
+EXIT_CODE=$?
+
+# ── Output ───────────────────────────────────────────────────────────
+
+# Always show stdout
+cat "$STDOUT_FILE"
+
+if [[ $EXIT_CODE -eq 0 ]]; then
+  # Success — show stderr as warnings if any
+  if [[ -s "$STDERR_FILE" ]]; then
+    echo ""
+    echo -e "${YELLOW}Warnings (stderr):${NC}"
+    cat "$STDERR_FILE"
+  fi
+  exit 0
+fi
+
+# ── Failure diagnostic ───────────────────────────────────────────────
+
+STDERR_CONTENT=$(cat "$STDERR_FILE")
+
+echo ""
+echo -e "${RED}┌─ SCRIPT FAILURE ─────────────────────────────────────────┐${NC}"
+echo -e "${RED}│ Script:    ${SCRIPT_NAME} ${SCRIPT_ARGS[*]+"${SCRIPT_ARGS[*]}"}${NC}"
+echo -e "${RED}│ Exit Code: ${EXIT_CODE}${NC}"
+echo -e "${RED}│${NC}"
+
+# Show stderr (truncated to 20 lines)
+if [[ -n "$STDERR_CONTENT" ]]; then
+  echo -e "${RED}│ Stderr:${NC}"
+  echo "$STDERR_CONTENT" | head -20 | while IFS= read -r line; do
+    echo -e "${RED}│   ${line}${NC}"
+  done
+  STDERR_LINES=$(echo "$STDERR_CONTENT" | wc -l | tr -d ' ')
+  if [[ "$STDERR_LINES" -gt 20 ]]; then
+    echo -e "${RED}│   ... (${STDERR_LINES} total lines, truncated)${NC}"
+  fi
+else
+  echo -e "${RED}│ Stderr:    (empty)${NC}"
+fi
+
+echo -e "${RED}│${NC}"
+
+# ── Diagnosis ────────────────────────────────────────────────────────
+
+echo -e "${RED}│ Diagnosis:${NC}"
+
+# Check common root causes
+if echo "$STDERR_CONTENT" | grep -qi "state.json not found\|state.json missing"; then
+  echo -e "${RED}│   Missing state.json — sprint was never initialized${NC}"
+  echo -e "${RED}│${NC}"
+  echo -e "${RED}│ Fix: Run ./.vbounce/scripts/init_sprint.mjs S-XX D-XX --stories STORY-IDS${NC}"
+
+elif echo "$STDERR_CONTENT" | grep -qi "not valid JSON\|Unexpected token\|SyntaxError"; then
+  echo -e "${RED}│   state.json is corrupted (invalid JSON)${NC}"
+  echo -e "${RED}│${NC}"
+  echo -e "${RED}│ Fix: Run ./.vbounce/scripts/validate_state.mjs to see errors,${NC}"
+  echo -e "${RED}│      then repair or regenerate with init_sprint.mjs${NC}"
+
+elif echo "$STDERR_CONTENT" | grep -qi "not found in state.json\|not found in stories"; then
+  echo -e "${RED}│   Story ID not registered in state.json${NC}"
+  echo -e "${RED}│${NC}"
+  echo -e "${RED}│ Fix: Verify the story ID, or add it via update_state.mjs${NC}"
+
+elif echo "$STDERR_CONTENT" | grep -qi "ENOENT\|no such file"; then
+  echo -e "${RED}│   A required file or directory is missing${NC}"
+  echo -e "${RED}│${NC}"
+  echo -e "${RED}│ Fix: Run ./.vbounce/scripts/doctor.mjs to identify missing files${NC}"
+
+elif echo "$STDERR_CONTENT" | grep -qi "permission denied\|EACCES"; then
+  echo -e "${RED}│   Permission denied on a file or directory${NC}"
+  echo -e "${RED}│${NC}"
+  echo -e "${RED}│ Fix: Check file permissions — shell scripts may need chmod +x${NC}"
+
+elif [[ $EXIT_CODE -eq 1 ]]; then
+  echo -e "${RED}│   Script reported failure (exit 1) — check stderr above${NC}"
+  echo -e "${RED}│${NC}"
+  echo -e "${RED}│ Fix: Run ./.vbounce/scripts/doctor.mjs for a full health check${NC}"
+
+else
+  echo -e "${RED}│   Unexpected exit code ${EXIT_CODE}${NC}"
+  echo -e "${RED}│${NC}"
+  echo -e "${RED}│ Fix: Run ./.vbounce/scripts/doctor.mjs for a full health check${NC}"
+fi
+
+echo -e "${RED}└──────────────────────────────────────────────────────────┘${NC}"
+
+exit $EXIT_CODE

package/scripts/update_state.mjs

@@ -16,16 +16,12 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { validateState } from './validate_state.mjs';
+import { VALID_STATES } from './constants.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '../..');
 const STATE_FILE = path.join(ROOT, '.vbounce', 'state.json');
 
-const VALID_STATES = [
-  'Draft', 'Refinement', 'Ready to Bounce', 'Bouncing',
-  'QA Passed', 'Architect Passed', 'Done', 'Escalated', 'Parking Lot'
-];
-
 function readState() {
   if (!fs.existsSync(STATE_FILE)) {
     console.error(`ERROR: ${STATE_FILE} not found. Run: vbounce sprint init S-XX D-XX`);

package/scripts/validate_state.mjs

@@ -10,16 +10,12 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { VALID_STATES } from './constants.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '../..');
 const STATE_FILE = path.join(ROOT, '.vbounce', 'state.json');
 
-const VALID_STATES = [
-  'Draft', 'Refinement', 'Ready to Bounce', 'Bouncing',
-  'QA Passed', 'Architect Passed', 'Done', 'Escalated', 'Parking Lot'
-];
-
 /**
  * Validates a state object. Returns { valid, errors }.
  * @param {object} state

package/skills/agent-team/SKILL.md

@@ -184,6 +184,14 @@ Examples:
    git checkout -b sprint/S-01 main
    mkdir -p .vbounce/archive
 
+1b. Initialize sprint state (MANDATORY):
+   ./.vbounce/scripts/run_script.sh init_sprint.mjs S-{XX} D-{NN} --stories STORY-ID1,STORY-ID2,...
+   - Extract story IDs and delivery ID from the confirmed Sprint Plan §1 table
+   - This creates .vbounce/state.json — required by all downstream scripts
+   - If state.json already exists for this sprint, the script will warn and overwrite
+   - Verify success: run_script.sh validate_state.mjs
+   - If this step fails, DO NOT proceed — no scripts will work without state.json
+
 2. Verify Sprint Plan:
    - Sprint Plan status must be "Confirmed" (human-approved in Phase 2)
    - §0 Sprint Readiness Gate must be fully checked
@@ -197,13 +205,13 @@ Examples:
 4. **Hotfix Path** (L1 Trivial tasks only — triaged during Phase 1):
    a. Create `HOTFIX-{Date}-{Name}.md` using the template.
    b. Delegate to Developer (no worktree needed if acting on active branch).
-   c. Developer runs `hotfix_manager.sh ledger "{Title}" "{Description}"` after implementation.
+   c. Developer runs `run_script.sh hotfix_manager.sh ledger "{Title}" "{Description}"` after implementation.
    d. Human/Lead verifies manually.
-   e. DevOps runs `hotfix_manager.sh sync` to update any active story worktrees.
+   e. DevOps runs `run_script.sh hotfix_manager.sh sync` to update any active story worktrees.
    f. Update Delivery Plan Status to "Done".
 
 5. **Gate Config Check**:
-   - If `.vbounce/gate-checks.json` does not exist, run `./.vbounce/scripts/init_gate_config.sh` to auto-detect the project stack and generate default gate checks.
+   - If `.vbounce/gate-checks.json` does not exist, run `./.vbounce/scripts/run_script.sh init_gate_config.sh` to auto-detect the project stack and generate default gate checks.
    - If it exists, verify it's current (stack detection may have changed).
 
 6. **Parallel Readiness Check** (before bouncing multiple stories simultaneously):
@@ -267,7 +275,7 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.vbounce/{tasks,reports}
 ### Step 3: QA Pass
 ```
 0. Run pre-QA gate scan:
-   ./.vbounce/scripts/pre_gate_runner.sh qa .worktrees/STORY-{ID}-{StoryName}/ sprint/S-{XX}
+   ./.vbounce/scripts/run_script.sh pre_gate_runner.sh qa .worktrees/STORY-{ID}-{StoryName}/ sprint/S-{XX}
    - If scan FAILS on trivial issues (debug statements, missing JSDoc, TODOs):
      Return to Developer for quick fix. Do NOT spawn QA for mechanical failures.
      If pre-gate scan fails 3+ times → Escalate: present failures to human with options:
@@ -293,7 +301,7 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.vbounce/{tasks,reports}
 ### Step 4: Architect Pass
 ```
 0. Run pre-Architect gate scan:
-   ./.vbounce/scripts/pre_gate_runner.sh arch .worktrees/STORY-{ID}-{StoryName}/ sprint/S-{XX}
+   ./.vbounce/scripts/run_script.sh pre_gate_runner.sh arch .worktrees/STORY-{ID}-{StoryName}/ sprint/S-{XX}
    - If scan reveals new dependencies or structural violations:
      Return to Developer for resolution. Do NOT spawn Architect for mechanical failures.
      If pre-gate scan fails 3+ times → Escalate to human (same options as pre-QA escalation).
@@ -315,6 +323,13 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.vbounce/{tasks,reports}
 
 ### Step 5: Story Merge (DevOps)
 ```
+0. Verify gate reports exist (MANDATORY before merge):
+   - Dev report:  .worktrees/STORY-{ID}-{StoryName}/.vbounce/reports/STORY-{ID}-{StoryName}-dev*.md
+   - QA report:   .worktrees/STORY-{ID}-{StoryName}/.vbounce/reports/STORY-{ID}-{StoryName}-qa*.md
+   - Arch report: .worktrees/STORY-{ID}-{StoryName}/.vbounce/reports/STORY-{ID}-{StoryName}-arch*.md
+   If ANY report is missing, DO NOT proceed with merge.
+   Return to Lead with: which reports are missing and which agents need to re-run.
+   (Fast Track stories skip QA/Arch — only Dev report required.)
 1. Spawn devops subagent with:
    - Story ID and sprint branch name
    - All gate reports (QA PASS + Architect PASS)
@@ -375,7 +390,7 @@ This phase gives ad-hoc post-delivery feedback a proper home. Without it, users
 After ALL stories are merged into `sprint/S-01`:
 ```
 1. Spawn architect subagent on sprint/S-01 branch
-2. First, Architect runs `./.vbounce/scripts/hotfix_manager.sh audit` to check for hotfix drift. If it fails, perform deep audit on flagged files.
+2. First, Architect runs `./.vbounce/scripts/run_script.sh hotfix_manager.sh audit` to check for hotfix drift. If it fails, perform deep audit on flagged files.
 3. Run Sprint Integration Audit — Deep Audit on combined changes
 4. Check for: duplicate routes, competing state, overlapping migrations
 5. If issues found:
@@ -423,14 +438,14 @@ After ALL stories are merged into `sprint/S-01`:
 7. **Framework Self-Assessment** (aggregated from agent reports):
    - Collect all `## Process Feedback` sections from agent reports in `.vbounce/archive/S-{XX}/`
    - Populate §5 Framework Self-Assessment tables in the Sprint Report by category
-   - **Always run** `suggest_improvements.mjs` — every sprint, unconditionally. First sprints generate the most friction.
+   - **Always run** `run_script.sh suggest_improvements.mjs` — every sprint, unconditionally. First sprints generate the most friction.
    - **Verbally present** the top improvement suggestions to the user. Do NOT just embed them in the report — tell the user directly:
      - Summarize each P0/P1 suggestion in plain language (what's broken, why it matters, what to change)
      - For P2/P3 suggestions, give a brief list and note they're in `.vbounce/improvement-suggestions.md`
      - Ask the user: *"Want me to run `/improve` to apply any of these?"*
    - If user approves → read `.vbounce/skills/improve/SKILL.md` and execute the improvement process
 8. Product Documentation check (runs on `main` after sprint merge):
-   a. **Staleness Detection** — run `./.vbounce/scripts/vdoc_staleness.mjs S-{XX}`
+   a. **Staleness Detection** — run `./.vbounce/scripts/run_script.sh vdoc_staleness.mjs S-{XX}`
       - Cross-references all Dev Reports' `files_modified` against manifest key files
       - Generates `.vbounce/scribe-task-S-{XX}.md` with targeted list of stale docs
       - Populates Sprint Report §1 "Product Docs Affected" table
@@ -558,8 +573,50 @@ If merging story branch into sprint branch creates conflicts:
 
 ---
 
+## Script Execution Protocol
+
+**All `.vbounce/scripts/*` invocations MUST go through the wrapper:**
+
+```bash
+./.vbounce/scripts/run_script.sh <script-name> [args...]
+```
+
+**Never call scripts directly.** The wrapper captures exit codes, stdout, and stderr separately, runs pre-flight checks (e.g. state.json existence), and on failure prints a structured diagnostic block with root cause and suggested fix.
+
+### When a Script Fails
+
+1. **Stop the current step.** Do not retry blindly or continue as if the script succeeded.
+2. **Read the diagnostic block.** The wrapper prints the exit code, stderr, root cause, and a suggested fix.
+3. **Attempt self-repair (once).** If the fix is within the agent's capability:
+   - Missing `state.json` → run `run_script.sh init_sprint.mjs S-{XX} D-{XX} --stories {IDS}`
+   - Invalid JSON → run `run_script.sh validate_state.mjs`, repair, retry
+   - Missing file/directory → run `run_script.sh doctor.mjs`, fix what's reported, retry
+   - Permission denied → `chmod +x` the script, retry
+4. **Re-run through the wrapper.** If the retry succeeds, continue the step. Log the failure and fix in the agent report under `## Script Incidents`.
+5. **Escalate if retry fails.** Write a **Script Failure Report** in the agent report and return it to the Lead:
+
+```markdown
+## Script Incidents
+
+### [FAIL] {script_name} {args}
+- **Exit code:** {N}
+- **Stderr:** {first 10 lines}
+- **Root cause:** {from diagnostic block or agent analysis}
+- **Self-repair attempted:** {what was tried}
+- **Status:** Resolved / Escalated
+- **Suggested fix:** {if escalated — what the Lead or human should do}
+```
+
+6. **Lead routes escalated failures:**
+   - Infrastructure issue (missing state, corrupt config) → Lead fixes and re-delegates
+   - Script bug → Lead presents to human with the Script Failure Report and the diagnostic output
+   - Repeated failure (same script fails 3+ times across stories) → Flag in Sprint Report §5 Framework Self-Assessment as a **Blocker**
+
+---
+
 ## Critical Rules
 
+- **All scripts go through run_script.sh.** Never invoke `.vbounce/scripts/*.mjs` or `*.sh` directly. The wrapper provides error capture, pre-flight validation, and structured diagnostics that agents depend on for self-repair.
 - **The Lead never writes code.** It plans, delegates, monitors, and consolidates.
 - **Enforce Sequential Dependencies.** Never parallelize stories where one depends on the other. Wait for merge.
 - **One story = one worktree.** Never mix stories in a single worktree.