vbounce-engine 2.5.1

package/scripts/validate_bounce_readiness.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+/**
+ * validate_bounce_readiness.mjs
+ * Pre-bounce gate check — verifies a story is ready to bounce.
+ *
+ * Usage:
+ *   ./.vbounce/scripts/validate_bounce_readiness.mjs STORY-005-02
+ */
+
+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, '../..');
+
+const storyId = process.argv[2];
+if (!storyId) {
+  console.error('Usage: validate_bounce_readiness.mjs STORY-ID');
+  process.exit(1);
+}
+
+const errors = [];
+const warnings = [];
+
+// 1. Check state.json
+const stateFile = path.join(ROOT, '.vbounce', 'state.json');
+if (!fs.existsSync(stateFile)) {
+  errors.push('.vbounce/state.json not found — run: vbounce sprint init S-XX D-XX');
+} else {
+  const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  if (!state.stories[storyId]) {
+    errors.push(`Story "${storyId}" not found in state.json`);
+  } else {
+    const story = state.stories[storyId];
+    if (story.state !== 'Ready to Bounce') {
+      errors.push(`Story state is "${story.state}" — must be "Ready to Bounce" before bouncing`);
+    }
+  }
+}
+
+// 2. Find sprint plan
+const sprintsDir = path.join(ROOT, 'product_plans', 'sprints');
+let sprintPlanFound = false;
+if (fs.existsSync(sprintsDir)) {
+  const sprintDirs = fs.readdirSync(sprintsDir);
+  for (const dir of sprintDirs) {
+    const planFile = path.join(sprintsDir, dir, `${dir}.md`);
+    if (fs.existsSync(planFile)) {
+      sprintPlanFound = true;
+      break;
+    }
+  }
+}
+if (!sprintPlanFound) {
+  warnings.push('No active Sprint Plan found in product_plans/sprints/');
+}
+
+// 3. Find story spec
+let storyFile = null;
+function findFile(dir, id) {
+  if (!fs.existsSync(dir)) return null;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      const found = findFile(path.join(dir, e.name), id);
+      if (found) return found;
+    } else if (e.name.includes(id)) {
+      return path.join(dir, e.name);
+    }
+  }
+  return null;
+}
+
+storyFile = findFile(path.join(ROOT, 'product_plans'), storyId);
+if (!storyFile) {
+  errors.push(`Story spec not found for "${storyId}" in product_plans/`);
+} else {
+  const storyContent = fs.readFileSync(storyFile, 'utf8');
+
+  // Check for §1, §2, §3
+  const hasSpec = /##\s*(1\.|§1|The Spec)/i.test(storyContent);
+  const hasCriteria = /##\s*(2\.|§2|The Truth|Acceptance)/i.test(storyContent);
+  const hasGuide = /##\s*(3\.|§3|Implementation)/i.test(storyContent);
+
+  if (!hasSpec) errors.push(`Story ${storyId}: §1 (spec) section not found`);
+  if (!hasCriteria) errors.push(`Story ${storyId}: §2 (acceptance criteria) section not found`);
+  if (!hasGuide) errors.push(`Story ${storyId}: §3 (implementation guide) section not found`);
+
+  // Check for minimum content in each section
+  const specMatch = storyContent.match(/##\s*(1\.|§1|The Spec)[^\n]*\n([\s\S]*?)(?=\n##|\n---|\Z)/i);
+  if (specMatch && specMatch[2].trim().length < 30) {
+    warnings.push(`Story ${storyId}: §1 spec section appears very short — verify it's complete`);
+  }
+}
+
+// 4. Check worktree
+const worktreeDir = path.join(ROOT, '.worktrees', storyId);
+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('');
+
+if (errors.length === 0 && warnings.length === 0) {
+  console.log(`✓ ${storyId} is READY TO BOUNCE`);
+  process.exit(0);
+}
+
+if (warnings.length > 0) {
+  warnings.forEach(w => console.warn(`  ⚠  ${w}`));
+}
+
+if (errors.length > 0) {
+  errors.forEach(e => console.error(`  ✗ ${e}`));
+  console.error(`\nNOT READY: Fix ${errors.length} error(s) before bouncing ${storyId}`);
+  process.exit(1);
+} else {
+  console.log(`  ✓ ${storyId} is ready (with warnings)`);
+  process.exit(0);
+}

package/scripts/validate_report.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+/**
+ * validate_report.mjs
+ * 
+ * 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.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+// Defined schemas for each report type
+const ROOT_CAUSE_ENUM = [
+    'missing_tests', 'missing_validation', 'spec_ambiguity', 'adr_violation',
+    'gold_plating', 'logic_error', 'integration_gap', 'type_error',
+    'state_management', 'error_handling', 'coupling', 'duplication'
+];
+
+const SCHEMAS = {
+    dev: ['status', 'correction_tax', 'tokens_used', 'tests_written', 'files_modified', 'lessons_flagged'],
+    qa: {
+        base: ['status', 'bounce_count', 'tokens_used', 'bugs_found', 'gold_plating_detected'],
+        conditional: { 'FAIL': ['failed_scenarios', 'root_cause'] }
+    },
+    arch: {
+        base: ['status', 'tokens_used'],
+        conditional: { 'PASS': ['safe_zone_score', 'ai_isms_detected', 'regression_risk'], 'FAIL': ['bounce_count', 'critical_failures', 'root_cause'] }
+    },
+    devops: {
+        base: ['type', 'status', 'tokens_used'],
+        conditional: { 'story-merge': ['conflicts_detected'], 'sprint-release': ['version'] }
+    },
+    scribe: ['mode', 'tokens_used', 'docs_created', 'docs_updated', 'docs_removed']
+};
+
+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 validateBugsArray(bugs, prefix) {
+    if (!Array.isArray(bugs)) throw new Error(`${prefix}: 'bugs' must be an array.`);
+    bugs.forEach((bug, i) => {
+        const bugRequired = ['scenario', 'expected', 'actual', 'files', 'severity'];
+        const bugMissing = bugRequired.filter(k => !(k in bug));
+        if (bugMissing.length > 0) throw new Error(`${prefix}: bugs[${i}] missing keys: ${bugMissing.join(', ')}`);
+        if (!Array.isArray(bug.files)) throw new Error(`${prefix}: bugs[${i}].files must be an array.`);
+        const validSeverities = ['Critical', 'High', 'Medium', 'Low'];
+        if (!validSeverities.includes(bug.severity)) throw new Error(`${prefix}: bugs[${i}].severity must be one of: ${validSeverities.join(', ')}`);
+    });
+}
+
+function validateFailuresArray(failures, prefix) {
+    if (!Array.isArray(failures)) throw new Error(`${prefix}: 'failures' must be an array.`);
+    const validDimensions = ['Architectural Consistency', 'Error Handling', 'Data Flow', 'Duplication', 'Test Quality', 'Coupling'];
+    failures.forEach((f, i) => {
+        const fRequired = ['dimension', 'severity', 'what_wrong', 'fix_required'];
+        const fMissing = fRequired.filter(k => !(k in f));
+        if (fMissing.length > 0) throw new Error(`${prefix}: failures[${i}] missing keys: ${fMissing.join(', ')}`);
+        if (!validDimensions.includes(f.dimension)) throw new Error(`${prefix}: failures[${i}].dimension must be one of: ${validDimensions.join(', ')}`);
+    });
+}
+
+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(', ')}`);
+        if (data.root_cause && !ROOT_CAUSE_ENUM.includes(data.root_cause)) {
+            throw new Error(`QA_SCHEMA_ERROR: Invalid root_cause '${data.root_cause}'. Must be one of: ${ROOT_CAUSE_ENUM.join(', ')}`);
+        }
+        if ('bugs' in data) validateBugsArray(data.bugs, 'QA_SCHEMA_ERROR');
+    }
+}
+
+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(', ')}`);
+    if (s === 'FAIL' && data.root_cause && !ROOT_CAUSE_ENUM.includes(data.root_cause)) {
+        throw new Error(`ARCH_SCHEMA_ERROR: Invalid root_cause '${data.root_cause}'. Must be one of: ${ROOT_CAUSE_ENUM.join(', ')}`);
+    }
+    if (s === 'FAIL' && 'failures' in data) validateFailuresArray(data.failures, 'ARCH_SCHEMA_ERROR');
+}
+
+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';
+    else if (filename.endsWith('-scribe.md')) agentType = 'scribe';
+
+    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);
+        if (agentType === 'scribe') {
+            const missing = SCHEMAS.scribe.filter(k => !(k in data));
+            if (missing.length > 0) throw new Error(`SCRIBE_SCHEMA_ERROR: Missing required keys: ${missing.join(', ')}`);
+        }
+
+        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/validate_sprint_plan.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * validate_sprint_plan.mjs
+ * Validates a Sprint Plan markdown file structure and cross-checks with state.json.
+ *
+ * Usage:
+ *   ./.vbounce/scripts/validate_sprint_plan.mjs product_plans/sprints/sprint-05/sprint-05.md
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '../..');
+
+const filePath = process.argv[2];
+if (!filePath) {
+  console.error('Usage: validate_sprint_plan.mjs <path-to-sprint-plan.md>');
+  process.exit(1);
+}
+
+const absPath = path.resolve(filePath);
+if (!fs.existsSync(absPath)) {
+  console.error(`ERROR: File not found: ${absPath}`);
+  process.exit(1);
+}
+
+const content = fs.readFileSync(absPath, 'utf8');
+const errors = [];
+const warnings = [];
+
+// 1. Extract YAML frontmatter
+const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+if (!fmMatch) {
+  errors.push('Missing YAML frontmatter (--- delimiters)');
+} else {
+  let fm;
+  try {
+    fm = yaml.load(fmMatch[1]);
+  } catch (e) {
+    errors.push(`Invalid YAML frontmatter: ${e.message}`);
+    fm = {};
+  }
+
+  const required = ['sprint_id', 'sprint_goal', 'dates', 'status', 'delivery'];
+  for (const f of required) {
+    if (!fm[f]) errors.push(`Frontmatter missing required field: "${f}"`);
+  }
+
+  // 2. Cross-check with state.json
+  const stateFile = path.join(ROOT, '.vbounce', 'state.json');
+  if (fs.existsSync(stateFile)) {
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+
+    // Find story IDs in §1 table
+    const tableRowRegex = /\|\s*\d+\s*\|\s*\[?(STORY-[\w-]+)/g;
+    const planStoryIds = new Set();
+    let m;
+    while ((m = tableRowRegex.exec(content)) !== null) {
+      planStoryIds.add(m[1]);
+    }
+
+    const stateStoryIds = new Set(Object.keys(state.stories || {}));
+
+    // Check for stories in plan but not in state
+    for (const id of planStoryIds) {
+      if (!stateStoryIds.has(id)) {
+        warnings.push(`Story ${id} is in Sprint Plan §1 but NOT in state.json`);
+      }
+    }
+
+    // Check for stories in state but not in plan
+    for (const id of stateStoryIds) {
+      if (!planStoryIds.has(id)) {
+        warnings.push(`Story ${id} is in state.json but NOT in Sprint Plan §1`);
+      }
+    }
+  }
+
+  // 3. Check §4 Execution Log if sprint is Completed
+  if (fm.status === 'Completed') {
+    if (!content.includes('<!-- EXECUTION_LOG_START -->') && !content.includes('## 4.') && !content.includes('## §4')) {
+      errors.push('Sprint is Completed but §4 Execution Log section is missing');
+    }
+  }
+}
+
+// 4. Check §1 table columns
+if (!content.includes('| Priority |') && !content.includes('|Priority|')) {
+  errors.push('§1 Active Scope table missing or malformed (expected "Priority" column header)');
+}
+if (!content.includes('V-Bounce State')) {
+  errors.push('§1 Active Scope table missing "V-Bounce State" column');
+}
+
+// Print results
+console.log(`Validating: ${filePath}`);
+if (errors.length === 0 && warnings.length === 0) {
+  console.log('✓ Sprint Plan is valid');
+  process.exit(0);
+}
+
+if (warnings.length > 0) {
+  console.warn('Warnings:');
+  warnings.forEach(w => console.warn(`  ⚠  ${w}`));
+}
+
+if (errors.length > 0) {
+  console.error('Errors:');
+  errors.forEach(e => console.error(`  ✗ ${e}`));
+  process.exit(1);
+} else {
+  process.exit(0);
+}

package/scripts/validate_state.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+/**
+ * validate_state.mjs
+ * Validates .vbounce/state.json schema.
+ * Usage: ./scripts/validate_state.mjs
+ * Also exportable: import { validateState } from './validate_state.mjs'
+ */
+
+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, '../..');
+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
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateState(state) {
+  const errors = [];
+
+  if (!state || typeof state !== 'object') {
+    return { valid: false, errors: ['state.json must be a JSON object'] };
+  }
+
+  if (!state.sprint_id || !/^S-\d{2}$/.test(state.sprint_id)) {
+    errors.push(`sprint_id "${state.sprint_id}" must match S-XX format (e.g. S-05)`);
+  }
+
+  if (!state.delivery_id || !/^D-\d{2}$/.test(state.delivery_id)) {
+    errors.push(`delivery_id "${state.delivery_id}" must match D-NN format (e.g. D-02)`);
+  }
+
+  if (!state.stories || typeof state.stories !== 'object') {
+    errors.push('stories field must be an object');
+  } else {
+    for (const [id, story] of Object.entries(state.stories)) {
+      if (!VALID_STATES.includes(story.state)) {
+        errors.push(`Story ${id}: invalid state "${story.state}". Must be one of: ${VALID_STATES.join(', ')}`);
+      }
+      if (typeof story.qa_bounces !== 'number' || !Number.isInteger(story.qa_bounces) || story.qa_bounces < 0) {
+        errors.push(`Story ${id}: qa_bounces must be a non-negative integer, got "${story.qa_bounces}"`);
+      }
+      if (typeof story.arch_bounces !== 'number' || !Number.isInteger(story.arch_bounces) || story.arch_bounces < 0) {
+        errors.push(`Story ${id}: arch_bounces must be a non-negative integer, got "${story.arch_bounces}"`);
+      }
+      if (story.state === 'Done' && story.worktree) {
+        errors.push(`Story ${id}: state is "Done" but worktree "${story.worktree}" is still set (should be null)`);
+      }
+    }
+  }
+
+  if (state.updated_at) {
+    const d = new Date(state.updated_at);
+    if (isNaN(d.getTime())) {
+      errors.push(`updated_at "${state.updated_at}" is not a valid ISO 8601 timestamp`);
+    }
+  } else {
+    errors.push('updated_at field is required');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// CLI entry point
+if (process.argv[1] && fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]))) {
+  if (!fs.existsSync(STATE_FILE)) {
+    console.error(`ERROR: ${STATE_FILE} not found. Run: vbounce sprint init S-XX D-XX`);
+    process.exit(1);
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+  } catch (e) {
+    console.error(`ERROR: state.json is not valid JSON — ${e.message}`);
+    process.exit(1);
+  }
+
+  const { valid, errors } = validateState(state);
+
+  if (valid) {
+    console.log(`VALID: state.json — sprint ${state.sprint_id}, ${Object.keys(state.stories || {}).length} stories`);
+    process.exit(0);
+  } else {
+    console.error('INVALID: state.json has errors:');
+    errors.forEach(e => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+}