@sandrinio/vbounce 1.6.0 → 1.7.0

package/scripts/close_sprint.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * close_sprint.mjs
+ * Sprint close automation — validates, archives, updates state.json.
+ *
+ * Usage:
+ *   ./scripts/close_sprint.mjs S-05
+ */
+
+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 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, '.bounce', 'state.json');
+
+// 1. Read state.json
+if (!fs.existsSync(stateFile)) {
+  console.error(`ERROR: .bounce/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, '.bounce', 'archive', sprintId);
+fs.mkdirSync(archiveDir, { recursive: true });
+
+// 4. Move sprint report if it exists
+const reportSrc = path.join(ROOT, '.bounce', `sprint-report-${sprintId}.md`);
+const reportLegacy = path.join(ROOT, '.bounce', '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 → .bounce/archive/${sprintId}/sprint-report-${sprintId}.md`);
+} else if (fs.existsSync(reportLegacy)) {
+  fs.copyFileSync(reportLegacy, reportDst);
+  console.log(`✓ Archived sprint report → .bounce/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}`;
+
+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. Run: vbounce trends && vbounce suggest ${sprintId}`);
+console.log('');
+console.log(`✓ Sprint ${sprintId} closed.`);

package/scripts/complete_story.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+/**
+ * complete_story.mjs
+ * Mark a story as Done — updates Sprint Plan §1 + §4, and state.json atomically.
+ *
+ * Usage:
+ *   ./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';
+
+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, '.bounce', 'state.json');
+if (!fs.existsSync(stateFile)) {
+  console.error('ERROR: .bounce/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}`);

package/scripts/doctor.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * doctor.mjs
+ * V-Bounce OS Health Check — validates all configs, templates, state files
+ * Usage: vbounce doctor
+ */
+
+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 checks = [];
+let issueCount = 0;
+
+function pass(msg) {
+  checks.push(`  ✓ ${msg}`);
+}
+
+function fail(msg, fix) {
+  checks.push(`  ✗ ${msg}${fix ? `\n    → Fix: ${fix}` : ''}`);
+  issueCount++;
+}
+
+function warn(msg) {
+  checks.push(`  ⚠ ${msg}`);
+}
+
+// Check LESSONS.md
+if (fs.existsSync(path.join(ROOT, 'LESSONS.md'))) {
+  pass('LESSONS.md exists');
+} else {
+  fail('LESSONS.md missing', 'Create LESSONS.md at project root');
+}
+
+// Check templates
+const requiredTemplates = ['sprint.md', 'delivery_plan.md', 'sprint_report.md', 'story.md', 'epic.md', 'charter.md', 'roadmap.md', 'risk_registry.md'];
+const templatesDir = path.join(ROOT, 'templates');
+let templateCount = 0;
+for (const t of requiredTemplates) {
+  if (fs.existsSync(path.join(templatesDir, t))) templateCount++;
+  else fail(`templates/${t} missing`, `Create from V-Bounce OS template`);
+}
+if (templateCount === requiredTemplates.length) pass(`templates/ complete (${templateCount}/${requiredTemplates.length})`);
+
+// Check .bounce directory
+if (fs.existsSync(path.join(ROOT, '.bounce'))) {
+  pass('.bounce/ directory exists');
+
+  // Check state.json
+  const stateFile = path.join(ROOT, '.bounce', 'state.json');
+  if (fs.existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      pass(`state.json valid (sprint ${state.sprint_id}, ${Object.keys(state.stories || {}).length} stories)`);
+    } catch (e) {
+      fail('state.json exists but is invalid JSON', 'Run: vbounce validate state');
+    }
+  } else {
+    warn('state.json not found — run: vbounce sprint init S-XX D-XX');
+  }
+} else {
+  warn('.bounce/ directory missing — run: vbounce sprint init S-XX D-XX');
+}
+
+// Check brain files
+const brainFiles = [
+  ['brains/CLAUDE.md', 'Tier 1 (Claude Code)'],
+  ['brains/GEMINI.md', 'Tier 2 (Gemini CLI)'],
+  ['brains/AGENTS.md', 'Tier 2 (Codex CLI)'],
+];
+for (const [f, tier] of brainFiles) {
+  if (fs.existsSync(path.join(ROOT, f))) pass(`Brain file: ${f} (${tier})`);
+  else fail(`Brain file: ${f} missing`, `Run: vbounce init --tool ${f.includes('GEMINI') ? 'gemini' : f.includes('AGENTS') ? 'codex' : 'claude'}`);
+}
+
+// Check optional brain files
+const optionalBrains = [
+  ['brains/copilot/copilot-instructions.md', 'copilot'],
+  ['brains/windsurf/.windsurfrules', 'windsurf'],
+];
+for (const [f, tool] of optionalBrains) {
+  if (fs.existsSync(path.join(ROOT, f))) pass(`Brain file: ${f} (Tier 4)`);
+  else warn(`Brain file: ${f} not found (optional) — run: vbounce init --tool ${tool}`);
+}
+
+// Check skills
+const requiredSkills = ['agent-team', 'doc-manager', 'lesson', 'vibe-code-review', 'react-best-practices', 'write-skill', 'improve'];
+const skillsDir = path.join(ROOT, 'skills');
+let skillCount = 0;
+for (const s of requiredSkills) {
+  const skillFile = path.join(skillsDir, s, 'SKILL.md');
+  if (fs.existsSync(skillFile)) skillCount++;
+  else fail(`skills/${s}/SKILL.md missing`);
+}
+if (skillCount === requiredSkills.length) pass(`Skills: ${skillCount}/${requiredSkills.length} installed`);
+
+// Check scripts
+const requiredScripts = [
+  'validate_report.mjs', 'update_state.mjs', 'validate_state.mjs',
+  'validate_sprint_plan.mjs', 'validate_bounce_readiness.mjs',
+  'init_sprint.mjs', 'close_sprint.mjs', 'complete_story.mjs',
+  'prep_qa_context.mjs', 'prep_arch_context.mjs', 'prep_sprint_context.mjs',
+  'prep_sprint_summary.mjs', 'sprint_trends.mjs', 'suggest_improvements.mjs',
+  'hotfix_manager.sh'
+];
+const scriptsDir = path.join(ROOT, 'scripts');
+let scriptCount = 0;
+for (const s of requiredScripts) {
+  if (fs.existsSync(path.join(scriptsDir, s))) scriptCount++;
+  else fail(`scripts/${s} missing`);
+}
+if (scriptCount === requiredScripts.length) pass(`Scripts: ${scriptCount}/${requiredScripts.length} available`);
+
+// Check product_plans structure
+if (fs.existsSync(path.join(ROOT, 'product_plans'))) {
+  pass('product_plans/ directory exists');
+} else {
+  warn('product_plans/ directory missing — create it to store planning documents');
+}
+
+// Check vbounce.config.json
+if (fs.existsSync(path.join(ROOT, 'vbounce.config.json'))) {
+  pass('vbounce.config.json found');
+} else {
+  warn('vbounce.config.json not found — using default context limits');
+}
+
+// Print results
+console.log('\nV-Bounce OS Health Check');
+console.log('========================');
+checks.forEach(c => console.log(c));
+console.log('');
+if (issueCount === 0) {
+  console.log('✓ All checks passed.');
+} else {
+  console.log(`Issues: ${issueCount}`);
+  console.log('Run suggested commands to fix.');
+}
+
+process.exit(issueCount > 0 ? 1 : 0);

package/scripts/init_sprint.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+/**
+ * init_sprint.mjs
+ * Sprint setup automation — creates state.json, sprint plan dir, and prints git commands.
+ *
+ * Usage:
+ *   ./scripts/init_sprint.mjs S-06 D-02 --stories STORY-011-05,STORY-005-01,STORY-005-02
+ */
+
+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 args = process.argv.slice(2);
+
+if (args.length < 2) {
+  console.error('Usage: init_sprint.mjs S-XX D-NN [--stories STORY-ID1,STORY-ID2,...]');
+  process.exit(1);
+}
+
+const sprintId = args[0]; // e.g. S-06
+const deliveryId = args[1]; // e.g. D-02
+
+if (!/^S-\d{2}$/.test(sprintId)) {
+  console.error(`ERROR: sprint_id "${sprintId}" must match S-XX format`);
+  process.exit(1);
+}
+if (!/^D-\d{2}$/.test(deliveryId)) {
+  console.error(`ERROR: delivery_id "${deliveryId}" must match D-NN format`);
+  process.exit(1);
+}
+
+const storiesArg = args.indexOf('--stories');
+const storyIds = storiesArg !== -1 ? args[storiesArg + 1].split(',') : [];
+
+// 1. Create .bounce/ directory
+const bounceDir = path.join(ROOT, '.bounce');
+fs.mkdirSync(bounceDir, { recursive: true });
+fs.mkdirSync(path.join(bounceDir, 'archive'), { recursive: true });
+fs.mkdirSync(path.join(bounceDir, 'reports'), { recursive: true });
+
+// 2. Create state.json
+const stateFile = path.join(bounceDir, 'state.json');
+if (fs.existsSync(stateFile)) {
+  console.warn(`⚠  state.json already exists. Overwriting...`);
+}
+
+const sprintNum = sprintId.replace('S-', '');
+const stories = {};
+for (const id of storyIds) {
+  stories[id.trim()] = {
+    state: 'Draft',
+    qa_bounces: 0,
+    arch_bounces: 0,
+    worktree: null
+  };
+}
+
+const state = {
+  sprint_id: sprintId,
+  delivery_id: deliveryId,
+  sprint_plan: `product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md`,
+  delivery_plan: `product_plans/strategy/${deliveryId}_DELIVERY_PLAN.md`,
+  stories,
+  phase: 'Phase 1',
+  last_action: `Sprint ${sprintId} initialized`,
+  updated_at: new Date().toISOString()
+};
+
+fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+console.log(`✓ Created .bounce/state.json`);
+
+// 3. Create sprint plan directory
+const sprintDir = path.join(ROOT, 'product_plans', 'sprints', `sprint-${sprintNum}`);
+fs.mkdirSync(sprintDir, { recursive: true });
+
+const sprintPlanFile = path.join(sprintDir, `sprint-${sprintNum}.md`);
+if (!fs.existsSync(sprintPlanFile)) {
+  // Copy from template
+  const templateFile = path.join(ROOT, 'templates', 'sprint.md');
+  if (fs.existsSync(templateFile)) {
+    let content = fs.readFileSync(templateFile, 'utf8');
+    // Replace placeholders
+    content = content.replace(/sprint-\{XX\}/g, `sprint-${sprintNum}`);
+    content = content.replace(/S-\{XX\}/g, sprintId);
+    content = content.replace(/D-\{NN\}/g, deliveryId);
+    content = content.replace(/status: "Planning \/ Active \/ Completed"/, 'status: "Planning"');
+    // Strip instructions block
+    content = content.replace(/<instructions>[\s\S]*?<\/instructions>\n\n/, '');
+    fs.writeFileSync(sprintPlanFile, content);
+    console.log(`✓ Created product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md`);
+  } else {
+    // Create minimal sprint plan
+    const minimal = `---\nsprint_id: "${sprintId}"\nsprint_goal: "TBD"\ndates: "TBD"\nstatus: "Planning"\ndelivery: "${deliveryId}"\n---\n\n# Sprint ${sprintId} Plan\n\n## 1. Active Scope\n\n| Priority | Story | Epic | Label | V-Bounce State | Blocker |\n|----------|-------|------|-------|----------------|---------|\n${storyIds.map((id, i) => `| ${i + 1} | ${id.trim()} | — | L2 | Draft | — |`).join('\n')}\n\n### Escalated / Parking Lot\n- (none)\n\n---\n\n## 2. Execution Strategy\n\n### Phase Plan\n- **Phase 1 (parallel)**: ${storyIds.join(', ')}\n\n### Risk Flags\n- (TBD)\n\n---\n\n## 3. Sprint Open Questions\n\n| Question | Options | Impact | Owner | Status |\n|----------|---------|--------|-------|--------|\n\n---\n\n<!-- EXECUTION_LOG_START -->\n## 4. Execution Log\n\n| Story | Final State | QA Bounces | Arch Bounces | Correction Tax | Notes |\n|-------|-------------|------------|--------------|----------------|-------|\n<!-- EXECUTION_LOG_END -->\n`;
+    fs.writeFileSync(sprintPlanFile, minimal);
+    console.log(`✓ Created product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md (minimal — template not found)`);
+  }
+} else {
+  console.log(`  Sprint plan already exists: product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md`);
+}
+
+// 4. Print git commands (don't execute)
+console.log('');
+console.log('Run these git commands to initialize the sprint branch:');
+console.log(`  git checkout -b sprint/${sprintId} main`);
+if (storyIds.length > 0) {
+  console.log('');
+  console.log('Then create worktrees for each story:');
+  storyIds.forEach(id => {
+    const trimmed = id.trim();
+    console.log(`  git worktree add .worktrees/${trimmed} -b story/${trimmed} sprint/${sprintId}`);
+    console.log(`  mkdir -p .worktrees/${trimmed}/.bounce/{tasks,reports}`);
+  });
+}
+
+console.log('');
+console.log(`✓ Sprint ${sprintId} initialized. Stories: ${storyIds.length > 0 ? storyIds.join(', ') : 'none (add manually)'}`);

package/scripts/prep_arch_context.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+/**
+ * prep_arch_context.mjs
+ * Generates an Architect context pack for a story.
+ *
+ * Usage:
+ *   ./scripts/prep_arch_context.mjs STORY-005-02
+ *
+ * Output: .bounce/arch-context-STORY-005-02.md
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+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_arch_context.mjs STORY-ID');
+  process.exit(1);
+}
+
+// Load config
+let config = { maxDiffLines: 500 };
+const configFile = path.join(ROOT, 'vbounce.config.json');
+if (fs.existsSync(configFile)) {
+  try { config = { ...config, ...JSON.parse(fs.readFileSync(configFile, 'utf8')) }; } catch {}
+}
+const MAX_DIFF_LINES = config.maxDiffLines || 500;
+
+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;
+}
+
+const searchDirs = [
+  path.join(ROOT, '.worktrees', storyId, '.bounce', 'reports'),
+  path.join(ROOT, '.bounce', 'reports'),
+  path.join(ROOT, '.bounce', 'archive'),
+];
+
+// 1. Find dev report (required)
+const devPattern = new RegExp(`${storyId.replace(/[-]/g, '[-]')}.*-dev\\.md$`);
+let devReport = null;
+for (const dir of searchDirs) {
+  const m = findFilesMatching(dir, devPattern);
+  if (m.length > 0) { devReport = m[0]; break; }
+}
+if (!devReport) {
+  console.error(`ERROR: Dev report not found for ${storyId}`);
+  process.exit(1);
+}
+
+// 2. Find QA report (optional but warn)
+const qaPattern = new RegExp(`${storyId.replace(/[-]/g, '[-]')}.*-qa.*\\.md$`);
+let qaReport = null;
+for (const dir of searchDirs) {
+  const m = findFilesMatching(dir, qaPattern);
+  if (m.length > 0) { qaReport = m[m.length - 1]; break; } // latest QA report
+}
+if (!qaReport) console.warn(`⚠  QA report not found for ${storyId} — proceeding without it`);
+
+// 3. Find story spec (required)
+const storyPattern = new RegExp(`${storyId.replace(/[-]/g, '[-]')}.*\\.md$`);
+const storyMatches = findFilesMatching(path.join(ROOT, 'product_plans'), storyPattern);
+if (storyMatches.length === 0) {
+  console.error(`ERROR: Story spec not found for ${storyId} in product_plans/`);
+  process.exit(1);
+}
+const storySpecFile = storyMatches[0];
+
+// Parse frontmatters
+let devFm = {}, qaFm = {};
+try {
+  const dc = fs.readFileSync(devReport, 'utf8');
+  const dm = dc.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (dm) devFm = yaml.load(dm[1]) || {};
+} catch {}
+if (qaReport) {
+  try {
+    const qc = fs.readFileSync(qaReport, 'utf8');
+    const qm = qc.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (qm) qaFm = yaml.load(qm[1]) || {};
+  } catch {}
+}
+
+// 4. Get git diff
+let diffContent = '';
+let diffTruncated = false;
+const stateFile = path.join(ROOT, '.bounce', 'state.json');
+try {
+  let diffCmd = 'git diff HEAD~5';
+  if (fs.existsSync(stateFile)) {
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    const sprintBranch = `sprint/${state.sprint_id}`;
+    try {
+      execSync(`git rev-parse ${sprintBranch}`, { cwd: ROOT, stdio: 'pipe' });
+      diffCmd = `git diff ${sprintBranch}...HEAD`;
+    } catch {}
+  }
+  diffContent = execSync(diffCmd, { cwd: ROOT }).toString();
+
+  if (!diffContent.trim()) {
+    console.warn(`⚠  Git diff is empty — proceeding without diff`);
+  } else {
+    const diffLines = diffContent.split('\n');
+    if (diffLines.length > MAX_DIFF_LINES) {
+      diffTruncated = true;
+      const fullDiffPath = path.join(ROOT, '.bounce', `arch-full-diff-${storyId}.txt`);
+      fs.writeFileSync(fullDiffPath, diffContent);
+      console.warn(`⚠  Diff truncated at ${MAX_DIFF_LINES} lines (was ${diffLines.length}). Full diff saved to .bounce/arch-full-diff-${storyId}.txt`);
+      diffContent = diffLines.slice(0, MAX_DIFF_LINES).join('\n');
+    }
+  }
+} catch (e) {
+  console.warn(`⚠  Could not get git diff: ${e.message}`);
+}
+
+// 5. 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, 20).join('\n');
+  if (lines.length > 20) lessonsExcerpt += `\n_(+${lines.length - 20} more lines)_`;
+}
+
+// 6. Assemble context pack
+const lines = [
+  `# Architect Context: ${storyId}`,
+  `> Generated: ${new Date().toISOString().split('T')[0]}`,
+  '',
+  `## Dev Report Summary`,
+  `| Field | Value |`,
+  `|-------|-------|`,
+  `| Status | ${devFm.status || '—'} |`,
+  `| Correction Tax | ${devFm.correction_tax || '—'} |`,
+  `| Tests Written | ${devFm.tests_written ?? '—'} |`,
+  `| Files Modified | ${Array.isArray(devFm.files_modified) ? devFm.files_modified.length : '—'} |`,
+  '',
+  `## QA Report Summary`,
+  qaReport
+    ? [`| Field | Value |`, `|-------|-------|`,
+       `| Status | ${qaFm.status || '—'} |`,
+       `| Bounce Count | ${qaFm.bounce_count ?? '—'} |`,
+       `| Bugs Found | ${qaFm.bugs_found ?? '—'} |`].join('\n')
+    : '_QA report not found_',
+  '',
+  `## Story Spec`,
+  `- File: \`${path.relative(ROOT, storySpecFile)}\``,
+  `- Read §3 Implementation Guide and §3.1 ADR References before auditing`,
+  '',
+  `## Git Diff${diffTruncated ? ` (TRUNCATED at ${MAX_DIFF_LINES} lines — full diff in .bounce/arch-full-diff-${storyId}.txt)` : ''}`,
+  '```diff',
+  diffContent || '(no diff available)',
+  '```',
+  '',
+  `## Relevant Lessons`,
+  lessonsExcerpt,
+];
+
+const output = lines.join('\n');
+const outputFile = path.join(ROOT, '.bounce', `arch-context-${storyId}.md`);
+fs.writeFileSync(outputFile, output);
+console.log(`✓ Architect context pack written to .bounce/arch-context-${storyId}.md`);
+if (diffTruncated) console.log(`  ⚠  Diff truncated — full diff at .bounce/arch-full-diff-${storyId}.txt`);