vbounce-engine 2.5.1

package/scripts/close_sprint.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * close_sprint.mjs
+ * Sprint close automation — validates, archives, updates state.json.
+ *
+ * Usage:
+ *   ./.vbounce/scripts/close_sprint.mjs S-05
+ */
+
+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 < 1) {
+  console.error('Usage: close_sprint.mjs S-XX');
+  process.exit(1);
+}
+
+const sprintId = args[0];
+if (!/^S-\d{2}$/.test(sprintId)) {
+  console.error(`ERROR: sprint_id "${sprintId}" must match S-XX format`);
+  process.exit(1);
+}
+
+const sprintNum = sprintId.replace('S-', '');
+const stateFile = path.join(ROOT, '.vbounce', 'state.json');
+
+// 1. Read state.json
+if (!fs.existsSync(stateFile)) {
+  console.error(`ERROR: .vbounce/state.json not found`);
+  process.exit(1);
+}
+
+const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+
+if (state.sprint_id !== sprintId) {
+  console.error(`ERROR: state.json is for sprint ${state.sprint_id}, not ${sprintId}`);
+  process.exit(1);
+}
+
+// 2. Check all stories are terminal
+const activeStories = Object.entries(state.stories || {}).filter(
+  ([, s]) => !['Done', 'Escalated', 'Parking Lot'].includes(s.state)
+);
+
+if (activeStories.length > 0) {
+  console.warn(`⚠  ${activeStories.length} stories are not in a terminal state:`);
+  activeStories.forEach(([id, s]) => console.warn(`   - ${id}: ${s.state}`));
+  console.warn('   Proceed? These stories will be left incomplete.');
+}
+
+// 3. Create archive directory
+const archiveDir = path.join(ROOT, '.vbounce', 'archive', sprintId);
+fs.mkdirSync(archiveDir, { recursive: true });
+
+// 4. Move sprint report if it exists
+const reportSrc = path.join(ROOT, '.vbounce', `sprint-report-${sprintId}.md`);
+const reportLegacy = path.join(ROOT, '.vbounce', 'sprint-report.md');
+const reportDst = path.join(archiveDir, `sprint-report-${sprintId}.md`);
+
+if (fs.existsSync(reportSrc)) {
+  fs.copyFileSync(reportSrc, reportDst);
+  console.log(`✓ Archived sprint report → .vbounce/archive/${sprintId}/sprint-report-${sprintId}.md`);
+} else if (fs.existsSync(reportLegacy)) {
+  fs.copyFileSync(reportLegacy, reportDst);
+  console.log(`✓ Archived sprint report → .vbounce/archive/${sprintId}/sprint-report-${sprintId}.md`);
+}
+
+// 5. Update state.json
+state.last_action = `Sprint ${sprintId} closed`;
+state.updated_at = new Date().toISOString();
+fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+console.log(`✓ Updated state.json`);
+
+// 6. Print manual steps
+const sprintPlanPath = `product_plans/sprints/sprint-${sprintNum}`;
+const archivePath = `product_plans/archive/sprints/sprint-${sprintNum}`;
+
+// 7. Auto-run improvement pipeline
+console.log('');
+console.log('Running self-improvement pipeline...');
+const suggestScript = path.join(__dirname, 'suggest_improvements.mjs');
+if (fs.existsSync(suggestScript)) {
+  // Run trends first (if available)
+  const trendsScript = path.join(__dirname, 'sprint_trends.mjs');
+  if (fs.existsSync(trendsScript)) {
+    const trendsResult = spawnSync(process.execPath, [trendsScript], {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+    });
+    if (trendsResult.status !== 0) {
+      console.warn('  ⚠ Trends analysis returned non-zero — continuing.');
+    }
+  }
+
+  // Run suggest (which internally runs post_sprint_improve.mjs)
+  const suggestResult = spawnSync(process.execPath, [suggestScript, sprintId], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+  if (suggestResult.status !== 0) {
+    console.warn('  ⚠ Improvement suggestions returned non-zero.');
+  }
+} else {
+  console.warn('  ⚠ suggest_improvements.mjs not found — skipping improvement pipeline.');
+}
+
+// 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: process.cwd() });
+  if (graphResult.status === 0) {
+    console.log('✓ Product graph regenerated');
+  }
+}
+
+console.log('');
+console.log('Manual steps remaining:');
+console.log(`  1. Archive sprint plan folder:`);
+console.log(`     mv ${sprintPlanPath}/ ${archivePath}/`);
+console.log(`  2. Update Delivery Plan §4 Completed Sprints with a summary row`);
+console.log(`  3. Remove delivered stories from Delivery Plan §3 Backlog`);
+console.log(`  4. Delete sprint branch (after merge to main):`);
+console.log(`     git branch -d sprint/${sprintId}`);
+console.log(`  5. Review .vbounce/improvement-suggestions.md — approve/reject/defer each item`);
+console.log(`  6. Run /improve to apply approved changes with brain-file sync`);
+console.log('');
+console.log(`✓ Sprint ${sprintId} closed.`);

package/scripts/complete_story.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+/**
+ * complete_story.mjs
+ * Mark a story as Done — updates Sprint Plan §1 + §4, and state.json atomically.
+ *
+ * Usage:
+ *   ./.vbounce/scripts/complete_story.mjs STORY-005-02 --qa-bounces 1 --arch-bounces 0 --correction-tax 5 --notes "Missing validation fixed"
+ */
+
+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, '../..');
+
+function parseArgs(argv) {
+  const result = { storyId: null, qaBounces: 0, archBounces: 0, correctionTax: '0%', notes: '' };
+  const args = argv.slice(2);
+  result.storyId = args[0];
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--qa-bounces') result.qaBounces = parseInt(args[++i], 10) || 0;
+    else if (args[i] === '--arch-bounces') result.archBounces = parseInt(args[++i], 10) || 0;
+    else if (args[i] === '--correction-tax') result.correctionTax = args[++i] + (args[i].includes('%') ? '' : '%');
+    else if (args[i] === '--notes') result.notes = args[++i];
+  }
+  return result;
+}
+
+const { storyId, qaBounces, archBounces, correctionTax, notes } = parseArgs(process.argv);
+
+if (!storyId) {
+  console.error('Usage: complete_story.mjs STORY-ID [--qa-bounces N] [--arch-bounces N] [--correction-tax N] [--notes "text"]');
+  process.exit(1);
+}
+
+// 1. Update state.json
+const stateFile = path.join(ROOT, '.vbounce', 'state.json');
+if (!fs.existsSync(stateFile)) {
+  console.error('ERROR: .vbounce/state.json not found');
+  process.exit(1);
+}
+const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+if (!state.stories[storyId]) {
+  console.error(`ERROR: Story "${storyId}" not found in state.json`);
+  process.exit(1);
+}
+state.stories[storyId].state = 'Done';
+state.stories[storyId].qa_bounces = qaBounces;
+state.stories[storyId].arch_bounces = archBounces;
+state.stories[storyId].worktree = null;
+state.last_action = `${storyId} completed`;
+state.updated_at = new Date().toISOString();
+fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+console.log(`✓ Updated state.json: ${storyId} → Done`);
+
+// 2. Find sprint plan
+const sprintNum = state.sprint_id.replace('S-', '');
+const sprintPlanPath = path.join(ROOT, 'product_plans', 'sprints', `sprint-${sprintNum}`, `sprint-${sprintNum}.md`);
+
+if (!fs.existsSync(sprintPlanPath)) {
+  console.warn(`⚠  Sprint plan not found at ${sprintPlanPath}. Update §1 and §4 manually.`);
+  process.exit(0);
+}
+
+let content = fs.readFileSync(sprintPlanPath, 'utf8');
+
+// 3. Update §1 table — find the row with storyId and change V-Bounce State to Done
+const tableRowRegex = new RegExp(`(\\|[^|]*\\|[^|]*${storyId.replace(/[-]/g, '[-]')}[^|]*\\|[^|]*\\|[^|]*\\|)([^|]+)(\\|[^|]*\\|)`, 'g');
+let updated = false;
+content = content.replace(tableRowRegex, (match, before, stateCell, after) => {
+  updated = true;
+  return `${before} Done ${after}`;
+});
+
+if (!updated) {
+  console.warn(`⚠  Could not find ${storyId} row in §1 table. Update V-Bounce State manually.`);
+}
+
+// 4. Add row to §4 Execution Log
+const logStart = '<!-- EXECUTION_LOG_START -->';
+const logEnd = '<!-- EXECUTION_LOG_END -->';
+const newRow = `| ${storyId} | Done | ${qaBounces} | ${archBounces} | ${correctionTax} | ${notes || '—'} |`;
+
+if (content.includes(logStart)) {
+  // Find the table in the execution log section and append a row
+  const startIdx = content.indexOf(logStart);
+  const endIdx = content.indexOf(logEnd);
+
+  if (endIdx > startIdx) {
+    const before = content.substring(0, endIdx);
+    const after = content.substring(endIdx);
+
+    // Check if header row exists, if not add it
+    const section = before.substring(startIdx);
+    if (!section.includes('| Story |')) {
+      const headerRow = `\n| Story | Final State | QA Bounces | Arch Bounces | Correction Tax | Notes |\n|-------|-------------|------------|--------------|----------------|-------|`;
+      content = before + headerRow + '\n' + newRow + '\n' + after;
+    } else {
+      content = before + newRow + '\n' + after;
+    }
+    console.log(`✓ Added row to §4 Execution Log`);
+  }
+} else {
+  // Append §4 section at end
+  content += `\n\n<!-- EXECUTION_LOG_START -->\n## 4. Execution Log\n\n| Story | Final State | QA Bounces | Arch Bounces | Correction Tax | Notes |\n|-------|-------------|------------|--------------|----------------|-------|\n${newRow}\n<!-- EXECUTION_LOG_END -->\n`;
+  console.log(`✓ Created §4 Execution Log with first row`);
+}
+
+fs.writeFileSync(sprintPlanPath, content);
+console.log(`✓ Updated sprint plan: ${storyId} Done`);
+console.log(`\n  QA bounces: ${qaBounces} | Arch bounces: ${archBounces} | Correction tax: ${correctionTax}`);
+
+// 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');
+}