@sandrinio/vbounce 1.7.0 → 1.9.0

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/scripts/verify_framework.mjs

@@ -63,7 +63,7 @@ const EXPECTED_PROMPT_SIGNATURES = {
 
 function main() {
     console.log("===========================================");
-    console.log(" V-Bounce OS: Framework Integrity Check");
+    console.log(" V-Bounce Engine: Framework Integrity Check");
     console.log("===========================================\n");
 
     let hasErrors = false;

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/skills/doc-manager/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: doc-manager
-description: "Use when creating, modifying, or navigating V-Bounce OS planning documents. Trigger on any request to create a charter, roadmap, epic, story, delivery plan, or risk registry — or when the user asks to update, refine, decompose, or transition documents between phases. Also trigger when an agent needs to know which template to use, where a document fits in the hierarchy, or what upstream/downstream documents to read before writing. This skill manages the full document lifecycle from Charter through Sprint execution."
+description: "Use when creating, modifying, or navigating V-Bounce Engine planning documents. Trigger on any request to create a charter, roadmap, epic, story, delivery plan, or risk registry — or when the user asks to update, refine, decompose, or transition documents between phases. Also trigger when an agent needs to know which template to use, where a document fits in the hierarchy, or what upstream/downstream documents to read before writing. This skill manages the full document lifecycle from Charter through Sprint execution."
 ---
 
 # Document Hierarchy Manager
 
 ## Purpose
 
-This skill is the navigation system for V-Bounce OS planning documents. It knows the full document hierarchy, what each template contains, where to find templates, and the rules for creating, modifying, and transitioning documents between phases.
+This skill is the navigation system for V-Bounce Engine planning documents. It knows the full document hierarchy, what each template contains, where to find templates, and the rules for creating, modifying, and transitioning documents between phases.
 
 **Core principle:** No document exists in isolation. Every document inherits context from upstream and feeds downstream consumers. YOU MUST read upstream documents before creating any new document.
 
@@ -120,10 +120,10 @@ product_plans/
 - `sprints/` contains active 1-week execution boundaries. A Story file physically moves here when a sprint begins.
 - `archive/` is where finished Sprints and finished Epics are moved for permanent record keeping.
 
-### V-Bounce OS Framework Structure
+### V-Bounce Engine Framework Structure
 
 ```
-V-Bounce OS/
+V-Bounce Engine/
 ├── brains/          — Agent brain files for each AI coding tool
 │   ├── CLAUDE.md        — Claude Code brain
 │   ├── AGENTS.md        — Codex CLI brain
@@ -148,7 +148,7 @@ When initializing a new project, deploy the correct brain file for the AI coding
 | Gemini CLI | `brains/GEMINI.md` | Project root as `GEMINI.md` |
 | Antigravity | `brains/GEMINI.md` | Project root + copy `skills/` to `.agents/skills/` |
 
-Brain files contain the V-Bounce process, critical rules, and skill references. Each tool's brain file is self-contained and authoritative. When updating V-Bounce OS rules, update each brain file directly and keep them in sync.
+Brain files contain the V-Bounce process, critical rules, and skill references. Each tool's brain file is self-contained and authoritative. When updating V-Bounce Engine rules, update each brain file directly and keep them in sync.
 
 ## Document Operations
 

package/skills/improve/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: improve
-description: "Use when the V-Bounce OS framework needs to evolve based on accumulated agent feedback. Activates after sprint retros, when recurring friction patterns emerge, or when the user explicitly asks to improve the framework. Reads Process Feedback from sprint reports, identifies patterns, proposes specific changes to templates, skills, brain files, scripts, and agent configs, and applies approved changes. This is the system's self-improvement loop."
+description: "Use when the V-Bounce Engine framework needs to evolve based on accumulated agent feedback. Activates after sprint retros, when recurring friction patterns emerge, or when the user explicitly asks to improve the framework. Reads Process Feedback from sprint reports, identifies patterns, proposes specific changes to templates, skills, brain files, scripts, and agent configs, and applies approved changes. This is the system's self-improvement loop."
 ---
 
 # Framework Self-Improvement
 
 ## Purpose
 
-V-Bounce OS is not static. Every sprint generates friction signals from agents who work within the framework daily. This skill closes the feedback loop: it reads what agents struggled with, identifies patterns, and proposes targeted improvements to the framework itself.
+V-Bounce Engine is not static. Every sprint generates friction signals from agents who work within the framework daily. This skill closes the feedback loop: it reads what agents struggled with, identifies patterns, and proposes targeted improvements to the framework itself.
 
 **Core principle:** No framework change happens without human approval. The system suggests — the human decides.
 

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".
 
 ---