@sandrinio/vbounce 1.6.0 → 1.7.0

package/scripts/suggest_improvements.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * suggest_improvements.mjs
+ * Generates improvement suggestions from sprint trends + lessons.
+ * Overwrites (not appends) to prevent stale suggestion accumulation.
+ *
+ * Usage:
+ *   ./scripts/suggest_improvements.mjs S-05
+ *
+ * Output: .bounce/improvement-suggestions.md
+ */
+
+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 sprintId = process.argv[2];
+if (!sprintId) {
+  console.error('Usage: suggest_improvements.mjs S-XX');
+  process.exit(1);
+}
+
+const today = new Date().toISOString().split('T')[0];
+
+// 1. Read trends if available
+const trendsFile = path.join(ROOT, '.bounce', 'trends.md');
+let trendsContent = null;
+if (fs.existsSync(trendsFile)) {
+  trendsContent = fs.readFileSync(trendsFile, 'utf8');
+}
+
+// 2. Read LESSONS.md
+const lessonsFile = path.join(ROOT, 'LESSONS.md');
+let lessonCount = 0;
+let oldLessons = [];
+if (fs.existsSync(lessonsFile)) {
+  const lines = fs.readFileSync(lessonsFile, 'utf8').split('\n');
+  // Count lessons by counting ### entries
+  const lessonEntries = lines.filter(l => /^###\s+\[\d{4}-\d{2}-\d{2}\]/.test(l));
+  lessonCount = lessonEntries.length;
+
+  // Flag lessons older than 90 days
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - 90);
+  oldLessons = lessonEntries.filter(entry => {
+    const dateMatch = entry.match(/\[(\d{4}-\d{2}-\d{2})\]/);
+    if (dateMatch) {
+      return new Date(dateMatch[1]) < cutoff;
+    }
+    return false;
+  });
+}
+
+// 3. Read improvement-log for rejected items (to avoid re-suggesting)
+const improvementLog = path.join(ROOT, '.bounce', 'improvement-log.md');
+let rejectedItems = [];
+if (fs.existsSync(improvementLog)) {
+  const logContent = fs.readFileSync(improvementLog, 'utf8');
+  // Simple extraction: look for table rows in "Rejected" section
+  const rejectedMatch = logContent.match(/## Rejected\n[\s\S]*?(?=\n## |$)/);
+  if (rejectedMatch) {
+    rejectedItems = rejectedMatch[0].split('\n')
+      .filter(l => l.startsWith('|') && !l.startsWith('| Sprint'))
+      .map(l => l.split('|')[2]?.trim())
+      .filter(Boolean);
+  }
+}
+
+// 4. Parse sprint stats from trends
+let lastSprintStats = null;
+if (trendsContent) {
+  const rows = trendsContent.split('\n').filter(l => l.match(/^\| S-\d{2} \|/));
+  if (rows.length > 0) {
+    const lastRow = rows[rows.length - 1].split('|').map(s => s.trim()).filter(Boolean);
+    lastSprintStats = {
+      sprintId: lastRow[0],
+      stories: parseInt(lastRow[1]) || 0,
+      firstPassRate: parseInt(lastRow[2]) || 100,
+      avgBounces: parseFloat(lastRow[3]) || 0,
+      avgTax: parseFloat(lastRow[4]) || 0,
+    };
+  }
+}
+
+const suggestions = [];
+let itemNum = 1;
+
+// 5. Generate suggestions based on data
+if (lastSprintStats) {
+  if (lastSprintStats.firstPassRate < 80) {
+    suggestions.push({
+      num: itemNum++,
+      category: 'Process',
+      title: `Low first-pass rate (${lastSprintStats.firstPassRate}%)`,
+      detail: `First-pass rate was below 80% in ${lastSprintStats.sprintId}. This suggests spec ambiguity or insufficient context packs.`,
+      recommendation: 'Add spec quality gate to `validate_bounce_readiness.mjs`: check Story §1 word count > 50 and §2 has ≥ 2 Gherkin scenarios.',
+      target: 'scripts/validate_bounce_readiness.mjs',
+      effort: 'Low',
+    });
+  }
+
+  if (lastSprintStats.avgTax > 10) {
+    suggestions.push({
+      num: itemNum++,
+      category: 'Process',
+      title: `High correction tax (${lastSprintStats.avgTax}% average)`,
+      detail: 'Average correction tax exceeded 10%, indicating significant human intervention was needed.',
+      recommendation: 'Auto-flag stories with more than 3 files expected in Sprint Plan §2 Risk Flags. Consider splitting before bouncing.',
+      target: 'skills/agent-team/SKILL.md Step 1',
+      effort: 'Low',
+    });
+  }
+
+  if (lastSprintStats.avgBounces > 0.5) {
+    suggestions.push({
+      num: itemNum++,
+      category: 'Process',
+      title: `High bounce rate (${lastSprintStats.avgBounces} avg per story)`,
+      detail: 'Run `vbounce trends` to see root cause breakdown and identify recurring patterns.',
+      recommendation: 'Review root_cause field in archived QA/Arch FAIL reports to identify systemic issues.',
+      target: 'scripts/sprint_trends.mjs',
+      effort: 'Low',
+    });
+  }
+}
+
+// Old lessons suggestion
+if (oldLessons.length > 0) {
+  const notRejected = oldLessons.filter(l => !rejectedItems.some(r => l.includes(r)));
+  if (notRejected.length > 0) {
+    suggestions.push({
+      num: itemNum++,
+      category: 'Framework',
+      title: `${notRejected.length} lessons older than 90 days`,
+      detail: notRejected.map(l => `  - ${l}`).join('\n'),
+      recommendation: 'Review these lessons. Lessons not triggered in 3+ sprints should be archived to LESSONS_ARCHIVE.md. Lessons proven over 3+ sprints should be graduated to agent configs.',
+      target: 'LESSONS.md',
+      effort: 'Trivial',
+    });
+  }
+}
+
+// General framework suggestions
+suggestions.push({
+  num: itemNum++,
+  category: 'Framework',
+  title: 'Review lesson graduation candidates',
+  detail: `You have ${lessonCount} lessons in LESSONS.md. Lessons proven over 3+ sprints should graduate to permanent agent config rules.`,
+  recommendation: 'Run a review: which lessons have prevented recurrences for 3+ sprints? Graduate those to `.claude/agents/*.md` or `brains/claude-agents/*.md`.',
+  target: 'LESSONS.md + brains/claude-agents/',
+  effort: 'Low',
+});
+
+suggestions.push({
+  num: itemNum++,
+  category: 'Health',
+  title: 'Run vbounce doctor',
+  detail: 'Verify the V-Bounce OS installation is healthy after this sprint.',
+  recommendation: 'Run: `vbounce doctor` — checks brain files, templates, scripts, state.json validity.',
+  target: 'scripts/doctor.mjs',
+  effort: 'Trivial',
+});
+
+// 6. Format output
+const suggestionBlocks = suggestions.map(s => {
+  const rejectedNote = rejectedItems.some(r => s.title.includes(r)) ? '\n> ⚠ This was previously rejected — skipping.' : '';
+  return `### ${s.num}. [${s.category}] ${s.title}${rejectedNote}
+${s.detail}
+
+**Recommendation:** ${s.recommendation}
+**Target:** \`${s.target}\`
+**Effort:** ${s.effort}`;
+}).join('\n\n---\n\n');
+
+const output = [
+  `# Improvement Suggestions (post ${sprintId})`,
+  `> Generated: ${today}. Review each item. Approved items are applied by the Lead at sprint boundary.`,
+  `> Rejected items go to \`.bounce/improvement-log.md\` with reason.`,
+  `> Applied items go to \`.bounce/improvement-log.md\` under Applied.`,
+  '',
+  suggestionBlocks || '_No suggestions generated — all metrics look healthy!_',
+  '',
+  '---',
+  '',
+  `## How to Apply`,
+  `- **Approve** → Lead applies change, records in \`.bounce/improvement-log.md\` under Applied`,
+  `- **Reject** → Record in \`.bounce/improvement-log.md\` under Rejected with reason`,
+  `- **Defer** → Record in \`.bounce/improvement-log.md\` under Deferred`,
+  '',
+  `> Framework changes (brains/, skills/, templates/) are applied at sprint boundaries only — never mid-sprint.`,
+].join('\n');
+
+const outputFile = path.join(ROOT, '.bounce', 'improvement-suggestions.md');
+fs.writeFileSync(outputFile, output); // overwrite, not append
+console.log(`✓ Improvement suggestions written to .bounce/improvement-suggestions.md`);
+console.log(`  ${suggestions.length} suggestion(s) generated`);

package/scripts/update_state.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+/**
+ * update_state.mjs
+ * Updates .bounce/state.json atomically at every V-Bounce state transition.
+ *
+ * Usage:
+ *   ./scripts/update_state.mjs STORY-005-02 "QA Passed"
+ *   ./scripts/update_state.mjs STORY-005-02 --qa-bounce
+ *   ./scripts/update_state.mjs STORY-005-02 --arch-bounce
+ *   ./scripts/update_state.mjs --set-phase "Phase 3"
+ *   ./scripts/update_state.mjs --set-action "QA FAIL on STORY-005-02, bouncing back to Dev"
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { validateState } from './validate_state.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const STATE_FILE = path.join(ROOT, '.bounce', '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`);
+    process.exit(1);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+  } catch (e) {
+    console.error(`ERROR: state.json is not valid JSON — ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function writeState(state) {
+  state.updated_at = new Date().toISOString();
+  const { valid, errors } = validateState(state);
+  if (!valid) {
+    console.error('ERROR: Would write invalid state:');
+    errors.forEach(e => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+  fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.error('Usage:');
+  console.error('  update_state.mjs STORY-ID "New State"');
+  console.error('  update_state.mjs STORY-ID --qa-bounce');
+  console.error('  update_state.mjs STORY-ID --arch-bounce');
+  console.error('  update_state.mjs --set-phase "Phase N"');
+  console.error('  update_state.mjs --set-action "description"');
+  process.exit(1);
+}
+
+const state = readState();
+
+// Global flags
+if (args[0] === '--set-phase') {
+  state.phase = args[1];
+  writeState(state);
+  console.log(`✓ Phase set to: ${args[1]}`);
+  process.exit(0);
+}
+
+if (args[0] === '--set-action') {
+  state.last_action = args[1];
+  writeState(state);
+  console.log(`✓ Last action set to: ${args[1]}`);
+  process.exit(0);
+}
+
+if (args[0] === '--show') {
+  console.log(JSON.stringify(state, null, 2));
+  process.exit(0);
+}
+
+// Story-specific updates
+const storyId = args[0];
+if (!state.stories) {
+  console.error('ERROR: state.json has no stories field');
+  process.exit(1);
+}
+if (!state.stories[storyId]) {
+  console.error(`ERROR: Story "${storyId}" not found in state.json`);
+  console.error(`Known stories: ${Object.keys(state.stories).join(', ')}`);
+  process.exit(1);
+}
+
+const flag = args[1];
+
+if (flag === '--qa-bounce') {
+  state.stories[storyId].qa_bounces = (state.stories[storyId].qa_bounces || 0) + 1;
+  state.last_action = `QA bounce on ${storyId} (total: ${state.stories[storyId].qa_bounces})`;
+  writeState(state);
+  console.log(`✓ ${storyId} QA bounces: ${state.stories[storyId].qa_bounces}`);
+
+} else if (flag === '--arch-bounce') {
+  state.stories[storyId].arch_bounces = (state.stories[storyId].arch_bounces || 0) + 1;
+  state.last_action = `Architect bounce on ${storyId} (total: ${state.stories[storyId].arch_bounces})`;
+  writeState(state);
+  console.log(`✓ ${storyId} Arch bounces: ${state.stories[storyId].arch_bounces}`);
+
+} else if (flag) {
+  // New state
+  if (!VALID_STATES.includes(flag)) {
+    console.error(`ERROR: Invalid state "${flag}"`);
+    console.error(`Valid states: ${VALID_STATES.join(', ')}`);
+    process.exit(1);
+  }
+  const prev = state.stories[storyId].state;
+  state.stories[storyId].state = flag;
+  if (flag === 'Done') {
+    state.stories[storyId].worktree = null;
+  }
+  state.last_action = `${storyId}: ${prev} → ${flag}`;
+  writeState(state);
+  console.log(`✓ ${storyId}: ${prev} → ${flag}`);
+
+} else {
+  console.error('ERROR: Specify a state or flag (--qa-bounce, --arch-bounce)');
+  process.exit(1);
+}

package/scripts/validate_bounce_readiness.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * validate_bounce_readiness.mjs
+ * Pre-bounce gate check — verifies a story is ready to bounce.
+ *
+ * Usage:
+ *   ./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, '.bounce', 'state.json');
+if (!fs.existsSync(stateFile)) {
+  errors.push('.bounce/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`);
+}
+
+// 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

@@ -13,15 +13,21 @@ 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'] }
+        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'] }
+        conditional: { 'PASS': ['safe_zone_score', 'ai_isms_detected', 'regression_risk'], 'FAIL': ['bounce_count', 'critical_failures', 'root_cause'] }
     },
     devops: {
         base: ['type', 'status', 'tokens_used'],
@@ -45,6 +51,29 @@ function validateDev(data) {
     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(', ')}`);
@@ -52,6 +81,10 @@ function validateQA(data) {
     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');
     }
 }
 
@@ -62,6 +95,10 @@ function validateArch(data) {
     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) {

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:
+ *   ./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, '.bounce', '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);
+}