@sandrinio/vbounce 2.0.0 → 2.1.0

package/scripts/product_graph.mjs

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+
+/**
+ * product_graph.mjs
+ * Scans product_plans/ for planning documents, extracts YAML frontmatter,
+ * and outputs a lightweight JSON graph to .bounce/product-graph.json.
+ *
+ * The graph gives AI instant awareness of all product documents and their
+ * relationships without reading every file.
+ *
+ * Usage:
+ *   node scripts/product_graph.mjs
+ *   node scripts/product_graph.mjs --json   # output to stdout instead of file
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+let yaml;
+try {
+  yaml = await import('js-yaml');
+} catch {
+  console.error('ERROR: js-yaml not installed. Run: npm install js-yaml');
+  process.exit(1);
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+const SCAN_DIRS = ['strategy', 'backlog', 'sprints', 'hotfixes'];
+const PRODUCT_PLANS = path.join(ROOT, 'product_plans');
+const OUTPUT_PATH = path.join(ROOT, '.bounce', 'product-graph.json');
+
+const args = process.argv.slice(2);
+const toStdout = args.includes('--json');
+
+// ── Document type detection ──────────────────────────────────────
+
+const DOC_PATTERNS = [
+  { pattern: /^EPIC-(\d+)/i, type: 'epic' },
+  { pattern: /^STORY-(\d+)-(\d+)/i, type: 'story' },
+  { pattern: /^SPIKE-(\d+)-(\d+)/i, type: 'spike' },
+  { pattern: /^HOTFIX-/i, type: 'hotfix' },
+  { pattern: /sprint-(\d+)\.md$/i, type: 'sprint-plan' },
+  { pattern: /sprint-report/i, type: 'sprint-report' },
+  { pattern: /charter/i, type: 'charter' },
+  { pattern: /roadmap/i, type: 'roadmap' },
+  { pattern: /delivery[_-]plan/i, type: 'delivery-plan' },
+  { pattern: /risk[_-]registry/i, type: 'risk-registry' },
+];
+
+/**
+ * Detect document type from filename.
+ * @param {string} filename
+ * @returns {string}
+ */
+function detectType(filename) {
+  for (const { pattern, type } of DOC_PATTERNS) {
+    if (pattern.test(filename)) return type;
+  }
+  return 'unknown';
+}
+
+/**
+ * Derive a document ID from filename and frontmatter.
+ * @param {string} filename
+ * @param {object} frontmatter
+ * @param {string} docType
+ * @returns {string}
+ */
+function deriveId(filename, frontmatter, docType) {
+  // Use explicit ID fields from frontmatter if available
+  if (frontmatter.epic_id) return frontmatter.epic_id;
+  if (frontmatter.story_id) return frontmatter.story_id;
+  if (frontmatter.spike_id) return frontmatter.spike_id;
+  if (frontmatter.sprint_id) return frontmatter.sprint_id;
+  if (frontmatter.hotfix_id) return frontmatter.hotfix_id;
+  if (frontmatter.delivery_id) return frontmatter.delivery_id;
+
+  // Derive from filename
+  const base = path.basename(filename, '.md');
+
+  const epicMatch = base.match(/^(EPIC-\d+)/i);
+  if (epicMatch) return epicMatch[1].toUpperCase();
+
+  const storyMatch = base.match(/^(STORY-\d+-\d+)/i);
+  if (storyMatch) return storyMatch[1].toUpperCase();
+
+  const spikeMatch = base.match(/^(SPIKE-\d+-\d+)/i);
+  if (spikeMatch) return spikeMatch[1].toUpperCase();
+
+  const sprintMatch = base.match(/^sprint-(\d+)$/i);
+  if (sprintMatch) return `S-${sprintMatch[1].padStart(2, '0')}`;
+
+  const hotfixMatch = base.match(/^(HOTFIX-[^.]+)/i);
+  if (hotfixMatch) return hotfixMatch[1].toUpperCase();
+
+  // Fallback: use docType + sanitized filename
+  if (docType === 'charter') return 'CHARTER';
+  if (docType === 'roadmap') return 'ROADMAP';
+  if (docType === 'risk-registry') return 'RISK-REGISTRY';
+  if (docType === 'delivery-plan') {
+    const dpMatch = base.match(/^(D-\d+)/i);
+    if (dpMatch) return dpMatch[1].toUpperCase();
+    return `DP-${base}`;
+  }
+
+  return base.toUpperCase();
+}
+
+// ── YAML extraction ──────────────────────────────────────────────
+
+/**
+ * Extract YAML frontmatter from a markdown file.
+ * @param {string} filePath
+ * @returns {{ frontmatter: object|null, title: string|null }}
+ */
+function extractFrontmatter(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return { frontmatter: null, title: null };
+  }
+
+  // Extract title from first heading
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  const title = titleMatch ? titleMatch[1].trim() : null;
+
+  // Extract YAML frontmatter
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!fmMatch) return { frontmatter: null, title };
+
+  try {
+    const frontmatter = yaml.default?.load
+      ? yaml.default.load(fmMatch[1])
+      : yaml.load(fmMatch[1]);
+    return { frontmatter: frontmatter || {}, title };
+  } catch (err) {
+    console.error(`  WARN: Malformed YAML in ${path.relative(ROOT, filePath)}: ${err.message}`);
+    return { frontmatter: null, title };
+  }
+}
+
+// ── Edge extraction ──────────────────────────────────────────────
+
+/**
+ * Extract edges from frontmatter fields and document content.
+ * @param {string} docId
+ * @param {object} fm - frontmatter
+ * @param {string} docType
+ * @param {string} filePath
+ * @returns {Array<{from: string, to: string, type: string}>}
+ */
+function extractEdges(docId, fm, docType, filePath) {
+  const edges = [];
+
+  // parent_epic_ref → parent edge
+  if (fm.parent_epic_ref) {
+    edges.push({ from: fm.parent_epic_ref, to: docId, type: 'parent' });
+  }
+
+  // Derive parent epic from story/spike ID pattern (STORY-003-01 → EPIC-003)
+  if (!fm.parent_epic_ref && (docType === 'story' || docType === 'spike')) {
+    const epicNum = docId.match(/(?:STORY|SPIKE)-(\d+)/i);
+    if (epicNum) {
+      const parentId = `EPIC-${epicNum[1].padStart(3, '0')}`;
+      edges.push({ from: parentId, to: docId, type: 'parent' });
+    }
+  }
+
+  // charter_ref → context-source edge
+  if (fm.charter_ref) {
+    edges.push({ from: fm.charter_ref, to: docId, type: 'context-source' });
+  }
+
+  // roadmap_ref → context-source edge
+  if (fm.roadmap_ref) {
+    edges.push({ from: fm.roadmap_ref, to: docId, type: 'context-source' });
+  }
+
+  // context_source → context-source edge (text field, try to match doc IDs)
+  if (fm.context_source && typeof fm.context_source === 'string') {
+    const refs = fm.context_source.match(/(?:EPIC|STORY|SPIKE|CHARTER|ROADMAP|S|D)-[\w-]+/gi) || [];
+    for (const ref of refs) {
+      edges.push({ from: ref.toUpperCase(), to: docId, type: 'context-source' });
+    }
+  }
+
+  // release → feeds edge (e.g., release: "D-02")
+  if (fm.release) {
+    const releaseId = fm.release.match(/(D-\d+)/i);
+    if (releaseId) {
+      edges.push({ from: docId, to: releaseId[1].toUpperCase(), type: 'feeds' });
+    }
+  }
+
+  // risk_registry_ref → context-source edge
+  if (fm.risk_registry_ref) {
+    edges.push({ from: 'RISK-REGISTRY', to: docId, type: 'context-source' });
+  }
+
+  // delivery field in sprint plans
+  if (fm.delivery) {
+    const dpId = fm.delivery.match(/(D-\d+)/i);
+    if (dpId) {
+      edges.push({ from: docId, to: dpId[1].toUpperCase(), type: 'feeds' });
+    }
+  }
+
+  // depends_on / dependencies (array or string)
+  const deps = fm.depends_on || fm.dependencies || [];
+  const depList = Array.isArray(deps) ? deps : [deps];
+  for (const dep of depList) {
+    if (typeof dep === 'string') {
+      const depIds = dep.match(/(?:EPIC|STORY|SPIKE|S|D)-[\w-]+/gi) || [];
+      for (const depId of depIds) {
+        edges.push({ from: depId.toUpperCase(), to: docId, type: 'depends-on' });
+      }
+    }
+  }
+
+  // Extract dependency table from document content (§4.2 pattern)
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const depTableMatch = content.match(/(?:depend|block|prerequisite)[\s\S]*?\|[\s\S]*?\|/gi);
+    if (depTableMatch) {
+      for (const tableBlock of depTableMatch) {
+        const docRefs = tableBlock.match(/(?:EPIC|STORY|SPIKE)-\d+(?:-\d+)?/gi) || [];
+        for (const ref of docRefs) {
+          const refId = ref.toUpperCase();
+          if (refId !== docId) {
+            edges.push({ from: refId, to: docId, type: 'depends-on' });
+          }
+        }
+      }
+    }
+
+    // Extract "unlocks" references
+    const unlocksMatch = content.match(/unlocks?[:\s]+([^\n]+)/gi) || [];
+    for (const line of unlocksMatch) {
+      const refs = line.match(/(?:EPIC|STORY|SPIKE)-\d+(?:-\d+)?/gi) || [];
+      for (const ref of refs) {
+        edges.push({ from: docId, to: ref.toUpperCase(), type: 'unlocks' });
+      }
+    }
+  } catch {
+    // Content extraction is best-effort
+  }
+
+  return edges;
+}
+
+// ── File scanning ────────────────────────────────────────────────
+
+/**
+ * Recursively find all .md files in a directory.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findMarkdownFiles(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findMarkdownFiles(fullPath));
+    } else if (entry.name.endsWith('.md')) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+// ── Main ─────────────────────────────────────────────────────────
+
+function buildGraph() {
+  const nodes = {};
+  const edges = [];
+  const warnings = [];
+
+  if (!fs.existsSync(PRODUCT_PLANS)) {
+    // Graceful: empty graph for missing product_plans/
+    const graph = { generated_at: new Date().toISOString(), nodes: {}, edges: [] };
+    return graph;
+  }
+
+  // Scan active directories only (not archive/)
+  for (const subdir of SCAN_DIRS) {
+    const scanPath = path.join(PRODUCT_PLANS, subdir);
+    const files = findMarkdownFiles(scanPath);
+
+    for (const filePath of files) {
+      const filename = path.basename(filePath);
+      const docType = detectType(filename);
+
+      if (docType === 'unknown' || docType === 'sprint-report') continue;
+
+      const { frontmatter, title } = extractFrontmatter(filePath);
+      const relPath = path.relative(ROOT, filePath);
+
+      // Build node even without frontmatter (use filename-derived data)
+      const fm = frontmatter || {};
+      const docId = deriveId(filename, fm, docType);
+
+      nodes[docId] = {
+        type: docType,
+        status: fm.status || null,
+        ambiguity: fm.ambiguity || null,
+        path: relPath,
+        title: title || docId,
+      };
+
+      // Extract edges
+      if (frontmatter) {
+        const docEdges = extractEdges(docId, fm, docType, filePath);
+        edges.push(...docEdges);
+      }
+    }
+  }
+
+  // Also scan root of product_plans/ for charter files
+  const rootFiles = fs.readdirSync(PRODUCT_PLANS, { withFileTypes: true })
+    .filter(e => !e.isDirectory() && e.name.endsWith('.md'));
+
+  for (const entry of rootFiles) {
+    const filePath = path.join(PRODUCT_PLANS, entry.name);
+    const docType = detectType(entry.name);
+    if (docType === 'unknown') continue;
+
+    const { frontmatter, title } = extractFrontmatter(filePath);
+    const relPath = path.relative(ROOT, filePath);
+    const fm = frontmatter || {};
+    const docId = deriveId(entry.name, fm, docType);
+
+    if (!nodes[docId]) {
+      nodes[docId] = {
+        type: docType,
+        status: fm.status || null,
+        ambiguity: fm.ambiguity || null,
+        path: relPath,
+        title: title || docId,
+      };
+
+      if (frontmatter) {
+        const docEdges = extractEdges(docId, fm, docType, filePath);
+        edges.push(...docEdges);
+      }
+    }
+  }
+
+  // Deduplicate edges
+  const edgeSet = new Set();
+  const uniqueEdges = edges.filter(e => {
+    const key = `${e.from}→${e.to}:${e.type}`;
+    if (edgeSet.has(key)) return false;
+    edgeSet.add(key);
+    return true;
+  });
+
+  return {
+    generated_at: new Date().toISOString(),
+    node_count: Object.keys(nodes).length,
+    edge_count: uniqueEdges.length,
+    nodes,
+    edges: uniqueEdges,
+  };
+}
+
+// ── Execute ──────────────────────────────────────────────────────
+
+const graph = buildGraph();
+
+if (toStdout) {
+  console.log(JSON.stringify(graph, null, 2));
+} else {
+  // Ensure .bounce/ exists
+  const bounceDir = path.join(ROOT, '.bounce');
+  fs.mkdirSync(bounceDir, { recursive: true });
+
+  fs.writeFileSync(OUTPUT_PATH, JSON.stringify(graph, null, 2) + '\n');
+  console.log(`✓ Product graph generated: .bounce/product-graph.json`);
+  console.log(`  Nodes: ${graph.node_count} | Edges: ${graph.edge_count}`);
+}

package/scripts/product_impact.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+/**
+ * product_impact.mjs
+ * Query "what's affected by changing document X?" using BFS traversal
+ * of the product graph.
+ *
+ * Usage:
+ *   node scripts/product_impact.mjs EPIC-002
+ *   node scripts/product_impact.mjs EPIC-002 --json
+ */
+
+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 GRAPH_PATH = path.join(ROOT, '.bounce', 'product-graph.json');
+
+const args = process.argv.slice(2);
+const docId = args.find(a => !a.startsWith('--'));
+const jsonOutput = args.includes('--json');
+
+if (!docId) {
+  console.error('Usage: product_impact.mjs <DOC-ID> [--json]');
+  console.error('  Example: product_impact.mjs EPIC-002');
+  console.error('  Run `vbounce graph` first to generate the product graph.');
+  process.exit(1);
+}
+
+// ── Load graph ───────────────────────────────────────────────────
+
+if (!fs.existsSync(GRAPH_PATH)) {
+  console.error('ERROR: .bounce/product-graph.json not found.');
+  console.error('Run `vbounce graph` first to generate the product graph.');
+  process.exit(1);
+}
+
+const graph = JSON.parse(fs.readFileSync(GRAPH_PATH, 'utf8'));
+const targetId = docId.toUpperCase();
+
+if (!graph.nodes[targetId]) {
+  console.error(`ERROR: Document "${targetId}" not found in the product graph.`);
+  console.error(`Available documents: ${Object.keys(graph.nodes).join(', ')}`);
+  process.exit(1);
+}
+
+// ── Build adjacency lists ────────────────────────────────────────
+
+// Downstream: edges where targetId is the source (from)
+// "What does this document feed into?"
+const downstream = new Map(); // from → [{to, type}]
+const upstream = new Map();   // to → [{from, type}]
+
+for (const edge of graph.edges) {
+  if (!downstream.has(edge.from)) downstream.set(edge.from, []);
+  downstream.get(edge.from).push({ to: edge.to, type: edge.type });
+
+  if (!upstream.has(edge.to)) upstream.set(edge.to, []);
+  upstream.get(edge.to).push({ from: edge.from, type: edge.type });
+}
+
+// ── BFS: direct + transitive dependents ──────────────────────────
+
+/**
+ * BFS traversal from a node following outgoing edges.
+ * @param {string} startId
+ * @param {Map} adjList - adjacency list (from → targets)
+ * @param {'downstream'|'upstream'} direction
+ * @returns {{ direct: Array, transitive: Array }}
+ */
+function bfs(startId, adjList, direction) {
+  const visited = new Set([startId]);
+  const direct = [];
+  const transitive = [];
+  const queue = [{ id: startId, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift();
+    const neighbors = adjList.get(id) || [];
+
+    for (const neighbor of neighbors) {
+      const neighborId = direction === 'downstream' ? neighbor.to : neighbor.from;
+
+      if (visited.has(neighborId)) continue; // Cycle protection
+      visited.add(neighborId);
+
+      const entry = {
+        id: neighborId,
+        type: neighbor.type,
+        via: id,
+        node: graph.nodes[neighborId] || null,
+      };
+
+      if (depth === 0) {
+        direct.push(entry);
+      } else {
+        transitive.push(entry);
+      }
+
+      queue.push({ id: neighborId, depth: depth + 1 });
+    }
+  }
+
+  return { direct, transitive };
+}
+
+// ── Run analysis ─────────────────────────────────────────────────
+
+const dependents = bfs(targetId, downstream, 'downstream');
+const feeders = bfs(targetId, upstream, 'upstream');
+
+const result = {
+  document: targetId,
+  document_info: graph.nodes[targetId],
+  direct_dependents: dependents.direct,
+  transitive_dependents: dependents.transitive,
+  upstream_feeders: feeders.direct.concat(feeders.transitive),
+  graph_generated_at: graph.generated_at,
+};
+
+// ── Output ───────────────────────────────────────────────────────
+
+if (jsonOutput) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  const node = graph.nodes[targetId];
+  console.log(`\n📊 Impact Analysis: ${targetId}`);
+  console.log(`   ${node.title}`);
+  console.log(`   Status: ${node.status || 'N/A'} | Type: ${node.type}`);
+  console.log(`   Path: ${node.path}`);
+
+  if (dependents.direct.length > 0) {
+    console.log(`\n🔽 Direct Dependents (${dependents.direct.length}):`);
+    for (const dep of dependents.direct) {
+      const label = dep.node ? dep.node.title : dep.id;
+      const status = dep.node?.status ? ` [${dep.node.status}]` : '';
+      console.log(`   ${dep.type}: ${label}${status}`);
+    }
+  } else {
+    console.log('\n🔽 Direct Dependents: none');
+  }
+
+  if (dependents.transitive.length > 0) {
+    console.log(`\n🔽 Transitive Dependents (${dependents.transitive.length}):`);
+    for (const dep of dependents.transitive) {
+      const label = dep.node ? dep.node.title : dep.id;
+      const status = dep.node?.status ? ` [${dep.node.status}]` : '';
+      console.log(`   ${dep.type}: ${label}${status} (via ${dep.via})`);
+    }
+  }
+
+  if (feeders.direct.length > 0 || feeders.transitive.length > 0) {
+    const allFeeders = [...feeders.direct, ...feeders.transitive];
+    console.log(`\n🔼 Upstream Feeders (${allFeeders.length}):`);
+    for (const f of allFeeders) {
+      const label = f.node ? f.node.title : f.id;
+      console.log(`   ${f.type}: ${label}`);
+    }
+  } else {
+    console.log('\n🔼 Upstream Feeders: none');
+  }
+
+  console.log(`\nGraph generated: ${graph.generated_at}`);
+  console.log('');
+}

package/skills/agent-team/SKILL.md

@@ -263,6 +263,8 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.bounce/{tasks,reports}
    ./scripts/pre_gate_runner.sh qa .worktrees/STORY-{ID}-{StoryName}/ sprint/S-{XX}
    - If scan FAILS on trivial issues (debug statements, missing JSDoc, TODOs):
      Return to Developer for quick fix. Do NOT spawn QA for mechanical failures.
+     If pre-gate scan fails 3+ times → Escalate: present failures to human with options:
+       a) Human fixes manually, b) Descope the story, c) Re-assign to a different approach.
    - If scan PASSES: Include scan output path in the QA task file.
 1. Spawn qa subagent in .worktrees/STORY-{ID}-{StoryName}/ with:
    - Developer Implementation Report
@@ -287,6 +289,7 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.bounce/{tasks,reports}
    ./scripts/pre_gate_runner.sh arch .worktrees/STORY-{ID}-{StoryName}/ sprint/S-{XX}
    - If scan reveals new dependencies or structural violations:
      Return to Developer for resolution. Do NOT spawn Architect for mechanical failures.
+     If pre-gate scan fails 3+ times → Escalate to human (same options as pre-QA escalation).
    - If scan PASSES: Include scan output path in the Architect task file.
 1. Spawn architect subagent in .worktrees/STORY-{ID}-{StoryName}/ with:
    - All reports for this story
@@ -319,7 +322,12 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.bounce/{tasks,reports}
 4. If merge conflicts:
    - Simple (imports, whitespace): DevOps resolves directly
    - Complex (logic): DevOps writes Conflict Report, Lead creates fix story
-5. If post-merge tests fail: DevOps reverts merge, reports failure to Lead
+5. If post-merge tests fail:
+   - DevOps reverts the merge and writes a Post-Merge Failure Report (what failed, which tests, suspected cause)
+   - Lead returns story to Developer with the failure report as input
+   - Developer fixes in the original worktree (which is preserved until merge succeeds)
+   - Story re-enters the bounce at Step 2 (Dev pass). QA/Arch bounce counts are NOT reset — this is a merge issue, not a gate failure.
+   - If post-merge fails 3+ times → Escalate to human
 ```
 Update sprint-{XX}.md: V-Bounce State → "Done"
 
@@ -342,7 +350,11 @@ After ALL stories are merged into `sprint/S-01`:
 2. First, Architect runs `./scripts/hotfix_manager.sh audit` to check for hotfix drift. If it fails, perform deep audit on flagged files.
 3. Run Sprint Integration Audit — Deep Audit on combined changes
 4. Check for: duplicate routes, competing state, overlapping migrations
-5. If issues found → create new stories to fix, bounce individually
+5. If issues found:
+   - Present findings to human with severity assessment
+   - AI suggests which epic the fix story should belong to
+   - Fix stories are added to the BACKLOG (not the current sprint) — they enter the next sprint through normal planning
+   - Exception: if the issue blocks the sprint release (e.g., broken build), fix inline on the sprint branch without creating a story
 ```
 
 ### Step 7: Sprint Consolidation
@@ -457,7 +469,7 @@ The Team Lead MUST update the active `sprint-{XX}.md` at every state transition.
 | Architect passes | §1: V-Bounce State → "Architect Passed" | **Nothing** |
 | DevOps merges story | §1: V-Bounce State → "Done". §4: Add Execution Log row (via `vbounce story complete`) | **Nothing** |
 | Escalated | §1: Move story to Escalated section | **Nothing** |
-| Sprint CLOSES | Status → "Completed" in frontmatter | §2: sprint → Completed. §4: add summary. §3: remove delivered stories |
+| Sprint CLOSES | Status → "Completed" in frontmatter | §2: sprint → Completed. §4: add summary. §3: remove delivered stories. **This is the ONLY time Delivery Plan updates.** |
 
 > **Key rule**: The Delivery Plan is updated ONLY at sprint close, never during active bouncing.
 > See `skills/agent-team/references/delivery-sync.md` for full sync rules.