@sandrinio/vbounce 1.6.0 → 1.8.0

package/skills/agent-team/SKILL.md

@@ -61,12 +61,12 @@ repo/                                   ← main working directory
 │
 └── .bounce/
     ├── reports/                        ← active working reports (GITIGNORED)
-    ├── sprint-report.md                ← current sprint report (GITIGNORED)
+    ├── sprint-report-S-{XX}.md          ← current sprint report (GITIGNORED)
     └── archive/                        ← completed sprint history (COMMITTED TO GIT)
         └── S-01/
             ├── STORY-001-01/           ← all agent reports for this story
-            ├── sprint-report.md        ← final sprint report
-            └── sprint-devops.md        ← release report
+            ├── sprint-report-S-{XX}.md  ← final sprint report
+            └── sprint-S-{XX}-devops.md  ← release report
 ```
 
 ### V-Bounce State → Git Operations
@@ -154,7 +154,7 @@ For tools without native subagent support (Cursor, Codex, Gemini, Antigravity):
 
 **After story completes:** Reports are archived to the shared `.bounce/archive/S-{XX}/STORY-{ID}-{StoryName}/` in the main repo before the worktree is removed.
 
-**Sprint Report:** Always written to `.bounce/sprint-report.md` in the main repo (not in any worktree).
+**Sprint Report:** Always written to `.bounce/sprint-report-S-{XX}.md` in the main repo (not in any worktree).
 
 ### Report File Naming
 
@@ -327,7 +327,7 @@ After ALL stories are merged into `sprint/S-01`:
 ```
 1. Read all archived reports in .bounce/archive/S-{XX}/
 2. **Sum the `tokens_used` field** from every agent report to calculate the sprint's total resource cost.
-3. Generate Sprint Report to .bounce/sprint-report.md:
+3. Generate Sprint Report to .bounce/sprint-report-S-{XX}.md:
    - Ensure the Sprint Report starts with a YAML frontmatter block containing:
      ```yaml
      ---
@@ -347,9 +347,9 @@ After ALL stories are merged into `sprint/S-01`:
    - Run full test suite + build + lint on main
    - Sprint branch cleanup
    - Environment verification (if applicable)
-   - DevOps writes Sprint Release Report to .bounce/archive/S-{XX}/sprint-devops.md
+   - DevOps writes Sprint Release Report to .bounce/archive/S-{XX}/sprint-S-{XX}-devops.md
 6. Lead finalizes:
-   - Move sprint-report.md to .bounce/archive/S-{XX}/
+   - Move sprint-report-S-{XX}.md to .bounce/archive/S-{XX}/
    - Record lessons (with user approval)
    - Update delivery_plan.md to reflect the completed sprint.
 7. **Framework Self-Assessment** (aggregated from agent reports):
@@ -359,17 +359,24 @@ After ALL stories are merged into `sprint/S-01`:
      - Offer to run the `improve` skill to propose framework changes
      - If user approves → read `skills/improve/SKILL.md` and execute the improvement process
 8. Product Documentation check (runs on `main` after sprint merge):
-   - If sprint delivered 3+ features, or if any Developer report flagged
-     stale product docs → offer to run vdoc to generate/update
-     vdocs/
-   - If user approves → spawn scribe subagent on `main` branch with:
-     - Sprint Report (what was built)
-     - Dev reports that flagged affected product docs
-     - Current _manifest.json (if exists)
-     - Mode: "audit" (if docs exist) or "init" (if first time)
-   - Scribe generates/updates docs and writes Scribe Report
-   - Documentation is post-implementation — it reflects what was built
-   - Scribe commits documentation as a follow-up commit on `main`
+   a. **Staleness Detection** — run `./scripts/vdoc_staleness.mjs S-{XX}`
+      - Cross-references all Dev Reports' `files_modified` against manifest key files
+      - Generates `.bounce/scribe-task-S-{XX}.md` with targeted list of stale docs
+      - Populates Sprint Report §1 "Product Docs Affected" table
+      - If no `vdocs/_manifest.json` exists → skip silently (graceful no-op)
+   b. **Scribe Task Decision:**
+      - If staleness detection found stale docs → offer targeted Scribe task
+      - If sprint delivered 3+ features and no vdocs exist → offer vdoc init
+      - If any Developer report flagged stale product docs → offer Scribe update
+   c. If user approves → spawn scribe subagent on `main` branch with:
+      - `.bounce/scribe-task-S-{XX}.md` (targeted task — when available)
+      - Sprint Report (what was built)
+      - Dev reports that flagged affected product docs
+      - Current _manifest.json (if exists)
+      - Mode: "audit" (if docs exist) or "init" (if first time)
+   d. Scribe generates/updates docs and writes Scribe Report
+      - Documentation is post-implementation — it reflects what was built
+      - Scribe commits documentation as a follow-up commit on `main`
 ```
 
 ---
@@ -420,15 +427,18 @@ When ALL sprints in a delivery (release) are done:
 
 The Team Lead MUST update the active `sprint-{XX}.md` at every state transition. This is the source of truth for execution.
 
-| Action | Sprint Plan Update |
-|--------|---------------------|
-| Worktree created | §1 Active Scope: V-Bounce State → "Bouncing" |
-| Dev report written | No update (still "Bouncing") |
-| QA passes | §1 Active Scope: V-Bounce State → "QA Passed" |
-| Architect passes | §1 Active Scope: V-Bounce State → "Architect Passed" |
-| DevOps merges story | §1 Active Scope: V-Bounce State → "Done" |
-| Escalated | §1 Escalated table |
-| DevOps merges sprint | Update `delivery_plan.md` to flag sprint delivered |
+| Action | Sprint Plan Update | Delivery Plan Update |
+|--------|-------------------|--------------------|
+| Worktree created | §1: V-Bounce State → "Bouncing" | **Nothing** — Sprint Plan is source of truth |
+| Dev report written | No update (still "Bouncing") | **Nothing** |
+| QA passes | §1: V-Bounce State → "QA Passed" | **Nothing** |
+| Architect passes | §1: V-Bounce State → "Architect Passed" | **Nothing** |
+| DevOps merges story | §1: V-Bounce State → "Done". §4: Add Execution Log row (via `vbounce story complete`) | **Nothing** |
+| Escalated | §1: Move story to Escalated section | **Nothing** |
+| Sprint CLOSES | Status → "Completed" in frontmatter | §2: sprint → Completed. §4: add summary. §3: remove delivered stories |
+
+> **Key rule**: The Delivery Plan is updated ONLY at sprint close, never during active bouncing.
+> See `skills/agent-team/references/delivery-sync.md` for full sync rules.
 
 ---
 
@@ -448,6 +458,21 @@ When QA bounce count >= 3 OR Architect bounce count >= 3:
 - **If returned to Refinement:** The spec has been rewritten. You MUST reset the QA and Architect bounce counters to 0 for this story.
 - If killed: `git worktree remove`, branch preserved unmerged
 
+### Mid-Sprint Change Requests
+When the user provides input mid-bounce that isn't a direct answer to an agent question (e.g., "this is broken", "change the approach", "I meant X not Y"), the Team Lead MUST triage it before acting.
+
+> See `skills/agent-team/references/mid-sprint-triage.md` for the full triage flow, routing rules, and logging requirements.
+
+**Quick reference — categories:**
+| Category | Route | Bounce Impact |
+|----------|-------|---------------|
+| **Bug** | Hotfix or bug-fix task in current story | No bounce increment |
+| **Spec Clarification** | Update Story spec, continue bounce | No impact |
+| **Scope Change** | Pause, update spec, confirm with user | Resets Dev pass |
+| **Approach Change** | Update §3 Implementation Guide, re-delegate | Resets Dev pass |
+
+Every change request is logged in `sprint-{XX}.md` §4 Execution Log with event type `CR` and reported in Sprint Report §2.1.
+
 ### Mid-Sprint Strategic Changes
 Charter and Roadmap are typically **frozen** during active sprints. However, if an emergency requires modifying them:
 1. You MUST pause active bouncing across all stories.
@@ -470,7 +495,7 @@ If merging story branch into sprint branch creates conflicts:
 - **Reports are the only handoff.** No agent communicates with another directly.
 - **One bounce = one report.** Every agent pass produces exactly one report file.
 - **Archive before remove.** Always copy reports to shared archive before removing a worktree.
-- **Sync the Delivery Plan.** Update V-Bounce state at EVERY transition. The Delivery Plan is the source of truth.
+- **Sync the Sprint Plan.** Update V-Bounce State in sprint-{XX}.md §1 at EVERY transition. The Sprint Plan is the source of truth DURING the sprint. The Delivery Plan is updated at sprint boundaries only — see `skills/agent-team/references/delivery-sync.md`.
 - **Track bounce counts.** QA and Architect bounces are tracked separately per story.
 - **Git tracking rules.** `.worktrees/`, `.bounce/reports/`, and `.bounce/sprint-report.md` are gitignored (ephemeral). `.bounce/archive/` is **committed to git** (permanent audit trail).
 - **Check risks before bouncing.** Read RISK_REGISTRY.md at sprint start. Flag high-severity risks that affect planned stories.

package/skills/agent-team/references/cleanup.md

@@ -0,0 +1,42 @@
+# Cleanup & Archive Rules
+
+> On-demand reference from agent-team/SKILL.md. Read during sprint close or when archiving.
+
+## After Each Story Completes (DevOps Step 5)
+
+1. Archive all reports to `.bounce/archive/S-{XX}/STORY-{ID}-{StoryName}/`
+2. Merge story branch into sprint branch (--no-ff)
+3. Validate tests/build on sprint branch
+4. Remove worktree: `git worktree remove .worktrees/STORY-{ID}-{StoryName}`
+5. Delete story branch: `git branch -d story/STORY-{ID}-{StoryName}`
+6. Write DevOps Merge Report to `.bounce/archive/S-{XX}/STORY-{ID}-{StoryName}/`
+
+## After Sprint Completes (DevOps Step 7)
+
+1. Merge sprint branch into main (--no-ff)
+2. Tag release: `git tag -a v{VERSION}`
+3. Run full validation (tests + build + lint)
+4. Delete sprint branch: `git branch -d sprint/S-{XX}`
+5. Verify `.worktrees/` is empty
+6. Write Sprint Release Report to `.bounce/archive/S-{XX}/sprint-S-{XX}-devops.md`
+7. Lead archives Sprint Plan: `mv product_plans/sprints/sprint-{XX}/ product_plans/archive/sprints/sprint-{XX}/`
+8. Lead archives sprint report: `mv .bounce/sprint-report-S-{XX}.md .bounce/archive/S-{XX}/`
+9. Run: `vbounce trends && vbounce suggest S-{XX}` — generates improvement recommendations
+
+## Retention Policy
+
+| Location | Status | Rule |
+|----------|--------|------|
+| `.bounce/archive/` | **Committed to git** | Permanent audit trail — never delete |
+| `.bounce/reports/` | **Gitignored** | Active working files only — ephemeral |
+| `.bounce/sprint-report-S-{XX}.md` | **Gitignored** | Active sprint report — archived on close |
+| `.bounce/sprint-context-*.md` | **Gitignored** | Regenerated each session |
+| `.worktrees/` | **Gitignored** | Ephemeral — exists only during active bouncing |
+| `product_plans/archive/` | **Committed** | Completed deliveries with all docs |
+
+## After Delivery Completes (Team Lead)
+
+1. Verify all stories in delivery are "Done" in Delivery Plan §4
+2. Move delivery folder: `mv product_plans/D-{NN}_{name}/ product_plans/archive/D-{NN}_{name}/`
+3. Add Delivery Log entry to Roadmap §7
+4. Update Roadmap §2 Release Plan: status → "Delivered"

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/*` |

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
@@ -54,9 +54,13 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 - {e.g., "STORY-001-03-email_notifications — Escalated (template integration failed 3x)"}
 
 ### Product Docs Affected
-> Any product documentation files modified, created, or identified for updates. Handed off to Scribe agent.
+> Auto-populated from staleness detection (`vbounce docs check S-{XX}`). Shows which vdocs were impacted by this sprint's code changes. Scribe agent receives a targeted task from `.bounce/scribe-task-S-{XX}.md`.
 
-- {e.g., "vdocs/api_reference.md — Added rate limiting details"}
+| Doc | Stale Key Files | Touched By | Priority | Scribe Action |
+|-----|----------------|------------|----------|---------------|
+| {e.g., `AUTHENTICATION_DOC.md`} | {e.g., `src/auth/index.ts`} | {e.g., `STORY-001-02`} | {HIGH/MEDIUM/LOW} | {Update / Quality Fix / New} |
+
+> If no `vdocs/_manifest.json` exists, write "N/A — vdoc not installed".
 
 ---
 
@@ -72,6 +76,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`.