@sandrinio/vbounce 1.5.0 → 1.7.0

package/skills/agent-team/references/delivery-sync.md

@@ -0,0 +1,43 @@
+# Delivery Plan Sync Rules
+
+> On-demand reference from agent-team/SKILL.md. When and how to update the Delivery Plan.
+
+## Core Rule
+
+**The Delivery Plan is updated ONLY at sprint boundaries — not during active bouncing.**
+
+Story state changes are tracked in the Sprint Plan (sprint-{XX}.md) §1 ONLY.
+The Delivery Plan is a strategic document — it does not track story states.
+
+## Sync Table
+
+| Action | Sprint Plan Update | Delivery Plan Update |
+|--------|-------------------|---------------------|
+| Sprint starts | Status → "Active" (frontmatter) | §2: sprint status → Active |
+| Story state changes | §1 V-Bounce State ONLY | **Nothing** |
+| Story completes | §1 state → Done, §4 Execution Log row added | **Nothing** |
+| Sprint ends | Status → "Completed" (frontmatter) | §2: sprint → Completed, §4: add summary row, §3: remove delivered stories |
+| Hotfix applied | No sprint plan change | **Nothing** |
+
+## What Each Document Owns
+
+**Sprint Plan** (sprint-{XX}.md):
+- Story states (§1 V-Bounce State column)
+- Context Pack Readiness (§1)
+- Execution Strategy and phases (§2)
+- Sprint open questions (§3)
+- Execution Log accumulation (§4)
+
+**Delivery Plan** (D-{NN}_DELIVERY_PLAN.md):
+- Epic-level status (§2)
+- Unassigned backlog stories (§3)
+- Completed sprint history (§4)
+- Project window and team (§1)
+
+## Never Do This
+
+- ❌ Update Delivery Plan §2/§3 when a story bounces
+- ❌ Update Delivery Plan §2/§3 when QA passes
+- ❌ Update Delivery Plan §2/§3 when Architect passes
+- ✅ Update Sprint Plan §1 for ALL state transitions during the sprint
+- ✅ Update Delivery Plan §4 only when a sprint CLOSES

package/skills/agent-team/references/git-strategy.md

@@ -0,0 +1,52 @@
+# Git Strategy Reference
+
+> On-demand reference from agent-team/SKILL.md. Read when setting up worktrees or performing git operations.
+
+## Branch Model
+
+```
+main                                    ← production
+└── sprint/S-01                         ← sprint branch (cut from main)
+    ├── story/STORY-001-01-login        ← story branch (worktree)
+    ├── story/STORY-001-02-auth         ← story branch (worktree)
+    └── story/STORY-001-03-api          ← story branch (worktree)
+```
+
+## Sprint Commands
+
+```bash
+# Cut sprint branch
+git checkout -b sprint/S-06 main
+
+# Create story worktree
+git worktree add .worktrees/STORY-001-01-login -b story/STORY-001-01-login sprint/S-06
+mkdir -p .worktrees/STORY-001-01-login/.bounce/{tasks,reports}
+
+# List active worktrees
+git worktree list
+
+# Merge story into sprint
+git checkout sprint/S-06
+git merge story/STORY-001-01-login --no-ff -m "Merge STORY-001-01: {Story Name}"
+
+# Remove worktree after merge
+git worktree remove .worktrees/STORY-001-01-login
+git branch -d story/STORY-001-01-login
+
+# Merge sprint into main
+git checkout main
+git merge sprint/S-06 --no-ff -m "Sprint S-06: {Sprint Goal}"
+git tag -a v{VERSION} -m "Release v{VERSION}"
+```
+
+## V-Bounce State → Git Operations
+
+| V-Bounce State | Git Operation |
+|---------------|---------------|
+| Sprint starts | `git checkout -b sprint/S-XX main` |
+| Ready to Bounce | `git worktree add .worktrees/STORY-{ID} -b story/STORY-{ID} sprint/S-XX` |
+| Bouncing | All work happens inside `.worktrees/STORY-{ID}/` |
+| Done | Merge story branch → sprint branch, `git worktree remove` |
+| Sprint Review → Done | Merge sprint branch → main |
+| Escalated | Worktree kept but frozen (no new commits) |
+| Parking Lot | Worktree removed, branch preserved unmerged |

package/skills/agent-team/references/mid-sprint-triage.md

@@ -0,0 +1,71 @@
+# Mid-Sprint Change Request Triage
+
+> On-demand reference from agent-team/SKILL.md. How the Team Lead handles user interruptions during an active sprint.
+
+## When This Applies
+
+Any time the user provides input mid-bounce that is **not** a direct answer to a question the agent asked. Examples:
+- "This is broken"
+- "Actually, change the auth to use OAuth"
+- "I meant X, not Y"
+- "Can we also add Z?"
+- "The wiring between A and B doesn't work"
+
+## Step 1 — Categorize
+
+The Team Lead MUST classify the request before acting:
+
+| Category | Definition | Example |
+|----------|-----------|---------|
+| **Bug** | Something built (or pre-existing) is broken | "Login crashes when email has a plus sign" |
+| **Spec Clarification** | The spec was ambiguous; user is clarifying intent, not changing scope | "By 'admin' I meant workspace admin, not super admin" |
+| **Scope Change** | User wants to add, remove, or modify requirements for the current story | "Also add a forgot-password flow to the login story" |
+| **Approach Change** | Implementation strategy is wrong; needs a different technical path | "Don't use REST for this — wire it through WebSockets instead" |
+
+### How to Decide
+
+```
+Is existing behavior broken?
+  YES → Bug
+  NO  → Is the user adding/removing/changing a requirement?
+          YES → Scope Change
+          NO  → Is the user correcting an ambiguity in the spec?
+                  YES → Spec Clarification
+                  NO  → Approach Change (technical direction shift)
+```
+
+## Step 2 — Route
+
+| Category | Action | Bounce Impact |
+|----------|--------|---------------|
+| **Bug** | If L1 (1-2 files): Hotfix Path. If larger: add as a bug-fix task within the current story bounce. | Does NOT increment QA/Arch bounce count. |
+| **Spec Clarification** | Update Story spec inline (§1 or §2). Add a note in the Change Log. Continue current bounce. | Does NOT reset or increment bounce count. |
+| **Scope Change** | Pause bounce. Update Story spec. If scope grew significantly, consider splitting into a new story. Reset Dev pass (QA/Arch counts preserved if prior passes are still valid). | Resets Dev pass only. Prior QA/Arch passes invalidated if the change affects tested areas. |
+| **Approach Change** | Update Story §3 Implementation Guide. Re-delegate to Developer with updated context. | Resets Dev pass only. Prior QA/Arch passes invalidated. |
+
+## Step 3 — Log
+
+Every change request MUST be logged in the Sprint Plan `sprint-{XX}.md` §4 Execution Log:
+
+```
+| {timestamp} | CR | {Category} | {STORY-ID} | {One-line description} |
+```
+
+Use `CR` as the event type to distinguish from regular bounce events.
+
+## Sprint Report Tracking
+
+At sprint consolidation (Step 7), the Team Lead includes a **§2.1 Change Requests** section in the Sprint Report summarizing all mid-sprint CRs. This keeps change-request-driven work separate from agent-driven bounces so metrics aren't skewed.
+
+| Story | Category | Description | Impact |
+|-------|----------|-------------|--------|
+| STORY-{ID} | Spec Clarification | Clarified admin role scope | No bounce reset |
+| STORY-{ID} | Scope Change | Added forgot-password flow | Dev pass reset, +1 session |
+
+## Key Rules
+
+- **Never silently absorb a user change.** Always categorize and log it.
+- **Bugs don't penalize the bounce count.** They are defects, not process failures.
+- **Spec clarifications are cheap.** Update the spec and move on — no ceremony needed.
+- **Scope changes are expensive.** Always pause, update the spec, and confirm with the user before resuming.
+- **Correction Tax still applies.** Human intervention is tracked, but the category explains *why*.

package/skills/agent-team/references/report-naming.md

@@ -0,0 +1,34 @@
+# Report Naming Conventions
+
+> On-demand reference from agent-team/SKILL.md. Canonical naming for all report files.
+
+## Story Report Files
+
+Pattern: `STORY-{EpicID}-{StoryID}-{StoryName}-{agent}[-bounce{N}].md`
+
+| Report | Filename | Location |
+|--------|----------|----------|
+| Dev (first pass) | `STORY-001-01-login-dev.md` | `.worktrees/STORY-001-01-login/.bounce/reports/` |
+| QA FAIL (first bounce) | `STORY-001-01-login-qa-bounce1.md` | `.worktrees/STORY-001-01-login/.bounce/reports/` |
+| Dev fix (second pass) | `STORY-001-01-login-dev-bounce2.md` | `.worktrees/STORY-001-01-login/.bounce/reports/` |
+| QA PASS | `STORY-001-01-login-qa-bounce2.md` | `.worktrees/STORY-001-01-login/.bounce/reports/` |
+| Architect | `STORY-001-01-login-arch.md` | `.worktrees/STORY-001-01-login/.bounce/reports/` |
+| DevOps merge | `STORY-001-01-login-devops.md` | `.bounce/archive/S-{XX}/STORY-001-01-login/` |
+
+## Sprint-Level Files
+
+| Report | Filename | Location |
+|--------|----------|----------|
+| Sprint DevOps | `sprint-S-{XX}-devops.md` | `.bounce/archive/S-{XX}/` |
+| Sprint Scribe | `sprint-S-{XX}-scribe.md` | `.bounce/archive/S-{XX}/` |
+| Sprint Report (active) | `sprint-report-S-{XX}.md` | `.bounce/` (gitignored) |
+| Sprint Report (archived) | `sprint-report-S-{XX}.md` | `.bounce/archive/S-{XX}/` (committed) |
+| Sprint Context Pack | `sprint-context-S-{XX}.md` | `.bounce/` (gitignored) |
+| Sprint Summary | `sprint-summary-S-{XX}.md` | `.bounce/` (gitignored) |
+
+## Key Rules
+
+- Sprint ID always uses `S-{XX}` format (two digits, zero-padded)
+- No delivery prefix on sprint-level files — sprint ID is globally unique
+- Active sprint reports include sprint ID in filename
+- `bounce{N}` suffix counts from 1 (bounce1 = first failure, bounce2 = second failure)

package/skills/doc-manager/SKILL.md

@@ -52,15 +52,16 @@ Epic §4 (Technical Context) ──→ Story §3 (Implementation Guide)
 Epic §5 (Decomposition) ──→ Story creation sequence
 Epic §6 (Risks) ──→ Risk Registry §1 (Active Risks)
 Epic §7 (Acceptance Criteria) ──→ Story §2 (The Truth)
-Epic §9 (Artifact Links) ──→ Delivery Plan §3 (Active Sprint)
+Epic §9 (Artifact Links) ──→ Delivery Plan §3 (Backlog)
 
 Story §1 (The Spec) ──→ Developer Agent
 Story §2 (The Truth) ──→ QA Agent
 Story §3 (Implementation Guide) ──→ Developer Agent
-Story status ──→ Delivery Plan §3 (V-Bounce State)
+Story status ──→ Sprint Plan §1 (V-Bounce State) [NOT Delivery Plan — see delivery-sync.md]
 
-Delivery Plan §3 (Active Sprint) ──→ Team Lead Agent (initialization)
-Delivery Plan §5 (Context Pack) ──→ Ready to Bounce gate
+Sprint Plan §1 (Active Scope) ──→ Team Lead Agent (source of truth during sprint)
+Sprint Plan §1 (Context Pack Readiness) ──→ Ready to Bounce gate
+Delivery Plan ──→ Updated at sprint boundaries ONLY (never mid-sprint)
 
 Risk Registry ←── ALL levels (cross-cutting input)
 ```

package/skills/improve/SKILL.md

@@ -70,7 +70,7 @@ Group findings by framework area:
 |------|-----------------|----------------|
 | **Templates** | Missing fields, unused sections, ambiguous instructions | `templates/*.md` |
 | **Agent Handoffs** | Missing report fields, redundant data, unclear formats | `brains/claude-agents/*.md` |
-| **RAG Pipeline** | Irrelevant results, missing context, stale embeddings | `scripts/vbounce_index.mjs`, `scripts/vbounce_ask.mjs`, `scripts/pre_bounce_sync.sh` |
+| **Context Prep** | Missing context, stale prep packs, truncation issues | `scripts/prep_sprint_context.mjs`, `scripts/prep_qa_context.mjs`, `scripts/prep_arch_context.mjs` |
 | **Skills** | Unclear instructions, missing steps, outdated references | `skills/*/SKILL.md`, `skills/*/references/*` |
 | **Process Flow** | Unnecessary steps, wrong ordering, missing gates | `skills/agent-team/SKILL.md`, `skills/doc-manager/SKILL.md` |
 | **Tooling** | Script failures, validation gaps, missing automation | `scripts/*`, `bin/*` |
@@ -107,6 +107,32 @@ For script changes, describe the new behavior.}
 **Reversibility:** {Easy — revert the edit / Medium — downstream docs may need updating}
 ```
 
+#### Special Case: Gate Check Proposals
+
+When agent feedback reveals a mechanical check that was repeated manually across multiple stories (e.g., "QA checked for inline styles 4 times"), propose adding it as a pre-gate check instead of a skill/template change:
+
+```markdown
+### Proposal {N}: Add pre-gate check — {check name}
+
+**Finding:** {Agent} manually performed {check description} in {N} stories this sprint.
+**Tokens saved:** ~{estimate} per story (based on agent token usage for this check type)
+**Gate:** qa / arch
+**Check config to add to `.bounce/gate-checks.json`:**
+```json
+{
+  "id": "custom_grep",
+  "gate": "arch",
+  "enabled": true,
+  "pattern": "{regex}",
+  "glob": "{file pattern}",
+  "should_find": false,
+  "description": "{human-readable description}"
+}
+```
+```
+
+This is the primary mechanism for the gate system to grow organically — the `improve` skill reads what agents repeatedly checked by hand and proposes automating those checks via `gate-checks.json`.
+
 ### Step 5: Present to Human
 Present ALL proposals as a numbered list. The human can:
 - **Approve** — apply the change

package/skills/lesson/SKILL.md

@@ -88,3 +88,26 @@ Rules for formatting:
 - **Rules are imperatives.** Write rules as direct commands, not suggestions.
 - **No duplicates.** Before recording, check if a similar lesson already exists. If so, update it instead of creating a new one.
 - **Keep it flat.** No categories, no tags, no metadata beyond the entry format. Simplicity is the feature.
+
+## Lesson Graduation
+
+Lessons that have been proven effective across 3+ sprints become permanent agent config rules.
+
+### Graduation Criteria
+
+A lesson is a **graduation candidate** when:
+- It has been active for 3+ sprints
+- It has been triggered (prevented a recurrence) at least once
+- No bounce in the last 3 sprints matches its root cause
+
+### Graduation Process
+
+1. `scripts/suggest_improvements.mjs` flags graduation candidates in improvement suggestions
+2. Human approves graduation
+3. Lead adds the rule to the relevant agent config (`brains/claude-agents/developer.md`, etc.)
+4. Lead removes or archives the lesson from `LESSONS.md` with a note: `[Graduated to {agent} config on {date}]`
+5. Record in `.bounce/improvement-log.md` under "Applied"
+
+### Why Graduation Matters
+
+`LESSONS.md` is a staging area, not a permanent rule store. Lessons that graduate become enforced constraints in the agent's core instructions — they can't be forgotten or overlooked. Lessons that stay in `LESSONS.md` are read on every session but are softer guidance. Keep `LESSONS.md` lean — stale lessons dilute the signal.

package/templates/delivery_plan.md

@@ -10,7 +10,7 @@ Delivery Lifecycle:
 - Active sprint work happens inside `sprints/sprint-{XX}/sprint-{XX}.md`, not here.
 - When the delivery is fully shipped, this entire document is archived.
 
-Output location: `product_plans/strategy/{delivery}_delivery_plan.md`
+Output location: `product_plans/D-{NN}_{release_name}/D-{NN}_DELIVERY_PLAN.md`
 Do NOT output these instructions.
 </instructions>
 # Delivery Plan: {Project Name}

package/templates/hotfix.md

@@ -53,5 +53,5 @@ complexity_label: "L1 (Trivial)"
 
 - [ ] {Simple step, e.g., "Open the settings modal and verify the button is aligned."}
 - [ ] Automated tests still pass (`npm test`).
-- [ ] **Framework Integrity**: If `brains/` or `skills/` were modified, log to `brains/CHANGELOG.md` and run `./scripts/pre_bounce_sync.sh`.
+- [ ] **Framework Integrity**: If `brains/` or `skills/` were modified, log to `brains/CHANGELOG.md`.
 - [ ] **Post-Fix Action**: Run `./scripts/hotfix_manager.sh ledger "HOTFIX: {Name}" "{Brief Fix Description}"`

package/templates/sprint.md

@@ -1,21 +1,25 @@
 <instructions>
-FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-2.
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
 
-1. **YAML Frontmatter**: Sprint ID, Goal, Dates, Status
-2. **§1 Active Scope**: Table of stories pulled into this sprint. The V-Bounce state tracks its progression.
-3. **§2 Sprint Open Questions**: Unresolved items blocking this active execution window.
+1. **YAML Frontmatter**: Sprint ID, Goal, Dates, Status, Delivery ref
+2. **§1 Active Scope**: Table of stories + Context Pack Readiness checklists
+3. **§2 Execution Strategy**: Parallel phases, dependencies, risk flags
+4. **§3 Sprint Open Questions**: Unresolved items blocking this sprint
+5. **§4 Execution Log**: Accumulated story results (populated during sprint, becomes Sprint Report §2 source)
 
 Output location: `product_plans/sprints/sprint-{XX}/sprint-{XX}.md`
 
 Role of this document:
-- This is the Tactical view of the active sprint execution.
-- It tracks ONLY the stories claimed for this 1-week window.
-- The Team Lead agent reads this to know what is in scope.
+- This is the SINGLE SOURCE OF TRUTH during active sprint execution.
+- The Team Lead updates this file at every state transition — NOT the Delivery Plan.
+- The Delivery Plan is only updated at sprint boundaries (start and end).
 
 Document Lifecycle:
-- Created by the Team Lead or PM during Sprint Setup.
-- Selected stories are physically moved from `product_plans/backlog/EPIC-*/` to `product_plans/sprints/sprint-{XX}/`.
-- When the sprint completes, this document (and the entire sprint folder) moves to `product_plans/archive/sprints/sprint-{XX}/`.
+- Created by the Team Lead at Sprint Setup (Step 0) via `vbounce sprint init`.
+- §1 V-Bounce States updated at every story transition.
+- §4 Execution Log gets one row per completed story (via `vbounce story complete`).
+- At sprint end, §4 becomes the skeleton for Sprint Report §2 — no reconstruction needed.
+- When the sprint completes, this document moves to `product_plans/archive/sprints/sprint-{XX}/`.
 
 Do NOT output these instructions.
 </instructions>
@@ -25,24 +29,72 @@ sprint_id: "sprint-{XX}"
 sprint_goal: "{One-sentence North Star}"
 dates: "{MM/DD - MM/DD}"
 status: "Planning / Active / Completed"
+delivery: "D-{NN}"
 ---
 
 # Sprint S-{XX} Plan
 
 ## 1. Active Scope
 > Stories pulled from the backlog for execution during this sprint window.
-> The V-Bounce State tracks the live status of the story (Draft -> Ready to Bounce -> Bouncing -> QA Passed -> Architect Passed -> Sprint Review -> Done).
+> V-Bounce State is the ONLY authoritative source for story status during the sprint.
 
 | Priority | Story | Epic | Label | V-Bounce State | Blocker |
 |----------|-------|------|-------|----------------|---------|
 | 1 | [STORY-XXX-YY: name](./STORY-XXX-YY-name.md) | EPIC-XXX | L2 | Draft | — |
 
+### Context Pack Readiness
+> Check before moving story to "Ready to Bounce". All items must be ✅.
+> Run `vbounce validate ready STORY-ID` to verify programmatically.
+
+**STORY-{ID}: {name}**
+- [ ] Story spec complete (§1)
+- [ ] Acceptance criteria defined (§2)
+- [ ] Implementation guide written (§3)
+- [ ] Ambiguity: Low / Medium (if High → back to Refinement)
+
+V-Bounce State: Draft / Refinement / Ready to Bounce
+
 ### Escalated / Parking Lot
 - STORY-XXX-YY: {name} — Reason: {escalated / deferred}
 
-## 2. Sprint Open Questions
-> Unresolved items that affect this specific 1-week execution window.
+---
+
+## 2. Execution Strategy
+> Written during sprint planning. Guides the Lead's delegation order.
+
+### Phase Plan
+- **Phase 1 (parallel)**: {Story IDs that can run simultaneously}
+- **Phase 2 (sequential)**: {Story IDs with dependencies — run in order}
+
+### Risk Flags
+- {Which stories touch shared modules — coordinate access}
+- {Sprint-specific risks pulled from Risk Registry}
+
+### Dependency Chain
+> Stories that MUST run sequentially (depends_on relationships).
+
+| Story | Depends On | Reason |
+|-------|-----------|--------|
+| STORY-XXX-YY | STORY-XXX-YY | {why sequential} |
+
+---
+
+## 3. Sprint Open Questions
+> Unresolved items that affect this specific sprint execution window.
+> Strategic questions belong in the Delivery Plan, not here.
 
 | Question | Options | Impact | Owner | Status |
 |----------|---------|--------|-------|--------|
 | {question} | A: {x}, B: {y} | Blocks {stories} | {name} | Open / Decided |
+
+---
+
+<!-- EXECUTION_LOG_START -->
+## 4. Execution Log
+> Updated by the Lead after each story completes via `vbounce story complete STORY-ID`.
+> This table becomes Sprint Report §2 at sprint end — no reconstruction needed.
+
+| Story | Final State | QA Bounces | Arch Bounces | Correction Tax | Notes |
+|-------|-------------|------------|--------------|----------------|-------|
+| STORY-XXX-YY | Done | 0 | 0 | 0% | {brief note} |
+<!-- EXECUTION_LOG_END -->

package/templates/sprint_report.md

@@ -3,7 +3,7 @@ FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-6.
 
 1. **YAML Frontmatter**: Sprint ID, Goal, Dates, Status, Delivery Ref, Delivery Plan Ref
 2. **§1 What Was Delivered**: User-facing summary — what's accessible/usable vs what's internal/backend
-3. **§2 Story Results**: Table of all stories with final status and per-story metrics
+3. **§2 Story Results**: Table of all stories with final status and per-story metrics. §2.1 Change Requests logs any mid-sprint user interventions (bugs, spec clarifications, scope/approach changes)
 4. **§3 Execution Metrics**: AI performance metrics — tokens, duration, bounces, correction tax
 5. **§4 Lessons Learned**: Flagged from agent reports, pending user approval to record
 6. **§5 Retrospective**: What went well, what didn't, and what to change — covers both project and delivery process
@@ -72,6 +72,13 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 ### Escalated Stories (if any)
 - **STORY-{ID}-{story_name}**: Escalated after {N} bounces. Root cause: {why}. Recommendation: {rewrite spec / descope / kill}.
 
+### 2.1 Change Requests
+> Mid-sprint user interventions — bugs found, spec clarifications, scope or approach changes. Tracked separately from agent-driven bounces so metrics aren't skewed. Omit this section if no CRs occurred.
+
+| Story | Category | Description | Impact |
+|-------|----------|-------------|--------|
+| STORY-{ID} | Bug / Spec Clarification / Scope Change / Approach Change | {One-line description} | {e.g., No bounce reset / Dev pass reset / +1 session} |
+
 ---
 
 ## 3. Execution Metrics

package/templates/story.md

@@ -153,4 +153,4 @@ POST /api/resource
 - [ ] LESSONS.md consulted before implementation.
 - [ ] No violations of Roadmap ADRs.
 - [ ] Documentation (API/Tech Stack) updated.
-- [ ] **Framework Integrity**: If `brains/` or `skills/` were modified, log to `brains/CHANGELOG.md` and run `./scripts/pre_bounce_sync.sh`.
+- [ ] **Framework Integrity**: If `brains/` or `skills/` were modified, log to `brains/CHANGELOG.md`.

package/scripts/pre_bounce_sync.sh

@@ -1,37 +0,0 @@
-#!/usr/bin/env bash
-
-# pre_bounce_sync.sh
-# 
-# Run this before kicking off the Implementation Loop (Bounce).
-# This prevents the "Stale Context" edge case by forcing the LanceDB
-# index to refresh with the latest rules from LESSONS.md and ROADMAP.md.
-
-echo "==========================================="
-echo " V-Bounce OS: Pre-Bounce Sync Started"
-echo "==========================================="
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
-ROOT_DIR="$(dirname "$SCRIPT_DIR")"
-
-cd "$ROOT_DIR" || exit 1
-
-# 1. Check for Node Modules
-if [ ! -d "node_modules" ]; then
-    echo "Error: node_modules not found. Run 'npm install'."
-    exit 1
-fi
-
-# 2. Rebuild the semantic search index
-echo "Syncing V-Bounce Knowledge Base (LanceDB)..."
-node ./scripts/vbounce_index.mjs --all
-
-if [ $? -ne 0 ]; then
-    echo "Error: LanceDB index sync failed."
-    exit 1
-fi
-
-echo "==========================================="
-echo " Pre-Bounce Sync Complete. RAG is fresh."
-echo " Ready for Team Lead delegation."
-echo "==========================================="
-exit 0

package/scripts/vbounce_ask.mjs

@@ -1,98 +0,0 @@
-#!/usr/bin/env node
-
-import fs from 'fs';
-import path from 'path';
-import { connect } from '@lancedb/lancedb';
-import { pipeline } from '@xenova/transformers';
-import { program } from 'commander';
-
-const LANCE_DIR = path.join(process.cwd(), '.bounce', '.lancedb');
-
-program
-    .name('vbounce_ask')
-    .description('Query V-Bounce OS LanceDB for relevant context')
-    .argument('<query>', 'The semantic query to search for')
-    .option('-f, --filter <field=value>', 'Filter by metadata (e.g., type=lesson)')
-    .option('-l, --limit <number>', 'Number of results to return', 3)
-    .parse(process.argv);
-
-const options = program.opts();
-const query = program.args[0];
-
-class LocalEmbeddingFunction {
-    constructor() {
-        this.modelName = 'Xenova/all-MiniLM-L6-v2';
-        this.extractor = null;
-    }
-
-    async init() {
-        if (!this.extractor) {
-            this.extractor = await pipeline('feature-extraction', this.modelName, {
-                quantized: true,
-            });
-        }
-    }
-
-    async embedQuery(text) {
-        await this.init();
-        const output = await this.extractor(text, { pooling: 'mean', normalize: true });
-        return Array.from(output.data);
-    }
-}
-
-async function main() {
-    if (!query) {
-        console.error("Error: Must provide a semantic query string.");
-        process.exit(1);
-    }
-
-    if (!fs.existsSync(LANCE_DIR)) {
-        console.error(`Error: LanceDB not found at ${LANCE_DIR}. Have you run vbounce_index yet?`);
-        process.exit(1);
-    }
-
-    const db = await connect(LANCE_DIR);
-    let table;
-    try {
-        table = await db.openTable('vbounce_context');
-    } catch (e) {
-        console.error("Error: Table 'vbounce_context' not found. Please index documents first.");
-        process.exit(1);
-    }
-
-    const embedder = new LocalEmbeddingFunction();
-    const queryVector = await embedder.embedQuery(query);
-
-    let search = table.vectorSearch(queryVector).limit(parseInt(options.limit));
-
-    if (options.filter) {
-        const [field, value] = options.filter.split('=');
-        // LanceDB JS uses SQL-like string criteria for filtering
-        if (field === "type") {
-            search = search.where(`\`type\` = '${value}'`);
-        } else if (field === "section") {
-            search = search.where(`\`section\` = '${value}'`);
-        }
-    }
-
-    const results = await search.toArray();
-
-    if (results.length === 0) {
-        console.log("No relevant context found.");
-        return;
-    }
-
-    console.log(`\n--- V-Bounce Semantic Retrieval ---`);
-    console.log(`Query: "${query}"`);
-    console.log(`Found ${results.length} relevant chunks.\n`);
-
-    results.forEach((r, idx) => {
-        console.log(`[Result ${idx + 1}] Source: ${r.file} (${r.type || 'unknown'} > ${r.section || 'General'})`);
-        console.log(`Distance: ${r._distance ? r._distance.toFixed(4) : 'N/A'}`);
-        console.log('-'.repeat(40));
-        console.log(r.text.trim());
-        console.log('\n');
-    });
-}
-
-main().catch(console.error);