@sandrinio/vbounce 1.3.2 → 1.5.0

package/README.md

@@ -18,12 +18,24 @@ Instead of treating your AI as a solo developer, V-Bounce OS forces distinct, sp
 
 1. **Requirements (`product_plans/`)**: The Team Lead defines standard, immutable templates (Charter, Epic, Story) before a single line of code is written.
 2. **Bounce Reports (`.bounce/`)**: During implementation, the QA and Architect agents do not edit code. They run deep codebase audits and emit structured "Bounce Reports" summarizing anti-patterns and regressions. The Developer must fix the issues and run the loop again until the code passes validation. 
-3. **Product Documentation (`product_documentation/`)**: The Scribe agent explores the *actual* codebase post-merge and uses our integrated `vdoc` tool to update feature-centric documentation and the semantic `_manifest.json` map. 
+3. **Product Documentation (`vdocs/`)**: The Scribe agent explores the *actual* codebase post-merge and uses our integrated `vdoc` tool to update feature-centric documentation and the semantic `_manifest.json` map. 
 
 The next time an agent writes code, it reads the `_manifest.json` and the `LESSONS.md` file from previous sprints. The context loop closes. Your AI writes better code because it finally understands the reality of your evolving system.
 
 ---
 
+## 📂 State-Based Folder Structure
+
+V-Bounce OS organizes planning documents (`product_plans/`) through a strict state machine based on folder location:
+
+- **`strategy/`**: High-level context (Charter, Roadmap, Risk Registry, Release Plans). Frozen during active sprints.
+- **`backlog/`**: Where unassigned work lives. Epics and their child Stories are refined here until selected for a sprint.
+- **`sprints/`**: The active execution workspace. A physical `sprint-XX/` boundary is created and Stories are moved in. Only one sprint is "Active" at a time.
+- **`hotfixes/`**: Trivial, emergency tasks that bypass sprint cycles.
+- **`archive/`**: Immutable history. Finished sprint folders and fully completed Epics are permanently moved here.
+
+---
+
 ## 🛠️ The Tech Stack
 
 V-Bounce OS is built to be **local-first, privacy-conscious, and blazing fast**.
@@ -71,7 +83,7 @@ npx @sandrinio/vbounce install codex
 - **Templates:** Markdown templates for your Charter, Roadmap, Epics, and Stories.
 - **Bundled Scripts:** Our validation pipeline (`validate_report.mjs`) and RAG synchronization engine (`pre_bounce_sync.sh`).
 - **Autonomous RAG Setup:** The installer automatically runs `npm install` for required libraries and initializes your local LanceDB knowledge base (`.bounce/.lancedb/`).
-- **vdoc Integration:** Fully compatible with [`@sandrinio/vdoc`](https://github.com/sandrinio/vdoc) to automatically construct semantic product documentation.
+- **vdoc Integration:** The installer offers to install [`@sandrinio/vdoc`](https://github.com/sandrinio/vdoc) for your platform — enabling automatic semantic product documentation generation via the Scribe agent.
 
 ### 🧰 The Bundled Skills
 V-Bounce OS installs a powerful suite of specialized markdown `skills/` directly into your workspace. These act as modular capabilities you can invoke dynamically or that the Team Lead agent will invoke automatically during the SDLC process:
@@ -84,6 +96,7 @@ V-Bounce OS installs a powerful suite of specialized markdown `skills/` directly
 | `react-best-practices` | Developer | A strict set of frontend execution rules the Developer must follow during implementation. <mark>*(Note: This skill serves as a template and must be customized by the human according to the specific tech stack being used.)*</mark> |
 | `vibe-code-review` | QA/Architect | Runs distinct review modes (Quick Scan, Deep Audit) to validate code against Acceptance Criteria and Architecture rules. |
 | `write-skill` | Lead | Allows the Team Lead to autonomously write and deploy entirely *new* skills if the team repeatedly encounters a novel problem. |
+| `improve` | Lead | The framework's self-improvement loop. Reads agent friction signals from sprint retros and proposes targeted changes to templates, skills, brain files, and scripts — with human approval. |
 
 ---
 
@@ -111,6 +124,19 @@ When a sprint concludes, V-Bounce OS generates structured reports so human revie
 ### 4. Progressive Learning (`LESSONS.md`)
 Every time the AI makes a mistake during the Bounce Loop, it flags the issue. During the sprint retrospective, these mistakes are recorded in `LESSONS.md`—a permanent project memory that all agents read *before* writing any future code. **Your AI gets smarter about your specific codebase with every single sprint.**
 
+### 5. Self-Improving Framework (`improve` skill)
+V-Bounce OS doesn't just improve your code — it improves *itself*. Every agent report includes a **Process Feedback** section where agents flag friction with the framework: a template missing a critical field, a handoff that lost context, a RAG query that returned irrelevant results, or a skill instruction that was unclear.
+
+These signals are aggregated into the Sprint Report's **Framework Self-Assessment** — categorized by area (Templates, Handoffs, RAG Pipeline, Skills, Process Flow, Tooling) with severity ratings and suggested fixes.
+
+After every 2-3 sprints, the Team Lead runs the `improve` skill which:
+1. Reads accumulated friction signals across sprints
+2. Identifies recurring patterns (same complaint from multiple agents = real problem)
+3. Proposes specific, targeted changes to templates, skills, brain files, or scripts
+4. **Applies nothing without your approval** — you review every proposed change
+
+The result: templates get sharper, handoffs get cleaner, skills get more precise, and the bounce loop gets tighter — all driven by the agents who actually use the framework every day.
+
 ---
 
 ## 🔍 Keywords for Searchability

package/bin/vbounce.mjs

@@ -58,6 +58,16 @@ if (!command || command !== 'install' || !targetPlatform) {
 
 const CWD = process.cwd();
 
+// Map vbounce platform names to vdoc platform names
+const vdocPlatformMap = {
+  claude: 'claude',
+  cursor: 'cursor',
+  gemini: 'gemini',
+  codex: 'agents',
+  vscode: 'vscode',
+  copilot: 'vscode'
+};
+
 const platformMappings = {
   claude: [
     { src: 'brains/CLAUDE.md', dest: 'CLAUDE.md' },
@@ -196,5 +206,25 @@ askQuestion('Proceed with installation? [y/N] ').then(async answer => {
     console.error('  \x1b[31m✖\x1b[0m Failed to initialize knowledge base. Run ./scripts/pre_bounce_sync.sh manually.');
   }
 
+  // vdoc integration
+  const vdocPlatform = vdocPlatformMap[targetPlatform];
+  if (vdocPlatform) {
+    const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const vdocAnswer = await new Promise(resolve => rl2.question('\n📝 Install vdoc (AI-powered documentation generator)? [y/N] ', resolve));
+    rl2.close();
+
+    if (vdocAnswer.trim().toLowerCase() === 'y' || vdocAnswer.trim().toLowerCase() === 'yes') {
+      console.log(`\n📝 Installing vdoc for ${vdocPlatform}...`);
+      try {
+        execSync(`npx @sandrinio/vdoc install ${vdocPlatform}`, { stdio: 'inherit', cwd: CWD });
+        console.log('  \x1b[32m✓\x1b[0m vdoc installed.');
+      } catch (err) {
+        console.error(`  \x1b[31m✖\x1b[0m Failed to install vdoc. Run manually: npx @sandrinio/vdoc install ${vdocPlatform}`);
+      }
+    } else {
+      console.log(`\n  Skipped. You can install later: npx @sandrinio/vdoc install ${vdocPlatform}`);
+    }
+  }
+
   console.log('\n✅ V-Bounce OS successfully installed! Welcome to the team.\n');
 });

package/brains/AGENTS.md

@@ -20,6 +20,7 @@ Skills are in the `skills/` directory. Each skill has a `SKILL.md` with instruct
 | `skills/react-best-practices/` | Frontend coding patterns and anti-patterns | Developer |
 | `skills/vibe-code-review/` | Code quality review (4 modes) | QA, Architect |
 | `skills/write-skill/` | Creating and refining agent skills | Team Lead |
+| `skills/improve/` | Framework self-improvement from agent feedback | Team Lead |
 
 ## The V-Bounce Process
 
@@ -32,9 +33,12 @@ Before starting any sprint, the Team Lead MUST:
 - **Triage the Request**: Is this an L1 Trivial change (1-2 files, cosmetic/minor)?
   - If YES → Use the **Hotfix Path** (create a Hotfix document, bypass Epic/Story).
   - If NO → Use the **Standard Path** (create/find Epic, Story).
+- **Determine Execution Mode**: Full Bounce vs Fast Track.
+- **Dependency Check**: Stories with `Depends On:` must execute sequentially.
 - Read RISK_REGISTRY.md — flag high-severity risks that affect planned stories.
-- Read DELIVERY_PLAN.md §5 Open Questions — do not bounce stories with unresolved blocking questions.
-- If product_documentation/_manifest.json exists, read it — understand what's documented, pass relevant doc references to agents.
+- Read `sprint-{XX}.md` §2 Sprint Open Questions — do not bounce stories with unresolved blocking questions.
+- If `vdocs/_manifest.json` exists, read it.
+- **Strategic Freeze**: Charter/Roadmap frozen during sprints. Use **Impact Analysis Protocol** if emergency changes occur. Evaluate active stories against new strategy. Pause until human approval.
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4 Stories):**
@@ -57,7 +61,7 @@ Before starting any sprint, the Team Lead MUST:
 
 ### Phase 3: Review
 Sprint Report → Human review → Delivery Plan updated → Lessons recorded → Next sprint.
-If sprint delivered new features or Dev reports flagged stale product docs → spawn Scribe agent to generate/update product_documentation/ via vdoc.
+If sprint delivered new features or Dev reports flagged stale product docs → spawn Scribe agent to generate/update vdocs/ via vdoc.
 
 ## Story States
 
@@ -83,7 +87,8 @@ Bouncing → Escalated (3+ failures)
 ### During Implementation
 4. Follow the Safe Zone. No new patterns or libraries without Architect approval.
 5. No Gold-Plating. Implement exactly what the Story specifies.
-6. Self-assess Correction Tax. Track % human intervention.
+6. Write Self-Documenting Code. JSDoc/docstrings required on all exports to prevent RAG poisoning.
+7. Self-assess Correction Tax. Track % human intervention.
 
 ### After Implementation
 7. Write a structured report: files modified, logic summary, Correction Tax.
@@ -109,18 +114,19 @@ V-Bounce OS/
 
 ## Document Locations
 
-Planning docs live in `product_plans/`. Each delivery (= release) gets a folder. Epics are subfolders. Stories live with their Epic. Completed deliveries archived to `product_plans/archive/`.
+Planning docs live in `product_plans/`. It uses a state-based architecture (`strategy/`, `backlog/`, `sprints/`, `archive/`). Completed items are archived to `product_plans/archive/`.
 
 | Document | Output |
 |----------|--------|
-| Charter | `product_plans/{project}_charter.md` |
-| Roadmap | `product_plans/{project}_roadmap.md` |
-| Risk Registry | `product_plans/RISK_REGISTRY.md` |
-| Delivery Plan | `product_plans/{delivery}/DELIVERY_PLAN.md` |
-| Epic | `product_plans/{delivery}/EPIC-{NNN}_{name}/EPIC-{NNN}.md` |
-| Story | `product_plans/{delivery}/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}.md` |
-| Sprint Report | `.bounce/sprint-report.md` |
-| Product Docs | `product_documentation/*.md` + `_manifest.json` |
+| Charter | `product_plans/strategy/{project}_charter.md` |
+| Roadmap | `product_plans/strategy/{project}_roadmap.md` |
+| Risk Registry | `product_plans/strategy/RISK_REGISTRY.md` |
+| Delivery Plan | `product_plans/strategy/{delivery}_delivery_plan.md` |
+| Sprint Plan | `product_plans/sprints/sprint-{XX}/sprint-{XX}.md` |
+| Epic | `product_plans/backlog/EPIC-{NNN}_{name}/EPIC-{NNN}.md` |
+| Story | `product_plans/backlog/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}-{StoryName}.md` |
+| Sprint Report | `product_plans/sprints/sprint-{XX}/sprint-report.md` |
+| Product Docs | `vdocs/*.md` + `_manifest.json` |
 
 ## Report Formats
 

package/brains/CHANGELOG.md

@@ -5,3 +5,27 @@ Per **Rule 13: Framework Integrity**, anytime an entry is made here, the orchest
 
 ## [2026-03-02]
 - **Initialized**: Created strict Framework Integrity tracking, YAML context handoffs, and RAG validation pipeline.
+
+## [2026-03-06]
+- **Fixed**: All brain files (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`) incorrectly referenced `DELIVERY_PLAN.md §5 Open Questions` or `ACTIVE_SPRINT.md §3 Open Questions`. Corrected to `sprint-{XX}.md §2 Sprint Open Questions` to match the authoritative `agent-team/SKILL.md` and `sprint.md` template.
+- **Fixed**: Removed duplicate "Product Plans Folder Structure" header in `doc-manager/SKILL.md`.
+- **Fixed**: `cursor-rules/vbounce-process.mdc` was missing Execution Mode, Sequential Dependencies, Impact Analysis Protocol, and Strategic Freeze rules from the 2026-03-05 update. Propagated.
+- **Removed**: `templates/active_sprint.md` — orphaned by the state-based refactor. Superseded by `templates/sprint.md`.
+- **Modified**: `cursor-rules/vbounce-rules.mdc` — added Rule 6 (JSDoc/docstrings), Rule 13 (YAML Frontmatter), Rule 14 (Framework Integrity) to match other brains.
+- **Modified**: `cursor-rules/vbounce-docs.mdc` — added Hotfix and Sprint Report entries to Document Locations table.
+- **Modified**: `cursor-rules/vbounce-process.mdc` — added `pre_bounce_sync.sh` and `validate_report.mjs` steps to Phase 2.
+- **Modified**: Renamed `product_documentation/` → `vdocs/` across all brains, skills, agents, templates, scripts, diagrams, README, OVERVIEW, and SETUP to align with `@sandrinio/vdoc` output conventions.
+- **Modified**: `bin/vbounce.mjs` — added optional vdoc installation step that auto-maps the user's chosen platform to the corresponding `npx @sandrinio/vdoc install <platform>` command.
+- **Modified**: `brains/SETUP.md` — updated folder structure diagram to reflect state-based `product_plans/` layout.
+- **Added**: `skills/improve/SKILL.md` — framework self-improvement skill. Reads agent Process Feedback from sprint retros, identifies patterns, proposes changes to templates/skills/brains/scripts with human approval.
+- **Modified**: All agent report templates (`developer.md`, `qa.md`, `architect.md`, `devops.md`, `scribe.md`) — added `## Process Feedback` section for framework friction signals.
+- **Modified**: `templates/sprint_report.md` §5 Retrospective — restructured into categorized Framework Self-Assessment (Templates, Handoffs, RAG, Skills, Process Flow, Tooling) with severity and suggested fixes.
+- **Modified**: `skills/agent-team/SKILL.md` Step 7 — added Framework Self-Assessment aggregation and `improve` skill trigger.
+- **Modified**: All brain files and `README.md` — added `improve` skill to skill references.
+
+## [2026-03-05]
+- **Modified**: Added `tokens_used` tracking to all agent instructions (`brains/claude-agents/*`).
+- **Modified**: Updated `skills/agent-team/SKILL.md` to consolidate tokens into `sprint_report.md`.
+- **Modified**: Updated `scripts/validate_report.mjs` to enforce `tokens_used` schema presence.
+- **Modified**: Refactored `STORY-{EpicID}-{StoryID}` file naming convention to `STORY-{EpicID}-{StoryID}-{StoryName}` across all templates, agent instructions, skill definitions, and architecture files for better human readability.
+- **Modified**: Refactored the generic `product_plans` folder into a state-based architecture (`strategy/`, `backlog/`, `sprints/`, `hotfixes/`, `archive/`). Separated Sprint tracking logic from `DELIVERY_PLAN.md` into a new `sprint.md` template. Updated `doc-manager` and `agent-team` orchestration to adhere to these physical transition rules.

package/brains/CLAUDE.md

@@ -16,6 +16,7 @@ You MUST follow the V-Bounce process. Deviating from it — skipping validation,
 @skills/react-best-practices/SKILL.md
 @skills/vibe-code-review/SKILL.md
 @skills/write-skill/SKILL.md
+@skills/improve/SKILL.md
 
 ## Subagents
 
@@ -44,9 +45,14 @@ Before starting any sprint, the Team Lead MUST:
 - **Triage the Request**: Is this an L1 Trivial change (1-2 files, cosmetic/minor)?
   - If YES → Use the **Hotfix Path** (create a Hotfix document, bypass Epic/Story).
   - If NO → Use the **Standard Path** (create/find Epic, Story).
+- **Determine Execution Mode**:
+  - Full Bounce (Default): dev → qa → arch → devops.
+  - Fast Track (L1/L2 Minor): dev → devops only (skip QA/Arch gates).
+- **Dependency Check**: Stories with `Depends On:` must execute sequentially. Wait for DevOps merge of Story A before starting Story B.
 - Read RISK_REGISTRY.md — flag high-severity risks that affect planned stories.
-- Read DELIVERY_PLAN.md §5 Open Questions — do not bounce stories with unresolved blocking questions.
-- If `product_documentation/_manifest.json` exists, read it — understand what's documented, pass relevant doc references to agents, and track what may become stale.
+- Read `sprint-{XX}.md` §2 Sprint Open Questions — do not bounce stories with unresolved blocking questions.
+- If `vdocs/_manifest.json` exists, read it.
+- **Strategic Freeze**: Charter and Roadmap are frozen during sprints. If emergency changes are needed, run the **Impact Analysis Protocol**: Evaluate sprint stories against new strategy. Pause work until human approval.
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4 Stories):**
@@ -69,7 +75,7 @@ Before starting any sprint, the Team Lead MUST:
 
 ### Phase 3: Review
 Sprint Report → Human review → Delivery Plan updated → Lessons recorded → Next sprint.
-If sprint delivered new features or Developer reports flagged stale product docs → spawn Scribe agent to generate/update product_documentation/ via vdoc.
+If sprint delivered new features or Developer reports flagged stale product docs → spawn Scribe agent to generate/update vdocs/ via vdoc.
 
 ## Story States
 
@@ -97,7 +103,8 @@ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architec
 ### During Implementation
 4. **Follow the Safe Zone**. No new patterns or libraries without Architect approval.
 5. **No Gold-Plating**. Implement exactly what the Story specifies.
-6. **Self-assess Correction Tax**. Track % human intervention.
+6. **Write Self-Documenting Code**. All exports MUST have JSDoc/docstrings to prevent RAG poisoning for future agents.
+7. **Self-assess Correction Tax**. Track % human intervention.
 
 ### After Implementation
 7. **Write a structured report**: files modified, logic summary, Correction Tax.
@@ -123,19 +130,20 @@ V-Bounce OS/
 
 ## Document Locations
 
-All planning documents live in `product_plans/`. Each delivery (= Roadmap Release) gets its own folder. Epics are subfolders. Stories live inside their parent Epic folder.
+All planning documents live in `product_plans/`, separated by state (`strategy/`, `backlog/`, `sprints/`, `archive/`).
 
 | Document | Template | Output |
 |----------|----------|--------|
-| Charter | `templates/charter.md` | `product_plans/{project}_charter.md` |
-| Roadmap | `templates/roadmap.md` | `product_plans/{project}_roadmap.md` |
-| Risk Registry | `templates/risk_registry.md` | `product_plans/RISK_REGISTRY.md` |
-| Delivery Plan | `templates/delivery_plan.md` | `product_plans/{delivery}/DELIVERY_PLAN.md` |
-| Epic | `templates/epic.md` | `product_plans/{delivery}/EPIC-{NNN}_{name}/EPIC-{NNN}.md` |
-| Story | `templates/story.md` | `product_plans/{delivery}/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}.md` |
-| Sprint Report | `templates/sprint_report.md` | `.bounce/sprint-report.md` |
-| Product Docs | (generated by vdoc) | `product_documentation/*.md` |
-| Doc Manifest | (generated by vdoc) | `product_documentation/_manifest.json` |
+| Charter | `templates/charter.md` | `product_plans/strategy/{project}_charter.md` |
+| Roadmap | `templates/roadmap.md` | `product_plans/strategy/{project}_roadmap.md` |
+| Risk Registry | `templates/risk_registry.md` | `product_plans/strategy/RISK_REGISTRY.md` |
+| Delivery Plan | `templates/delivery_plan.md` | `product_plans/strategy/{delivery}_delivery_plan.md` |
+| Sprint Plan | `templates/sprint.md` | `product_plans/sprints/sprint-{XX}/sprint-{XX}.md` |
+| Epic | `templates/epic.md` | `product_plans/backlog/EPIC-{NNN}_{name}/EPIC-{NNN}.md` |
+| Story | `templates/story.md` | `product_plans/backlog/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}-{StoryName}.md` |
+| Sprint Report | `templates/sprint_report.md` | `product_plans/sprints/sprint-{XX}/sprint-report.md` |
+| Product Docs | (generated by vdoc) | `vdocs/*.md` |
+| Doc Manifest | (generated by vdoc) | `vdocs/_manifest.json` |
 
 Completed deliveries are archived to `product_plans/archive/` and logged in Roadmap §7 Delivery Log.
 

package/brains/GEMINI.md

@@ -23,6 +23,7 @@ For Antigravity: copy skills to `.agents/skills/` for workspace-scoped discovery
 | `skills/react-best-practices/` | Frontend coding patterns and anti-patterns | Developer |
 | `skills/vibe-code-review/` | Code quality review (4 modes) | QA, Architect |
 | `skills/write-skill/` | Creating and refining agent skills | Team Lead |
+| `skills/improve/` | Framework self-improvement from agent feedback | Team Lead |
 
 ## The V-Bounce Process
 
@@ -35,9 +36,14 @@ Before starting any sprint, the Team Lead MUST:
 - **Triage the Request**: Is this an L1 Trivial change (1-2 files, cosmetic/minor)?
   - If YES → Use the **Hotfix Path** (create a Hotfix document, bypass Epic/Story).
   - If NO → Use the **Standard Path** (create/find Epic, Story).
+- **Determine Execution Mode**:
+  - Full Bounce (Default): dev → qa → arch → devops.
+  - Fast Track (L1/L2 Minor): dev → devops only (skip QA/Arch gates).
+- **Dependency Check**: Stories with `Depends On:` must execute sequentially. Wait for DevOps merge of Story A before starting Story B.
 - Read RISK_REGISTRY.md — flag high-severity risks that affect planned stories.
-- Read DELIVERY_PLAN.md §5 Open Questions — do not bounce stories with unresolved blocking questions.
-- If `product_documentation/_manifest.json` exists, read it — understand what's documented, pass relevant doc references to agents.
+- Read `sprint-{XX}.md` §2 Sprint Open Questions — do not bounce stories with unresolved blocking questions.
+- If `vdocs/_manifest.json` exists, read it.
+- **Strategic Freeze**: Charter and Roadmap are frozen during sprints. If emergency changes are needed, run the **Impact Analysis Protocol**: Evaluate sprint stories against new strategy. Pause work until human approval.
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4 Stories):**
@@ -60,7 +66,7 @@ Before starting any sprint, the Team Lead MUST:
 
 ### Phase 3: Review
 Sprint Report → Human review → Delivery Plan updated → Lessons recorded → Next sprint.
-If sprint delivered new features or Dev reports flagged stale product docs → spawn Scribe agent to generate/update product_documentation/ via vdoc.
+If sprint delivered new features or Dev reports flagged stale product docs → spawn Scribe agent to generate/update vdocs/ via vdoc.
 
 ## Story States
 
@@ -88,7 +94,8 @@ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architec
 ### During Implementation
 4. **Follow the Safe Zone**. No new patterns or libraries without Architect approval.
 5. **No Gold-Plating**. Implement exactly what the Story specifies.
-6. **Self-assess Correction Tax**. Track % human intervention.
+6. **Write Self-Documenting Code**. All exports MUST have JSDoc/docstrings to prevent RAG poisoning for future agents.
+7. **Self-assess Correction Tax**. Track % human intervention.
 
 ### After Implementation
 7. **Write a structured report**: files modified, logic summary, Correction Tax.
@@ -114,18 +121,19 @@ V-Bounce OS/
 
 ## Document Locations
 
-Planning docs live in `product_plans/`. Each delivery (= release) gets a folder. Epics are subfolders. Stories live with their Epic. Completed deliveries archived to `product_plans/archive/`.
+Planning docs live in `product_plans/`. It uses a state-based architecture (`strategy/`, `backlog/`, `sprints/`, `archive/`). Completed items are archived to `product_plans/archive/`.
 
 | Document | Output |
 |----------|--------|
-| Charter | `product_plans/{project}_charter.md` |
-| Roadmap | `product_plans/{project}_roadmap.md` |
-| Risk Registry | `product_plans/RISK_REGISTRY.md` |
-| Delivery Plan | `product_plans/{delivery}/DELIVERY_PLAN.md` |
-| Epic | `product_plans/{delivery}/EPIC-{NNN}_{name}/EPIC-{NNN}.md` |
-| Story | `product_plans/{delivery}/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}.md` |
-| Sprint Report | `.bounce/sprint-report.md` |
-| Product Docs | `product_documentation/*.md` + `_manifest.json` |
+| Charter | `product_plans/strategy/{project}_charter.md` |
+| Roadmap | `product_plans/strategy/{project}_roadmap.md` |
+| Risk Registry | `product_plans/strategy/RISK_REGISTRY.md` |
+| Delivery Plan | `product_plans/strategy/{delivery}_delivery_plan.md` |
+| Sprint Plan | `product_plans/sprints/sprint-{XX}/sprint-{XX}.md` |
+| Epic | `product_plans/backlog/EPIC-{NNN}_{name}/EPIC-{NNN}.md` |
+| Story | `product_plans/backlog/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}-{StoryName}.md` |
+| Sprint Report | `product_plans/sprints/sprint-{XX}/sprint-report.md` |
+| Product Docs | `vdocs/*.md` + `_manifest.json` |
 
 ## Report Formats
 

package/brains/SETUP.md

@@ -143,16 +143,13 @@ your-project/
 │   ├── react-best-practices/
 │   └── write-skill/
 ├── templates/                 ← document templates
-├── product_plans/             ← planning documents
-│   ├── {project}_charter.md
-│   ├── {project}_roadmap.md
-│   ├── RISK_REGISTRY.md
-│   └── D-01_{release}/
-│       ├── DELIVERY_PLAN.md
-│       └── EPIC-001_{name}/
-│           ├── EPIC-001.md
-│           └── STORY-001-01.md
-├── product_documentation/     ← generated by Scribe (post-sprint)
+├── product_plans/             ← planning documents (state-based)
+│   ├── strategy/              ← charter, roadmap, risk registry, delivery plan
+│   ├── backlog/               ← epics and unassigned stories
+│   ├── sprints/               ← active sprint execution workspace
+│   ├── hotfixes/              ← L1 emergency tasks
+│   └── archive/               ← completed sprints and epics
+├── vdocs/     ← generated by Scribe (post-sprint)
 ├── .bounce/                   ← reports & sprint archives (archive/ is committed)
 │   ├── reports/               ← active reports (gitignored)
 │   └── archive/               ← completed sprint history (committed to git)

package/brains/claude-agents/architect.md

@@ -15,7 +15,7 @@ Audit the codebase for structural integrity, standards compliance, and long-term
 ## Before Auditing
 
 1. **Query Project Lessons**: Run `./scripts/vbounce_ask.mjs "architectural constraints and historical mistakes for <story summary>"` to retrieve relevant context from `LESSONS.md` and past reports.
-2. **Read all reports** for this story (`.bounce/reports/STORY-{ID}-*.md`) — Dev Report, QA Report.
+2. **Read all reports** for this story (`.bounce/reports/STORY-{ID}-{StoryName}-*.md`) — Dev Report, QA Report.
 3. **Read the full Story spec** — especially §3 Implementation Guide and §3.1 ADR References.
 4. **Read Roadmap §3 ADRs** — every architecture decision the implementation must comply with.
 
@@ -63,21 +63,30 @@ Check that the changes don't break existing functionality:
 - Check for modified shared utilities, types, or config
 - Verify imports and exports haven't broken dependency chains
 
+### Documentation Verification (RAG Hygiene)
+Check that the codebase remains self-documenting for downstream RAG consumption:
+- Does the implementation match the existing `vdocs/_manifest.json` (if one exists)?
+- If it diverges entirely, you MUST fail the audit and instruct the Developer to update their report's Documentation Delta.
+- Are exported functions, components, and schemas adequately JSDoc commented? Code must explain the *why*.
+
 ## Your Output
 
-Write an **Architectural Audit Report** to `.bounce/reports/STORY-{ID}-arch.md`.
+Write an **Architectural Audit Report** to `.bounce/reports/STORY-{ID}-{StoryName}-arch.md`.
 You MUST include the YAML frontmatter block exactly as shown below:
 
+**Token Tracking**: Before generating this report, retrieve your session's token usage (if you are Claude, ask your CLI; if Gemini, read your context estimate; if Codex, read your log output) and populate `tokens_used`.
+
 ### If Audit PASSES:
 ```markdown
 ---
 status: "PASS"
 safe_zone_score: {SCORE}
+tokens_used: {number}
 ai_isms_detected: {count}
 regression_risk: "{Low/Medium/High}"
 ---
 
-# Architectural Audit Report: STORY-{ID} — PASS
+# Architectural Audit Report: STORY-{ID}-{StoryName} — PASS
 
 ## Safe Zone Compliance: {SCORE}/10
 
@@ -110,6 +119,12 @@ regression_risk: "{Low/Medium/High}"
 ## Lessons for Future Prompts
 - {What should we tell the Dev Agent differently next time?}
 
+## Process Feedback
+> Optional. Note friction with the V-Bounce framework itself — templates, handoffs, RAG quality, skills.
+
+- {e.g., "vibe-code-review Deep Audit checklist missing a dimension for accessibility"}
+- {e.g., "None"}
+
 ## Recommendation
 PASS — Ready for Sprint Review.
 ```
@@ -119,10 +134,11 @@ PASS — Ready for Sprint Review.
 ---
 status: "FAIL"
 bounce_count: {N}
+tokens_used: {number}
 critical_failures: {count}
 ---
 
-# Architectural Audit Report: STORY-{ID} — FAIL
+# Architectural Audit Report: STORY-{ID}-{StoryName} — FAIL
 
 ## Critical Failures
 ### Issue 1: {Short description}
@@ -132,6 +148,12 @@ critical_failures: {count}
 - **What's wrong (plain language)**: {Non-coder analogy}
 - **Fix required**: {What the Dev needs to change}
 
+## Process Feedback
+> Optional. Note friction with the V-Bounce framework itself — templates, handoffs, RAG quality, skills.
+
+- {e.g., "Trend Check had no baseline — first sprint, but the template still requires comparison"}
+- {e.g., "None"}
+
 ## Recommendation
 FAIL — Returning to Developer. Architect bounce count: {N}.
 ```
@@ -146,10 +168,10 @@ When the Team Lead asks for a **Sprint Integration Audit** (after all stories pa
 
 ## Checkpointing
 
-After completing each major phase of your audit (e.g., Deep Audit done, Trend Check done, ADR compliance checked), write a progress checkpoint to `.bounce/reports/STORY-{ID}-arch-checkpoint.md`:
+After completing each major phase of your audit (e.g., Deep Audit done, Trend Check done, ADR compliance checked), write a progress checkpoint to `.bounce/reports/STORY-{ID}-{StoryName}-arch-checkpoint.md`:
 
 ```markdown
-# Architect Checkpoint: STORY-{ID}
+# Architect Checkpoint: STORY-{ID}-{StoryName}
 ## Completed
 - {Which audit phases are done}
 ## Remaining

package/brains/claude-agents/developer.md

@@ -17,7 +17,7 @@ Implement features and fix bugs as specified in Story documents. You write code
 3. **Read the Story spec** — §1 The Spec for requirements, §3 Implementation Guide for technical approach.
 3. **Check ADR references** in §3.1 — comply with all architecture decisions from the Roadmap.
 4. **Read relevant react-best-practices rules** — consult `skills/react-best-practices/` for patterns matching your task.
-5. **Check product documentation** — if the task file references product docs from `product_documentation/`, read them. Understand how the existing feature works before changing adjacent code. If your implementation changes behavior described in a product doc, flag it in your report.
+5. **Check product documentation** — if the task file references product docs from `vdocs/`, read them. Understand how the existing feature works before changing adjacent code. If your implementation changes behavior described in a product doc, flag it in your report.
 
 ## During Implementation
 
@@ -27,32 +27,36 @@ Implement features and fix bugs as specified in Story documents. You write code
 3. **Refactor:** Clean up the code for readability and architecture without breaking the tests.
 
 - **Follow the Safe Zone.** Do not introduce new patterns, libraries, or architectural changes.
+- **Write Self-Documenting Code.** To prevent RAG poisoning downstream, you MUST write clear JSDoc/docstrings for all exported functions, components, schemas, and routing logic. Explain the *why*, not just the *what*. If you fail to document your code, the Scribe agent cannot generate an accurate `_manifest.json` for future sprints.
 - **No Gold-Plating.** Implement exactly what the Story specifies. Extra features are defects, not bonuses.
 - **Track your Correction Tax.** Note every point where you needed human intervention or made a wrong turn.
 
 ## If You Discover the Spec is Wrong
 
 Do NOT proceed with a broken spec. Instead:
-- Write a **Spec Conflict Report** to `.bounce/reports/STORY-{ID}-conflict.md`
+- Write a **Spec Conflict Report** to `.bounce/reports/STORY-{ID}-{StoryName}-conflict.md`
 - Describe exactly what's wrong (missing API, changed schema, contradictory requirements)
 - Stop implementation and wait for the Lead to resolve
 
 ## Your Output
 
-Write a **Developer Implementation Report** to `.bounce/reports/STORY-{ID}-dev.md`. 
+Write a **Developer Implementation Report** to `.bounce/reports/STORY-{ID}-{StoryName}-dev.md`. 
 You MUST include the YAML frontmatter block exactly as shown below:
 
 ```markdown
 ---
 status: "implemented"
 correction_tax: {X}
+tokens_used: {number}
 tests_written: {number of tests generated}
 files_modified:
   - "path/to/file.ts"
 lessons_flagged: {number of lessons}
 ---
 
-# Developer Implementation Report: STORY-{ID}
+# Developer Implementation Report: STORY-{ID}-{StoryName}
+
+**Token Tracking**: Before generating this report, retrieve your session's token usage (if you are Claude, ask your CLI; if Gemini, read your context estimate; if Codex, read your log output) and populate `tokens_used`.
 
 ## Files Modified
 - `path/to/file.ts` — {what changed and why}
@@ -68,22 +72,31 @@ lessons_flagged: {number of lessons}
 - {Any gotchas, non-obvious behaviors, or multi-attempt fixes worth recording}
 
 ## Product Docs Affected
-- {List any product_documentation/ docs whose described behavior changed due to this implementation. "None" if no docs affected.}
+- {List any vdocs/ docs whose described behavior changed due to this implementation. "None" if no docs affected.}
 
 ## Status
 - [ ] Code compiles without errors
 - [ ] Automated tests were written FIRST (Red) and now pass (Green)
 - [ ] LESSONS.md was read before implementation
 - [ ] ADRs from Roadmap §3 were followed
+- [ ] Code is self-documenting (JSDoc/docstrings added to all exports to prevent RAG poisoning)
 - [ ] No new patterns or libraries introduced
+
+## Process Feedback
+> Optional. Note friction with the V-Bounce framework itself — templates, handoffs, RAG quality, tooling.
+> These are about the *process*, not the *code*. Aggregated into Sprint Retro for framework improvement.
+
+- {e.g., "Story template §3 didn't mention which existing modules to reuse — had to search manually"}
+- {e.g., "RAG query for 'auth constraints' returned irrelevant results from an old sprint"}
+- {e.g., "None"}
 ```
 
 ## Checkpointing
 
-After completing each major phase of your work (e.g., initial implementation done, tests written, bug fixes applied), write a progress checkpoint to `.bounce/reports/STORY-{ID}-dev-checkpoint.md`:
+After completing each major phase of your work (e.g., initial implementation done, tests written, bug fixes applied), write a progress checkpoint to `.bounce/reports/STORY-{ID}-{StoryName}-dev-checkpoint.md`:
 
 ```markdown
-# Developer Checkpoint: STORY-{ID}
+# Developer Checkpoint: STORY-{ID}-{StoryName}
 ## Completed
 - {What's done so far}
 ## Remaining