@sandrinio/vbounce 1.5.0 → 1.7.0

package/brains/AGENTS.md

@@ -42,14 +42,16 @@ Before starting any sprint, the Team Lead MUST:
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4 Stories):**
-0. Team Lead runs `./scripts/pre_bounce_sync.sh` to ensure LanceDB RAG context is fresh.
+0. **Orient via state**: Read `.bounce/state.json` (`vbounce state show`) for instant context. Run `vbounce prep sprint S-{XX}` to generate a fresh context pack.
 1. Team Lead sends Story context pack to Developer.
-2. Developer queries LanceDB, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
-3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report before passing to Architect/Dev.
-4. Dev fixes and resubmits. 3+ failures → Escalated.
-5. Architect runs Deep Audit + Trend Check, validates Safe Zone compliance and ADR adherence.
-6. DevOps merges story branch into sprint branch, validates post-merge, handles release tagging.
-7. Team Lead consolidates reports into Sprint Report.
+2. Developer reads LESSONS.md and the Story context pack, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
+3. **Pre-QA Gate Scan:** Team Lead runs `./scripts/pre_gate_runner.sh qa` to catch mechanical failures before spawning QA. If trivial issues → return to Dev.
+4. QA runs Quick Scan + PR Review (skipping pre-scanned checks), validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report.
+5. Dev fixes and resubmits. 3+ failures → Escalated.
+6. **Pre-Architect Gate Scan:** Team Lead runs `./scripts/pre_gate_runner.sh arch` to catch structural issues before spawning Architect. If mechanical failures → return to Dev.
+7. Architect runs Deep Audit + Trend Check (skipping pre-scanned checks), validates Safe Zone compliance and ADR adherence.
+8. DevOps merges story branch into sprint branch, validates post-merge (tests + lint + build), handles release tagging.
+9. Team Lead consolidates reports into Sprint Report.
 
 **Hotfix Path (L1 Trivial Tasks):**
 1. Team Lead evaluates request and creates `HOTFIX-{Date}-{Name}.md`.
@@ -99,7 +101,7 @@ Bouncing → Escalated (3+ failures)
 10. One source of truth. Reference upstream documents, don't duplicate.
 11. Change Logs are mandatory on every document modification.
 12. Agent Reports MUST use YAML Frontmatter. Every `.bounce/report/` generated must start with a strict `---` YAML block containing the core status and metrics before the Markdown body.
-13. Framework Integrity. Any modification to a `brains/` or `skills/` file MUST be recorded in `brains/CHANGELOG.md` and trigger `./scripts/pre_bounce_sync.sh`.
+13. Framework Integrity. Any modification to a `brains/` or `skills/` file MUST be recorded in `brains/CHANGELOG.md`.
 
 ## Framework Structure
 
@@ -121,11 +123,11 @@ Planning docs live in `product_plans/`. It uses a state-based architecture (`str
 | 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` |
+| Delivery Plan | `product_plans/D-{NN}_{release_name}/D-{NN}_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` |
+| Sprint Report | `.bounce/sprint-report-S-{XX}.md` |
 | Product Docs | `vdocs/*.md` + `_manifest.json` |
 
 ## Report Formats

package/brains/CHANGELOG.md

@@ -1,11 +1,109 @@
 # V-Bounce OS Brains & Skills Changelog
 
 This log tracks modifications to the core agentic framework (e.g., `brains/`, `skills/`). 
-Per **Rule 13: Framework Integrity**, anytime an entry is made here, the orchestrator MUST trigger `./scripts/pre_bounce_sync.sh` to update the RAG embeddings globally.
+Per **Rule 13: Framework Integrity**, anytime an entry is made here, all tool-specific brain files must be reviewed for consistency.
+
+## [2026-03-12] — LanceDB Removal
+
+- **Removed**: `scripts/vbounce_ask.mjs` — LanceDB semantic query tool. Replaced by direct `LESSONS.md` reads.
+- **Removed**: `scripts/vbounce_index.mjs` — LanceDB indexer. No longer needed.
+- **Removed**: `scripts/pre_bounce_sync.sh` — RAG sync script. No longer needed.
+- **Modified**: `package.json` — Removed `@lancedb/lancedb` and `@xenova/transformers` dependencies. Only `js-yaml`, `marked`, `commander` remain.
+- **Modified**: `bin/vbounce.mjs` — Removed `vbounce sync` command; simplified `install` to not run RAG init or install embedding deps.
+- **Modified**: `brains/CLAUDE.md`, `brains/AGENTS.md`, `brains/GEMINI.md`, `brains/cursor-rules/vbounce-process.mdc` — Phase 2 Step 0 now reads state.json + runs `vbounce prep sprint` instead of `pre_bounce_sync.sh`; Step 2 now says "read LESSONS.md" instead of "query LanceDB".
+- **Modified**: `brains/claude-agents/developer.md`, `qa.md`, `architect.md` — "Before" steps now read LESSONS.md directly instead of calling `vbounce_ask.mjs`.
+- **Modified**: `brains/SETUP.md` — Step 7 rewritten as "Initialize Your First Sprint" (`vbounce sprint init`, `vbounce doctor`, `vbounce prep sprint`).
+- **Modified**: `brains/CHANGELOG.md` Rule 13 — Removed `pre_bounce_sync.sh` trigger; only CHANGELOG.md update required.
+- **Modified**: `templates/story.md`, `templates/hotfix.md` — Framework Integrity checklist item no longer mentions `pre_bounce_sync.sh`.
+- **Modified**: `scripts/doctor.mjs` — Removed `pre_bounce_sync.sh` from required scripts list (now 15 scripts).
+- **Modified**: `skills/improve/SKILL.md` — "RAG Pipeline" area renamed to "Context Prep" pointing to prep scripts.
+- **Modified**: `README.md` — Removed "Semantic Context (Local RAG)" section; updated Tech Stack to reflect file-based context model; updated CLI reference.
+- **Modified**: `.gitignore` — Removed `.bounce/.lancedb/` entry.
+- **Rationale**: Modern LLMs have 200K+ token context windows. The prep scripts (`vbounce prep sprint/qa/arch`) + LESSONS.md graduation provide targeted, deterministic context without embedding models, sync steps, or heavy dependencies. Removes ~50MB of node_modules and eliminates the most common setup failure point.
+
+## [2026-03-12] — V-Bounce OS Optimization Plan (12-Change Batch)
+
+### State Management (Change #1)
+- **Added**: `.bounce/state.json` — machine-readable sprint state snapshot for crash recovery. Tracks sprint_id, delivery_id, current_phase, last_action, and per-story state (V-Bounce state, bounce counts, worktree path, updated_at).
+- **Added**: `scripts/validate_state.mjs` — schema validator for state.json; exports `validateState(obj)` function with strict checks on format, enum values, and cross-field consistency.
+- **Added**: `scripts/update_state.mjs` — atomic state.json updater; supports `--qa-bounce`, `--arch-bounce`, `--set-phase`, `--set-action`, `--show` flags; calls validateState after every write.
+- **Modified**: `brains/CLAUDE.md` Phase 2 Step 0 — updated to "Orient via state: Read `.bounce/state.json`" for instant context recovery.
+- **Modified**: `brains/GEMINI.md` Phase 2 Step 0 — same state.json orientation update.
+
+### Sprint Scripts (Change #2)
+- **Added**: `scripts/init_sprint.mjs` — creates `.bounce/` dir, state.json (stories in Draft), sprint plan dir, copies template; prints git commands.
+- **Added**: `scripts/close_sprint.mjs` — validates terminal states, archives sprint report, updates state.json, prints manual steps.
+- **Added**: `scripts/complete_story.mjs` — updates state.json to Done, updates sprint plan §1 V-Bounce State, appends row to §4 Execution Log via `<!-- EXECUTION_LOG_START -->` anchor.
+
+### Sprint Plan as Accumulator (Change #3)
+- **Modified**: `templates/sprint.md` — added `delivery` frontmatter field; new §2 Execution Strategy with phase plan and risk flags; Context Pack Readiness checklists in §1; §4 Execution Log with `<!-- EXECUTION_LOG_START -->` / `<!-- EXECUTION_LOG_END -->` anchors.
+- **Added**: `scripts/validate_sprint_plan.mjs` — validates sprint plan YAML frontmatter, §1 table structure, cross-checks story IDs with state.json, checks §4 on Completed sprints.
+
+### Richer YAML in Agent Reports (Change #4)
+- **Modified**: `brains/claude-agents/qa.md` — FAIL report template now includes `bugs:` array (scenario/expected/actual/files/severity) and `gold_plating:` array in YAML frontmatter; added `template_version: "2.0"` to both PASS and FAIL templates. Markdown body is now narrative-only expansion.
+- **Modified**: `brains/claude-agents/architect.md` — FAIL report template now includes `failures:` array (dimension/severity/what_wrong/fix_required) in YAML frontmatter; added `template_version: "2.0"` to both PASS and FAIL templates.
+- **Modified**: `scripts/validate_report.mjs` — added `validateBugsArray()` and `validateFailuresArray()` helpers; QA FAIL validates `bugs[]` structure when present; Arch FAIL validates `failures[]` structure when present; added `ROOT_CAUSE_ENUM` validation for both QA and Arch FAIL reports.
+
+### Validation Layer (Change #9)
+- **Added**: `scripts/validate_bounce_readiness.mjs` — pre-bounce gate; checks story state, sprint plan, story spec, required sections, worktree existence; exits 1 on any failure.
+- **Added**: `scripts/validate_sprint_plan.mjs` — validates sprint plan structure and cross-references.
+
+### Context Management (Change #12)
+- **Added**: `scripts/prep_sprint_context.mjs` — generates `.bounce/sprint-context-S-XX.md`; reads state.json (required), sprint plan, LESSONS.md (first 50 lines), RISK_REGISTRY; MAX_CONTEXT_LINES=200.
+- **Added**: `scripts/prep_qa_context.mjs` — generates `.bounce/qa-context-STORY-ID.md`; exits 1 if dev report or story spec missing; MAX_CONTEXT_LINES=300.
+- **Added**: `scripts/prep_arch_context.mjs` — generates `.bounce/arch-context-STORY-ID.md`; exits 1 if dev report/story spec missing; git diff truncated at MAX_DIFF_LINES=500.
+- **Added**: `scripts/prep_sprint_summary.mjs` — generates `.bounce/sprint-summary-S-XX.md` from archived reports.
+- **Added**: `vbounce.config.json` — `{ maxDiffLines: 500, maxContextLines: 200, maxQaContextLines: 300, contextBudgetWarningTokens: 12000, lessonStaleDays: 90, tool: "claude" }`.
+- **Modified**: `brains/CLAUDE.md` Skills section — agent-team + lesson always-loaded; other skills moved to on-demand; context budget note added.
+
+### Self-Improvement Loop (Change #10)
+- **Added**: `scripts/sprint_trends.mjs` — scans `.bounce/archive/` dirs; computes per-sprint first-pass rate, avg bounces, correction tax, root_cause breakdown; generates `.bounce/trends.md`.
+- **Added**: `scripts/suggest_improvements.mjs` — reads trends.md, LESSONS.md, improvement-log.md; flags stale lessons (>90 days), low first-pass rate, high correction tax; generates `.bounce/improvement-suggestions.md`.
+- **Added**: `.bounce/improvement-log.md` — Applied/Rejected/Deferred tracking table.
+- **Modified**: `brains/CLAUDE.md` Phase 3 — added `vbounce trends` + `vbounce suggest S-{XX}` to end-of-sprint workflow.
+
+### Root Cause Tagging (Change #11)
+- **Modified**: `brains/claude-agents/qa.md` — added `root_cause:` enum field to FAIL report YAML template.
+- **Modified**: `brains/claude-agents/architect.md` — added `root_cause:` enum field to FAIL report YAML template.
+- **Modified**: `scripts/validate_report.mjs` — `root_cause` validated against 12-value enum for QA and Arch FAIL reports.
+
+### Document Separation of Concerns (Change #7)
+- **Modified**: `skills/agent-team/SKILL.md` — Sprint Plan Sync table updated to 3-column format; Delivery Plan updated ONLY at sprint close.
+- **Added**: `skills/agent-team/references/delivery-sync.md` — core rule table, what each document owns, "Never Do This" list.
+- **Added**: `skills/agent-team/references/report-naming.md` — canonical naming conventions for all report files.
+- **Added**: `skills/agent-team/references/cleanup.md` — after-story and after-sprint cleanup procedures, retention policy table.
+- **Added**: `skills/agent-team/references/git-strategy.md` — branch model, all git commands for sprint/worktree/merge/cleanup.
+
+### Lesson Graduation (Change #6)
+- **Modified**: `skills/lesson/SKILL.md` — added Lesson Graduation section: criteria (3+ sprints, triggered once, no recent recurrence), process (suggest→approve→add to config→remove→log), rationale ("LESSONS.md is a staging area, not a permanent rule store").
+
+### Automation CLI (Change #8)
+- **Modified**: `bin/vbounce.mjs` — all new commands wired: `state show/update`, `sprint init/close`, `story complete`, `validate report/state/sprint/ready`, `prep qa/arch/sprint/summary`, `sync`, `trends`, `suggest`, `doctor`.
+
+### Framework Health (Change #8)
+- **Added**: `scripts/doctor.mjs` — health check; verifies LESSONS.md, templates, .bounce/, state.json, brain files, skills, scripts; exits 1 on hard failures.
+
+### Tier 4 Brain Files (Change #12)
+- **Added**: `brains/copilot/copilot-instructions.md` — Tier 4 (Copilot/VS Code) brain file: key behaviors, CLI commands, document hierarchy, report format, critical rules.
+- **Added**: `brains/windsurf/.windsurfrules` — Tier 4 (Windsurf) brain file: before-coding checklist, document rules, state management commands, critical rules.
+- **Modified**: `brains/GEMINI.md` — added full `## CLI Commands` section with all 15+ vbounce commands.
+
+---
 
 ## [2026-03-02]
 - **Initialized**: Created strict Framework Integrity tracking, YAML context handoffs, and RAG validation pipeline.
 
+## [2026-03-06] — Pre-Gate Automation
+- **Added**: `scripts/pre_gate_common.sh` — shared gate check functions with auto-detection for JS/TS, Python, Rust, Go stacks.
+- **Added**: `scripts/pre_gate_runner.sh` — universal pre-gate scanner. Reads `.bounce/gate-checks.json` config or falls back to auto-detected defaults. Runs before QA (`qa`) and Architect (`arch`) agents to catch mechanical failures with zero tokens.
+- **Added**: `scripts/init_gate_config.sh` — auto-detects project stack (language, framework, test runner, build/lint commands) and generates `.bounce/gate-checks.json`.
+- **Modified**: `brains/claude-agents/qa.md` — added Pre-Computed Scan Results section. QA skips checks covered by `pre-qa-scan.txt`.
+- **Modified**: `brains/claude-agents/architect.md` — added Pre-Computed Scan Results section. Architect skips mechanical checks covered by `pre-arch-scan.txt`.
+- **Modified**: `brains/claude-agents/devops.md` — added `npm run lint` (tsc --noEmit) to post-merge validation.
+- **Modified**: `skills/agent-team/SKILL.md` — wired pre-gate scans into Steps 3 (QA) and 4 (Architect). Added gate config init to Step 0 sprint setup. Added lint to post-merge validation.
+- **Modified**: All brain files (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`, `cursor-rules/vbounce-process.mdc`) — updated bounce sequence to include pre-gate scan steps.
+- **Modified**: `skills/improve/SKILL.md` — added Gate Check Proposals section for iteratively growing project-specific checks via `gate-checks.json`.
+
 ## [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`.

package/brains/CLAUDE.md

@@ -11,24 +11,29 @@ You MUST follow the V-Bounce process. Deviating from it — skipping validation,
 ## Skills
 
 @skills/agent-team/SKILL.md
-@skills/doc-manager/SKILL.md
 @skills/lesson/SKILL.md
-@skills/react-best-practices/SKILL.md
-@skills/vibe-code-review/SKILL.md
-@skills/write-skill/SKILL.md
-@skills/improve/SKILL.md
+
+> **On-demand skills** — invoke these when needed (lower context overhead):
+> - `/doc` → `@skills/doc-manager/SKILL.md` — document creation/editing
+> - `/review` → `@skills/vibe-code-review/SKILL.md` — code review passes
+> - `/write-skill` → `@skills/write-skill/SKILL.md` — skill authoring
+> - `/improve` → `@skills/improve/SKILL.md` — framework improvement
+> - `/react` → `@skills/react-best-practices/SKILL.md` — frontend patterns
+
+> **Context budget**: Always-loaded skills (agent-team + lesson) use ~9,000 tokens.
+> On-demand skills are read by subagents directly from `skills/` when needed.
 
 ## Subagents
 
-Specialized agents are defined in `.claude/agents/` and spawned via the Task tool:
+Specialized agents are defined in `brains/claude-agents/` (deploy to `.claude/agents/` via `vbounce init --tool claude`) and spawned via the Task tool:
 
 | Agent | Config | Role |
 |-------|--------|------|
-| Developer | `.claude/agents/developer.md` | Implements features. Tools: Read, Edit, Write, Bash, Glob, Grep |
-| QA | `.claude/agents/qa.md` | Validates against acceptance criteria. Tools: Read, Bash, Glob, Grep (no Edit/Write) |
-| Architect | `.claude/agents/architect.md` | Audits structure and compliance. Tools: Read, Glob, Grep, Bash (no Edit/Write) |
-| DevOps | `.claude/agents/devops.md` | Merges, deploys, infra checks. Tools: Read, Edit, Write, Bash, Glob, Grep |
-| Scribe | `.claude/agents/scribe.md` | Product documentation generation. Tools: Read, Write, Bash, Glob, Grep |
+| Developer | `brains/claude-agents/developer.md` | Implements features. Tools: Read, Edit, Write, Bash, Glob, Grep |
+| QA | `brains/claude-agents/qa.md` | Validates against acceptance criteria. Tools: Read, Bash, Glob, Grep (no Edit/Write) |
+| Architect | `brains/claude-agents/architect.md` | Audits structure and compliance. Tools: Read, Glob, Grep, Bash (no Edit/Write) |
+| DevOps | `brains/claude-agents/devops.md` | Merges, deploys, infra checks. Tools: Read, Edit, Write, Bash, Glob, Grep |
+| Scribe | `brains/claude-agents/scribe.md` | Product documentation generation. Tools: Read, Write, Bash, Glob, Grep |
 
 Deploy from: `brains/claude-agents/` → `.claude/agents/`
 
@@ -56,14 +61,16 @@ Before starting any sprint, the Team Lead MUST:
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4 Stories):**
-0. Team Lead runs `./scripts/pre_bounce_sync.sh` to ensure LanceDB RAG context is fresh.
+0. **Orient via state**: Read `.bounce/state.json` for instant context (current phase, story states, last action). Run `vbounce prep sprint S-{XX}` to generate a fresh context pack.
 1. Team Lead sends Story context pack to Developer.
-2. Developer queries LanceDB, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
-3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report before passing to Architect/Dev.
-4. Dev fixes and resubmits. 3+ failures → Escalated.
-5. Architect runs Deep Audit + Trend Check, validates Safe Zone compliance and ADR adherence.
-6. DevOps merges story branch into sprint branch, validates post-merge, handles release tagging.
-7. Team Lead consolidates reports into Sprint Report.
+2. Developer reads LESSONS.md and the Story context pack, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
+3. **Pre-QA Gate Scan:** Team Lead runs `./scripts/pre_gate_runner.sh qa` to catch mechanical failures (tests, build, lint, debug output, JSDoc) before spawning QA. If trivial issues found → return to Dev.
+4. QA runs Quick Scan + PR Review (skipping pre-scanned checks), validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report.
+5. Dev fixes and resubmits. 3+ failures → Escalated.
+6. **Pre-Architect Gate Scan:** Team Lead runs `./scripts/pre_gate_runner.sh arch` to catch structural issues (new deps, file sizes) before spawning Architect. If mechanical failures → return to Dev.
+7. Architect runs Deep Audit + Trend Check (skipping pre-scanned checks), validates Safe Zone compliance and ADR adherence.
+8. DevOps merges story branch into sprint branch, validates post-merge (tests + lint + build), handles release tagging.
+9. Team Lead consolidates reports into Sprint Report.
 
 **Hotfix Path (L1 Trivial Tasks):**
 1. Team Lead evaluates request and creates `HOTFIX-{Date}-{Name}.md`.
@@ -74,7 +81,7 @@ Before starting any sprint, the Team Lead MUST:
 6. DevOps (or Team Lead) runs `./scripts/hotfix_manager.sh sync` to update active worktrees.
 
 ### Phase 3: Review
-Sprint Report → Human review → Delivery Plan updated → Lessons recorded → Next sprint.
+Sprint Report → Human review → Delivery Plan updated (at boundary only) → Lessons recorded → Run `vbounce trends` + `vbounce suggest S-{XX}` for improvement recommendations → Next sprint.
 If sprint delivered new features or Developer reports flagged stale product docs → spawn Scribe agent to generate/update vdocs/ via vdoc.
 
 ## Story States
@@ -115,7 +122,7 @@ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architec
 10. **One source of truth**. Reference upstream documents, don't duplicate.
 11. **Change Logs are mandatory** on every document modification.
 12. **Agent Reports MUST use YAML Frontmatter**. Every `.bounce/report/` generated must start with a strict `---` YAML block containing the core status and metrics before the Markdown body.
-13. **Framework Integrity**. Any modification to a `brains/` or `skills/` file MUST be recorded in `brains/CHANGELOG.md` and trigger `./scripts/pre_bounce_sync.sh`.
+13. **Framework Integrity**. Any modification to a `brains/` or `skills/` file MUST be recorded in `brains/CHANGELOG.md`.
 
 ## Framework Structure
 
@@ -137,11 +144,11 @@ All planning documents live in `product_plans/`, separated by state (`strategy/`
 | 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` |
+| Delivery Plan | `templates/delivery_plan.md` | `product_plans/D-{NN}_{release_name}/D-{NN}_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` |
+| Sprint Report | `templates/sprint_report.md` | `.bounce/sprint-report-S-{XX}.md` |
 | Product Docs | (generated by vdoc) | `vdocs/*.md` |
 | Doc Manifest | (generated by vdoc) | `vdocs/_manifest.json` |
 

package/brains/GEMINI.md

@@ -25,6 +25,42 @@ For Antigravity: copy skills to `.agents/skills/` for workspace-scoped discovery
 | `skills/write-skill/` | Creating and refining agent skills | Team Lead |
 | `skills/improve/` | Framework self-improvement from agent feedback | Team Lead |
 
+## CLI Commands
+
+V-Bounce OS ships a CLI. Use these commands for state management instead of editing files manually:
+
+```bash
+# Sprint management
+vbounce sprint init S-06 D-02 --stories STORY-001,STORY-002
+vbounce sprint close S-05
+
+# Story management
+vbounce story complete STORY-005-02 --qa-bounces 1 --arch-bounces 0 --correction-tax 5
+
+# State transitions
+vbounce state show                              # see current sprint state
+vbounce state update STORY-005-02 "QA Passed"  # transition story state
+vbounce state update STORY-005-02 --qa-bounce  # increment QA bounce counter
+
+# Validation
+vbounce validate report <file>    # validate agent report YAML
+vbounce validate state            # validate state.json
+vbounce validate sprint           # validate Sprint Plan
+vbounce validate ready STORY-ID   # pre-bounce gate check
+
+# Context packs
+vbounce prep qa STORY-005-02      # generate QA context pack
+vbounce prep arch STORY-005-02    # generate Architect context pack
+vbounce prep sprint S-06          # generate Sprint context pack
+
+# Self-improvement
+vbounce trends                    # cross-sprint trend analysis
+vbounce suggest S-06              # generate improvement suggestions
+
+# Health check
+vbounce doctor                    # validate all configs, templates, state files
+```
+
 ## The V-Bounce Process
 
 ### Phase 1: Verification (Planning)
@@ -47,14 +83,16 @@ Before starting any sprint, the Team Lead MUST:
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4 Stories):**
-0. Team Lead runs `./scripts/pre_bounce_sync.sh` to ensure LanceDB RAG context is fresh.
+0. **Orient via state**: Read `.bounce/state.json` if it exists (`vbounce state show`). Run `vbounce prep sprint S-{XX}` to generate a fresh context pack.
 1. Team Lead sends Story context pack to Developer.
-2. Developer queries LanceDB, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
-3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report before passing to Architect/Dev.
-4. Dev fixes and resubmits. 3+ failures → Escalated.
-5. Architect runs Deep Audit + Trend Check, validates Safe Zone compliance and ADR adherence.
-6. DevOps merges story branch into sprint branch, validates post-merge, handles release tagging.
-7. Team Lead consolidates reports into Sprint Report.
+2. Developer reads LESSONS.md and the Story context pack, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
+3. **Pre-QA Gate Scan:** Team Lead runs `./scripts/pre_gate_runner.sh qa` to catch mechanical failures before spawning QA. If trivial issues → return to Dev.
+4. QA runs Quick Scan + PR Review (skipping pre-scanned checks), validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report.
+5. Dev fixes and resubmits. 3+ failures → Escalated.
+6. **Pre-Architect Gate Scan:** Team Lead runs `./scripts/pre_gate_runner.sh arch` to catch structural issues before spawning Architect. If mechanical failures → return to Dev.
+7. Architect runs Deep Audit + Trend Check (skipping pre-scanned checks), validates Safe Zone compliance and ADR adherence.
+8. DevOps merges story branch into sprint branch, validates post-merge (tests + lint + build), handles release tagging.
+9. Team Lead consolidates reports into Sprint Report.
 
 **Hotfix Path (L1 Trivial Tasks):**
 1. Team Lead evaluates request and creates `HOTFIX-{Date}-{Name}.md`.
@@ -128,11 +166,11 @@ Planning docs live in `product_plans/`. It uses a state-based architecture (`str
 | 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` |
+| Delivery Plan | `product_plans/D-{NN}_{release_name}/D-{NN}_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` |
+| Sprint Report | `.bounce/sprint-report-S-{XX}.md` |
 | Product Docs | `vdocs/*.md` + `_manifest.json` |
 
 ## Report Formats

package/brains/SETUP.md

@@ -117,16 +117,22 @@ The agent will:
 4. Merge completed stories
 5. Generate a Sprint Report for your review
 
-## Step 7: Automated RAG Initialization
+## Step 7: Initialize Your First Sprint
 
-V-Bounce OS uses LanceDB to provide agents with targeted context. While the `npx @sandrinio/vbounce install` command handles this automatically, you can manually re-trigger a sync if you add new architectural rules or change your brains:
+Once installed, start your first sprint:
 
 ```bash
-# Re-build your local knowledge base
-./scripts/pre_bounce_sync.sh
+# Create state.json + sprint plan directory
+vbounce sprint init S-01 D-01
+
+# Verify everything is in order
+vbounce doctor
+
+# Generate a context pack for your sprint
+vbounce prep sprint S-01
 ```
 
-This updates your local embeddings in `.bounce/.lancedb/`. Agents use `./scripts/vbounce_ask.mjs` to fetch rules on demand, ensuring they are always aligned with your latest Roadmap and Lessons.
+Context packs are generated on-demand before each bounce. Agents read `LESSONS.md`, the sprint plan, and relevant story specs directly — no embedding or sync step required.
 
 ## Folder Structure After Setup
 

package/brains/claude-agents/architect.md

@@ -14,11 +14,20 @@ 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.
+1. **Read LESSONS.md**: Scan for architectural constraints and historical mistakes relevant to this story. Any entry touching the affected modules is a mandatory audit target.
 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.
 
+## Pre-Computed Scan Results
+
+Before you were spawned, the Team Lead ran `scripts/pre_gate_runner.sh arch`. Read the results at `.bounce/reports/pre-arch-scan.txt`.
+
+- If **ALL checks PASS**: Skip mechanical verification in your Deep Audit (dependency changes, file sizes, test/build/lint status). Focus on **judgment-based dimensions**: architectural consistency, error handling quality, data flow traceability, coupling assessment, and AI-ism detection.
+- If **ANY check FAILS**: Note failures in your report. Focus your audit on the areas that failed.
+
+The 6-dimension evaluation should focus on qualitative judgment. Mechanical checks (new deps, file sizes, exports documentation) are pre-computed — reference `pre-arch-scan.txt` rather than re-running them.
+
 ## Your Audit Process
 
 ### Deep Audit (Full Codebase Analysis)
@@ -84,6 +93,7 @@ safe_zone_score: {SCORE}
 tokens_used: {number}
 ai_isms_detected: {count}
 regression_risk: "{Low/Medium/High}"
+template_version: "2.0"
 ---
 
 # Architectural Audit Report: STORY-{ID}-{StoryName} — PASS
@@ -136,17 +146,23 @@ status: "FAIL"
 bounce_count: {N}
 tokens_used: {number}
 critical_failures: {count}
+root_cause: "{adr_violation|missing_tests|spec_ambiguity|logic_error|coupling|duplication|error_handling|state_management|gold_plating|integration_gap}"
+template_version: "2.0"
+failures:
+  - dimension: "{Architectural Consistency|Error Handling|Data Flow|Duplication|Test Quality|Coupling}"
+    severity: "Critical"
+    what_wrong: "{Specific problem — machine-readable summary}"
+    fix_required: "{Exact change the Dev must make}"
 ---
 
 # Architectural Audit Report: STORY-{ID}-{StoryName} — FAIL
 
 ## Critical Failures
+> Structured failure data is in the YAML frontmatter above (`failures:` array). Expand on each issue here with depth.
+
 ### Issue 1: {Short description}
-- **Dimension**: {Which of the 6 dimensions}
-- **Severity**: Critical / High
-- **What's wrong**: {Specific problem}
-- **What's wrong (plain language)**: {Non-coder analogy}
-- **Fix required**: {What the Dev needs to change}
+- **Plain language**: {Non-coder analogy}
+- **Context**: {Why this matters architecturally — historical precedent, ADR violated, risk to future stories}
 
 ## Process Feedback
 > Optional. Note friction with the V-Bounce framework itself — templates, handoffs, RAG quality, skills.

package/brains/claude-agents/developer.md

@@ -12,8 +12,8 @@ Implement features and fix bugs as specified in Story documents. You write code
 
 ## Before Writing ANY Code
 
-1. **Query Project Lessons**: Run `./scripts/vbounce_ask.mjs "<summarize your specific coding task here>"` to retrieve relevant constraints and gotchas from `LESSONS.md` and historical reports. Treat these as hard constraints. No exceptions.
-2. **Query Architectural Decisions**: If your task involves core systems (auth, db, state), run `./scripts/vbounce_ask.mjs "<system> decisions"` to get relevant ADRs from the Roadmap.
+1. **Read LESSONS.md** at the project root. Scan for entries relevant to your task — treat them as hard constraints. No exceptions.
+2. **Read ADR references**: If your task involves core systems (auth, db, state), read Roadmap §3 ADRs directly.
 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.

package/brains/claude-agents/devops.md

@@ -63,6 +63,9 @@ When resolving conflicts:
 # Run test suite on the merged sprint branch
 npm test  # or project-appropriate test command
 
+# Type check (if applicable)
+npm run lint  # tsc --noEmit or equivalent linter
+
 # Verify no regressions
 npm run build  # or project-appropriate build command
 

package/brains/claude-agents/qa.md

@@ -12,16 +12,23 @@ Validate that the Developer's implementation meets the Story's acceptance criter
 
 ## Before Testing
 
-1. **Query Project Lessons**: Run `./scripts/vbounce_ask.mjs "<summarize the story spec here>"` to retrieve known failure patterns relevant to this story from `LESSONS.md` and past reports.
+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.
 
+## Pre-Computed Scan Results
+
+Before you were spawned, the Team Lead ran `scripts/pre_gate_runner.sh qa`. Read the results at `.bounce/reports/pre-qa-scan.txt`.
+
+- If **ALL checks PASS**: Skip the mechanical portions of Quick Scan (test existence, build, debug statements, TODOs, JSDoc coverage). Focus your Quick Scan on **architectural consistency and error handling** only.
+- If **ANY check FAILS**: The Team Lead should have fixed trivial failures before spawning you. If failures remain, note them in your report but do not re-run the checks — trust the scan output.
+
 ## Your Testing Process
 
 ### Quick Scan (Health Check)
-Run a fast structural check of the project using the vibe-code-review skill (Quick Scan mode):
+Run a fast structural check using the vibe-code-review skill (Quick Scan mode):
 - Read `skills/vibe-code-review/SKILL.md` and `skills/vibe-code-review/references/quick-scan.md`
-- Execute the checks against the codebase
+- Skip checks already covered by `pre-qa-scan.txt` (tests exist, build passes, no debug output, no TODOs, JSDoc coverage). Focus on **judgment-based structural assessment**.
 - Flag any obvious structural issues
 
 ### PR Review (Diff Analysis)
@@ -73,6 +80,7 @@ bounce_count: {N}
 tokens_used: {number}
 bugs_found: 0
 gold_plating_detected: false
+template_version: "2.0"
 ---
 
 # QA Validation Report: STORY-{ID}-{StoryName} — PASS
@@ -123,22 +131,30 @@ bounce_count: {N}
 tokens_used: {number}
 bugs_found: {number of bugs}
 gold_plating_detected: {true/false}
+template_version: "2.0"
 failed_scenarios:
   - "{scenario name}"
+root_cause: "{missing_tests|missing_validation|spec_ambiguity|gold_plating|logic_error|integration_gap|type_error|state_management|error_handling|coupling|duplication}"
+bugs:
+  - scenario: "{Which Gherkin scenario failed}"
+    expected: "{What should happen}"
+    actual: "{What actually happens}"
+    files: ["{src/path/to/file.ts}"]
+    severity: "High"
+gold_plating: []
 ---
 
 # QA Validation Report: STORY-{ID}-{StoryName} — FAIL (Bounce {N})
 
 ## Failures
+> Structured bug data is in the YAML frontmatter above (`bugs:` array). Expand on each finding here with plain-language context.
+
 ### Bug 1: {Short description}
-- **Scenario**: {Which Gherkin scenario failed}
-- **Expected**: {What should happen}
-- **Actual**: {What actually happens}
-- **Files**: {Which files are likely involved}
-- **Severity**: Critical / High / Medium / Low
+- **Plain language**: {Non-coder analogy}
+- **Context**: {Additional detail not captured in YAML — reproduction steps, environment notes, related code smell}
 
 ## Gold-Plating Findings
-- {Any unnecessary additions}
+- {Any unnecessary additions not captured in gold_plating[] array, or "None"}
 
 ## Process Feedback
 > Optional. Note friction with the V-Bounce framework itself — templates, handoffs, RAG quality, tooling.

package/brains/copilot/copilot-instructions.md

@@ -0,0 +1,49 @@
+# V-Bounce OS — GitHub Copilot Instructions
+
+This project uses **V-Bounce OS** — a structured AI-agent development framework.
+
+## What This Means for You
+
+You are operating in Tier 4 (Awareness) mode. You understand the project uses V-Bounce OS but you do not orchestrate agents.
+
+## Key Behaviors
+
+1. **When editing planning documents** (`product_plans/**/*.md`): follow the templates in `templates/`. Do not change section numbering or YAML frontmatter structure.
+
+2. **When editing agent reports** (`.bounce/reports/**/*.md`): YAML frontmatter is mandatory. Never remove it.
+
+3. **When asked about project state**: suggest running `vbounce state show` or reading `.bounce/state.json`.
+
+4. **When creating new stories or epics**: use `templates/story.md` and `templates/epic.md`.
+
+## CLI Commands
+
+```bash
+vbounce state show            # current sprint state
+vbounce validate report <f>   # validate a report file
+vbounce doctor                # project health check
+vbounce prep qa STORY-ID      # generate QA context
+```
+
+## Document Hierarchy
+
+Charter → Roadmap → Epic → Story → Sprint Plan → Delivery Plan
+
+Never skip levels. Stories must trace back to an Epic. Sprints must reference a Delivery Plan.
+
+## Report Format
+
+All agent reports must start with YAML frontmatter:
+```yaml
+---
+status: "PASS" | "FAIL"
+tokens_used: {number}
+# ... agent-specific fields
+---
+```
+
+## Critical Rules
+
+- Read `LESSONS.md` before modifying code in this project
+- No gold-plating — implement exactly what the Story specifies
+- Follow the Safe Zone — no new patterns without Architect approval

package/brains/cursor-rules/vbounce-process.mdc

@@ -19,14 +19,16 @@ Before sprints: Lead triages request (L1 Trivial → Hotfix Path. L2-L4 → Epic
 
 ### Phase 2: The Bounce (Implementation)
 **Standard Path (L2-L4):**
-0. Team Lead runs `./scripts/pre_bounce_sync.sh` to ensure LanceDB RAG context is fresh.
+0. Team Lead reads `.bounce/state.json` (`vbounce state show`) and runs `vbounce prep sprint S-{XX}` for a fresh context pack.
 1. Team Lead sends Story context pack to Developer.
-2. Developer reads LESSONS.md, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
-3. QA validates against Story §2 The Truth. If fail → Bug Report to Dev. CLI Orchestrator must run `./scripts/validate_report.mjs` on the QA report before passing to Architect/Dev.
-4. Dev fixes and resubmits. 3+ failures → Escalated.
-5. Architect validates Safe Zone compliance and ADR adherence.
-6. DevOps merges story into sprint branch, validates, handles releases.
-7. Team Lead consolidates into Sprint Report.
+2. Developer reads LESSONS.md and the Story context pack, implements code, writes Implementation Report. CLI Orchestrator must run `./scripts/validate_report.mjs` on the report to enforce YAML strictness.
+3. Pre-QA Gate Scan: `./scripts/pre_gate_runner.sh qa` catches mechanical failures before spawning QA. Trivial issues → return to Dev.
+4. QA validates against Story §2 The Truth (skipping pre-scanned checks). If fail → Bug Report to Dev.
+5. Dev fixes and resubmits. 3+ failures → Escalated.
+6. Pre-Architect Gate Scan: `./scripts/pre_gate_runner.sh arch` catches structural issues before spawning Architect.
+7. Architect validates Safe Zone compliance and ADR adherence (skipping pre-scanned checks).
+8. DevOps merges story into sprint branch, validates (tests + lint + build), handles releases.
+9. Team Lead consolidates into Sprint Report.
 
 **Hotfix Path (L1 Trivial Task):**
 1. Team Lead evaluates request and creates `HOTFIX-{Date}-{Name}.md`.