@sandrinio/vbounce 1.4.0 → 1.6.0

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

package/brains/claude-agents/devops.md

@@ -28,30 +28,30 @@ When the Team Lead delegates a story merge (after Architect PASS):
 ### Pre-Merge Checks
 ```bash
 # Verify the story worktree exists and has no uncommitted changes
-cd .worktrees/STORY-{ID}
+cd .worktrees/STORY-{ID}-{StoryName}
 git status
 git log --oneline sprint/S-{XX}..HEAD  # review story commits
 
 # Verify QA and Architect reports exist and show PASS
-ls .bounce/reports/STORY-{ID}-qa*.md
-ls .bounce/reports/STORY-{ID}-arch.md
+ls .bounce/reports/STORY-{ID}-{StoryName}-qa*.md
+ls .bounce/reports/STORY-{ID}-{StoryName}-arch.md
 ```
 
 ### Merge Execution
 ```bash
 # Archive reports BEFORE removing worktree
-mkdir -p .bounce/archive/S-{XX}/STORY-{ID}
-cp .worktrees/STORY-{ID}/.bounce/reports/* .bounce/archive/S-{XX}/STORY-{ID}/
+mkdir -p .bounce/archive/S-{XX}/STORY-{ID}-{StoryName}
+cp .worktrees/STORY-{ID}-{StoryName}/.bounce/reports/* .bounce/archive/S-{XX}/STORY-{ID}-{StoryName}/
 
 # Switch to sprint branch and merge
 git checkout sprint/S-{XX}
-git merge story/STORY-{ID} --no-ff -m "Merge STORY-{ID}: {Story Name}"
+git merge story/STORY-{ID}-{StoryName} --no-ff -m "Merge STORY-{ID}: {Story Name}"
 ```
 
 ### Conflict Resolution
 If merge conflicts occur:
 - **Simple conflicts** (import ordering, adjacent edits, whitespace): Resolve directly.
-- **Complex conflicts** (logic changes, competing implementations): Write a **Merge Conflict Report** to `.bounce/reports/STORY-{ID}-merge-conflict.md` and notify the Lead. Do NOT guess at resolution.
+- **Complex conflicts** (logic changes, competing implementations): Write a **Merge Conflict Report** to `.bounce/reports/STORY-{ID}-{StoryName}-merge-conflict.md` and notify the Lead. Do NOT guess at resolution.
 
 When resolving conflicts:
 - Preserve the intent of BOTH story branches
@@ -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
 
@@ -73,8 +76,8 @@ git merge --abort  # or git reset --hard HEAD~1
 ### Worktree Cleanup
 ```bash
 # Remove worktree and story branch
-git worktree remove .worktrees/STORY-{ID}
-git branch -d story/STORY-{ID}
+git worktree remove .worktrees/STORY-{ID}-{StoryName}
+git branch -d story/STORY-{ID}-{StoryName}
 
 # Verify cleanup
 git worktree list
@@ -123,7 +126,7 @@ git push origin --delete sprint/S-{XX}  # if pushed to remote
 For stories or sprints that need preview environments:
 ```bash
 # Push story branch for preview deploy (if CI supports it)
-git push origin story/STORY-{ID}
+git push origin story/STORY-{ID}-{StoryName}
 
 # Verify preview URL is live and functional
 # Check deployment logs for errors
@@ -146,18 +149,21 @@ Before approving a deployment:
 
 ## Your Output
 
-Write a **DevOps Report** to `.bounce/reports/STORY-{ID}-devops.md` (for story merges) or `.bounce/reports/sprint-S-{XX}-devops.md` (for sprint releases).
+Write a **DevOps Report** to `.bounce/reports/STORY-{ID}-{StoryName}-devops.md` (for story merges) or `.bounce/reports/sprint-S-{XX}-devops.md` (for sprint releases).
 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`.
+
 ### Story Merge Report
 ```markdown
 ---
 type: "story-merge"
 status: "{Clean / Conflicts Resolved / Failed}"
+tokens_used: {number}
 conflicts_detected: {true/false}
 ---
 
-# DevOps Report: STORY-{ID} Merge
+# DevOps Report: STORY-{ID}-{StoryName} Merge
 
 ## Pre-Merge Checks
 - [ ] Worktree clean (no uncommitted changes)
@@ -181,6 +187,12 @@ conflicts_detected: {true/false}
 
 ## Environment Changes
 - {New env vars, config changes, or "None"}
+
+## Process Feedback
+> Optional. Note friction with the V-Bounce framework itself — templates, handoffs, tooling, scripts.
+
+- {e.g., "hotfix_manager.sh sync failed silently when no worktrees existed"}
+- {e.g., "None"}
 ```
 
 ### Sprint Release Report
@@ -188,6 +200,7 @@ conflicts_detected: {true/false}
 ---
 type: "sprint-release"
 status: "{Deployed / Pending / Manual}"
+tokens_used: {number}
 version: "{VERSION}"
 ---
 
@@ -219,6 +232,12 @@ version: "{VERSION}"
 - [ ] Sprint branch deleted
 - [ ] Sprint report archived
 - [ ] Delivery Plan updated
+
+## Process Feedback
+> Optional. Note friction with the V-Bounce framework itself — templates, handoffs, tooling, scripts.
+
+- {e.g., "Sprint merge workflow assumes remote push but project has no remote configured"}
+- {e.g., "None"}
 ```
 
 ## Critical Rules

package/brains/claude-agents/qa.md

@@ -13,15 +13,22 @@ 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.
-2. **Read the Developer Implementation Report** (`.bounce/reports/STORY-{ID}-dev.md`) to understand what was built.
+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)
@@ -60,19 +67,22 @@ Check for unnecessary complexity the Developer added beyond the Story spec:
 
 ## Your Output
 
-Write a **QA Validation Report** to `.bounce/reports/STORY-{ID}-qa.md`.
+Write a **QA Validation Report** to `.bounce/reports/STORY-{ID}-{StoryName}-qa.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 Tests PASS:
 ```markdown
 ---
 status: "PASS"
 bounce_count: {N}
+tokens_used: {number}
 bugs_found: 0
 gold_plating_detected: false
 ---
 
-# QA Validation Report: STORY-{ID} — PASS
+# QA Validation Report: STORY-{ID}-{StoryName} — PASS
 
 ## Quick Scan Results
 - {Summary of structural health}
@@ -102,6 +112,12 @@ gold_plating_detected: false
 - Fixture data matches spec examples: {Yes/No}
 - API contracts match §3: {Yes/No}
 
+## Process Feedback
+> Optional. Note friction with the V-Bounce framework itself — templates, handoffs, RAG quality, tooling.
+
+- {e.g., "Dev report didn't specify which test runner was used — had to discover it myself"}
+- {e.g., "None"}
+
 ## Recommendation
 PASS — Ready for Architect review.
 ```
@@ -111,13 +127,14 @@ PASS — Ready for Architect review.
 ---
 status: "FAIL"
 bounce_count: {N}
+tokens_used: {number}
 bugs_found: {number of bugs}
 gold_plating_detected: {true/false}
 failed_scenarios:
   - "{scenario name}"
 ---
 
-# QA Validation Report: STORY-{ID} — FAIL (Bounce {N})
+# QA Validation Report: STORY-{ID}-{StoryName} — FAIL (Bounce {N})
 
 ## Failures
 ### Bug 1: {Short description}
@@ -130,6 +147,12 @@ failed_scenarios:
 ## Gold-Plating Findings
 - {Any unnecessary additions}
 
+## Process Feedback
+> Optional. Note friction with the V-Bounce framework itself — templates, handoffs, RAG quality, tooling.
+
+- {e.g., "Story §2 Gherkin scenarios were ambiguous — 'valid input' not defined"}
+- {e.g., "None"}
+
 ## Recommendation
 FAIL — Returning to Developer for fixes. Bounce count: {N}/3.
 ```
@@ -142,10 +165,10 @@ Every finding must include a non-coder analogy. Examples:
 
 ## Checkpointing
 
-After completing each major phase of your testing (e.g., Quick Scan done, PR Review done, scenarios validated), write a progress checkpoint to `.bounce/reports/STORY-{ID}-qa-checkpoint.md`:
+After completing each major phase of your testing (e.g., Quick Scan done, PR Review done, scenarios validated), write a progress checkpoint to `.bounce/reports/STORY-{ID}-{StoryName}-qa-checkpoint.md`:
 
 ```markdown
-# QA Checkpoint: STORY-{ID}
+# QA Checkpoint: STORY-{ID}-{StoryName}
 ## Completed
 - {Which testing phases are done}
 ## Remaining

package/brains/claude-agents/scribe.md

@@ -17,13 +17,13 @@ You follow the **vdoc workflow**: explore the codebase → plan documentation st
 
 1. **Read LESSONS.md** at the project root. Check for known documentation gotchas and naming conventions.
 2. **Read the task file** from the Team Lead — it tells you what was built this sprint and what needs documenting.
-3. **If `product_documentation/_manifest.json` exists**, read it first. Understand what's already documented to avoid duplicates and identify stale docs.
+3. **If `vdocs/_manifest.json` exists**, read it first. Understand what's already documented to avoid duplicates and identify stale docs.
 4. **Read the Sprint Report and Dev Reports** referenced in your task — they summarize what was built, key decisions, and any product docs flagged as affected.
 
 ## Documentation Workflow
 
 ### Mode: Init (No existing docs)
-When `product_documentation/` doesn't exist yet:
+When `vdocs/` doesn't exist yet:
 
 1. **Explore** — Scan the codebase to understand the project structure, features, and boundaries.
    - Read key entry points, config files, and route definitions
@@ -33,17 +33,17 @@ When `product_documentation/` doesn't exist yet:
    - Group by feature, not by file
    - Each doc should cover a cohesive capability
    - Identify cross-cutting concerns (auth, error handling, etc.)
-3. **Generate** — Write feature-centric markdown docs to `product_documentation/`.
+3. **Generate** — Write feature-centric markdown docs to `vdocs/`.
    - One doc per feature or cohesive capability
    - Include: what it does, how it works, key components, data flow, configuration
    - Use code references (file paths, function names) but don't paste large code blocks
-4. **Manifest** — Create/update `product_documentation/_manifest.json`.
+4. **Manifest** — Create/update `vdocs/_manifest.json`.
    - Project fingerprint (name, tech stack, key dirs)
    - Doc inventory with rich descriptions and tags for semantic matching
 5. **Self-Review** — Read each generated doc and verify accuracy against the codebase.
 
 ### Mode: Audit (Existing docs)
-When `product_documentation/` already exists:
+When `vdocs/` already exists:
 
 1. **Read `_manifest.json`** — understand current doc inventory.
 2. **Compare against codebase** — look for:
@@ -85,7 +85,7 @@ The manifest is a semantic routing table — it helps agents quickly find releva
   },
   "docs": [
     {
-      "path": "product_documentation/auth-system.md",
+      "path": "vdocs/auth-system.md",
       "title": "Authentication System",
       "description": "JWT-based auth with refresh tokens, OAuth providers, and role-based access control",
       "tags": ["auth", "jwt", "oauth", "rbac", "login", "session"],
@@ -100,9 +100,12 @@ The manifest is a semantic routing table — it helps agents quickly find releva
 Write a **Scribe Report** to `.bounce/reports/sprint-S-{XX}-scribe.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`.
+
 ```markdown
 ---
 mode: "{init / audit / create}"
+tokens_used: {number}
 docs_created: {count}
 docs_updated: {count}
 docs_removed: {count}
@@ -135,6 +138,12 @@ docs_removed: {count}
 
 ## Lessons Flagged
 - {Any documentation gotchas worth recording}
+
+## Process Feedback
+> Optional. Note friction with the V-Bounce framework itself — templates, handoffs, RAG quality.
+
+- {e.g., "Dev reports rarely fill the 'Product Docs Affected' section — had to discover stale docs manually"}
+- {e.g., "None"}
 ```
 
 ## Critical Rules
@@ -145,5 +154,5 @@ docs_removed: {count}
 - **Feature-centric, not file-centric.** Organize by user-visible capabilities, not by file paths.
 - **You NEVER communicate with other agents directly.** Your report is your only output.
 - **You NEVER modify LESSONS.md.** Flag documentation lessons for the Lead to record.
-- **You NEVER modify application code.** You only create/edit files in `product_documentation/`.
+- **You NEVER modify application code.** You only create/edit files in `vdocs/`.
 - **Self-review is not optional.** Read every doc you write and verify it against the codebase.

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

@@ -8,17 +8,20 @@ alwaysApply: false
 
 ## Document Locations
 
-All in `product_plans/`. Deliveries get folders. Epics are subfolders. Stories live with Epic.
+All in `product_plans/`. Uses a state-based architecture (`strategy/`, `backlog/`, `sprints/`, `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` |
-| 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` |
+| Hotfix | `product_plans/hotfixes/HOTFIX-{Date}-{Name}.md` |
+| Sprint Report | `product_plans/sprints/sprint-{XX}/sprint-report.md` |
+| Product Docs | `vdocs/*.md` + `_manifest.json` |
 
 ## Skills Reference
 
@@ -30,6 +33,7 @@ All in `product_plans/`. Deliveries get folders. Epics are subfolders. Stories l
 | react-best-practices | `skills/react-best-practices/` | Developer |
 | vibe-code-review | `skills/vibe-code-review/` | QA, Architect |
 | write-skill | `skills/write-skill/` | Team Lead |
+| improve | `skills/improve/` | Team Lead |
 
 ## Report Formats
 

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

@@ -15,17 +15,20 @@ Documents are created in strict hierarchy — no level can be skipped:
 Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → Risk Registry (risks)
 
 ### Pre-Bounce Checks
-Before sprints: Lead triages request (L1 Trivial → Hotfix Path. L2-L4 → Epic Path). Lead reads RISK_REGISTRY.md (flag blocking risks), DELIVERY_PLAN.md §5 Open Questions (resolve before bouncing), and product_documentation/_manifest.json (know what's documented).
+Before sprints: Lead triages request (L1 Trivial → Hotfix Path. L2-L4 → Epic Path). Determines Execution Mode (Full Bounce vs Fast Track). Enforces sequential dependency order for stories with `Depends On:`. Reads RISK_REGISTRY.md (flag blocking risks), `sprint-{XX}.md` §2 Sprint Open Questions (resolve before bouncing), and vdocs/_manifest.json (know what's documented). Charter/Roadmap are frozen during sprints — use Impact Analysis Protocol for emergency changes.
 
 ### 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.
 1. Team Lead sends Story context pack to Developer.
-2. Developer reads LESSONS.md, implements code, writes Implementation Report.
-3. QA validates against Story §2 The Truth. If fail → Bug Report to 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, 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`.
@@ -36,7 +39,7 @@ Before sprints: Lead triages request (L1 Trivial → Hotfix Path. L2-L4 → Epic
 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. If new features delivered → spawn Scribe agent to generate/update product_documentation/.
+Sprint Report → Human review → Delivery Plan updated → Lessons recorded. If new features delivered → spawn Scribe agent to generate/update vdocs/.
 
 ### Story States
 Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architect Passed → Sprint Review → Done

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

@@ -14,13 +14,16 @@ alwaysApply: true
 ## 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. Extra features are defects.
-6. **Self-assess Correction Tax**. Track % human intervention needed.
+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 needed.
 
 ## After Implementation
-7. **Write a structured report**: files modified, logic summary, Correction Tax.
-8. **Flag lessons**. Gotchas and multi-attempt fixes get flagged for recording.
+8. **Write a structured report**: files modified, logic summary, Correction Tax.
+9. **Flag lessons**. Gotchas and multi-attempt fixes get flagged for recording.
 
 ## Always
-9. **Reports are the only handoff**. No direct agent-to-agent communication.
-10. **One source of truth**. Reference upstream documents, don't duplicate.
-11. **Change Logs are mandatory** on every document modification.
+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 `.bounce/report/` generated must start with a strict `---` YAML block containing core status and metrics before the Markdown body.
+14. **Framework Integrity**. Any modification to a `brains/` or `skills/` file MUST be recorded in `brains/CHANGELOG.md` and trigger `./scripts/pre_bounce_sync.sh`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrinio/vbounce",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "V-Bounce OS: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
   "type": "module",
   "bin": {

package/scripts/init_gate_config.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# init_gate_config.sh — Auto-detect project stack and generate .bounce/gate-checks.json
+# Usage: ./scripts/init_gate_config.sh [project-path]
+#
+# Run once during project setup or when the improve skill suggests new checks.
+# Safe to re-run — merges with existing config (preserves custom checks).
+
+set -euo pipefail
+
+PROJECT_PATH="${1:-.}"
+PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+CONFIG_PATH="${PROJECT_PATH}/.bounce/gate-checks.json"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${CYAN}V-Bounce OS Gate Config Initializer${NC}"
+echo -e "Project: ${PROJECT_PATH}"
+echo ""
+
+# ── Detect stack ─────────────────────────────────────────────────────
+
+LANGUAGE="unknown"
+FRAMEWORK="unknown"
+TEST_RUNNER="unknown"
+BUILD_CMD=""
+LINT_CMD=""
+TEST_CMD=""
+
+# Language detection
+if [[ -f "${PROJECT_PATH}/tsconfig.json" ]]; then
+  LANGUAGE="typescript"
+elif [[ -f "${PROJECT_PATH}/package.json" ]]; then
+  LANGUAGE="javascript"
+elif [[ -f "${PROJECT_PATH}/pyproject.toml" || -f "${PROJECT_PATH}/setup.py" || -f "${PROJECT_PATH}/requirements.txt" ]]; then
+  LANGUAGE="python"
+elif [[ -f "${PROJECT_PATH}/Cargo.toml" ]]; then
+  LANGUAGE="rust"
+elif [[ -f "${PROJECT_PATH}/go.mod" ]]; then
+  LANGUAGE="go"
+elif [[ -f "${PROJECT_PATH}/build.gradle" || -f "${PROJECT_PATH}/pom.xml" ]]; then
+  LANGUAGE="java"
+elif [[ -f "${PROJECT_PATH}/Package.swift" ]]; then
+  LANGUAGE="swift"
+fi
+
+echo -e "Language: ${GREEN}${LANGUAGE}${NC}"
+
+# Framework detection (JS/TS ecosystem)
+if [[ -f "${PROJECT_PATH}/package.json" ]]; then
+  PKG_CONTENT=$(cat "${PROJECT_PATH}/package.json")
+
+  if echo "$PKG_CONTENT" | grep -q '"next"'; then FRAMEWORK="nextjs"
+  elif echo "$PKG_CONTENT" | grep -q '"react"'; then FRAMEWORK="react"
+  elif echo "$PKG_CONTENT" | grep -q '"vue"'; then FRAMEWORK="vue"
+  elif echo "$PKG_CONTENT" | grep -q '"svelte"'; then FRAMEWORK="svelte"
+  elif echo "$PKG_CONTENT" | grep -q '"express"'; then FRAMEWORK="express"
+  elif echo "$PKG_CONTENT" | grep -q '"fastify"'; then FRAMEWORK="fastify"
+  elif echo "$PKG_CONTENT" | grep -q '"@angular/core"'; then FRAMEWORK="angular"
+  fi
+
+  # Test runner
+  if echo "$PKG_CONTENT" | grep -q '"vitest"'; then TEST_RUNNER="vitest"
+  elif echo "$PKG_CONTENT" | grep -q '"jest"'; then TEST_RUNNER="jest"
+  elif echo "$PKG_CONTENT" | grep -q '"mocha"'; then TEST_RUNNER="mocha"
+  elif echo "$PKG_CONTENT" | grep -q '"ava"'; then TEST_RUNNER="ava"
+  fi
+
+  # Commands from scripts
+  BUILD_CMD=$(node -e "try{const p=require('${PROJECT_PATH}/package.json');console.log(p.scripts&&p.scripts.build||'')}catch(e){}" 2>/dev/null || echo "")
+  LINT_CMD=$(node -e "try{const p=require('${PROJECT_PATH}/package.json');console.log(p.scripts&&p.scripts.lint||'')}catch(e){}" 2>/dev/null || echo "")
+  TEST_CMD=$(node -e "try{const p=require('${PROJECT_PATH}/package.json');const t=p.scripts&&p.scripts.test||'';if(t&&!t.includes('no test specified'))console.log(t);else console.log('')}catch(e){}" 2>/dev/null || echo "")
+elif [[ "$LANGUAGE" == "python" ]]; then
+  if command -v pytest &>/dev/null; then TEST_RUNNER="pytest"; fi
+  if command -v ruff &>/dev/null; then LINT_CMD="ruff check ."; fi
+elif [[ "$LANGUAGE" == "rust" ]]; then
+  TEST_RUNNER="cargo"
+  BUILD_CMD="cargo build"
+  LINT_CMD="cargo clippy"
+elif [[ "$LANGUAGE" == "go" ]]; then
+  TEST_RUNNER="go"
+  BUILD_CMD="go build ./..."
+  LINT_CMD="golangci-lint run"
+fi
+
+echo -e "Framework: ${GREEN}${FRAMEWORK}${NC}"
+echo -e "Test runner: ${GREEN}${TEST_RUNNER}${NC}"
+[[ -n "$BUILD_CMD" ]] && echo -e "Build: ${GREEN}${BUILD_CMD}${NC}"
+[[ -n "$LINT_CMD" ]] && echo -e "Lint: ${GREEN}${LINT_CMD}${NC}"
+echo ""
+
+# ── Generate config ──────────────────────────────────────────────────
+
+# Build QA checks array
+QA_CHECKS='[
+    { "id": "tests_exist", "enabled": true, "description": "Verify test files exist for modified source files" },
+    { "id": "tests_pass", "enabled": true, "description": "Run test suite" },
+    { "id": "build", "enabled": true, "description": "Run build command" },
+    { "id": "lint", "enabled": true, "description": "Run linter" },
+    { "id": "no_debug_output", "enabled": true, "description": "No debug statements in modified files" },
+    { "id": "no_todo_fixme", "enabled": true, "description": "No TODO/FIXME in modified files" },
+    { "id": "exports_have_docs", "enabled": true, "description": "Exported symbols have doc comments" }
+  ]'
+
+# Build Architect checks array
+ARCH_CHECKS='[
+    { "id": "tests_exist", "enabled": true, "description": "Verify test files exist for modified source files" },
+    { "id": "tests_pass", "enabled": true, "description": "Run test suite" },
+    { "id": "build", "enabled": true, "description": "Run build command" },
+    { "id": "lint", "enabled": true, "description": "Run linter" },
+    { "id": "no_debug_output", "enabled": true, "description": "No debug statements in modified files" },
+    { "id": "no_todo_fixme", "enabled": true, "description": "No TODO/FIXME in modified files" },
+    { "id": "exports_have_docs", "enabled": true, "description": "Exported symbols have doc comments" },
+    { "id": "no_new_deps", "enabled": true, "description": "No new dependencies without review" },
+    { "id": "file_size", "enabled": true, "max_lines": 500, "description": "Source files under 500 lines" }
+  ]'
+
+# Write config
+mkdir -p "$(dirname "$CONFIG_PATH")"
+
+cat > "$CONFIG_PATH" << HEREDOC
+{
+  "version": 1,
+  "detected_stack": {
+    "language": "${LANGUAGE}",
+    "framework": "${FRAMEWORK}",
+    "test_runner": "${TEST_RUNNER}",
+    "build_cmd": "${BUILD_CMD}",
+    "lint_cmd": "${LINT_CMD}",
+    "test_cmd": "${TEST_CMD}"
+  },
+  "qa_checks": ${QA_CHECKS},
+  "arch_checks": ${ARCH_CHECKS},
+  "custom_checks": []
+}
+HEREDOC
+
+echo -e "${GREEN}Generated: ${CONFIG_PATH}${NC}"
+echo ""
+echo "Universal checks enabled. To add project-specific checks:"
+echo "  1. Run sprints and let agents collect Process Feedback"
+echo "  2. Use the 'improve' skill to propose new checks"
+echo "  3. Or manually add entries to the custom_checks array"
+echo ""
+echo -e "Example custom check (add to custom_checks):"
+echo '  { "id": "custom_grep", "gate": "arch", "enabled": true,'
+echo '    "pattern": "var\\(--my-prefix-", "glob": "*.tsx",'
+echo '    "should_find": false, "description": "No raw CSS vars in components" }'