@sandrinio/vbounce 1.9.0 → 2.1.0

package/README.md

@@ -8,9 +8,162 @@ V-Bounce Engine turns AI assistants — Claude Code, Cursor, Gemini, Copilot, Co
 
 ---
 
-## How It Works
+## The Problem
 
-V-Bounce Engine is built around a **Context Loop** — a closed feedback system that makes agents smarter with each sprint.
+AI coding agents are powerful — but without structure, they create expensive chaos:
+
+- **No accountability.** The agent writes code, but nobody reviews it against requirements before it ships. Bugs that a junior engineer would catch survive to production.
+- **Invisible progress.** You ask "how's the feature going?" and the only answer is "the agent is still running." No milestones, no intermediate artifacts, no way to course-correct mid-sprint.
+- **No institutional memory.** Every session starts from zero. The agent makes the same architectural mistake it made last week because nothing captures what went wrong.
+- **Rework cycles.** Without quality gates, bad code compounds. A missed requirement discovered late costs 10x more to fix than one caught early.
+- **Risk blindness.** There's no structured way to assess what could go wrong before the agent starts building.
+
+V-Bounce Engine solves this by wrapping AI agents in the same discipline that makes human engineering teams reliable: planning documents, role-based reviews, automated gates, and a learning loop that compounds knowledge across sprints.
+
+---
+
+## Built-in Guardrails
+
+Every risk that keeps you up at night has a specific mechanism that catches it:
+
+| Risk | What catches it |
+|------|----------------|
+| Agent ships code that doesn't match requirements | **QA gate** — validates every story against acceptance criteria before merge |
+| Architectural drift over time | **Architect gate** — audits against your ADRs on every story |
+| One bad story breaks everything | **Git worktrees** — every story is isolated; failures can't contaminate other work |
+| Agent gets stuck in a loop | **3-bounce escalation** — after 3 failed attempts, the story surfaces to a human |
+| Scope creep on "quick fixes" | **Hotfix hard-stop** — Developer must stop if a fix touches more than 2 files |
+| Same mistakes keep happening | **LESSONS.md** — agents read accumulated mistakes before writing future code |
+| Silent regressions | **Root cause tagging** — every failure is tagged and tracked across sprints |
+| Framework itself becomes stale | **Self-improvement skill** — analyzes friction patterns and proposes changes (with your approval) |
+
+---
+
+## Planning With V-Bounce
+
+V-Bounce separates planning into two layers: **what to build** and **how to ship it**. The AI is your planning partner — not a tool you invoke with commands.
+
+### Product Planning — What to Build
+
+Just talk to the AI. Say "plan a feature for X" or "create an epic for payments" and it handles the rest — reading upstream documents, researching your codebase, and drafting planning documents.
+
+A document hierarchy that mirrors how product teams already think:
+
+```
+Charter  (WHY — vision, principles, constraints)
+  → Roadmap  (WHAT/WHEN — releases, milestones, architecture decisions)
+    → Epic  (scoped WHAT — a feature with clear boundaries)
+      → Story  (HOW — implementation spec with acceptance criteria)
+```
+
+**You write the top levels. The AI builds the bottom — informed by your actual codebase.**
+
+When creating Epics, the AI researches your codebase to fill Technical Context with real file paths and verified dependencies — not guesses. When decomposing Epics into Stories, the AI reads affected files, explores architecture patterns, and creates small, focused stories by deliverable (vertical slices), not by layer.
+
+Every document includes an **ambiguity score**:
+- 🔴 High — requirements unclear, blocked from development
+- 🟡 Medium — tech TBD but logic is clear, safe to plan
+- 🟢 Low — fully specified, ready to build
+
+No level can be skipped. This prevents the most common AI failure mode: building the wrong thing because requirements were vague.
+
+### Execution Planning — How to Ship It
+
+Once you know *what* to build, three documents govern *how* it gets delivered:
+
+| Document | Scope | Who uses it | What it tracks |
+|----------|-------|-------------|----------------|
+| **Delivery Plan** | A full release (multiple sprints) | PM | Which Epics are included, project window (start/end dates), high-level backlog prioritization, escalated/parked stories |
+| **Sprint Plan** | One sprint (typically 1 week) | Team Lead + PM | Active story scope, context pack readiness checklists, execution strategy (parallel vs sequential phases), dependency chains, risk flags, and a live execution log |
+| **Risk Registry** | Cross-cutting (all levels) | PM + Architect | Active risks with likelihood/impact scoring, phase-stamped analysis log, mitigations, and resolution history |
+
+**How they connect:**
+
+```
+Delivery Plan  (the milestone — "we're shipping auth + payments by March 30")
+  → Sprint Plan  (this week — "stories 01-03 in parallel, 04 depends on 01")
+       ↑
+  Risk Registry  (cross-cutting — reviewed at every sprint boundary)
+```
+
+The **Delivery Plan** is updated only at sprint boundaries. The **Sprint Plan** is the single source of truth during active execution — every story state transition is recorded there. At sprint end, the Sprint Plan's execution log becomes the skeleton for the Sprint Report automatically.
+
+The **Sprint Plan** also includes a **Context Pack Readiness** checklist for each story — a preflight check ensuring the spec is complete, acceptance criteria are defined, and ambiguity is low before any code is written. If a story isn't ready, it stays in Refinement.
+
+---
+
+## Reports and Visibility
+
+V-Bounce generates structured reports at every stage — designed to answer stakeholder questions without requiring anyone to read code:
+
+| Report | When it's generated | What it answers |
+|--------|-------------------|-----------------|
+| **Implementation Report** | After each story is built | What was built? What decisions were made? What tests were added? |
+| **QA Report** | After validation | Does the implementation match the acceptance criteria? What failed? |
+| **Architect Report** | After audit | Does this align with our architecture? Any ADR violations? |
+| **Sprint Report** | End of sprint | What shipped? What bounced? What's the correction tax? Lessons learned? |
+| **Release Report** | After merge | What went to production? Environment changes? Post-merge validations? |
+| **Scribe Report** | After documentation pass | What product docs were created, updated, or flagged as stale? |
+
+**You don't need to read code to manage the sprint.** The reports surface exactly what a PM or PO needs to make decisions.
+
+---
+
+## What You Can Measure
+
+V-Bounce tracks metrics that map directly to product and delivery health:
+
+| Metric | What it tells you | Action when it's bad |
+|--------|------------------|---------------------|
+| **Bounce Rate (QA)** | How often code fails acceptance criteria | Stories may have vague requirements — tighten acceptance criteria |
+| **Bounce Rate (Architect)** | How often code violates architecture rules | ADRs may be unclear, or the agent needs better context |
+| **Correction Tax** | 0% = agent delivered autonomously, 100% = human rewrote everything | High tax means the agent needs better guidance (Charter, Roadmap, or Skills) |
+| **Root Cause Distribution** | Why things fail — `missing_tests`, `adr_violation`, `spec_ambiguity`, etc. | Invest in the category that fails most often |
+| **Escalation Rate** | How often stories hit the 3-bounce limit | Chronic escalation signals structural issues in planning docs |
+| **Sprint Velocity** | Stories completed per sprint | Track trend over time — should improve as LESSONS.md grows |
+
+Run `vbounce trends` to see cross-sprint analysis. Run `vbounce suggest` for AI-generated improvement recommendations.
+
+---
+
+## How a Sprint Flows
+
+Here's what a sprint looks like from the product side — no terminal commands, no code:
+
+**Phase 1 — Planning**
+You talk to the AI about what to build. The AI creates Epics and Stories by reading upstream documents and researching your codebase. Ambiguity, risks, and open questions are surfaced and discussed collaboratively.
+
+**Phase 2 — Sprint Planning**
+You and the AI decide what goes into the sprint together. The AI reads the backlog, proposes scope, and surfaces blockers — open questions, unresolved ambiguity, dependency risks, edge cases. You discuss, adjust, and confirm. **No sprint starts without your explicit confirmation.** The Sprint Plan is mandatory.
+
+**Phase 3 — The Bounce**
+The AI team works autonomously. For each Story:
+1. The **Developer** builds the feature in isolation (with E2E tests, not just unit tests)
+2. The **QA agent** checks: does the code meet the acceptance criteria?
+3. The **Architect agent** checks: does the code follow our architecture rules?
+4. If either check fails, the work "bounces" back to the Developer with a tagged reason
+5. After 3 bounces, the story escalates — the AI presents root causes and options (re-scope, split, spike, or remove), and you decide
+
+Lessons are recorded **immediately** after each story merges, not deferred to sprint close.
+
+**Phase 4 — Review**
+The Sprint Report lands. It tells you:
+- What shipped and what didn't
+- How many bounces each story took (and why)
+- The correction tax (how much human intervention was needed)
+- Test counts per story
+- Lessons already captured during the sprint
+- Recommendations for process improvements
+
+You review, approve the release, and the sprint archives itself. The next sprint starts smarter because the agents now carry forward everything they learned.
+
+---
+
+## Continuous Improvement
+
+Most AI coding setups are stateless — every session starts from scratch. V-Bounce is the opposite.
+
+The **Context Loop** is a closed feedback system that makes your AI team measurably better over time:
 
 ```
 Plan  ──>  Build  ──>  Bounce  ──>  Document  ──>  Learn
@@ -22,15 +175,121 @@ Plan  ──>  Build  ──>  Bounce  ──>  Document  ──>  Learn
                   Next sprint reads it all
 ```
 
-**Plan.** The Team Lead writes requirements using structured templates (Charter, Epic, Story) before any code is written.
+After each sprint:
+- **LESSONS.md** captures every mistake — agents read this before writing future code
+- **Trend analysis** spots recurring patterns (e.g., "auth-related stories bounce 3x more than average")
+- **Self-improvement pipeline** analyzes friction and proposes concrete framework changes
+- **Scribe** keeps product documentation in sync with actual code
+
+Sprint 1 might have a 40% bounce rate. By Sprint 5, that number drops — because the agents have accumulated context about your codebase, your architecture decisions, and your team's standards.
+
+### The Self-Improvement Pipeline
+
+When a sprint closes (`vbounce sprint close`), an automated pipeline analyzes what went wrong and proposes how to fix the framework itself:
+
+```
+Sprint Close
+  │
+  ├── Trend Analysis         → Cross-sprint bounce patterns
+  │
+  ├── Retro Parser           → Reads §5 Framework Self-Assessment tables
+  │                            from the Sprint Report
+  │
+  ├── Lesson Analyzer        → Classifies LESSONS.md rules by what they
+  │                            can become: gate checks, scripts, template
+  │                            fields, or permanent agent rules
+  │
+  ├── Recurrence Detector    → Cross-references archived sprint reports
+  │                            to find findings that keep coming back
+  │
+  ├── Effectiveness Checker  → Did last sprint's improvements actually
+  │                            resolve their target findings?
+  │
+  └── Improvement Suggestions → Human-readable proposals with impact levels
+```
+
+Every proposal gets an **impact level** so you know what to fix first:
+
+| Level | Label | Meaning | When to fix |
+|-------|-------|---------|-------------|
+| **P0** | Critical | Blocks agent work or causes incorrect output | Before next sprint |
+| **P1** | High | Causes rework — bounces, wasted tokens, repeated manual steps | This improvement cycle |
+| **P2** | Medium | Friction that slows agents but doesn't block | Within 2 sprints |
+| **P3** | Low | Polish — nice-to-have | Batch when convenient |
+
+### Lessons Become Automation
 
-**Build.** The Developer agent implements each Story in an isolated git worktree and submits an Implementation Report.
+The pipeline doesn't just track lessons — it classifies each one by what it can become:
 
-**Bounce.** The QA agent validates against acceptance criteria. The Architect agent audits against your architecture rules. If either fails, the work bounces back to the Developer — up to 3 times before escalating to you. Every failure is tagged with a root cause (`missing_tests`, `adr_violation`, `spec_ambiguity`, etc.) for trend analysis.
+| Lesson pattern | Becomes | Example |
+|---------------|---------|---------|
+| "Always check X", "Never use Y" | **Gate check** — automated grep/lint rule | "Never import from internal modules" → pre-gate grep pattern |
+| "Run X before Y" | **Script** — validation step | "Run type-check before QA" → added to pre_gate_runner.sh |
+| "Include X in the story" | **Template field** — required section | "Include rollback plan" → new field in story template |
+| General behavioral rules (3+ sprints old) | **Agent config** — permanent brain rule | "Always check for N+1 queries" → graduated to Architect config |
 
-**Document.** After merge, the Scribe agent maps the actual codebase into semantic product documentation using [vdoc](https://github.com/sandrinio/vdoc) (optional).
+This means your framework evolves organically: agents report friction, the pipeline classifies it, you approve the fix, and the next sprint runs smoother. No manual analysis required.
 
-**Learn.** Sprint mistakes are recorded in `LESSONS.md`. All agents read it before writing future code. The framework also tracks its own performance — bounce rates, correction tax, recurring failure patterns — and suggests improvements to its own templates and skills.
+Run `vbounce improve S-XX` anytime to trigger the pipeline on demand.
+
+---
+
+## Is V-Bounce Right For You?
+
+**Best fit:**
+- Teams using AI agents for production code (not just prototypes)
+- Projects with clear requirements that can be expressed as acceptance criteria
+- Codebases where architectural consistency matters
+- Teams that want to scale AI usage without losing quality control
+
+**Less ideal for:**
+- One-off scripts or throwaway prototypes (overkill)
+- Exploratory research with no defined requirements
+- Projects where the entire team is deeply embedded in every code change anyway
+
+**Minimum setup:** One person who can run `npx` commands + one person who can write a Charter and Epics. That's it.
+
+---
+
+## Roles and Responsibilities
+
+### Human
+
+You own the planning and the final say. The agents never ship without your approval.
+
+| Responsibility | What it involves |
+|---------------|-----------------|
+| **Set vision and constraints** | Write the Charter and Roadmap — define what to build and what's off-limits |
+| **Define requirements** | Break Roadmap into Epics and Stories with acceptance criteria |
+| **Review and approve** | Read sprint reports, approve releases, intervene on escalations |
+| **Tune agent performance** | Adjust brain files, skills, and ADRs based on trend data and bounce patterns |
+| **Install and configure** | Run the installer, verify setup with `vbounce doctor` |
+
+### Agent — Team Lead (Orchestrator)
+
+The Team Lead reads your planning documents and coordinates the entire sprint. It never writes code — it delegates, tracks state, and generates reports.
+
+| Responsibility | What it involves |
+|---------------|-----------------|
+| **Sprint orchestration** | Assigns stories, manages state transitions, enforces the bounce loop |
+| **Agent delegation** | Spawns Developer, QA, Architect, DevOps, and Scribe agents as needed |
+| **Report routing** | Reads each agent's output and decides the next step (pass, bounce, escalate) |
+| **Escalation** | Surfaces stories to the human after 3 failed bounces |
+| **Sprint reporting** | Consolidates execution data into Sprint Reports and Release Reports |
+
+### Agent — Specialists (Developer, QA, Architect, DevOps, Scribe)
+
+Five specialist agents, each with a single job and strict boundaries:
+
+| Agent | What it does | Constraints |
+|-------|-------------|-------------|
+| **Developer** | Implements stories in isolated worktrees, submits implementation reports | Works only in its assigned worktree |
+| **QA** | Validates code against acceptance criteria | Read-only — cannot modify code |
+| **Architect** | Audits against ADRs and architecture rules | Read-only — cannot modify code |
+| **DevOps** | Merges passing stories into the sprint branch | Only acts after both gates pass |
+| **Scribe** | Generates and maintains product documentation from the actual codebase | Only runs after merge |
+
+One person can fill the entire human side. The framework scales to the team you have.
 
 ---
 
@@ -63,25 +322,30 @@ your-project/
 │   ├── architect.md
 │   ├── devops.md
 │   └── scribe.md
-├── templates/                   # 9 Markdown + YAML frontmatter templates
+├── templates/                   # 12 Markdown + YAML frontmatter templates
 │   ├── charter.md
 │   ├── roadmap.md
 │   ├── epic.md
 │   ├── story.md
+│   ├── spike.md
 │   ├── sprint.md
 │   ├── delivery_plan.md
 │   ├── sprint_report.md
 │   ├── hotfix.md
+│   ├── bug.md
+│   ├── change_request.md
 │   └── risk_registry.md
-├── skills/                      # 7 modular skill files (see Skills below)
+├── skills/                      # 9 modular skill files (see Skills below)
 │   ├── agent-team/
 │   ├── doc-manager/
+│   ├── product-graph/
 │   ├── lesson/
 │   ├── vibe-code-review/
 │   ├── write-skill/
 │   ├── improve/
+│   ├── file-organization/
 │   └── react-best-practices/   # Example — customize for your stack
-├── scripts/                     # 23 automation scripts (validation, context prep, state)
+├── scripts/                     # 26 automation scripts (validation, context prep, state, graph)
 └── package.json                 # 3 deps: js-yaml, marked, commander. Nothing else.
 ```
 
@@ -138,11 +402,13 @@ Skills are modular markdown instructions the Team Lead invokes automatically dur
 | Skill | Purpose |
 |-------|---------|
 | `agent-team` | Spawns temporary sub-agents (Dev, QA, Architect, DevOps, Scribe) to parallelize work |
-| `doc-manager` | Enforces the document hierarchy for Epics and Stories |
+| `doc-manager` | Enforces the document hierarchy, cascade rules, and planning workflows |
+| `product-graph` | Dependency-aware document intelligence — knows what's blocked, what's affected by changes |
 | `lesson` | Extracts mistakes from sprints into `LESSONS.md` |
 | `vibe-code-review` | Runs Quick Scan or Deep Audit against acceptance criteria and architecture rules |
 | `write-skill` | Allows the Team Lead to author new skills when the team encounters a recurring problem |
 | `improve` | Self-improvement loop — reads agent friction signals across sprints and proposes framework changes (with your approval) |
+| `file-organization` | File structure management and organization verification |
 | `react-best-practices` | Example tech-stack skill — customize this for your own stack |
 
 ---
@@ -184,6 +450,10 @@ vbounce story complete STORY-ID       # Mark story done, update state
 vbounce state show                    # Print current state
 vbounce state update STORY-ID STATE   # Update story state
 
+# Product graph
+vbounce graph                         # Generate document dependency graph
+vbounce graph impact EPIC-002         # Show what's affected by a change
+
 # Context preparation
 vbounce prep sprint S-01              # Sprint context pack
 vbounce prep qa STORY-ID              # QA context pack
@@ -198,6 +468,7 @@ vbounce validate ready STORY-ID       # Pre-bounce readiness gate
 # Self-improvement
 vbounce trends                        # Cross-sprint trend analysis
 vbounce suggest S-01                  # Generate improvement suggestions
+vbounce improve S-01                  # Full self-improvement pipeline
 
 # Health check
 vbounce doctor                        # Verify setup
@@ -219,8 +490,11 @@ product_plans/                   # Created when you start planning
 
 .bounce/                         # Created on first sprint init
   state.json                     #   Machine-readable sprint state (crash recovery)
+  product-graph.json             #   Document dependency graph (auto-generated)
   reports/                       #   QA and Architect bounce reports
-  improvement-log.md             #   Tracked improvement suggestions
+  improvement-manifest.json      #   Machine-readable improvement proposals (auto-generated)
+  improvement-suggestions.md     #   Human-readable suggestions with impact levels (auto-generated)
+  improvement-log.md             #   Applied/rejected/deferred improvement tracking
 
 .worktrees/                      # Git worktrees for isolated story branches
 
@@ -229,18 +503,28 @@ LESSONS.md                       # Accumulated mistakes — agents read this bef
 
 ---
 
-## End-of-Sprint Reports
-
-When a sprint concludes, V-Bounce Engine generates three structured reports:
-
-- **Sprint Report** — what was delivered, execution metrics (tokens, cost, bounce rates), story results, lessons learned, and a retrospective.
-- **Release Report** — the DevOps agent's merge log, environment changes, and post-merge validations.
-- **Scribe Report** — which product documentation was created, updated, or flagged as stale.
+## Glossary
+
+| Term | Definition |
+|------|-----------|
+| **Bounce** | When a story fails a quality gate (QA or Architect) and gets sent back to the Developer for fixes |
+| **Bounce Rate** | Percentage of stories that fail a gate on the first attempt |
+| **Context Loop** | The closed feedback cycle: Plan → Build → Bounce → Document → Learn → next sprint |
+| **Correction Tax** | How much human intervention a story needed — 0% is fully autonomous, 100% means a human rewrote it |
+| **Escalation** | When a story hits the 3-bounce limit and surfaces to a human for intervention |
+| **Gate** | An automated quality checkpoint — QA validates requirements, Architect validates structure |
+| **Hotfix Path** | A fast track for trivial (L1) changes: 1-2 files, no QA/Architect gates, human verifies directly |
+| **L1–L4** | Complexity labels: L1 Trivial, L2 Standard, L3 Complex, L4 Uncertain |
+| **Root Cause Tag** | A label on every bounce failure (e.g., `missing_tests`, `adr_violation`) used for trend analysis |
+| **Scribe** | The documentation agent that maps code into semantic product docs |
+| **Sprint Report** | End-of-sprint summary: what shipped, metrics, bounce analysis, lessons, retrospective |
+| **Worktree** | An isolated git checkout where a single story is implemented — prevents cross-story interference |
 
 ---
 
 ## Documentation
 
+- [System Overview with diagrams](OVERVIEW.md)
 - [Epic template and structure](templates/epic.md)
 - [Hotfix edge cases](docs/HOTFIX_EDGE_CASES.md)
 - [vdoc integration](https://github.com/sandrinio/vdoc)

package/bin/vbounce.mjs

@@ -82,10 +82,13 @@ 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 graph [generate]              Generate product document graph
+  vbounce graph impact <DOC-ID>         Show what's affected by a document change
   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 improve <sprintId>           Run full self-improvement pipeline
   vbounce doctor                       Validate all configs and state files
 
 Install Platforms:
@@ -195,6 +198,40 @@ if (command === 'suggest') {
   runScript('suggest_improvements.mjs', args.slice(1));
 }
 
+// -- improve --
+if (command === 'improve') {
+  rl.close();
+  // Full pipeline: analyze → trends → suggest
+  const sprintArg = args[1];
+  if (!sprintArg) {
+    console.error('Usage: vbounce improve S-XX');
+    process.exit(1);
+  }
+  // Run trends first
+  const trendsPath = path.join(pkgRoot, 'scripts', 'sprint_trends.mjs');
+  if (fs.existsSync(trendsPath)) {
+    console.log('Step 1/2: Running cross-sprint trend analysis...');
+    spawnSync(process.execPath, [trendsPath], { stdio: 'inherit', cwd: process.cwd() });
+  }
+  // Run suggest (which internally runs post_sprint_improve.mjs)
+  console.log('\nStep 2/2: Running improvement analyzer + suggestions...');
+  runScript('suggest_improvements.mjs', [sprintArg]);
+}
+
+// -- graph --
+if (command === 'graph') {
+  rl.close();
+  if (sub === 'impact') {
+    runScript('product_impact.mjs', args.slice(2));
+  } else if (!sub || sub === 'generate') {
+    runScript('product_graph.mjs', args.slice(2));
+  } else {
+    console.error(`Unknown graph subcommand: ${sub}`);
+    console.error('Usage: vbounce graph [generate] | vbounce graph impact <DOC-ID>');
+    process.exit(1);
+  }
+}
+
 // -- docs --
 if (command === 'docs') {
   rl.close();
@@ -540,6 +577,13 @@ if (command === 'install') {
       console.log(`  \x1b[32m✓\x1b[0m ${rule.dest}`);
     }
 
+    // Create LESSONS.md if missing
+    const lessonsPath = path.join(CWD, 'LESSONS.md');
+    if (!fs.existsSync(lessonsPath)) {
+      fs.writeFileSync(lessonsPath, '# Lessons Learned\n\nProject-specific lessons recorded after each story merge. Read this before writing code.\n');
+      console.log(`  \x1b[32m✓\x1b[0m LESSONS.md (created)`);
+    }
+
     // Write install metadata
     writeInstallMeta(pkgVersion, targetPlatform, installedFiles, hashes);
     console.log(`  \x1b[32m✓\x1b[0m .bounce/install-meta.json`);