vbounce-engine 2.5.1

package/brains/AGENTS.md

@@ -0,0 +1,71 @@
+# V-Bounce Engine — Agent Brain (Codex CLI)
+
+> This file configures OpenAI Codex CLI to operate within the V-Bounce Engine framework.
+
+## Identity
+
+You are an AI operating within **V-Bounce Engine** — a structured system for planning, implementing, and validating software.
+
+You have two roles depending on the phase:
+- **During Planning (Phase 1 & 2):** You work directly with the human. You are their planning partner — you create documents, research the codebase, surface risks, and discuss trade-offs. No subagents are involved.
+- **During Execution (Phase 3):** You are the Team Lead orchestrating specialist agents (Developer, QA, Architect, DevOps, Scribe) through structured reports.
+
+You MUST follow the V-Bounce process. Deviating from it — skipping validation, ignoring LESSONS.md, or writing code without reading the Story spec — is a defect, not a shortcut.
+
+## Phase Routing
+
+Determine which phase you're in from what the human is asking, then load the right skill.
+
+| User Intent | Phase | Load |
+|---|---|---|
+| Plan, create, discuss features, priorities, status | Phase 1 (Planning) | `doc-manager`, `product-graph` |
+| "Start a sprint", scope selection, "what should we work on?" | Phase 2 (Sprint Planning) | `doc-manager`, `product-graph` |
+| Sprint confirmed, "bounce", implement stories | Phase 3 (Execution) | `agent-team` |
+| Review sprint, retrospective, improvement | Phase 4 (Review) | `improve` |
+| Scope change to existing documents | Any | `product-graph` (impact first), then `doc-manager` |
+| Code review | Any | `vibe-code-review` |
+| Lesson or gotcha to record | Any | `lesson` |
+
+## Critical Rules
+
+### Before Writing Code
+1. **Read LESSONS.md** at the project root. Every time. No exceptions.
+2. **Read the Story spec** (§1 The Spec + §3 Implementation Guide). Do not infer requirements.
+3. **Check ADRs** in the Roadmap (§3). Comply with recorded architecture decisions.
+
+### During Implementation
+4. **Comply with ADRs**. No new patterns or libraries unless approved in Roadmap §3. The Architect validates compliance.
+5. **No Gold-Plating**. Implement exactly what the Story specifies.
+6. **Write Self-Documenting Code**. All exports MUST have JSDoc/docstrings.
+7. **Self-assess Correction Tax**. Track % human intervention.
+
+### After Implementation
+8. **Write a structured report**: files modified, logic summary, Correction Tax.
+9. **Flag lessons**. Gotchas and multi-attempt fixes get flagged for recording.
+
+### Always
+10. **Reports are the only handoff**. No direct agent-to-agent communication.
+11. **One source of truth**. Reference upstream documents, don't duplicate.
+12. **Change Logs are mandatory** on every document modification.
+13. **Agent Reports MUST use YAML Frontmatter**. Every `.vbounce/report/` file starts with strict YAML.
+14. **Framework Integrity**. Any modification to `.claude/agents/`, `.vbounce/skills/`, `.vbounce/templates/`, or `.vbounce/scripts/` MUST be recorded in `.vbounce/CHANGELOG.md` and reflected in `VBOUNCE_MANIFEST.md`.
+
+## Skills
+
+Skills are in the `.vbounce/skills/` directory. Each skill has a `SKILL.md` with instructions.
+
+**Loaded by phase** (see Phase Routing above):
+- **Always:** Read `.vbounce/skills/lesson/SKILL.md`
+- **Planning (Phase 1 & 2):** Read `.vbounce/skills/doc-manager/SKILL.md` + `.vbounce/skills/product-graph/SKILL.md`
+- **Execution (Phase 3):** Read `.vbounce/skills/agent-team/SKILL.md`
+
+**On-demand:** `vibe-code-review`, `react-best-practices`, `write-skill`, `improve`, `file-organization`
+
+## Quick Reference
+
+- **Document ops:** `.vbounce/skills/doc-manager/SKILL.md` — hierarchy, cascade rules, planning workflows
+- **Product graph:** `.vbounce/product-graph.json` — document relationships and state
+- **Bounce orchestration:** `.vbounce/skills/agent-team/SKILL.md` — agent delegation, sprint execution
+- **Planning docs:** `product_plans/` — `strategy/`, `backlog/`, `sprints/`, `hotfixes/`, `archive/`
+- **Sprint state:** `.vbounce/state.json` — machine-readable sprint state
+- **Framework map:** `VBOUNCE_MANIFEST.md` — complete file and process registry

package/brains/CHANGELOG.md

@@ -0,0 +1,398 @@
+# V-Bounce Engine 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, all tool-specific brain files must be reviewed for consistency.
+
+## [2026-03-25] — .vbounce/ Directory Consolidation (v2.5.0)
+
+### Directory Consolidation (EPIC-002)
+- **All framework files** now deploy under `.vbounce/` instead of project root:
+  - `skills/` → `.vbounce/skills/`
+  - `templates/` → `.vbounce/templates/`
+  - `scripts/` → `.vbounce/scripts/`
+  - `.bounce/` → `.vbounce/` (merged)
+  - `MANIFEST.md` → `.vbounce/VBOUNCE_MANIFEST.md`
+- **550+ path references** updated across 55 files (brains, skills, agents, templates, scripts, docs)
+- **Modified**: `bin/vbounce.mjs` — platform mappings deploy to `.vbounce/`, added migration logic for old layout, added `vbounce uninstall` command, auto-deploys `.vbounce/.gitignore`
+- **Modified**: `scripts/doctor.mjs` — validates `.vbounce/templates/`, `.vbounce/skills/`, `.vbounce/scripts/`
+- **Modified**: All brain files — skill references now use `.vbounce/skills/` paths
+- **Modified**: All subagent configs — script and report paths use `.vbounce/`
+- **Modified**: All skill files — cross-references use `.vbounce/` paths
+- **Renamed**: `MANIFEST.md` → `VBOUNCE_MANIFEST.md`, now included in npm package
+- **Added**: `.vbounce/.gitignore` template — nested gitignore for mixed committed/runtime content
+- **Note**: Historical entries in this changelog retain original paths (they describe what happened at that time)
+
+### Manifest & Version
+- **Modified**: `VBOUNCE_MANIFEST.md` — updated all registry paths, version 2.4.0→2.5.0
+- **Modified**: `package.json` — version bumped to 2.5.0, added `VBOUNCE_MANIFEST.md` to files array
+
+---
+
+## [2026-03-25] — Story Template Rewrite & Git Cleanup (v2.4.0)
+
+### Story Template Rewrite (Modified)
+- **Modified**: `templates/story.md` — 7 improvements:
+  1. Complexity legend moved to `<instructions>` block only (not repeated in output)
+  2. Single `complexity_label` frontmatter field (removed redundant `complexity`)
+  3. Flexible §1.1 format: user-facing stories use "As a {Persona}..." format; infrastructure stories can use direct problem statements
+  4. Added §1.3 Out of Scope section (prevents scope creep)
+  5. Generic §2.2 Verification Steps (removed UI bias — adapts to story type)
+  6. §3.4 API Contract reframed: documents existing contracts to comply with OR new contracts to create. Table format with Endpoint/Method/Auth/Request/Response
+  7. §4.2 Definition of Done trimmed from 11 to 6 items (removed duplicates of §4.1 and general best practices)
+
+### Git History Cleanup
+- **Modified**: `.gitignore` — added explicit exclusions for `product_plans/`, `vdocs/`, `.bounce/`, `/temporary/`
+- Git history rewritten via `filter-branch` to remove internal development artifacts from public repo
+
+### Manifest & Version
+- **Modified**: `MANIFEST.md` — updated story template Key Sections (added §1.3 Out of Scope), version 2.3.0→2.4.0
+- **Modified**: `package.json` — version bumped to 2.4.0
+- **Modified**: `CHANGELOG.md` — backfilled missing 2.2.0 and 2.3.0 entries, added 2.4.0
+
+---
+
+## [2026-03-24] — Post-Sprint Improvement Pipeline & Process Enhancements (v2.3.0)
+
+### Unconditional Improvement Suggestions (Modified)
+- **Modified**: `skills/agent-team/SKILL.md` Step 7.7 — Framework Self-Assessment now **always** runs `suggest_improvements.mjs`, not just conditionally on 2nd+ sprint or blocker findings. First sprints generate the most friction.
+- **Key change**: Team Lead must **verbally present** P0/P1 suggestions to the user in plain language, not just embed them in the sprint report. Lower-priority items referenced in `.bounce/improvement-suggestions.md`.
+
+### User Walkthrough Phase (New)
+- **Modified**: `skills/agent-team/SKILL.md` — added **Step 5.7: User Walkthrough** between story merges and Sprint Integration Audit. User tests the running app; feedback tracked as "Review Feedback" (no Correction Tax) or "Bug" (counts as Bug Fix Tax). Gives post-delivery feedback a proper home instead of ad-hoc post-sprint changes.
+
+### Sprint Context Template (New)
+- **Added**: `templates/sprint_context.md` — shared context file for all agents in a sprint. Contains design tokens, UI conventions, shared patterns, locked dependencies, active lessons, sprint-specific rules. Created at Step 0.7 (Sprint Setup), included in every agent task file. Reduces divergence between parallel agents.
+- **Modified**: `skills/agent-team/SKILL.md` Step 0 — added Step 0.7 to create sprint context file. Step 1 now includes sprint context in agent task files.
+
+### Correction Tax Split (Modified)
+- **Modified**: `templates/sprint_report.md` — Correction Tax now split into two sub-categories:
+  - **Bug Fix Tax**: Quality failures that agents should have caught. Triggers threshold alerts.
+  - **Enhancement Tax**: Healthy iteration from user feedback. Does NOT trigger alerts.
+- Story Results table now includes "Tax Type" column (Bug Fix / Enhancement / Mixed).
+
+### Quality Gates in Story Template (Modified)
+- **Modified**: `templates/story.md` — §4 renamed from "Definition of Done" to "Quality Gates". Added §4.1 "Minimum Test Expectations" table (unit, component, E2E, integration counts defined during planning). §4.2 is the existing Definition of Done checklist, now includes sprint context consultation.
+
+### Accelerated Lesson Graduation (Modified)
+- **Modified**: `skills/lesson/SKILL.md` — added accelerated graduation path. Lessons can graduate after 1 sprint (instead of 3) when: affected 5+ files, caused a bounce, or describe cross-cutting concerns. Flagged by `suggest_improvements.mjs` at P1.
+
+### QA Runtime Verification (Modified)
+- **Modified**: `brains/claude-agents/qa.md` — added "Runtime Verification" step between test execution and spec fidelity check. QA starts the dev server, verifies no white screens or startup crashes, clicks through main flows. Smoke test gate for runtime health.
+
+### Token Tracking Enforcement (Modified)
+- **Modified**: All 5 subagent configs (`developer.md`, `qa.md`, `architect.md`, `devops.md`, `scribe.md`):
+  - Promoted token tracking from a soft inline instruction in the report template to a **mandatory pre-report section** ("Before Writing Your Report (Mandatory)").
+  - Removed the old `**Token Tracking**:` block from the report body — instructions now live in their own section with explicit "Do NOT skip" language.
+  - Added warning: "Reports with `0/0/0` tokens and no failure explanation will be flagged by the Team Lead."
+  - Developer agent: added "Token tracking completed" to the Status checklist.
+
+### Manifest & Version
+- **Modified**: `MANIFEST.md` — added sprint_context.md to Template Registry, Step 5.7 to Process Flow, updated Phase 4 to show unconditional improvement pipeline, template count 12→13, total ~173→~174. Version 2.2.1→2.3.0.
+- **Modified**: `package.json` — version bumped to 2.3.0.
+
+---
+
+## [2026-03-23] — Token Tracking Reliability Fixes
+
+### Script: Worktree-Aware Session Discovery (Fixed)
+- **Modified**: `scripts/count_tokens.mjs` — `findProjectDir()` now falls back to `git rev-parse --git-common-dir` when CWD walk-up fails. Fixes agents in git worktrees unable to find their Claude Code session JSONL files.
+- **Refactored**: Extracted `tryProjectDir()` helper from `findProjectDir()` to reduce duplication.
+
+### Agent Reports: Input/Output Token Split (Modified)
+- **Modified**: All 5 subagent configs (`developer.md`, `qa.md`, `architect.md`, `devops.md`, `scribe.md`):
+  - YAML frontmatter changed from `tokens_used: {number}` to `input_tokens: {number}`, `output_tokens: {number}`, `total_tokens: {number}`.
+  - Token Tracking instructions now include fallback: if `count_tokens.mjs` not found in worktree, try `$(git rev-parse --show-toplevel)/scripts/count_tokens.mjs`.
+  - If both fail, agents set all token fields to `0` and note the failure in Process Feedback.
+
+### Sprint Consolidation: Token Aggregation Improvements (Modified)
+- **Modified**: `skills/agent-team/SKILL.md` Step 7 — Team Lead now:
+  - Sums `input_tokens`, `output_tokens`, and `total_tokens` separately from agent reports.
+  - Uses task notification `total_tokens` as authoritative fallback when script-based totals are `0` or diverge >20%.
+  - Cross-references three data sources: agent report YAML, task notifications, and `vbounce tokens --sprint` output.
+- **Modified**: `templates/sprint_report.md` — YAML frontmatter now includes `total_input_tokens` and `total_output_tokens` alongside `total_tokens_used`.
+
+---
+
+## [2026-03-23] — Token Tracking: Per-Agent, Per-Story, Per-Sprint
+
+### Token Tracking Script (New)
+- **Added**: `scripts/count_tokens.mjs` — parses Claude Code JSONL session files for exact token counts. Modes:
+  - `--self`: auto-detects own subagent JSONL (most recently modified file in subagents/)
+  - `--self --append <story.md> --name Developer`: writes input/output/total row to story's Token Usage table
+  - `--all`: per-subagent breakdown for current session
+  - `--sprint S-XX`: aggregates Token Usage tables from all story docs in a sprint folder
+  - `--json`: machine-readable output for report YAML frontmatter
+- **Modified**: `bin/vbounce.mjs` — added `tokens` CLI command with all modes
+
+### Subagent Token Self-Reporting (Modified)
+- **Modified**: All 5 subagent configs (`developer.md`, `qa.md`, `architect.md`, `devops.md`, `scribe.md`):
+  - Token Tracking instruction changed from vague "retrieve your session's token usage" to concrete two-step:
+    1. `node scripts/count_tokens.mjs --self --json` → populate `tokens_used` in report YAML
+    2. `node scripts/count_tokens.mjs --self --append <story.md> --name <Agent>` → write row to story doc
+  - Each story document accumulates a Token Usage table with per-agent input/output/total
+- **Modified**: `brains/claude-agents/developer.md` — also fixed stale "Follow the Safe Zone" → "Comply with ADRs"
+
+### Sprint Token Aggregation
+- `--sprint S-XX` reads all STORY-*.md files in the sprint folder, parses their Token Usage tables, outputs per-story and sprint-total token counts. JSON mode provides data for Sprint Report §3 Execution Metrics.
+
+---
+
+## [2026-03-22] — Bug & Change Request Templates + Process Fixes
+
+### Bug Report Template (New)
+- **Added**: `templates/bug.md` — documents defects found mid-sprint or post-sprint. YAML frontmatter (bug_id, status, severity, found_during, affected_story, reporter). Sections: The Bug (repro steps, expected/actual), Impact (blocking?, affected areas, data impact), Fix Approach (root cause, files, complexity), Verification. Triage rule: L1 bugs use hotfix.md, larger bugs use this template.
+
+### Change Request Template (New)
+- **Added**: `templates/change_request.md` — documents scope changes or approach changes mid-sprint. YAML frontmatter (cr_id, status, category, urgency, affected_stories, requestor). Sections: The Change (original vs proposed), Impact Assessment (affected stories, sprint impact, risk), Decision (human approves/rejects/defers), Execution Plan. Categories: Scope Change and Approach Change (from mid-sprint-triage.md).
+
+### Mid-Sprint Triage Update
+- **Modified**: `skills/agent-team/references/mid-sprint-triage.md` — added Template column to categorization table linking each category to its template. Added decision tree that routes L1 bugs to hotfix.md, larger bugs to bug.md, scope/approach changes to change_request.md, spec clarifications to inline updates. Added Step 4 (present to human). Updated Sprint Report tracking table with Document column.
+
+### Doc-Manager Update
+- **Modified**: `skills/doc-manager/SKILL.md` — added Bug Report and Change Request to Template Locations table.
+
+### Sprint Template Improvements
+- **Modified**: `templates/sprint.md` — added Shared File Map table to §2 (forces explicit merge ordering for parallel stories touching same files). Added Execution Mode table (L1→Fast Track, L2→needs human approval, L3/L4→Full Bounce always). Updated Dependency Chain reason column to include "shared file" as a dependency type.
+
+### Process Fixes
+- **Modified**: `skills/agent-team/SKILL.md` — pre-gate scan escalation after 3 failures (present to human with options). Post-merge test failure recovery path (revert → return to Dev → re-enter Step 2 → escalate after 3). Integration audit fix stories go to backlog (not current sprint) unless release-blocking. Delivery Plan Sync table clarified: updates ONLY at sprint close.
+- **Modified**: `skills/doc-manager/SKILL.md` — added Complexity Labels (L1-L4) to TRANSITION section. Epic readiness gate changed from "reviewed" to "decided mitigation OR explicitly accepted as known risk."
+- **Modified**: `skills/improve/SKILL.md` — fixed stale `pre_bounce_sync.sh` references → `vbounce doctor`. Clarified improvement cadence: analysis runs every sprint, applying is human's call.
+- **Modified**: `brains/CLAUDE.md`, `brains/GEMINI.md`, `brains/AGENTS.md` — replaced "Follow the Safe Zone" with "Comply with ADRs" (concrete, already enforced by Architect).
+- **Modified**: `bin/vbounce.mjs` — install now creates LESSONS.md if missing.
+- **Modified**: `MANIFEST.md` — added bug.md and change_request.md to Template Registry. Updated template count (10→12).
+
+---
+
+## [2026-03-22] — Ownership Restructure: Eliminate Process Knowledge Duplication
+
+### Problem
+Process knowledge (cascade rules, document hierarchy, critical rules, script registry, story states) was duplicated 2-3x across process-guide skill, doc-manager skill, MANIFEST.md, and brain files. Six concepts had no clear single owner, creating drift risk.
+
+### Solution: Each concept has exactly ONE owner
+
+**Ownership map:**
+- **Brain files** own: identity, phase routing table, critical rules (14 rules), skill loading
+- **doc-manager** owns: document hierarchy, information flow, cascade rules, story states, complexity labels, ambiguity rubric, planning workflows, transitions, archiving
+- **agent-team** owns: bounce sequence, worktrees, reports, git strategy, escalation, cleanup
+- **product-graph** owns: graph JSON interpretation, impact analysis, blocked document detection
+- **lesson** owns: lesson recording, graduation
+- **MANIFEST.md** owns: file/skill/script registries, file counts, version tracking (maintainer tool, not deployed)
+
+### Changes
+
+#### Deleted
+- **Deleted**: `skills/process-guide/SKILL.md` — its content was distributed:
+  - Phase routing table → brain files (all three)
+  - Critical rules (14 rules) → brain files (all three)
+  - Script registry → deleted (redundant with CLI `--help` and each skill mentioning its own scripts)
+  - Cascade rules → already in doc-manager (single owner)
+  - Story states → already in doc-manager (single owner)
+  - Document hierarchy → already in doc-manager (single owner)
+  - Complexity labels → moved to doc-manager
+
+#### Modified
+- **Modified**: `skills/doc-manager/SKILL.md` — added Complexity Labels section (L1-L4 definitions) to TRANSITION area. doc-manager is now the single owner of all document-related cross-cutting concepts.
+- **Modified**: `brains/CLAUDE.md` — added Phase Routing table (~10 lines) and Critical Rules (14 rules, ~25 lines). Removed process-guide references. ~85 lines total.
+- **Modified**: `brains/GEMINI.md` — mirrored: added Phase Routing + Critical Rules, removed process-guide references. ~95 lines total (includes CLI commands).
+- **Modified**: `brains/AGENTS.md` — mirrored: added Phase Routing + Critical Rules, removed process-guide references. ~70 lines total.
+- **Modified**: `MANIFEST.md` — removed process-guide from Skill Registry. Updated skill count (48→47). Updated total count.
+
+### Sync Notes
+- All three main brain files (CLAUDE.md, GEMINI.md, AGENTS.md) have identical Phase Routing and Critical Rules sections.
+- Cursor rules and Tier 4 brains (copilot, windsurf) not yet updated — should be synced in a follow-up change.
+
+---
+
+## [2026-03-22] — Product Graph + Process Awareness (EPIC-003 + EPIC-004)
+
+### Product Graph (EPIC-003)
+
+#### Graph Generation Script (New)
+- **Added**: `scripts/product_graph.mjs` — scans `product_plans/` active directories (strategy/, backlog/, sprints/, hotfixes/), extracts YAML frontmatter, outputs `.bounce/product-graph.json` with nodes (type, status, ambiguity, path, title) and edges (parent, depends-on, unlocks, context-source, feeds). Graceful empty graph for missing/empty product_plans/, skips malformed YAML with warning.
+
+#### Impact Analysis Script (New)
+- **Added**: `scripts/product_impact.mjs` — queries "what's affected by X?" using BFS traversal of the product graph. Outputs direct dependents, transitive dependents, upstream feeders. Visited-set for cycle protection. Supports `--json` output mode.
+
+#### Product Graph Skill (New)
+- **Added**: `skills/product-graph/SKILL.md` — interpretation rules for the product graph JSON. Three-tier loading protocol (graph JSON → specific frontmatter → full documents). Edge type semantics, regeneration triggers, blocked document detection logic.
+
+#### CLI Wiring
+- **Modified**: `bin/vbounce.mjs` — added `graph` command (`vbounce graph [generate]`, `vbounce graph impact <DOC-ID>`). Updated help text.
+
+#### Sprint Lifecycle Integration
+- **Modified**: `scripts/init_sprint.mjs` — added non-blocking product graph regeneration after sprint init.
+- **Modified**: `scripts/complete_story.mjs` — added non-blocking product graph regeneration after story completion.
+- **Modified**: `scripts/close_sprint.mjs` — added non-blocking product graph regeneration after sprint close.
+
+#### Doc-Manager Cascade Rule
+- **Modified**: `skills/doc-manager/SKILL.md` — added cascade rule: "After any cascade, run `vbounce graph` to regenerate the product graph."
+
+### Process Awareness (EPIC-004)
+
+#### Process-Guide Skill (New)
+- **Added**: `skills/process-guide/SKILL.md` — condensed process intelligence from MANIFEST.md, doc-manager, and CLAUDE.md. Contains: process flow (4 phases), phase routing table (user intent → phase → skill to load), script registry (all scripts by category), document hierarchy and cascade rules, story states, complexity labels, self-improvement awareness, and all 14 critical rules. ~200 lines, ~3,000 tokens.
+
+#### Brain File Slim-Down
+- **Modified**: `brains/CLAUDE.md` — reduced from ~259 lines to ~55 lines. Moved process flow (Phase 1-4), critical rules, document locations, report formats, story states, complexity labels to process-guide skill. Kept: identity, skill pointers (with phase-based loading), subagent table, quick reference. agent-team now loads only during Phase 3 (was always-loaded).
+- **Modified**: `brains/GEMINI.md` — mirrored slim-down. Skill loading now phase-based (process-guide always, doc-manager/product-graph for planning, agent-team for execution). Kept CLI commands section and quick reference.
+- **Modified**: `brains/AGENTS.md` — mirrored slim-down. Same phase-based skill loading structure.
+
+#### Agent-Team Conditional Loading
+- **Modified**: `brains/CLAUDE.md` Skills section — agent-team is no longer `@`-included (always-loaded). Instead, it loads on-demand when entering Phase 3. Only lesson remains always-loaded via `@`. Context budget reduced from ~9,000 tokens always to ~500 tokens always + ~3,000 during planning + ~9,000 during execution.
+
+### Integration
+- **Modified**: `MANIFEST.md` — added process-guide and product-graph to Skill Registry. Added product_graph.mjs and product_impact.mjs to Script Registry (new "Product Graph" category). Updated Process Flow to reference new skills. Updated file counts (skills: 46→48, scripts: 24→26, total: ~162→~166). Version bumped to 2.1.0.
+
+### Sync Notes
+- All three main brain files (CLAUDE.md, GEMINI.md, AGENTS.md) are consistent in their skill loading structure and quick reference section.
+- Cursor rules and Tier 4 brains (copilot, windsurf) not yet updated — should be synced in a follow-up change.
+
+---
+
+## [2026-03-13] — Discovery Phase: Structured Spike System
+
+### Spike Template (New)
+- **Added**: `templates/spike.md` — spike document template with YAML frontmatter (spike_id, parent_epic_ref, status, ambiguity_before, time_box), 8 sections (Question, Constraints, Approach, Findings, Decision, Residual Risk, Affected Documents checklist, Change Log). Hierarchy Level 3.5 — child of Epic, sibling of Story. Output location: `product_plans/backlog/EPIC-{NNN}_{name}/SPIKE-{EpicID}-{NNN}-{topic}.md`.
+
+### Discovery Reference (New)
+- **Added**: `skills/agent-team/references/discovery.md` — spike execution protocol. Covers: when discovery triggers, spike lifecycle (Open → Investigating → Findings Ready → Validated → Closed), 4-step execution protocol (Create → Investigate → Validate → Close & Propagate), timing rules, integration with bounce sequence.
+
+### Doc-Manager Skill (Modified)
+- **Modified**: `skills/doc-manager/SKILL.md` — added Spike row to Template Locations table; added spike file to folder structure diagram; added spike information flows (Epic §8 → Spike §1, Spike §4 → Epic §4, Spike §5 → Roadmap §3, Spike §6 → Risk Registry); added Spike pre-read requirements; added spike cascade rules; added spike transition gates (Probing/Spiking → Refinement, Spike → Validated, Spike → Closed); updated Developer and Architect agent integration rows with spike ownership; added Ambiguity Assessment Rubric section with 🔴/🟡/🟢 signal definitions and spike creation trigger.
+
+### Agent-Team Skill (Modified)
+- **Modified**: `skills/agent-team/SKILL.md` — added Step 0.5: Discovery Check between Sprint Setup and Story Initialization; added critical rule "Resolve discovery before bouncing" requiring L4/🔴 stories to complete spikes before entering bounce sequence.
+
+### Claude Brain (Modified)
+- **Modified**: `brains/CLAUDE.md` — added Discovery Check to Pre-Bounce Checks; expanded L4 complexity label with spike creation and validation requirements; updated Story States diagram to show spike sub-flow (Dev investigates → Arch validates → docs updated).
+
+### Sync Notes
+- Other brain files (`GEMINI.md`, `AGENTS.md`, `cursor-rules/`) not yet updated — should be synced in a follow-up change.
+
+---
+
+## [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 Engine 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`.
+- **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

@@ -0,0 +1,90 @@
+# V-Bounce Engine — Agent Brain
+
+> This file configures Claude Code to operate within the V-Bounce Engine framework.
+
+## Identity
+
+You are an AI operating within **V-Bounce Engine** — a structured system for planning, implementing, and validating software.
+
+You have two roles depending on the phase:
+- **During Planning (Phase 1 & 2):** You work directly with the human. You are their planning partner — you create documents, research the codebase, surface risks, and discuss trade-offs. You MAY spawn the **Explorer** agent (Haiku) for raw fact-gathering; Explorer returns a structured Context Pack — you analyze it.
+- **During Execution (Phase 3):** You are the Team Lead orchestrating specialist subagents (Developer, QA, Architect, DevOps, Scribe) through structured reports.
+
+You MUST follow the V-Bounce process. Deviating from it — skipping validation, ignoring LESSONS.md, or writing code without reading the Story spec — is a defect, not a shortcut.
+
+## Phase Routing
+
+Determine which phase you're in from what the human is asking, then load the right skill.
+
+| User Intent | Phase | Load |
+|---|---|---|
+| Plan, create, discuss features, priorities, status | Phase 1 (Planning) | `doc-manager`, `product-graph` |
+| "Start a sprint", scope selection, "what should we work on?" | Phase 2 (Sprint Planning) | `doc-manager`, `product-graph` |
+| Sprint confirmed, "bounce", implement stories | Phase 3 (Execution) | `agent-team` |
+| Review sprint, retrospective, improvement | Phase 4 (Review) | `improve` |
+| Scope change to existing documents | Any | `product-graph` (impact first), then `doc-manager` |
+| Code review | Any | `vibe-code-review` |
+| Lesson or gotcha to record | Any | `lesson` |
+
+## Critical Rules
+
+### Before Writing Code
+1. **Read LESSONS.md** at the project root. Every time. No exceptions.
+2. **Read the Story spec** (§1 The Spec + §3 Implementation Guide). Do not infer requirements.
+3. **Check ADRs** in the Roadmap (§3). Comply with recorded architecture decisions.
+
+### During Implementation
+4. **Comply with ADRs**. No new patterns or libraries unless approved in Roadmap §3. The Architect validates compliance.
+5. **No Gold-Plating**. Implement exactly what the Story specifies.
+6. **Write Self-Documenting Code**. All exports MUST have JSDoc/docstrings.
+7. **Self-assess Correction Tax**. Track % human intervention.
+
+### After Implementation
+8. **Write a structured report**: files modified, logic summary, Correction Tax.
+9. **Flag lessons**. Gotchas and multi-attempt fixes get flagged for recording.
+
+### Always
+10. **Reports are the only handoff**. No direct agent-to-agent communication.
+11. **One source of truth**. Reference upstream documents, don't duplicate.
+12. **Change Logs are mandatory** on every document modification.
+13. **Agent Reports MUST use YAML Frontmatter**. Every `.vbounce/report/` file starts with strict YAML.
+14. **Framework Integrity**. Any modification to `.claude/agents/`, `.vbounce/skills/`, `.vbounce/templates/`, or `.vbounce/scripts/` MUST be recorded in `.vbounce/CHANGELOG.md` and reflected in `VBOUNCE_MANIFEST.md`.
+
+## Skills
+
+@.vbounce/skills/lesson/SKILL.md
+
+> **Loaded by phase** (see Phase Routing above):
+> - **Planning (Phase 1 & 2):** Load `@.vbounce/skills/doc-manager/SKILL.md` + `@.vbounce/skills/product-graph/SKILL.md`
+> - **Execution (Phase 3):** Load `@.vbounce/skills/agent-team/SKILL.md`
+
+> **On-demand skills:**
+> - `/doc` → `@.vbounce/skills/doc-manager/SKILL.md`
+> - `/review` → `@.vbounce/skills/vibe-code-review/SKILL.md` — code review
+> - `/write-skill` → `@.vbounce/skills/write-skill/SKILL.md` — skill authoring
+> - `/improve` → `@.vbounce/skills/improve/SKILL.md` — framework improvement
+> - `/react` → `@.vbounce/skills/react-best-practices/SKILL.md` — frontend patterns
+
+## Subagents
+
+Specialized agents in `.claude/agents/`:
+
+| Agent | Config | Role |
+|-------|--------|------|
+| Explorer | `.claude/agents/explorer.md` | Gathers raw facts during Planning (Haiku model). Tools: Read, Glob, Grep, Bash (no Edit/Write) |
+| 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 |
+
+Reports flow through `.vbounce/reports/` — see agent-team skill for the full orchestration protocol.
+
+## Quick Reference
+
+- **Document ops:** `.vbounce/skills/doc-manager/SKILL.md` — hierarchy, cascade rules, planning workflows
+- **Product graph:** `.vbounce/product-graph.json` — document relationships and state
+- **Bounce orchestration:** `.vbounce/skills/agent-team/SKILL.md` — subagent delegation, worktrees, sprint execution
+- **Planning docs:** `product_plans/` — `strategy/`, `backlog/`, `sprints/`, `hotfixes/`, `archive/`
+- **Sprint state:** `.vbounce/state.json` — machine-readable sprint state
+- **Framework map:** `VBOUNCE_MANIFEST.md` — complete file and process registry