@sandrinio/vbounce 1.7.0 → 1.8.0

package/bin/vbounce.mjs

@@ -81,6 +81,8 @@ Usage:
   vbounce prep qa <storyId>            Generate QA context pack
   vbounce prep arch <storyId>          Generate Architect context pack
   vbounce prep sprint <sprintId>       Generate Sprint context pack
+  vbounce docs match --story <ID>      Match story scope against vdoc manifest
+  vbounce docs check <sprintId>        Detect stale vdocs and generate Scribe task
   vbounce trends                       Cross-sprint trend analysis
   vbounce suggest <sprintId>           Generate improvement suggestions
   vbounce doctor                       Validate all configs and state files
@@ -192,6 +194,20 @@ if (command === 'suggest') {
   runScript('suggest_improvements.mjs', args.slice(1));
 }
 
+// -- docs --
+if (command === 'docs') {
+  rl.close();
+  if (sub === 'match') {
+    runScript('vdoc_match.mjs', args.slice(2));
+  } else if (sub === 'check') {
+    runScript('vdoc_staleness.mjs', args.slice(2));
+  } else {
+    console.error(`Unknown docs subcommand: ${sub}`);
+    console.error('Usage: vbounce docs match --story <ID> | vbounce docs check <sprintId>');
+    process.exit(1);
+  }
+}
+
 // -- doctor --
 if (command === 'doctor') {
   rl.close();

package/brains/claude-agents/qa.md

@@ -15,6 +15,7 @@ Validate that the Developer's implementation meets the Story's acceptance criter
 1. **Read LESSONS.md**: Scan for failure patterns relevant to this story. Treat matching entries as known risk areas to probe first.
 2. **Read the Developer Implementation Report** (`.bounce/reports/STORY-{ID}-{StoryName}-dev.md`) to understand what was built.
 3. **Read Story §2 The Truth** — these are your pass/fail criteria. If the Gherkin scenarios don't pass, the bounce failed.
+4. **Check vdoc context**: If the QA context pack includes a `## vdoc Context` section, read the referenced product docs. Cross-reference the Developer's changes against documented behavior — if the implementation contradicts what a vdoc describes, flag it as a behavioral regression even if the Gherkin scenarios pass. Check the Blast Radius warnings for features that may be indirectly affected.
 
 ## Pre-Computed Scan Results
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrinio/vbounce",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "V-Bounce OS: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
   "type": "module",
   "bin": {

package/scripts/prep_qa_context.mjs

@@ -13,6 +13,7 @@
 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));
@@ -96,7 +97,23 @@ const filesModified = Array.isArray(devFm.files_modified)
   ? devFm.files_modified.map(f => `- ${f}`).join('\n')
   : '_Not specified in dev report_';
 
-// 5. Assemble context pack
+// 5. vdoc context (optional — graceful skip if no manifest)
+let vdocSection = '';
+const vdocMatchScript = path.join(__dirname, 'vdoc_match.mjs');
+if (fs.existsSync(vdocMatchScript) && fs.existsSync(path.join(ROOT, 'vdocs', '_manifest.json'))) {
+  try {
+    const modifiedFiles = Array.isArray(devFm.files_modified) ? devFm.files_modified.join(',') : '';
+    const vdocArgs = [`--story`, storyId];
+    if (modifiedFiles) vdocArgs.push('--files', modifiedFiles);
+    vdocArgs.push('--context');
+    const vdocOutput = execSync(`node "${vdocMatchScript}" ${vdocArgs.map(a => `"${a}"`).join(' ')}`, { cwd: ROOT, encoding: 'utf8', timeout: 10000 }).trim();
+    if (vdocOutput && !vdocOutput.includes('No vdoc matches')) {
+      vdocSection = vdocOutput;
+    }
+  } catch { /* vdoc matching failed — skip silently */ }
+}
+
+// 6. Assemble context pack
 const lines = [
   `# QA Context: ${storyId}`,
   `> Generated: ${new Date().toISOString().split('T')[0]}`,
@@ -117,6 +134,7 @@ const lines = [
   `## Files Modified`,
   filesModified,
   '',
+  ...(vdocSection ? [vdocSection, ''] : []),
   `## Relevant Lessons`,
   lessonsExcerpt,
 ];

package/scripts/prep_sprint_context.mjs

@@ -13,6 +13,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -75,7 +76,28 @@ 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
+// 6. vdoc summary (optional — graceful skip if no manifest)
+let vdocSummary = '';
+const manifestPath = path.join(ROOT, 'vdocs', '_manifest.json');
+if (fs.existsSync(manifestPath)) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const docCount = (manifest.documentation || []).length;
+    const docList = (manifest.documentation || []).slice(0, 10)
+      .map(d => `| ${d.filepath} | ${d.title} | ${(d.tags || []).slice(0, 4).join(', ')} | ${(d.deps || []).join(', ') || '—'} |`)
+      .join('\n');
+    vdocSummary = [
+      `## Product Documentation (vdoc)`,
+      `> ${docCount} feature doc(s) available in vdocs/`,
+      '',
+      `| Doc | Title | Tags | Dependencies |`,
+      `|-----|-------|------|-------------|`,
+      docList,
+    ].join('\n');
+  } catch { /* skip on parse error */ }
+}
+
+// 7. Assemble context pack
 const lines = [
   `# Sprint Context: ${sprintId}`,
   `> Generated: ${new Date().toISOString().split('T')[0]} | Sprint: ${sprintId} | Delivery: ${state.delivery_id}`,
@@ -91,6 +113,7 @@ const lines = [
   `|-------|-------|------------|--------------|----------|`,
   storyRows || '| (no stories) | — | — | — | — |',
   '',
+  ...(vdocSummary ? [vdocSummary, ''] : []),
   `## Relevant Lessons`,
   lessonsExcerpt,
   '',

package/scripts/validate_bounce_readiness.mjs

@@ -102,6 +102,33 @@ if (!fs.existsSync(worktreeDir)) {
   warnings.push(`.worktrees/${storyId}/ not found — create with: git worktree add .worktrees/${storyId} -b story/${storyId} sprint/S-XX`);
 }
 
+// 5. vdoc impact check (warning only — never blocks bounce)
+const manifestPath = path.join(ROOT, 'vdocs', '_manifest.json');
+if (fs.existsSync(manifestPath) && storyFile) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const docs = manifest.documentation || [];
+    const storyLower = fs.readFileSync(storyFile, 'utf8').toLowerCase();
+
+    // Extract file paths mentioned in the story
+    const storyFileRefs = storyLower.match(/(?:src|lib|app|pages|components|api|services|scripts)\/[^\s,)'"]+/g) || [];
+
+    for (const doc of docs) {
+      const docKeyFiles = (doc.keyFiles || []).map(f => f.toLowerCase());
+      const overlap = docKeyFiles.filter(kf =>
+        storyFileRefs.some(sf => sf.includes(kf) || kf.includes(sf))
+      );
+      if (overlap.length > 0) {
+        warnings.push(`vdoc impact: ${doc.filepath} — key files overlap with story scope (${overlap.slice(0, 3).join(', ')}). Doc may need updating post-sprint.`);
+        const deps = doc.deps || [];
+        if (deps.length > 0) {
+          warnings.push(`  ↳ Blast radius: ${deps.join(', ')} may also be affected`);
+        }
+      }
+    }
+  } catch { /* skip on manifest parse error */ }
+}
+
 // Print results
 console.log(`Bounce readiness check: ${storyId}`);
 console.log('');

package/scripts/vdoc_match.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+/**
+ * vdoc_match.mjs
+ * Reads vdocs/_manifest.json and matches story scope against doc tags,
+ * descriptions, and key files. Returns relevant doc paths and blast radius.
+ *
+ * Usage:
+ *   ./scripts/vdoc_match.mjs --story STORY-005-02
+ *   ./scripts/vdoc_match.mjs --files "src/auth/index.ts,src/middleware/auth.ts"
+ *   ./scripts/vdoc_match.mjs --keywords "authentication,jwt,login"
+ *
+ * Output: JSON to stdout, human-readable to stderr
+ */
+
+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, '..');
+
+// ── Config ────────────────────────────────────────────────────────
+
+const configPath = path.join(ROOT, 'vbounce.config.json');
+const config = fs.existsSync(configPath)
+  ? JSON.parse(fs.readFileSync(configPath, 'utf8'))
+  : {};
+
+const MAX_MATCHES = config.vdocMaxMatches || 3;
+const VDOCS_DIR = path.join(ROOT, 'vdocs');
+const MANIFEST_PATH = path.join(VDOCS_DIR, '_manifest.json');
+const SLICES_DIR = path.join(VDOCS_DIR, '_slices');
+
+// ── Parse args ────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+let storyId = null;
+let inputFiles = [];
+let inputKeywords = [];
+let outputFormat = 'human'; // human | json | context
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case '--story':   storyId = args[++i]; break;
+    case '--files':   inputFiles = args[++i].split(',').map(f => f.trim()); break;
+    case '--keywords': inputKeywords = args[++i].split(',').map(k => k.trim().toLowerCase()); break;
+    case '--json':    outputFormat = 'json'; break;
+    case '--context': outputFormat = 'context'; break;
+  }
+}
+
+if (!storyId && inputFiles.length === 0 && inputKeywords.length === 0) {
+  console.error('Usage: vdoc_match.mjs --story STORY-ID | --files "f1,f2" | --keywords "k1,k2"');
+  console.error('  --json     Output JSON to stdout');
+  console.error('  --context  Output context-pack markdown to stdout');
+  process.exit(1);
+}
+
+// ── Load manifest ─────────────────────────────────────────────────
+
+if (!fs.existsSync(MANIFEST_PATH)) {
+  if (outputFormat === 'json') {
+    console.log(JSON.stringify({ matches: [], blastRadius: [], reason: 'no_manifest' }));
+  } else {
+    console.error('No vdocs/_manifest.json found — skipping vdoc matching');
+  }
+  process.exit(0); // Graceful no-op
+}
+
+const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+const docs = manifest.documentation || [];
+
+// ── Extract search terms from story ───────────────────────────────
+
+if (storyId) {
+  // Find story spec to extract keywords and file references
+  const storyPattern = new RegExp(storyId.replace(/[-]/g, '[-]'));
+  const storyFiles = findFiles(path.join(ROOT, 'product_plans'), storyPattern);
+
+  if (storyFiles.length > 0) {
+    const storyContent = fs.readFileSync(storyFiles[0], 'utf8').toLowerCase();
+
+    // Extract file paths mentioned in the story
+    const fileRefs = storyContent.match(/(?:src|lib|app|pages|components|api|services|scripts)\/[^\s,)'"]+/g) || [];
+    inputFiles.push(...fileRefs);
+
+    // Extract tags from story frontmatter
+    const tagMatch = storyContent.match(/tags:\s*\[([^\]]+)\]/);
+    if (tagMatch) {
+      inputKeywords.push(...tagMatch[1].split(',').map(t => t.trim().replace(/['"]/g, '')));
+    }
+
+    // Use story name parts as keywords
+    const nameParts = storyId.split('-').slice(3).join('-').replace(/_/g, ' ').split(/\s+/);
+    inputKeywords.push(...nameParts.filter(p => p.length > 2));
+  }
+}
+
+// ── Score each doc ────────────────────────────────────────────────
+
+const scored = docs.map(doc => {
+  let score = 0;
+  const reasons = [];
+
+  // 1. File path overlap (strongest signal)
+  const docKeyFiles = extractKeyFiles(doc);
+  const fileOverlap = inputFiles.filter(f => docKeyFiles.some(kf => kf.includes(f) || f.includes(kf)));
+  if (fileOverlap.length > 0) {
+    score += fileOverlap.length * 10;
+    reasons.push(`file overlap: ${fileOverlap.join(', ')}`);
+  }
+
+  // 2. Tag match
+  const docTags = (doc.tags || []).map(t => t.toLowerCase());
+  const tagOverlap = inputKeywords.filter(k => docTags.includes(k));
+  if (tagOverlap.length > 0) {
+    score += tagOverlap.length * 5;
+    reasons.push(`tag match: ${tagOverlap.join(', ')}`);
+  }
+
+  // 3. Description keyword match
+  const desc = (doc.description || '').toLowerCase();
+  const descMatches = inputKeywords.filter(k => desc.includes(k));
+  if (descMatches.length > 0) {
+    score += descMatches.length * 3;
+    reasons.push(`description match: ${descMatches.join(', ')}`);
+  }
+
+  // 4. Title keyword match
+  const title = (doc.title || '').toLowerCase();
+  const titleMatches = inputKeywords.filter(k => title.includes(k));
+  if (titleMatches.length > 0) {
+    score += titleMatches.length * 2;
+    reasons.push(`title match: ${titleMatches.join(', ')}`);
+  }
+
+  return { ...doc, score, reasons };
+}).filter(d => d.score > 0).sort((a, b) => b.score - a.score);
+
+// ── Top matches ───────────────────────────────────────────────────
+
+const topMatches = scored.slice(0, MAX_MATCHES);
+
+// ── Blast radius (deps of matched docs) ──────────────────────────
+
+const matchedFeatures = new Set(topMatches.map(d => d.title));
+const blastRadius = [];
+
+for (const match of topMatches) {
+  const deps = match.deps || [];
+  for (const dep of deps) {
+    if (!matchedFeatures.has(dep)) {
+      const depDoc = docs.find(d => d.title === dep || d.filepath.toLowerCase().includes(dep.toLowerCase().replace(/\s+/g, '_')));
+      if (depDoc) {
+        blastRadius.push({ feature: dep, doc: depDoc.filepath, triggeredBy: match.title });
+      } else {
+        blastRadius.push({ feature: dep, doc: null, triggeredBy: match.title });
+      }
+    }
+  }
+}
+
+// ── Output ────────────────────────────────────────────────────────
+
+const result = {
+  matches: topMatches.map(d => ({
+    filepath: d.filepath,
+    title: d.title,
+    score: d.score,
+    reasons: d.reasons,
+    deps: d.deps || [],
+  })),
+  blastRadius,
+};
+
+if (outputFormat === 'json') {
+  console.log(JSON.stringify(result, null, 2));
+} else if (outputFormat === 'context') {
+  // Output context-pack markdown using slices where available
+  if (topMatches.length === 0) {
+    console.log('<!-- No vdoc matches found -->');
+  } else {
+    console.log('## vdoc Context');
+    console.log('');
+    for (const match of topMatches) {
+      const sliceName = match.filepath.replace(/_DOC\.md$/, '_SLICE.md').replace(/\.md$/, '_SLICE.md');
+      const slicePath = path.join(SLICES_DIR, sliceName);
+      const fullPath = path.join(VDOCS_DIR, match.filepath);
+
+      if (fs.existsSync(slicePath)) {
+        console.log(fs.readFileSync(slicePath, 'utf8'));
+      } else if (fs.existsSync(fullPath)) {
+        // Fallback: extract Overview section from full doc
+        const content = fs.readFileSync(fullPath, 'utf8');
+        const overviewMatch = content.match(/## Overview\s*\n(?:<!--[^>]*-->\s*\n)?\s*([\s\S]*?)(?=\n---|\n##)/);
+        if (overviewMatch) {
+          console.log(`### ${match.title}`);
+          console.log(overviewMatch[1].trim().split('\n').slice(0, 5).join('\n'));
+          console.log('');
+        }
+      }
+      console.log('');
+    }
+
+    if (blastRadius.length > 0) {
+      console.log('### Blast Radius Warning');
+      console.log('Changes to matched features may also affect:');
+      for (const br of blastRadius) {
+        console.log(`- **${br.feature}** (triggered by ${br.triggeredBy})${br.doc ? ` — see ${br.doc}` : ''}`);
+      }
+      console.log('');
+    }
+  }
+} else {
+  // Human-readable to stderr
+  if (topMatches.length === 0) {
+    console.error('No vdoc matches found for the given scope.');
+  } else {
+    console.error(`\n✓ ${topMatches.length} vdoc match(es) found:\n`);
+    for (const match of topMatches) {
+      console.error(`  ${match.filepath} (score: ${match.score})`);
+      console.error(`    ${match.reasons.join(' | ')}`);
+    }
+    if (blastRadius.length > 0) {
+      console.error(`\n⚠ Blast radius — also affected:`);
+      for (const br of blastRadius) {
+        console.error(`  ${br.feature} (via ${br.triggeredBy})`);
+      }
+    }
+    console.error('');
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+function findFiles(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(...findFiles(full, pattern));
+    else if (pattern.test(e.name)) results.push(full);
+  }
+  return results;
+}
+
+function extractKeyFiles(doc) {
+  // From manifest entry — check if keyFiles exist in frontmatter-style
+  const files = [];
+  if (doc.keyFiles) files.push(...doc.keyFiles);
+
+  // Also try reading the doc to get Key Files table
+  const docPath = path.join(VDOCS_DIR, doc.filepath);
+  if (fs.existsSync(docPath)) {
+    const content = fs.readFileSync(docPath, 'utf8');
+    const keyFilesMatch = content.match(/## Key Files[\s\S]*?\|[^|]+\|[^|]+\|[^|]+\|([\s\S]*?)(?=\n---|\n##)/);
+    if (keyFilesMatch) {
+      const rows = keyFilesMatch[1].split('\n').filter(r => r.includes('|'));
+      for (const row of rows) {
+        const cells = row.split('|').map(c => c.trim());
+        const filePath = cells[1]?.replace(/`/g, '');
+        if (filePath && filePath.includes('/')) files.push(filePath);
+      }
+    }
+  }
+  return files;
+}

package/scripts/vdoc_staleness.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+/**
+ * vdoc_staleness.mjs
+ * Cross-references Dev Reports' files_modified against vdoc manifest key files.
+ * Generates a targeted Scribe task file listing stale docs.
+ *
+ * Usage:
+ *   ./scripts/vdoc_staleness.mjs S-05
+ *
+ * Output: .bounce/scribe-task-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: vdoc_staleness.mjs S-XX');
+  process.exit(1);
+}
+
+const VDOCS_DIR = path.join(ROOT, 'vdocs');
+const MANIFEST_PATH = path.join(VDOCS_DIR, '_manifest.json');
+
+// ── Check manifest ────────────────────────────────────────────────
+
+if (!fs.existsSync(MANIFEST_PATH)) {
+  console.log('No vdocs/_manifest.json found — skipping staleness check');
+  process.exit(0);
+}
+
+const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+const docs = manifest.documentation || [];
+
+// ── Collect all files_modified from Dev Reports ───────────────────
+
+const allModifiedFiles = new Set();
+const storyModifications = {}; // storyId -> files
+
+function findDevReports(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const 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(...findDevReports(full));
+    else if (e.name.endsWith('-dev.md')) results.push(full);
+  }
+  return results;
+}
+
+const reportDirs = [
+  path.join(ROOT, '.bounce', 'reports'),
+  path.join(ROOT, '.bounce', 'archive', sprintId),
+];
+
+for (const dir of reportDirs) {
+  const reports = findDevReports(dir);
+  for (const report of reports) {
+    try {
+      const content = fs.readFileSync(report, 'utf8');
+      const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+      if (!fmMatch) continue;
+      const fm = yaml.load(fmMatch[1]) || {};
+      const files = fm.files_modified || [];
+      const storyMatch = path.basename(report).match(/STORY-[\w-]+/);
+      const storyId = storyMatch ? storyMatch[0] : 'unknown';
+      storyModifications[storyId] = files;
+      files.forEach(f => allModifiedFiles.add(f));
+    } catch { /* skip malformed reports */ }
+  }
+}
+
+if (allModifiedFiles.size === 0) {
+  console.log('No files_modified found in Dev Reports — nothing to check');
+  process.exit(0);
+}
+
+// ── Cross-reference against manifest key files ────────────────────
+
+const staleDocs = [];
+
+for (const doc of docs) {
+  // Get key files from doc frontmatter or Key Files section
+  const docKeyFiles = [];
+
+  // From manifest entry
+  if (doc.keyFiles) docKeyFiles.push(...doc.keyFiles);
+
+  // From the doc file itself
+  const docPath = path.join(VDOCS_DIR, doc.filepath);
+  if (fs.existsSync(docPath)) {
+    const content = fs.readFileSync(docPath, 'utf8');
+
+    // Parse frontmatter keyFiles
+    const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (fmMatch) {
+      try {
+        const fm = yaml.load(fmMatch[1]) || {};
+        if (fm.keyFiles) docKeyFiles.push(...fm.keyFiles);
+      } catch { /* ignore */ }
+    }
+
+    // Parse Key Files table
+    const tableMatch = content.match(/## Key Files[\s\S]*?\|[^|]+\|[^|]+\|[^|]+\|([\s\S]*?)(?=\n---|\n##)/);
+    if (tableMatch) {
+      const rows = tableMatch[1].split('\n').filter(r => r.includes('|'));
+      for (const row of rows) {
+        const cells = row.split('|').map(c => c.trim());
+        const filePath = cells[1]?.replace(/`/g, '');
+        if (filePath && filePath.includes('/')) docKeyFiles.push(filePath);
+      }
+    }
+  }
+
+  // Check for overlap
+  const uniqueKeyFiles = [...new Set(docKeyFiles)];
+  const overlapping = uniqueKeyFiles.filter(kf =>
+    [...allModifiedFiles].some(mf => mf.includes(kf) || kf.includes(mf))
+  );
+
+  if (overlapping.length > 0) {
+    // Find which stories touched these files
+    const touchedBy = [];
+    for (const [sid, files] of Object.entries(storyModifications)) {
+      if (files.some(f => overlapping.some(o => f.includes(o) || o.includes(f)))) {
+        touchedBy.push(sid);
+      }
+    }
+
+    staleDocs.push({
+      filepath: doc.filepath,
+      title: doc.title,
+      overlappingFiles: overlapping,
+      touchedBy,
+    });
+  }
+}
+
+if (staleDocs.length === 0) {
+  console.log('✓ No stale vdocs detected — all docs are current');
+  process.exit(0);
+}
+
+// ── Generate Scribe task file ─────────────────────────────────────
+
+const taskLines = [
+  `---`,
+  `sprint_id: "${sprintId}"`,
+  `mode: "audit"`,
+  `stale_docs: ${staleDocs.length}`,
+  `generated: "${new Date().toISOString().split('T')[0]}"`,
+  `---`,
+  ``,
+  `# Scribe Task: ${sprintId} — Targeted Doc Update`,
+  ``,
+  `> Auto-generated by staleness detection. ${staleDocs.length} doc(s) need updating.`,
+  ``,
+  `## Stale Documents`,
+  ``,
+  `| Doc | Title | Files Modified | Touched By |`,
+  `|-----|-------|---------------|------------|`,
+  ...staleDocs.map(d =>
+    `| ${d.filepath} | ${d.title} | ${d.overlappingFiles.slice(0, 3).join(', ')}${d.overlappingFiles.length > 3 ? ` (+${d.overlappingFiles.length - 3})` : ''} | ${d.touchedBy.join(', ')} |`
+  ),
+  ``,
+  `## Instructions`,
+  ``,
+  `For each stale doc:`,
+  `1. Read the current doc and the Dev Reports from the stories listed above`,
+  `2. Re-read the modified source files to understand what changed`,
+  `3. Update only the affected sections — do not rewrite the entire doc`,
+  `4. Bump frontmatter \`version\` (increment by 1) and set \`lastUpdated\` to today`,
+  `5. Update the manifest entry if tags or description need adjustment`,
+  `6. Regenerate the context slice in \`vdocs/_slices/\``,
+  ``,
+  `## Priority`,
+  ``,
+  ...staleDocs.map(d => {
+    const fileCount = d.overlappingFiles.length;
+    const priority = fileCount >= 3 ? 'HIGH' : fileCount >= 2 ? 'MEDIUM' : 'LOW';
+    return `- **${d.filepath}**: ${priority} (${fileCount} key file(s) modified)`;
+  }),
+];
+
+const taskFile = path.join(ROOT, '.bounce', `scribe-task-${sprintId}.md`);
+fs.writeFileSync(taskFile, taskLines.join('\n'));
+
+console.log(`✓ Scribe task written to .bounce/scribe-task-${sprintId}.md`);
+console.log(`  ${staleDocs.length} stale doc(s) detected:`);
+for (const d of staleDocs) {
+  console.log(`  - ${d.filepath} (${d.overlappingFiles.length} key files modified by ${d.touchedBy.join(', ')})`);
+}

package/skills/agent-team/SKILL.md

@@ -359,17 +359,24 @@ After ALL stories are merged into `sprint/S-01`:
      - Offer to run the `improve` skill to propose framework changes
      - If user approves → read `skills/improve/SKILL.md` and execute the improvement process
 8. Product Documentation check (runs on `main` after sprint merge):
-   - If sprint delivered 3+ features, or if any Developer report flagged
-     stale product docs → offer to run vdoc to generate/update
-     vdocs/
-   - If user approves → spawn scribe subagent on `main` branch with:
-     - Sprint Report (what was built)
-     - Dev reports that flagged affected product docs
-     - Current _manifest.json (if exists)
-     - Mode: "audit" (if docs exist) or "init" (if first time)
-   - Scribe generates/updates docs and writes Scribe Report
-   - Documentation is post-implementation — it reflects what was built
-   - Scribe commits documentation as a follow-up commit on `main`
+   a. **Staleness Detection** — run `./scripts/vdoc_staleness.mjs S-{XX}`
+      - Cross-references all Dev Reports' `files_modified` against manifest key files
+      - Generates `.bounce/scribe-task-S-{XX}.md` with targeted list of stale docs
+      - Populates Sprint Report §1 "Product Docs Affected" table
+      - If no `vdocs/_manifest.json` exists → skip silently (graceful no-op)
+   b. **Scribe Task Decision:**
+      - If staleness detection found stale docs → offer targeted Scribe task
+      - If sprint delivered 3+ features and no vdocs exist → offer vdoc init
+      - If any Developer report flagged stale product docs → offer Scribe update
+   c. If user approves → spawn scribe subagent on `main` branch with:
+      - `.bounce/scribe-task-S-{XX}.md` (targeted task — when available)
+      - Sprint Report (what was built)
+      - Dev reports that flagged affected product docs
+      - Current _manifest.json (if exists)
+      - Mode: "audit" (if docs exist) or "init" (if first time)
+   d. Scribe generates/updates docs and writes Scribe Report
+      - Documentation is post-implementation — it reflects what was built
+      - Scribe commits documentation as a follow-up commit on `main`
 ```
 
 ---

package/templates/sprint_report.md

@@ -54,9 +54,13 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 - {e.g., "STORY-001-03-email_notifications — Escalated (template integration failed 3x)"}
 
 ### Product Docs Affected
-> Any product documentation files modified, created, or identified for updates. Handed off to Scribe agent.
+> Auto-populated from staleness detection (`vbounce docs check S-{XX}`). Shows which vdocs were impacted by this sprint's code changes. Scribe agent receives a targeted task from `.bounce/scribe-task-S-{XX}.md`.
 
-- {e.g., "vdocs/api_reference.md — Added rate limiting details"}
+| Doc | Stale Key Files | Touched By | Priority | Scribe Action |
+|-----|----------------|------------|----------|---------------|
+| {e.g., `AUTHENTICATION_DOC.md`} | {e.g., `src/auth/index.ts`} | {e.g., `STORY-001-02`} | {HIGH/MEDIUM/LOW} | {Update / Quality Fix / New} |
+
+> If no `vdocs/_manifest.json` exists, write "N/A — vdoc not installed".
 
 ---