@sandrinio/vbounce 1.5.0 → 1.7.0

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(', ')}`);

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);
+}