@sandrinio/vbounce 1.6.0 → 1.7.0

package/scripts/prep_qa_context.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * prep_qa_context.mjs
+ * Generates a QA context pack for a story.
+ *
+ * Usage:
+ *   ./scripts/prep_qa_context.mjs STORY-005-02
+ *
+ * Output: .bounce/qa-context-STORY-005-02.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 storyId = process.argv[2];
+if (!storyId) {
+  console.error('Usage: prep_qa_context.mjs STORY-ID');
+  process.exit(1);
+}
+
+const MAX_CONTEXT_LINES = 300;
+
+function findFilesMatching(dir, pattern) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) results.push(...findFilesMatching(full, pattern));
+    else if (pattern.test(e.name)) results.push(full);
+  }
+  return results;
+}
+
+// 1. Find dev report (required)
+const devReportPattern = new RegExp(`${storyId.replace(/[-]/g, '[-]')}.*-dev\\.md$`);
+const searchDirs = [
+  path.join(ROOT, '.worktrees', storyId, '.bounce', 'reports'),
+  path.join(ROOT, '.bounce', 'reports'),
+  path.join(ROOT, '.bounce', 'archive'),
+];
+let devReport = null;
+for (const dir of searchDirs) {
+  const matches = findFilesMatching(dir, devReportPattern);
+  if (matches.length > 0) { devReport = matches[0]; break; }
+}
+
+if (!devReport) {
+  console.error(`ERROR: Dev report not found for ${storyId}. Searched in:`);
+  searchDirs.forEach(d => console.error(`  - ${d}`));
+  process.exit(1);
+}
+
+// Parse dev report frontmatter
+let devFm = {};
+try {
+  const devContent = fs.readFileSync(devReport, 'utf8');
+  const fmMatch = devContent.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (fmMatch) devFm = yaml.load(fmMatch[1]) || {};
+} catch (e) {
+  console.error(`ERROR: Dev report has invalid YAML frontmatter — ${e.message}`);
+  process.exit(1);
+}
+
+// 2. Find story spec (required)
+const storySpecPattern = new RegExp(`${storyId.replace(/[-]/g, '[-]')}.*\\.md$`);
+const storySpecMatches = findFilesMatching(path.join(ROOT, 'product_plans'), storySpecPattern);
+if (storySpecMatches.length === 0) {
+  console.error(`ERROR: Story spec not found for ${storyId} in product_plans/`);
+  process.exit(1);
+}
+const storySpecFile = storySpecMatches[0];
+const storyContent = fs.readFileSync(storySpecFile, 'utf8');
+
+// Extract §2 acceptance criteria
+const criteriaMatch = storyContent.match(/##\s*(2\.|§2|The Truth|Acceptance)[^\n]*\n([\s\S]*?)(?=\n##|\n---|\Z)/i);
+const criteriaSection = criteriaMatch ? criteriaMatch[2].trim().split('\n').slice(0, 30).join('\n') : '_Could not extract §2 — read story spec directly_';
+
+// 3. Read LESSONS.md
+const lessonsFile = path.join(ROOT, 'LESSONS.md');
+let lessonsExcerpt = '_No LESSONS.md found_';
+if (fs.existsSync(lessonsFile)) {
+  const lines = fs.readFileSync(lessonsFile, 'utf8').split('\n');
+  lessonsExcerpt = lines.slice(0, 30).join('\n');
+  if (lines.length > 30) lessonsExcerpt += `\n_(+${lines.length - 30} more lines)_`;
+}
+
+// 4. Format files modified list
+const filesModified = Array.isArray(devFm.files_modified)
+  ? devFm.files_modified.map(f => `- ${f}`).join('\n')
+  : '_Not specified in dev report_';
+
+// 5. Assemble context pack
+const lines = [
+  `# QA Context: ${storyId}`,
+  `> Generated: ${new Date().toISOString().split('T')[0]}`,
+  `> Dev report: ${path.relative(ROOT, devReport)}`,
+  `> Story spec: ${path.relative(ROOT, storySpecFile)}`,
+  '',
+  `## Dev Report Summary`,
+  `| Field | Value |`,
+  `|-------|-------|`,
+  `| Status | ${devFm.status || '—'} |`,
+  `| Correction Tax | ${devFm.correction_tax || '—'} |`,
+  `| Tests Written | ${devFm.tests_written ?? '—'} |`,
+  `| Lessons Flagged | ${devFm.lessons_flagged || 'none'} |`,
+  '',
+  `## Story Acceptance Criteria (§2)`,
+  criteriaSection,
+  '',
+  `## Files Modified`,
+  filesModified,
+  '',
+  `## Relevant Lessons`,
+  lessonsExcerpt,
+];
+
+const output = lines.join('\n');
+const outputLines = output.split('\n');
+let finalOutput = output;
+if (outputLines.length > MAX_CONTEXT_LINES) {
+  finalOutput = outputLines.slice(0, MAX_CONTEXT_LINES).join('\n');
+  finalOutput += `\n\n> ⚠ Truncated at ${MAX_CONTEXT_LINES} lines. Read source files for complete content.`;
+}
+
+const outputFile = path.join(ROOT, '.bounce', `qa-context-${storyId}.md`);
+fs.writeFileSync(outputFile, finalOutput);
+console.log(`✓ QA context pack written to .bounce/qa-context-${storyId}.md`);

package/scripts/prep_sprint_context.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * prep_sprint_context.mjs
+ * Generates a sprint context pack — single file replacing 6+ separate reads.
+ *
+ * Usage:
+ *   ./scripts/prep_sprint_context.mjs S-05
+ *
+ * Output: .bounce/sprint-context-S-05.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: prep_sprint_context.mjs S-XX');
+  process.exit(1);
+}
+
+const MAX_CONTEXT_LINES = 200;
+
+// 1. Read state.json (required)
+const stateFile = path.join(ROOT, '.bounce', 'state.json');
+if (!fs.existsSync(stateFile)) {
+  console.error('ERROR: .bounce/state.json not found. Run: vbounce sprint init');
+  process.exit(1);
+}
+const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+
+// 2. Find sprint plan
+const sprintNum = sprintId.replace('S-', '');
+const sprintPlanPath = path.join(ROOT, 'product_plans', 'sprints', `sprint-${sprintNum}`, `sprint-${sprintNum}.md`);
+if (!fs.existsSync(sprintPlanPath)) {
+  console.error(`ERROR: Sprint plan not found at ${sprintPlanPath}`);
+  process.exit(1);
+}
+const sprintPlan = fs.readFileSync(sprintPlanPath, 'utf8');
+
+// Extract sprint goal from frontmatter
+const goalMatch = sprintPlan.match(/sprint_goal:\s*"([^"]+)"/);
+const sprintGoal = goalMatch ? goalMatch[1] : 'TBD';
+
+// 3. Read LESSONS.md (first 50 lines)
+const lessonsFile = path.join(ROOT, 'LESSONS.md');
+let lessonsExcerpt = '_No LESSONS.md found_';
+if (fs.existsSync(lessonsFile)) {
+  const lines = fs.readFileSync(lessonsFile, 'utf8').split('\n');
+  lessonsExcerpt = lines.slice(0, 50).join('\n');
+  if (lines.length > 50) lessonsExcerpt += `\n\n_(${lines.length - 50} more lines — read LESSONS.md for full content)_`;
+}
+
+// 4. Find RISK_REGISTRY
+let riskExcerpt = '_No RISK_REGISTRY.md found_';
+const riskPaths = [
+  path.join(ROOT, 'product_plans', 'strategy', 'RISK_REGISTRY.md'),
+  path.join(ROOT, 'RISK_REGISTRY.md'),
+];
+for (const rp of riskPaths) {
+  if (fs.existsSync(rp)) {
+    const lines = fs.readFileSync(rp, 'utf8').split('\n');
+    riskExcerpt = lines.slice(0, 20).join('\n');
+    if (lines.length > 20) riskExcerpt += `\n\n_(${lines.length - 20} more lines — read RISK_REGISTRY.md for full content)_`;
+    break;
+  }
+}
+
+// 5. Build story state table from state.json
+const storyRows = Object.entries(state.stories || {})
+  .map(([id, s]) => `| ${id} | ${s.state} | ${s.qa_bounces} | ${s.arch_bounces} | ${s.worktree || '—'} |`)
+  .join('\n');
+
+// 6. Assemble context pack
+const lines = [
+  `# Sprint Context: ${sprintId}`,
+  `> Generated: ${new Date().toISOString().split('T')[0]} | Sprint: ${sprintId} | Delivery: ${state.delivery_id}`,
+  '',
+  `## Sprint Plan Summary`,
+  `- **Goal**: ${sprintGoal}`,
+  `- **Phase**: ${state.phase || 'N/A'}`,
+  `- **Last action**: ${state.last_action || 'N/A'}`,
+  `- **Stories**: ${Object.keys(state.stories || {}).length}`,
+  '',
+  `## Current State`,
+  `| Story | State | QA Bounces | Arch Bounces | Worktree |`,
+  `|-------|-------|------------|--------------|----------|`,
+  storyRows || '| (no stories) | — | — | — | — |',
+  '',
+  `## Relevant Lessons`,
+  lessonsExcerpt,
+  '',
+  `## Risk Summary`,
+  riskExcerpt,
+];
+
+const output = lines.join('\n');
+const outputLines = output.split('\n');
+
+let finalOutput = output;
+let truncated = false;
+if (outputLines.length > MAX_CONTEXT_LINES) {
+  finalOutput = outputLines.slice(0, MAX_CONTEXT_LINES).join('\n');
+  finalOutput += `\n\n> ⚠ Context pack truncated at ${MAX_CONTEXT_LINES} lines (was ${outputLines.length}). Read source files for complete content.`;
+  truncated = true;
+}
+
+// 7. Write output
+const outputFile = path.join(ROOT, '.bounce', `sprint-context-${sprintId}.md`);
+fs.writeFileSync(outputFile, finalOutput);
+
+console.log(`✓ Sprint context pack written to .bounce/sprint-context-${sprintId}.md`);
+if (truncated) console.warn(`  ⚠  Content was truncated (exceeded ${MAX_CONTEXT_LINES} lines)`);
+console.log(`  Stories: ${Object.keys(state.stories || {}).length} | Phase: ${state.phase || 'N/A'}`);

package/scripts/prep_sprint_summary.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+/**
+ * prep_sprint_summary.mjs
+ * Generates sprint metrics summary from archived agent reports.
+ *
+ * Usage:
+ *   ./scripts/prep_sprint_summary.mjs S-05
+ *
+ * Output: .bounce/sprint-summary-S-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 sprintId = process.argv[2];
+if (!sprintId) {
+  console.error('Usage: prep_sprint_summary.mjs S-XX');
+  process.exit(1);
+}
+
+const archiveDir = path.join(ROOT, '.bounce', 'archive', sprintId);
+if (!fs.existsSync(archiveDir)) {
+  console.error(`ERROR: Archive directory not found: ${archiveDir}`);
+  console.error('No archived reports found for ' + sprintId);
+  process.exit(1);
+}
+
+function findReports(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) results.push(...findReports(full));
+    else if (e.name.endsWith('.md')) results.push(full);
+  }
+  return results;
+}
+
+const allReports = findReports(archiveDir);
+if (allReports.length === 0) {
+  console.error(`ERROR: No reports found in ${archiveDir}`);
+  process.exit(1);
+}
+
+function parseFm(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (match) return yaml.load(match[1]) || {};
+  } catch {}
+  return {};
+}
+
+// Categorize reports
+const devReports = allReports.filter(f => /-dev(-bounce\d+)?\.md$/.test(f));
+const qaReports = allReports.filter(f => /-qa(-bounce\d+)?\.md$/.test(f));
+const archReports = allReports.filter(f => /-arch(-bounce\d+)?\.md$/.test(f));
+
+// Extract unique story IDs
+const storyIds = new Set();
+const storyPattern = /(STORY-[\w-]+)-(?:dev|qa|arch|devops)/;
+for (const r of allReports) {
+  const m = path.basename(r).match(storyPattern);
+  if (m) storyIds.add(m[1]);
+}
+
+// Metrics
+let totalTokens = 0;
+let totalQaBounces = 0;
+let totalArchBounces = 0;
+let correctionTaxSum = 0;
+let correctionTaxCount = 0;
+let firstPassCount = 0;
+let escalatedCount = 0;
+const storyMetrics = {};
+
+for (const id of storyIds) {
+  storyMetrics[id] = { qaBounces: 0, archBounces: 0, correctionTax: 0, done: false };
+}
+
+for (const r of devReports) {
+  const fm = parseFm(r);
+  if (fm.tokens_used) totalTokens += fm.tokens_used;
+  const tax = parseFloat(String(fm.correction_tax || '0').replace('%', ''));
+  if (!isNaN(tax)) { correctionTaxSum += tax; correctionTaxCount++; }
+  const m = path.basename(r).match(storyPattern);
+  if (m && storyMetrics[m[1]]) storyMetrics[m[1]].correctionTax = tax;
+}
+
+for (const r of qaReports) {
+  const fm = parseFm(r);
+  if (fm.tokens_used) totalTokens += fm.tokens_used;
+  if (fm.status === 'FAIL') {
+    const m = path.basename(r).match(storyPattern);
+    if (m && storyMetrics[m[1]]) storyMetrics[m[1]].qaBounces++;
+    totalQaBounces++;
+  }
+}
+
+for (const r of archReports) {
+  const fm = parseFm(r);
+  if (fm.tokens_used) totalTokens += fm.tokens_used;
+  if (fm.status === 'FAIL') {
+    const m = path.basename(r).match(storyPattern);
+    if (m && storyMetrics[m[1]]) storyMetrics[m[1]].archBounces++;
+    totalArchBounces++;
+  }
+}
+
+for (const [id, m] of Object.entries(storyMetrics)) {
+  if (m.qaBounces === 0) firstPassCount++;
+}
+
+const totalStories = storyIds.size;
+const avgCorrectionTax = correctionTaxCount > 0 ? (correctionTaxSum / correctionTaxCount).toFixed(1) : '0.0';
+const firstPassRate = totalStories > 0 ? ((firstPassCount / totalStories) * 100).toFixed(0) : '0';
+
+// Build story breakdown table
+const storyBreakdownRows = [...storyIds].map(id => {
+  const m = storyMetrics[id];
+  return `| ${id} | ${m.qaBounces} | ${m.archBounces} | ${m.correctionTax}% |`;
+}).join('\n');
+
+const output = [
+  `# Sprint Summary: ${sprintId}`,
+  `> Generated: ${new Date().toISOString().split('T')[0]}`,
+  '',
+  `## Metrics`,
+  `| Metric | Value |`,
+  `|--------|-------|`,
+  `| Total Stories | ${totalStories} |`,
+  `| First-Pass Rate | ${firstPassRate}% |`,
+  `| Total QA Bounces | ${totalQaBounces} |`,
+  `| Total Arch Bounces | ${totalArchBounces} |`,
+  `| Avg Correction Tax | ${avgCorrectionTax}% |`,
+  `| Total Tokens Used | ${totalTokens.toLocaleString()} |`,
+  '',
+  `## Story Breakdown`,
+  `| Story | QA Bounces | Arch Bounces | Correction Tax |`,
+  `|-------|------------|--------------|----------------|`,
+  storyBreakdownRows || '| (no stories) | — | — | — |',
+].join('\n');
+
+const outputFile = path.join(ROOT, '.bounce', `sprint-summary-${sprintId}.md`);
+fs.writeFileSync(outputFile, output);
+console.log(`✓ Sprint summary written to .bounce/sprint-summary-${sprintId}.md`);
+console.log(`  Stories: ${totalStories} | First-pass: ${firstPassRate}% | Total tokens: ${totalTokens.toLocaleString()}`);

package/scripts/sprint_trends.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+/**
+ * sprint_trends.mjs
+ * Cross-sprint trend analysis from archived reports.
+ *
+ * Usage:
+ *   ./scripts/sprint_trends.mjs
+ *
+ * Output: .bounce/trends.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 archiveBase = path.join(ROOT, '.bounce', 'archive');
+
+if (!fs.existsSync(archiveBase)) {
+  console.log('No sprint history found (.bounce/archive/ does not exist)');
+  process.exit(0);
+}
+
+const sprintDirs = fs.readdirSync(archiveBase)
+  .filter(d => /^S-\d{2}$/.test(d))
+  .sort();
+
+if (sprintDirs.length === 0) {
+  console.log('No sprint history found (no S-XX directories in .bounce/archive/)');
+  process.exit(0);
+}
+
+function findReports(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) results.push(...findReports(full));
+    else if (e.name.endsWith('.md')) results.push(full);
+  }
+  return results;
+}
+
+function parseFm(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (match) return yaml.load(match[1]) || {};
+  } catch {}
+  return {};
+}
+
+const sprintStats = [];
+const rootCauseCounts = {};
+
+for (const sprintId of sprintDirs) {
+  const sprintDir = path.join(archiveBase, sprintId);
+  const reports = findReports(sprintDir);
+
+  const storyIds = new Set();
+  const pattern = /(STORY-[\w-]+)-(?:dev|qa|arch|devops)/;
+  for (const r of reports) {
+    const m = path.basename(r).match(pattern);
+    if (m) storyIds.add(m[1]);
+  }
+
+  let qaFails = 0, archFails = 0, firstPassCount = 0;
+  let correctionTaxSum = 0, correctionTaxCount = 0, totalTokens = 0;
+  const storyQaBounces = {};
+
+  for (const r of reports) {
+    const fm = parseFm(r);
+    if (fm.tokens_used) totalTokens += fm.tokens_used;
+
+    const bn = path.basename(r);
+    if (/-qa(-bounce\d+)?\.md$/.test(bn) && fm.status === 'FAIL') {
+      qaFails++;
+      const m = bn.match(pattern);
+      if (m) storyQaBounces[m[1]] = (storyQaBounces[m[1]] || 0) + 1;
+
+      // Collect root causes
+      if (fm.root_cause) {
+        rootCauseCounts[fm.root_cause] = rootCauseCounts[fm.root_cause] || {};
+        rootCauseCounts[fm.root_cause][sprintId] = (rootCauseCounts[fm.root_cause][sprintId] || 0) + 1;
+      }
+    }
+    if (/-arch(-bounce\d+)?\.md$/.test(bn) && fm.status === 'FAIL') {
+      archFails++;
+      if (fm.root_cause) {
+        rootCauseCounts[fm.root_cause] = rootCauseCounts[fm.root_cause] || {};
+        rootCauseCounts[fm.root_cause][sprintId] = (rootCauseCounts[fm.root_cause][sprintId] || 0) + 1;
+      }
+    }
+    if (/-dev\.md$/.test(bn)) {
+      const tax = parseFloat(String(fm.correction_tax || '0').replace('%', ''));
+      if (!isNaN(tax)) { correctionTaxSum += tax; correctionTaxCount++; }
+    }
+  }
+
+  for (const [id] of Object.entries(storyQaBounces)) {
+    if (!storyQaBounces[id]) firstPassCount++;
+  }
+  // Stories with no QA failures = first pass
+  for (const id of storyIds) {
+    if (!storyQaBounces[id]) firstPassCount++;
+  }
+
+  const totalStories = storyIds.size;
+  const firstPassRate = totalStories > 0 ? Math.round((firstPassCount / totalStories) * 100) : 100;
+  const avgBounces = totalStories > 0 ? ((qaFails + archFails) / totalStories).toFixed(2) : '0.00';
+  const avgTax = correctionTaxCount > 0 ? (correctionTaxSum / correctionTaxCount).toFixed(1) : '0.0';
+
+  sprintStats.push({ sprintId, totalStories, firstPassRate, avgBounces, avgTax, totalTokens });
+}
+
+// Build process health table
+const healthRows = sprintStats.map(s =>
+  `| ${s.sprintId} | ${s.totalStories} | ${s.firstPassRate}% | ${s.avgBounces} | ${s.avgTax}% | ${s.totalTokens.toLocaleString()} |`
+).join('\n');
+
+// Build root cause table if data available
+let rootCauseSection = '';
+const allCauses = Object.keys(rootCauseCounts);
+if (allCauses.length > 0) {
+  const causeRows = allCauses.map(cause => {
+    const counts = sprintDirs.map(s => rootCauseCounts[cause][s] || 0);
+    return `| ${cause} | ${counts.join(' | ')} |`;
+  });
+  rootCauseSection = [
+    '',
+    `## Bounce Root Causes`,
+    `| Category | ${sprintDirs.join(' | ')} |`,
+    `|----------|${sprintDirs.map(() => '---').join('|')}|`,
+    ...causeRows,
+  ].join('\n');
+}
+
+const output = [
+  `# V-Bounce Trends`,
+  `> Generated: ${new Date().toISOString().split('T')[0]} | Sprints analyzed: ${sprintDirs.join(', ')}`,
+  '',
+  `## Process Health`,
+  `| Sprint | Stories | First-Pass Rate | Avg Bounces | Avg Correction Tax | Total Tokens |`,
+  `|--------|---------|----------------|-------------|-------------------|--------------|`,
+  healthRows || '| (no data) | — | — | — | — | — |',
+  rootCauseSection,
+  '',
+  `---`,
+  `Run \`vbounce suggest S-XX\` to generate improvement recommendations based on this data.`,
+].join('\n');
+
+const outputFile = path.join(ROOT, '.bounce', 'trends.md');
+fs.writeFileSync(outputFile, output);
+console.log(`✓ Trends written to .bounce/trends.md`);
+console.log(`  Sprints analyzed: ${sprintDirs.join(', ')}`);