@sandrinio/vbounce 1.4.0 → 1.6.0

package/skills/agent-team/SKILL.md

@@ -41,9 +41,9 @@ Every story gets its own worktree. This isolates code changes so a failed fix on
 ```
 main                                    ← production
 └── sprint/S-01                         ← sprint branch (cut from main)
-    ├── story/STORY-001-01              ← story branch (worktree)
-    ├── story/STORY-001-02              ← story branch (worktree)
-    └── story/STORY-001-03              ← story branch (worktree)
+    ├── story/STORY-001-01-login        ← story branch (worktree)
+    ├── story/STORY-001-02-auth         ← story branch (worktree)
+    └── story/STORY-001-03-api          ← story branch (worktree)
 ```
 
 ### Directory Layout
@@ -51,12 +51,12 @@ main                                    ← production
 ```
 repo/                                   ← main working directory
 ├── .worktrees/                         ← worktree root (GITIGNORED)
-│   ├── STORY-001-01/                   ← isolated worktree for story
+│   ├── STORY-001-01-login/             ← isolated worktree for story
 │   │   ├── (full codebase checkout)
 │   │   └── .bounce/                    ← reports live here during bounce
 │   │       ├── tasks/
 │   │       └── reports/
-│   └── STORY-001-02/
+│   └── STORY-001-02-auth/
 │       └── ...
 │
 └── .bounce/
@@ -74,8 +74,8 @@ repo/                                   ← main working directory
 | V-Bounce State | Git Operation |
 |---------------|---------------|
 | Sprint starts | `git checkout -b sprint/S-01 main` |
-| Ready to Bounce | `git worktree add .worktrees/STORY-{ID} -b story/STORY-{ID} sprint/S-01` |
-| Bouncing | All work happens inside `.worktrees/STORY-{ID}/` |
+| Ready to Bounce | `git worktree add .worktrees/STORY-{ID}-{StoryName} -b story/STORY-{ID}-{StoryName} sprint/S-01` |
+| Bouncing | All work happens inside `.worktrees/STORY-{ID}-{StoryName}/` |
 | Done | Merge story branch → sprint branch, `git worktree remove` |
 | Sprint Review → Done | Merge sprint branch → main |
 | Escalated | Worktree kept but frozen (no new commits) |
@@ -88,19 +88,19 @@ repo/                                   ← main working directory
 git checkout -b sprint/S-01 main
 
 # Create worktree for a story
-git worktree add .worktrees/STORY-001-01 -b story/STORY-001-01 sprint/S-01
-mkdir -p .worktrees/STORY-001-01/.bounce/{tasks,reports}
+git worktree add .worktrees/STORY-001-01-login -b story/STORY-001-01-login sprint/S-01
+mkdir -p .worktrees/STORY-001-01-login/.bounce/{tasks,reports}
 
 # List active worktrees
 git worktree list
 
 # Merge completed story into sprint branch
 git checkout sprint/S-01
-git merge story/STORY-001-01 --no-ff -m "Merge STORY-001-01: {Story Name}"
+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
-git branch -d story/STORY-001-01
+git worktree remove .worktrees/STORY-001-01-login
+git branch -d story/STORY-001-01-login
 
 # Merge sprint into main
 git checkout main
@@ -117,16 +117,16 @@ The Team Lead spawns agents using Claude Code's Task tool. Each subagent works i
 
 **Critical:** Always set the working directory to the worktree when delegating:
 ```
-Lead: "Use the developer subagent. Working directory: .worktrees/STORY-001-01/
-       Read the story spec at product_plans/{delivery}/EPIC-001_{name}/STORY-001-01.md
+Lead: "Use the developer subagent. Working directory: .worktrees/STORY-001-01-login/
+       Read the story spec at product_plans/sprints/sprint-{XX}/STORY-001-01-login.md
        and implement it.
-       Write the implementation report to .bounce/reports/STORY-001-01-dev.md"
+       Write the implementation report to .bounce/reports/STORY-001-01-login-dev.md"
 ```
 
 **Parallel delegation (independent stories in separate worktrees):**
 ```
-Lead: "Use the developer subagent in .worktrees/STORY-001-01/"
-      AND "Use the developer subagent in .worktrees/STORY-001-02/"
+Lead: "Use the developer subagent in .worktrees/STORY-001-01-login/"
+      AND "Use the developer subagent in .worktrees/STORY-001-02-auth/"
       (safe — each worktree is fully isolated)
 ```
 
@@ -141,7 +141,7 @@ For sustained parallel coordination with inter-agent messaging. Enable with `CLA
 
 For tools without native subagent support (Cursor, Codex, Gemini, Antigravity):
 
-1. Lead writes a task file to `.worktrees/STORY-{ID}/.bounce/tasks/STORY-{ID}-{agent}.md`
+1. Lead writes a task file to `.worktrees/STORY-{ID}-{StoryName}/.bounce/tasks/STORY-{ID}-{StoryName}-{agent}.md`
 2. Open the worktree directory in the target tool (Cursor, Antigravity, etc.)
 3. Agent reads the task file, executes, writes report to `.bounce/reports/`
 4. Lead monitors reports from the main repo
@@ -150,9 +150,9 @@ For tools without native subagent support (Cursor, Codex, Gemini, Antigravity):
 
 ## The Report Buffer (Hybrid Model)
 
-**During bounce:** Reports live INSIDE the story's worktree at `.worktrees/STORY-{ID}/.bounce/reports/`. This keeps reports co-located with the code they describe.
+**During bounce:** Reports live INSIDE the story's worktree at `.worktrees/STORY-{ID}-{StoryName}/.bounce/reports/`. This keeps reports co-located with the code they describe.
 
-**After story completes:** Reports are archived to the shared `.bounce/archive/S-{XX}/STORY-{ID}/` in the main repo before the worktree is removed.
+**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).
 
@@ -161,13 +161,13 @@ For tools without native subagent support (Cursor, Codex, Gemini, Antigravity):
 `STORY-{EpicID}-{StoryID}-{agent}[-bounce{N}].md`
 
 Examples:
-- `STORY-001-01-dev.md` — first Dev report
-- `STORY-001-01-qa-bounce1.md` — first QA report (found bugs)
-- `STORY-001-01-dev-bounce2.md` — Dev's fix after QA bounce
-- `STORY-001-01-qa-bounce2.md` — second QA report (passed)
-- `STORY-001-01-arch.md` — Architect audit
-- `STORY-001-01-devops.md` — DevOps merge report
-- `STORY-001-01-conflict.md` — Spec conflict (if any)
+- `STORY-001-01-login-dev.md` — first Dev report
+- `STORY-001-01-login-qa-bounce1.md` — first QA report (found bugs)
+- `STORY-001-01-login-dev-bounce2.md` — Dev's fix after QA bounce
+- `STORY-001-01-login-qa-bounce2.md` — second QA report (passed)
+- `STORY-001-01-login-arch.md` — Architect audit
+- `STORY-001-01-login-devops.md` — DevOps merge report
+- `STORY-001-01-login-conflict.md` — Spec conflict (if any)
 - `sprint-S-01-devops.md` — Sprint release report
 - `sprint-S-01-scribe.md` — Documentation generation report
 
@@ -184,11 +184,11 @@ Examples:
 2. Read RISK_REGISTRY.md — check for open risks relevant to this sprint's stories.
    If high-severity risks affect planned stories, flag to human before proceeding.
 
-3. Read DELIVERY_PLAN.md — check §5 Open Questions.
+3. Read sprint-{XX}.md — check §2 Sprint Open Questions.
    If unresolved questions block stories in this sprint, flag to human.
    Do NOT start bouncing stories with unresolved blocking questions.
 
-4. If product_documentation/_manifest.json exists, read it.
+4. If vdocs/_manifest.json exists, read it.
    Understand what's already documented — this informs which stories
    may require doc updates after the sprint.
 
@@ -201,33 +201,44 @@ Examples:
    e. DevOps runs `hotfix_manager.sh sync` to update any active story worktrees.
    f. Update Delivery Plan Status to "Done".
 
-6. **Parallel Readiness Check** (before bouncing multiple stories simultaneously):
+6. **Gate Config Check**:
+   - If `.bounce/gate-checks.json` does not exist, run `./scripts/init_gate_config.sh` to auto-detect the project stack and generate default gate checks.
+   - If it exists, verify it's current (stack detection may have changed).
+
+7. **Parallel Readiness Check** (before bouncing multiple stories simultaneously):
    - Verify test runner config excludes `.worktrees/` (vitest, jest, pytest, etc.)
    - Verify no shared mutable state between worktrees (e.g., shared temp files, singletons writing to same path)
    - Verify `.gitignore` includes `.worktrees/`
    If any check fails, fix before spawning parallel stories. Intermittent test failures from worktree cross-contamination erode trust in the test suite fast.
 
-7. Update DELIVERY_PLAN.md: Sprint Status → "Active"
+8. **Dependency Check & Execution Mode**:
+   - For each story, check the `Depends On:` field in its template.
+   - If Story B depends on Story A, you MUST execute them sequentially. Do not create Story B's worktree or spawn its Developer until Story A has successfully passed the DevOps merge step.
+   - Determine Execution Mode:
+     - **Full Bounce (Default)**: Normal L2-L4 stories go through full Dev → QA → Architect → DevOps flow.
+     - **Fast Track (L1/L2 Minor)**: For cosmetic UI tweaks or isolated refactors, execute Dev → DevOps only. Skip QA and Architect loops to save overhead. Validate manually during Sprint Review.
+     
+9. Update sprint-{XX}.md: Status → "Active"
 ```
 
 ### Step 1: Story Initialization
 For each story with V-Bounce State "Ready to Bounce":
 ```bash
 # Create isolated worktree
-git worktree add .worktrees/STORY-{ID} -b story/STORY-{ID} sprint/S-01
-mkdir -p .worktrees/STORY-{ID}/.bounce/{tasks,reports}
+git worktree add .worktrees/STORY-{ID}-{StoryName} -b story/STORY-{ID}-{StoryName} sprint/S-01
+mkdir -p .worktrees/STORY-{ID}-{StoryName}/.bounce/{tasks,reports}
 ```
 - Read the full Story spec
 - Read LESSONS.md
 - Check RISK_REGISTRY.md for risks tagged to this story or its Epic
-- If `product_documentation/_manifest.json` exists, identify docs relevant to this story's scope (match against manifest descriptions/tags). Include relevant doc references in the task file so the Developer has product context.
+- If `vdocs/_manifest.json` exists, identify docs relevant to this story's scope (match against manifest descriptions/tags). Include relevant doc references in the task file so the Developer has product context.
 - **Adjacent implementation check:** For stories that modify or extend modules touched by earlier stories in this sprint, identify existing implementations the Developer should reuse. Add to the task file: `"Reuse these existing modules: {list with file paths and brief description of what each provides}"`. This prevents agents from independently re-implementing logic that already exists — a common source of duplication when stories run in parallel.
-- Create task file in `.worktrees/STORY-{ID}/.bounce/tasks/`
-- Update DELIVERY_PLAN.md: V-Bounce State → "Bouncing"
+- Create task file in `.worktrees/STORY-{ID}-{StoryName}/.bounce/tasks/`
+- Update sprint-{XX}.md: V-Bounce State → "Bouncing"
 
 ### Step 2: Developer Pass
 ```
-1. Spawn developer subagent in .worktrees/STORY-{ID}/ with:
+1. Spawn developer subagent in .worktrees/STORY-{ID}-{StoryName}/ with:
    - Story §1 The Spec + §3 Implementation Guide
    - LESSONS.md
    - Relevant react-best-practices rules
@@ -238,13 +249,20 @@ mkdir -p .worktrees/STORY-{ID}/.bounce/{tasks,reports}
 
 ### Step 3: QA Pass
 ```
-1. Spawn qa subagent in .worktrees/STORY-{ID}/ with:
+0. Run pre-QA gate scan:
+   ./scripts/pre_gate_runner.sh qa .worktrees/STORY-{ID}-{StoryName}/ sprint/S-{XX}
+   - If scan FAILS on trivial issues (debug statements, missing JSDoc, TODOs):
+     Return to Developer for quick fix. Do NOT spawn QA for mechanical failures.
+   - If scan PASSES: Include scan output path in the QA task file.
+1. Spawn qa subagent in .worktrees/STORY-{ID}-{StoryName}/ with:
    - Developer Implementation Report
+   - Pre-QA scan results (.bounce/reports/pre-qa-scan.txt)
    - Story §2 The Truth (acceptance criteria)
    - LESSONS.md
 2. QA validates against Gherkin scenarios, runs vibe-code-review
+   (skipping checks already covered by pre-qa-scan.txt)
 3. If FAIL:
-   - QA writes Bug Report (STORY-{ID}-qa-bounce{N}.md)
+   - QA writes Bug Report (STORY-{ID}-{StoryName}-qa-bounce{N}.md)
    - Increment bounce counter
    - If QA bounce count >= 3 → V-Bounce State → "Escalated", STOP
    - Else → Return to Step 2 with Bug Report as input
@@ -255,8 +273,14 @@ mkdir -p .worktrees/STORY-{ID}/.bounce/{tasks,reports}
 
 ### Step 4: Architect Pass
 ```
-1. Spawn architect subagent in .worktrees/STORY-{ID}/ with:
+0. Run pre-Architect gate scan:
+   ./scripts/pre_gate_runner.sh arch .worktrees/STORY-{ID}-{StoryName}/ sprint/S-{XX}
+   - If scan reveals new dependencies or structural violations:
+     Return to Developer for resolution. Do NOT spawn Architect for mechanical failures.
+   - If scan PASSES: Include scan output path in the Architect task file.
+1. Spawn architect subagent in .worktrees/STORY-{ID}-{StoryName}/ with:
    - All reports for this story
+   - Pre-Architect scan results (.bounce/reports/pre-arch-scan.txt)
    - Full Story spec + Roadmap §3 ADRs
    - LESSONS.md
 2. If FAIL:
@@ -265,6 +289,8 @@ mkdir -p .worktrees/STORY-{ID}/.bounce/{tasks,reports}
    - Else → Return to Step 2 with Architect feedback as input
 3. If PASS:
    - V-Bounce State → "Architect Passed"
+
+*(Note: If the Team Lead assigned this story to the "Fast Track" execution mode, skip Steps 3 and 4 entirely. The Developer passes directly to Step 5: DevOps Story Merge.)*
 ```
 
 ### Step 5: Story Merge (DevOps)
@@ -275,17 +301,17 @@ mkdir -p .worktrees/STORY-{ID}/.bounce/{tasks,reports}
    - LESSONS.md
 2. DevOps performs:
    - Pre-merge checks (worktree clean, gate reports verified)
-   - Archive reports to .bounce/archive/S-{XX}/STORY-{ID}/
+   - Archive reports to .bounce/archive/S-{XX}/STORY-{ID}-{StoryName}/
    - Merge story branch into sprint branch (--no-ff)
-   - Post-merge validation (tests + build on sprint branch)
+   - Post-merge validation (tests + lint + build on sprint branch)
    - Worktree removal and story branch cleanup
-3. DevOps writes Merge Report to .bounce/archive/S-{XX}/STORY-{ID}/STORY-{ID}-devops.md
+3. DevOps writes Merge Report to .bounce/archive/S-{XX}/STORY-{ID}-{StoryName}/STORY-{ID}-{StoryName}-devops.md
 4. If merge conflicts:
    - Simple (imports, whitespace): DevOps resolves directly
    - Complex (logic): DevOps writes Conflict Report, Lead creates fix story
 5. If post-merge tests fail: DevOps reverts merge, reports failure to Lead
 ```
-Update DELIVERY_PLAN.md: V-Bounce State → "Done"
+Update sprint-{XX}.md: V-Bounce State → "Done"
 
 ### Step 6: Sprint Integration Audit
 After ALL stories are merged into `sprint/S-01`:
@@ -300,8 +326,15 @@ After ALL stories are merged into `sprint/S-01`:
 ### Step 7: Sprint Consolidation
 ```
 1. Read all archived reports in .bounce/archive/S-{XX}/
-2. Generate Sprint Report to .bounce/sprint-report.md
-3. V-Bounce State → "Sprint Review" for all stories
+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:
+   - Ensure the Sprint Report starts with a YAML frontmatter block containing:
+     ```yaml
+     ---
+     total_tokens_used: {sum of all agent tokens}
+     ---
+     ```
+4. V-Bounce State → "Sprint Review" for all stories
 4. Present Sprint Report to human
 5. **BLOCKING STEP — Lesson Approval:**
    Review and approve/reject ALL flagged lessons from §4 of the Sprint Report.
@@ -318,11 +351,17 @@ After ALL stories are merged into `sprint/S-01`:
 6. Lead finalizes:
    - Move sprint-report.md to .bounce/archive/S-{XX}/
    - Record lessons (with user approval)
-   - Update DELIVERY_PLAN.md
-7. Product Documentation check (runs on `main` after sprint merge):
+   - Update delivery_plan.md to reflect the completed sprint.
+7. **Framework Self-Assessment** (aggregated from agent reports):
+   - Collect all `## Process Feedback` sections from agent reports in `.bounce/archive/S-{XX}/`
+   - Populate §5 Framework Self-Assessment tables in the Sprint Report by category
+   - If this is the 2nd or 3rd consecutive sprint, or if any Blocker-severity findings exist:
+     - 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
-     product_documentation/
+     vdocs/
    - If user approves → spawn scribe subagent on `main` branch with:
      - Sprint Report (what was built)
      - Dev reports that flagged affected product docs
@@ -338,11 +377,11 @@ After ALL stories are merged into `sprint/S-01`:
 ## Cleanup Process
 
 ### After Each Story Completes (DevOps handles via Step 5)
-1. Archive reports to `.bounce/archive/S-{XX}/STORY-{ID}/`
+1. Archive 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}`
-5. Delete story branch: `git branch -d story/STORY-{ID}`
+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
 
 ### After Sprint Completes (DevOps handles via Step 7)
@@ -352,7 +391,7 @@ After ALL stories are merged into `sprint/S-01`:
 4. Delete sprint branch: `git branch -d sprint/S-{XX}`
 5. Verify `.worktrees/` is empty (all worktrees removed)
 6. Write Sprint Release Report
-7. Lead updates DELIVERY_PLAN.md: move sprint to §6 Completed Sprints
+7. Lead archives the sprint folder to `archive/` according to doc-manager physical move rules.
 
 ### After Delivery Completes (Team Lead handles)
 When ALL sprints in a delivery (release) are done:
@@ -377,19 +416,19 @@ When ALL sprints in a delivery (release) are done:
 
 ---
 
-## Delivery Plan Sync
+## Sprint Plan Sync
 
-The Team Lead MUST update DELIVERY_PLAN.md at every state transition. This is the source of truth.
+The Team Lead MUST update the active `sprint-{XX}.md` at every state transition. This is the source of truth for execution.
 
-| Action | Delivery Plan Update |
+| Action | Sprint Plan Update |
 |--------|---------------------|
-| Worktree created | §3 Active Sprint: V-Bounce State → "Bouncing" |
+| Worktree created | §1 Active Scope: V-Bounce State → "Bouncing" |
 | Dev report written | No update (still "Bouncing") |
-| QA passes | §3 Active Sprint: V-Bounce State → "QA Passed" |
-| Architect passes | §3 Active Sprint: V-Bounce State → "Architect Passed" |
-| DevOps merges story | §3 Active Sprint: V-Bounce State → "Done" |
-| Escalated | §4 Backlog → Escalated table |
-| DevOps merges sprint | §6 Completed Sprints: add summary row |
+| 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 |
 
 ---
 
@@ -398,19 +437,23 @@ The Team Lead MUST update DELIVERY_PLAN.md at every state transition. This is th
 ### Spec Conflict
 Developer writes a Spec Conflict Report. Lead pauses the bounce:
 - Remove worktree (preserve branch for reference)
-- Return story to Refinement in DELIVERY_PLAN.md
+- Return story to Refinement in sprint-{XX}.md and copy it back to backlog/
 - After spec is fixed, recreate worktree and restart bounce
 
 ### Escalated Stories
 When QA bounce count >= 3 OR Architect bounce count >= 3:
 - Worktree is kept but frozen (no new work)
-- Lead writes Escalation Report to `.bounce/archive/S-{XX}/STORY-{ID}/escalation.md`
+- Lead writes Escalation Report to `.bounce/archive/S-{XX}/STORY-{ID}-{StoryName}/escalation.md`
 - Human decides: rewrite spec → Refinement, descope → split, kill → Parking Lot
 - **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 Charter Changes
-Charter and Roadmap are **frozen** during active sprints. Changes queued in `CHANGE_QUEUE.md`, applied at sprint boundaries. Critical risks trigger Emergency Sprint Review.
+### 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.
+2. Delegate to doc-manager to run the **Sprint Impact Analysis Protocol**.
+3. Evaluate the active stories in `sprint-{XX}.md` against the new strategy to determine if they are: Unaffected, Require Scope Adjustment, or Invalidated.
+4. Only abort stories that are explicitly Invalidated by the human. Unaffected stories may resume bouncing.
 
 ### Merge Conflicts
 If merging story branch into sprint branch creates conflicts:
@@ -422,6 +465,7 @@ If merging story branch into sprint branch creates conflicts:
 ## Critical Rules
 
 - **The Lead never writes code.** It plans, delegates, monitors, and consolidates.
+- **Enforce Sequential Dependencies.** Never parallelize stories where one depends on the other. Wait for merge.
 - **One story = one worktree.** Never mix stories in a single worktree.
 - **Reports are the only handoff.** No agent communicates with another directly.
 - **One bounce = one report.** Every agent pass produces exactly one report file.
@@ -430,8 +474,8 @@ If merging story branch into sprint branch creates conflicts:
 - **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.
-- **Resolve open questions first.** Read DELIVERY_PLAN.md §5 Open Questions at sprint start. Do not bounce stories with unresolved blocking questions.
-- **Know what's documented.** If `product_documentation/_manifest.json` exists, read it at sprint start. Pass relevant doc references to agents. Offer documentation updates after sprints that deliver new features.
+- **Resolve open questions first.** Read the active `sprint-{XX}.md` §2 Sprint Open Questions at sprint start. Do not bounce stories with unresolved blocking questions.
+- **Know what's documented.** If `vdocs/_manifest.json` exists, read it at sprint start. Pass relevant doc references to agents. Offer documentation updates after sprints that deliver new features.
 
 ## Keywords
 

package/skills/doc-manager/SKILL.md

@@ -69,48 +69,55 @@ Risk Registry ←── ALL levels (cross-cutting input)
 
 | Document | Template Path | Output Location |
 |----------|---------------|-----------------|
-| Charter | `templates/charter.md` | `product_plans/{project}_charter.md` |
-| Roadmap | `templates/roadmap.md` | `product_plans/{project}_roadmap.md` |
-| Risk Registry | `templates/risk_registry.md` | `product_plans/RISK_REGISTRY.md` |
-| Delivery Plan | `templates/delivery_plan.md` | `product_plans/{delivery}/DELIVERY_PLAN.md` |
-| Epic | `templates/epic.md` | `product_plans/{delivery}/EPIC-{NNN}_{name}/EPIC-{NNN}.md` |
-| Story | `templates/story.md` | `product_plans/{delivery}/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}.md` |
-| Hotfix | `templates/hotfix.md` | `product_plans/{delivery}/HOTFIX-{Date}-{Name}.md` |
-| Sprint Report | `templates/sprint_report.md` | `.bounce/sprint-report.md` (archived after sprint) |
-
-### Product Plans Folder Structure
+| Charter | `templates/charter.md` | `product_plans/strategy/{project}_charter.md` |
+| Roadmap | `templates/roadmap.md` | `product_plans/strategy/{project}_roadmap.md` |
+| Risk Registry | `templates/risk_registry.md` | `product_plans/strategy/RISK_REGISTRY.md` |
+| Delivery Plan | `templates/delivery_plan.md` | `product_plans/strategy/{delivery}_delivery_plan.md` |
+| Sprint Plan | `templates/sprint.md` | `product_plans/sprints/sprint-{XX}/sprint-{XX}.md` |
+| Epic | `templates/epic.md` | `product_plans/backlog/EPIC-{NNN}_{name}/EPIC-{NNN}_{name}.md` |
+| Story | `templates/story.md` | `product_plans/backlog/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}-{StoryName}.md` |
+| Hotfix | `templates/hotfix.md` | `product_plans/hotfixes/HOTFIX-{Date}-{Name}.md` |
+| Sprint Report | `templates/sprint_report.md` | `product_plans/sprints/sprint-{XX}/sprint-report.md` |
+
+### Product Plans Folder Structure (State-Based)
 
 ```
 product_plans/
-├── {project}_charter.md                 ← project-level (root)
-├── {project}_roadmap.md                 ← project-level (root)
-├── RISK_REGISTRY.md                     ← project-level (root)
+├── strategy/                      ← high-level, frozen during sprints
+│   ├── charter.md
+│   ├── roadmap.md
+│   ├── delivery_plan.md           ← release timelines
+│   └── risk_registry.md
+│
+├── backlog/                       ← planned but NOT active
+│   ├── EPIC-001_authentication/
+│   │   ├── EPIC-001_authentication.md
+│   │   ├── STORY-001-01-login_ui.md
+│   │   └── STORY-001-02-auth_api.md
 │
-├── D-01_{release_name}/                 ← delivery folder (1 per release)
-│   ├── DELIVERY_PLAN.md                 ← at delivery root
-│   ├── EPIC-001_{epic_name}/            ← epic folder
-│   │   ├── EPIC-001.md                  ← epic document
-│   │   ├── STORY-001-01.md              ← stories live with their epic
-│   │   └── STORY-001-02.md
-│   └── EPIC-002_{epic_name}/
-│       ├── EPIC-002.md
-│       └── STORY-002-01.md
+├── sprints/                       ← active execution workspace
+│   ├── sprint-01/                 ← active sprint boundary
+│   │   ├── sprint-01.md           ← Sprint Plan
+│   │   └── STORY-001-01-login_ui.md       ← (moved here during sprint setup)
 │
-├── D-02_{release_name}/                 ← next delivery
-│   ├── DELIVERY_PLAN.md
-│   └── ...
+├── hotfixes/                      ← emergency tasks bypassing sprints
+│   └── HOTFIX-20260306-db_crash.md
 │
-└── archive/                             ← completed deliveries
-    └── D-01_{release_name}/             ← whole folder moved here
+└── archive/                       ← immutable history
+    ├── sprints/
+    │   └── sprint-01/             ← (whole sprint folder moved here when closed)
+    │       ├── sprint-01.md
+    │       ├── STORY-001-01-login_ui.md
+    │       └── sprint-report.md   
+    └── epics/
+        └── EPIC-001_authentication/       ← (moved here only when 100% complete)
 ```
 
 **Key rules:**
-- Charter, Roadmap, Risk Registry live at `product_plans/` root (project-level, shared across deliveries)
-- Each delivery (= Roadmap Release) gets a folder: `D-{NN}_{release_name}/`
-- Each Epic gets a subfolder named `EPIC-{NNN}_{epic_name}/`
-- Stories live inside their parent Epic's folder — a Story never exists without an Epic
-- Delivery Plan lives at the root of its delivery folder
-- When a delivery completes: Team Lead moves the entire delivery folder to `product_plans/archive/` and adds a Delivery Log entry to the Roadmap (§7)
+- `strategy/` documents are project-level and frozen while a sprint is active.
+- `backlog/` contains Epics and their unassigned child Stories.
+- `sprints/` contains active 1-week execution boundaries. A Story file physically moves here when a sprint begins.
+- `archive/` is where finished Sprints and finished Epics are moved for permanent record keeping.
 
 ### V-Bounce OS Framework Structure
 
@@ -170,7 +177,8 @@ Before creating any document, YOU MUST:
 
 When modifying a document:
 
-1. **Sprint Freeze Check:** Read `DELIVERY_PLAN.md`. If a sprint is currently Active, the Charter and Roadmap are **FROZEN**. DO NOT modify them directly. Instead, append the requested change to `CHANGE_QUEUE.md` at the project root.
+1. **Sprint Freeze Check:** Read `sprint-XX.md` (if one exists in `product_plans/sprints/`). If a sprint is currently Active, the Charter and Roadmap are **FROZEN**. DO NOT modify them directly. 
+   - ***Emergency Impact Analysis Protocol:*** If a human insists on modifying a frozen strategic document mid-sprint, you MUST pause active bouncing and write a Sprint Impact Analysis Report. Evaluate the active stories in `sprint-{XX}.md` against the new strategy to determine if they are: Unaffected, Require Scope Adjustment, or Invalidated. Only Invalidated stories are aborted. Update the documents only after the human approves the Impact Analysis.
 2. Read the document being modified
 3. Read upstream documents if the change affects inherited fields
 4. Make the change
@@ -203,7 +211,7 @@ When modifying a document:
    - Pull §3 Implementation Guide from Epic §4 Technical Context
    - Set Complexity Label (L1-L4) based on file count and pattern familiarity
 4. Link all created Stories back in Epic §9 Artifact Links
-5. Update Delivery Plan §4 Backlog with new stories
+5. Update Delivery Plan §3 High-Level Backlog with new stories
 
 ### TRANSITION — Moving Documents Between Phases
 
@@ -217,6 +225,12 @@ When modifying a document:
 | Story → Ready to Bounce | Ambiguity 🟢 + ALL Context Pack items checked (Delivery Plan §5) |
 | Hotfix → Bouncing | Complexity strictly L1 + Targets 1-2 files |
 
+**Physical Move Rules for State Transitions:**
+
+- **Sprint Setup Phase**: The Team Lead physically MOVES the `STORY-XXX.md` file from `product_plans/backlog/EPIC-XXX/` to `product_plans/sprints/sprint-{XX}/`. 
+- **Sprint Closure Phase**: The Team Lead physically MOVES the entire sprint folder (`sprints/sprint-{XX}/`) to `product_plans/archive/sprints/sprint-{XX}/`. 
+- **Epic Closure**: Once every story attached to an Epic has been archived, the Epic folder itself is moved from `backlog/` to `archive/epics/`.
+
 **V-Bounce State transitions for Stories:**
 
 ```
@@ -249,19 +263,19 @@ Bouncing → Done: Dev implements + Human manually verifies + DevOps runs `hotfi
 | **Scribe** | Product documentation, _manifest.json | Sprint Report, Dev Reports, codebase |
 | **PM/BA (Human)** | Charter, Roadmap, Epic, Story §1 + §2 | Everything |
 
-## Delivery Archiving
+## Sprint Archiving
 
-When a delivery (release) is complete:
+When a sprint is complete:
 
-1. Team Lead moves the entire delivery folder to `product_plans/archive/`:
+1. Team Lead moves the entire sprint folder to the archive:
+   ```bash
+   mv product_plans/sprints/sprint-{XX}/ product_plans/archive/sprints/sprint-{XX}/
+   ```
+2. Team Lead checks the parent Epics of the completed stories. If an Epic is now 100% complete (all its stories are in the archive), the Team Lead moves the Epic folder:
    ```bash
-   mv product_plans/D-01_foundation/ product_plans/archive/D-01_foundation/
+   mv product_plans/backlog/EPIC-{NNN}_{name}/ product_plans/archive/epics/EPIC-{NNN}_{name}/
    ```
-2. Team Lead adds a **Delivery Log** entry to Roadmap §7 with:
-   - Delivery ID, date, release tag
-   - Release Notes (summary of sprint reports from this delivery)
-   - Key metrics (stories delivered, bounce ratio, correction tax averages)
-3. Update Roadmap §2 Release Plan: set the release status to "Delivered"
+3. Team Lead updates the Epic tracking checklists to reflect the newly archived states.
 
 ## Critical Rules