@sandrinio/vbounce 2.0.0 → 2.1.0

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

@@ -1,4 +1,4 @@
-# Mid-Sprint Change Request Triage
+# Mid-Sprint Triage
 
 > On-demand reference from agent-team/SKILL.md. How the Team Lead handles user interruptions during an active sprint.
 
@@ -15,57 +15,71 @@ Any time the user provides input mid-bounce that is **not** a direct answer to a
 
 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" |
+| Category | Definition | Example | Template |
+|----------|-----------|---------|----------|
+| **Bug** | Something built (or pre-existing) is broken | "Login crashes when email has a plus sign" | `templates/bug.md` (or `templates/hotfix.md` if L1) |
+| **Spec Clarification** | The spec was ambiguous; user is clarifying intent, not changing scope | "By 'admin' I meant workspace admin, not super admin" | No template — update story spec inline |
+| **Scope Change** | User wants to add, remove, or modify requirements for the current story | "Also add a forgot-password flow to the login story" | `templates/change_request.md` |
+| **Approach Change** | Implementation strategy is wrong; needs a different technical path | "Don't use REST for this — wire it through WebSockets instead" | `templates/change_request.md` |
 
 ### How to Decide
 
 ```
 Is existing behavior broken?
   YES → Bug
+    Is it L1 (1-2 files, trivial)? → Hotfix Path (templates/hotfix.md)
+    Is it larger? → Bug Report (templates/bug.md) → fix task in current sprint
   NO  → Is the user adding/removing/changing a requirement?
-          YES → Scope Change
+          YES → Scope Change (templates/change_request.md)
           NO  → Is the user correcting an ambiguity in the spec?
-                  YES → Spec Clarification
-                  NO  → Approach Change (technical direction shift)
+                  YES → Spec Clarification (update story inline, no template)
+                  NO  → Approach Change (templates/change_request.md)
 ```
 
 ## 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. |
+| Category | Action | Bounce Impact | Document Created |
+|----------|--------|---------------|------------------|
+| **Bug (L1)** | Hotfix Path: Dev fixes, human verifies, merge directly | None — does NOT increment bounce count | `product_plans/hotfixes/HOTFIX-{Date}-{Name}.md` |
+| **Bug (L2+)** | Create bug report, add as fix task within current story bounce | None — does NOT increment bounce count | `product_plans/sprints/sprint-{XX}/BUG-{Date}-{Name}.md` |
+| **Spec Clarification** | Update Story spec inline (§1 or §2). Add a note in the Change Log. Continue current bounce. | None | No separate document |
+| **Scope Change** | **Pause bounce.** Create CR document. Present impact to human. Wait for decision. If approved: update Story spec, reset Dev pass. If rejected: continue as-is. If deferred: add to backlog. | Resets Dev pass. Prior QA/Arch invalidated if change affects tested areas. | `product_plans/sprints/sprint-{XX}/CR-{Date}-{Name}.md` |
+| **Approach Change** | Create CR document. Update Story §3 Implementation Guide. Re-delegate to Developer with updated context. | Resets Dev pass. Prior QA/Arch invalidated. | `product_plans/sprints/sprint-{XX}/CR-{Date}-{Name}.md` |
 
 ## Step 3 — Log
 
-Every change request MUST be logged in the Sprint Plan `sprint-{XX}.md` §4 Execution Log:
+Every triage event MUST be logged in the Sprint Plan `sprint-{XX}.md` §4 Execution Log:
 
 ```
-| {timestamp} | CR | {Category} | {STORY-ID} | {One-line description} |
+| {Story or N/A} | {Category} | 0 | 0 | — | CR: {One-line description} |
 ```
 
-Use `CR` as the event type to distinguish from regular bounce events.
+Use the Notes column with `CR:` prefix to distinguish from regular story completions.
+
+## Step 4 — Present to Human
+
+After categorizing, the Team Lead MUST present the triage decision to the human:
+
+1. State the category: "This is a **{Bug / Scope Change / Approach Change / Spec Clarification}**."
+2. For Bugs: state severity and whether it blocks the current story
+3. For Scope/Approach Changes: present the impact assessment from the CR document and ask for decision (Approve / Reject / Defer)
+4. For Spec Clarifications: state what was clarified and confirm with human before updating
 
 ## 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.
+At sprint consolidation (Step 7), the Team Lead includes a **§2.1 Change Requests** section in the Sprint Report summarizing all mid-sprint triage events:
 
-| 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 |
+| Story | Category | Description | Impact | Document |
+|-------|----------|-------------|--------|----------|
+| STORY-{ID} | Bug | Login crash on plus-sign emails | Fixed via hotfix, no bounce reset | HOTFIX-2026-03-22-login-plus |
+| STORY-{ID} | Scope Change | Added forgot-password flow | Dev pass reset, +1 session | CR-2026-03-22-forgot-password |
 
 ## Key Rules
 
-- **Never silently absorb a user change.** Always categorize and log it.
+- **Never silently absorb a user change.** Always categorize, document, 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.
+- **Scope changes require a CR document and human approval.** Always pause, assess impact, and confirm before resuming.
+- **Approach changes require a CR document.** The technical pivot must be recorded for audit trail.
 - **Correction Tax still applies.** Human intervention is tracked, but the category explains *why*.
+- **Everything gets a document or an inline update.** No change goes unrecorded.

package/skills/doc-manager/SKILL.md

@@ -85,6 +85,8 @@ Spike §6 (Residual Risk) ──→ Risk Registry §1 (Active Risks)
 | Story | `templates/story.md` | `product_plans/backlog/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}-{StoryName}.md` |
 | Spike | `templates/spike.md` | `product_plans/backlog/EPIC-{NNN}_{name}/SPIKE-{EpicID}-{NNN}-{topic}.md` |
 | Hotfix | `templates/hotfix.md` | `product_plans/hotfixes/HOTFIX-{Date}-{Name}.md` |
+| Bug Report | `templates/bug.md` | `product_plans/sprints/sprint-{XX}/BUG-{Date}-{Name}.md` |
+| Change Request | `templates/change_request.md` | `product_plans/sprints/sprint-{XX}/CR-{Date}-{Name}.md` |
 | Sprint Report | `templates/sprint_report.md` | `product_plans/sprints/sprint-{XX}/sprint-report.md` |
 
 ### Product Plans Folder Structure (State-Based)
@@ -200,6 +202,24 @@ Before creating any document, YOU MUST:
 4. Fill sections by pulling from upstream sources (see Information Flow above)
 5. Set the Ambiguity Score based on completeness
 6. Verify all cross-references are valid
+7. **Present edge cases and open questions to the human** (see below)
+
+**After creating an Epic — mandatory discussion step:**
+
+After writing the Epic document, you MUST present §6 (Risks & Edge Cases) and §8 (Open Questions) to the human in chat. Do not silently file them — the human needs to see what's uncertain to make good decisions.
+
+Format your presentation like this:
+1. Summarize the epic in 1-2 sentences
+2. List each edge case from §6 with its proposed mitigation — ask the human if the mitigation is adequate or if they see other risks
+3. List each open question from §8 — present the options, explain the impact, and ask the human to decide or delegate
+4. State the current ambiguity score and what must be resolved before decomposition into stories
+
+The epic is NOT ready for decomposition until:
+- All **blocking** questions in §8 are resolved (status = "Decided")
+- All edge cases in §6 have either a decided mitigation or are explicitly accepted as known risk by the human
+- Ambiguity is 🟡 or 🟢
+
+If the human resolves questions during discussion, update the epic document immediately (change §8 status to "Decided", update §6 mitigations, adjust ambiguity score).
 
 **Pre-read requirements by document type:**
 
@@ -242,6 +262,8 @@ When modifying a document:
 | Spike §4/§5 (Findings/Decision) | Epic §4 Technical Context, Epic §8 Open Questions, Risk Registry §1 |
 | Spike §5 (Decision — architectural) | Roadmap §3 ADRs (new row) |
 
+**After any cascade:** Run `vbounce graph` to regenerate the product graph so downstream consumers have current state.
+
 ### DECOMPOSE — Breaking Down Documents
 
 **Epic → Stories:**
@@ -341,7 +363,7 @@ Sprint Planning is a collaborative process between AI and human. No sprint start
 |------------|------|
 | Charter → Ready for Roadmap | Ambiguity 🟡 or 🟢 (§1 and §5 filled) |
 | Roadmap → Ready for Epics | Charter Ambiguity 🟢 + Roadmap §2 and §3 filled |
-| Epic → Ready for Stories | Ambiguity 🟡 or 🟢 (§2 Scope and §4 Tech Context filled) |
+| Epic → Ready for Stories | Ambiguity 🟡 or 🟢 + §2 Scope filled + §4 Tech Context filled + §8 all blocking questions Decided + §6 each edge case has a decided mitigation OR is explicitly accepted as known risk |
 | Story → Ready to Bounce | Ambiguity 🟢 + ALL Context Pack items checked (Sprint Plan §1) |
 | Sprint Plan → Confirmed | §0 Readiness Gate checklist complete + Human explicitly confirms |
 | Sprint Plan → Active | Status is Confirmed (human approval obtained) |
@@ -356,6 +378,13 @@ Sprint Planning is a collaborative process between AI and human. No sprint start
 - **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/`.
 
+**Complexity Labels:**
+
+- **L1**: Trivial — Single file, <1hr, known pattern. → Hotfix Path
+- **L2**: Standard — 2-3 files, known pattern, ~2-4hr. *(default)* → Full Bounce
+- **L3**: Complex — Cross-cutting, spike may be needed, ~1-2 days. → Full Bounce
+- **L4**: Uncertain — Requires spikes before Bounce, >2 days. → Discovery first
+
 **V-Bounce State transitions for Stories:**
 
 ```

package/skills/improve/SKILL.md

@@ -39,9 +39,9 @@ Every improvement proposal is classified by impact to help the human prioritize:
 
 ## When to Use
 
-- **Automatically** — `vbounce sprint close S-XX` runs the improvement pipeline and generates `.bounce/improvement-suggestions.md`
+- **Automatically** — `vbounce sprint close S-XX` runs the improvement pipeline and regenerates `.bounce/improvement-suggestions.md` (overwrites previous — always reflects latest data)
 - **On demand** — `vbounce improve S-XX` runs the full pipeline (trends + analyzer + suggestions)
-- After every 2-3 sprints (recommended cadence for applying approved changes)
+- **Applying changes:** After every 1-3 sprints, human reviews suggestions and runs `/improve` to apply approved ones. The analysis runs every sprint; applying changes is the human's call.
 - When the same Process Feedback appears across multiple sprint reports
 - When the user explicitly asks to improve templates, skills, or process
 - When a sprint's Framework Self-Assessment reveals Blocker-severity findings
@@ -239,7 +239,7 @@ For each approved proposal:
 
 ### Step 7: Validate
 After all changes are applied:
-1. Run `./scripts/pre_bounce_sync.sh` to update RAG embeddings with the new framework content
+1. Run `vbounce doctor` to verify framework integrity
 2. Verify no cross-references are broken (template paths, skill names, report field names)
 3. Confirm brain file consistency — all surfaces should describe the same process
 
@@ -284,7 +284,7 @@ The Team Lead should note in the Sprint Report whether the previous improvement
 - **Never change the framework without human approval.** Propose, don't impose.
 - **Keep all brain surfaces in sync.** A change to CLAUDE.md must be reflected in GEMINI.md, AGENTS.md, and cursor-rules/.
 - **Log everything.** Every change goes in `brains/CHANGELOG.md` with the finding that motivated it.
-- **Run pre_bounce_sync.sh after changes.** Updated skills and rules must be re-indexed for RAG.
+- **Run `vbounce doctor` after changes.** Verify framework integrity after applying improvements.
 - **Don't over-engineer.** Fix the actual problem reported by agents. Don't add speculative improvements.
 - **Respect the hierarchy.** Template changes are low-risk. Process flow changes are high-risk. Scope accordingly.
 - **Skills are living documents.** If a skill's instructions consistently confuse agents, rewrite the confusing section — don't add workarounds elsewhere.

package/skills/product-graph/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: product-graph
+description: "Use when you need to understand document relationships, check what's affected by a change, find blocked documents, or assess the state of planning documents. Provides structured awareness of the full product document graph without reading every file. Auto-loaded during planning sessions."
+---
+
+# Product Graph — Document Relationship Intelligence
+
+## Purpose
+
+This skill gives you instant awareness of all product planning documents and their relationships. Instead of globbing and reading every file in `product_plans/`, you read a single JSON graph that maps every document, its status, and how it connects to other documents.
+
+## Three-Tier Loading Protocol
+
+When you need to understand the product document landscape, load information in tiers — stop at the tier that answers your question:
+
+### Tier 1: Graph JSON (~400-1000 tokens)
+Read `.bounce/product-graph.json` for a bird's-eye view.
+- All document IDs, types, statuses, and paths
+- All edges (dependencies, parent relationships, feeds)
+- **Use when:** answering "what exists?", "what's blocked?", "what depends on X?"
+
+### Tier 2: Specific Frontmatter (~200-500 tokens per doc)
+Read the YAML frontmatter of specific documents identified in Tier 1.
+- Ambiguity scores, priorities, tags, owners, dates
+- **Use when:** you need details about specific documents (not the full set)
+
+### Tier 3: Full Documents (~500-3000 tokens per doc)
+Read the complete document body.
+- Full specs, scope boundaries, acceptance criteria, open questions
+- **Use when:** creating or modifying documents, decomposing epics, or resolving ambiguity
+
+## Edge Type Semantics
+
+| Edge Type | Meaning | Direction |
+|-----------|---------|-----------|
+| `parent` | Document is a child of another (Story → Epic) | parent → child |
+| `depends-on` | Document cannot proceed until dependency is done | dependency → dependent |
+| `unlocks` | Completing this document enables another | source → unlocked |
+| `context-source` | Document draws context from another | source → consumer |
+| `feeds` | Document contributes to a delivery/release | document → delivery |
+
+## When to Regenerate the Graph
+
+Run `vbounce graph` (or `node scripts/product_graph.mjs`) after:
+- **Any document edit** that changes status, dependencies, or relationships
+- **Sprint lifecycle events** (sprint init, story complete, sprint close)
+- **Planning session start** — ensure graph reflects current state
+- **Document creation or archival** — new nodes or removed nodes
+
+The graph is a cache — it's cheap to regenerate and stale data is worse than no data.
+
+## Blocked Document Detection
+
+A document is **blocked** when:
+1. It has incoming `depends-on` edges from documents with status != "Done"/"Implemented"/"Completed"
+2. It has `ambiguity: 🔴 High` and linked spikes are not Validated/Closed
+3. Its parent document has status "Parking Lot" or "Escalated"
+
+To find blocked documents:
+1. Read the graph (Tier 1)
+2. For each node, check its incoming `depends-on` edges
+3. Look up the source node's status
+4. If any source is not in a terminal state → document is blocked
+
+## Impact Analysis
+
+To understand what changes when you modify a document:
+```bash
+vbounce graph impact <DOC-ID>        # human-readable
+vbounce graph impact <DOC-ID> --json # machine-readable
+```
+
+This runs BFS traversal and returns:
+- **Direct dependents** — documents immediately affected
+- **Transitive dependents** — documents affected through cascading dependencies
+- **Upstream feeders** — documents that feed into the changed document
+
+## Graph JSON Schema
+
+```json
+{
+  "generated_at": "ISO-8601 timestamp",
+  "node_count": 5,
+  "edge_count": 12,
+  "nodes": {
+    "EPIC-002": {
+      "type": "epic|story|spike|charter|roadmap|delivery-plan|sprint-plan|risk-registry|hotfix",
+      "status": "Draft|Refinement|Ready to Bounce|Bouncing|Done|Implemented|...",
+      "ambiguity": "🔴 High|🟡 Medium|🟢 Low|null",
+      "path": "product_plans/backlog/EPIC-002_.../EPIC-002_....md",
+      "title": "Human-readable title from first heading"
+    }
+  },
+  "edges": [
+    { "from": "EPIC-002", "to": "D-02", "type": "feeds" }
+  ]
+}
+```
+
+## Keywords
+
+product graph, document graph, dependency, impact analysis, what's affected, what's blocked, document relationships, planning state

package/templates/bug.md

@@ -0,0 +1,90 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. This documents a defect found during or after sprint execution.
+
+1. **YAML Frontmatter**: Bug ID, Status, Severity, Found During, Affected Story, Reporter
+2. **§1 The Bug**: What's broken, reproduction steps, expected vs actual
+3. **§2 Impact**: What's affected, is it blocking?
+4. **§3 Fix Approach**: Proposed fix, affected files, estimated complexity
+5. **§4 Verification**: How to verify the fix
+
+When to use this template:
+- User reports something is broken mid-sprint
+- QA discovers a defect not covered by acceptance criteria
+- Post-sprint manual review finds an issue
+- A previously working feature regresses
+
+Triage rules (from mid-sprint-triage.md):
+- If the bug is L1 (1-2 files, trivial fix) → use templates/hotfix.md instead
+- If the bug is larger → use THIS template, add to current sprint as a fix task
+- Bug fixes do NOT increment QA/Architect bounce counts
+
+Output location: `product_plans/sprints/sprint-{XX}/BUG-{Date}-{Name}.md`
+If no sprint is active: `product_plans/backlog/BUG-{Date}-{Name}.md`
+
+Do NOT output these instructions.
+</instructions>
+
+---
+bug_id: "BUG-{YYYY-MM-DD}-{name}"
+status: "Open / In Progress / Fixed / Wont Fix"
+severity: "Critical / High / Medium / Low"
+found_during: "Sprint S-{XX} / Post-Sprint Review / User Report"
+affected_story: "STORY-{ID} / N/A (pre-existing)"
+reporter: "{human / QA / user}"
+---
+
+# BUG: {Short Description}
+
+## 1. The Bug
+
+**Current Behavior:**
+{What happens — be specific}
+
+**Expected Behavior:**
+{What should happen instead}
+
+**Reproduction Steps:**
+1. {Step 1}
+2. {Step 2}
+3. {Observe: ...}
+
+**Environment:**
+- {Browser/OS/Node version if relevant}
+- {Branch: sprint/S-XX or main}
+
+---
+
+## 2. Impact
+
+- **Blocking?** {Yes — blocks STORY-{ID} / No — cosmetic / degraded}
+- **Affected Areas:** {Which features, pages, or flows}
+- **Users Affected:** {All users / specific persona / edge case only}
+- **Data Impact:** {None / corrupted data / lost data}
+
+---
+
+## 3. Fix Approach
+
+- **Root Cause:** {Why it's broken — if known}
+- **Proposed Fix:** {What to change}
+- **Files to Modify:** `{filepath1}`, `{filepath2}`
+- **Complexity:** {L1 Trivial / L2 Standard / L3 Complex}
+
+> If complexity is L1 → consider using `templates/hotfix.md` instead for faster resolution.
+
+---
+
+## 4. Verification
+
+- [ ] {Reproduction steps no longer reproduce the bug}
+- [ ] {Existing tests still pass}
+- [ ] {New test covers the bug scenario — if applicable}
+- [ ] Run `./scripts/hotfix_manager.sh ledger "BUG: {Name}" "{Brief description}"`
+
+---
+
+## Change Log
+
+| Date | Author | Change |
+|------|--------|--------|
+| {YYYY-MM-DD} | {name} | Created |

package/templates/change_request.md

@@ -0,0 +1,105 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. This documents a scope change or new requirement discovered mid-sprint.
+
+1. **YAML Frontmatter**: CR ID, Status, Category, Urgency, Affected Stories, Requestor
+2. **§1 The Change**: What's being requested and why
+3. **§2 Impact Assessment**: What it affects, what breaks, what gets delayed
+4. **§3 Decision**: Approved action with rationale
+5. **§4 Execution Plan**: How the change will be handled
+
+When to use this template:
+- User requests a new feature or scope expansion mid-sprint
+- User wants to change the technical approach of an active story
+- External dependency change forces a pivot
+- Requirements discovered during implementation that weren't in the original spec
+
+Categories (from mid-sprint-triage.md):
+- **Scope Change**: Adding/removing/modifying requirements → use THIS template
+- **Approach Change**: Different technical path → use THIS template
+- **Spec Clarification**: Just clarifying ambiguity → do NOT use this template (update story spec inline)
+- **Bug**: Something is broken → use templates/bug.md instead
+
+Triage rules:
+- Scope changes PAUSE the active bounce until the human approves
+- Approach changes reset the Dev pass
+- All CRs are logged in Sprint Plan §4 Execution Log with event type "CR"
+- CRs that can't fit in the current sprint go to backlog for next sprint planning
+
+Output location: `product_plans/sprints/sprint-{XX}/CR-{Date}-{Name}.md`
+If no sprint is active: `product_plans/backlog/CR-{Date}-{Name}.md`
+
+Do NOT output these instructions.
+</instructions>
+
+---
+cr_id: "CR-{YYYY-MM-DD}-{name}"
+status: "Open / Approved / Rejected / Deferred"
+category: "Scope Change / Approach Change"
+urgency: "Blocking / This Sprint / Next Sprint"
+affected_stories: ["STORY-{ID}"]
+requestor: "{human / AI / external}"
+---
+
+# CR: {Short Description}
+
+## 1. The Change
+
+**What is being requested:**
+{Describe the change clearly}
+
+**Why:**
+{Business reason, user feedback, technical discovery, external dependency change}
+
+**Original vs Proposed:**
+| Aspect | Original | Proposed |
+|--------|----------|----------|
+| {Scope/Approach/Tech} | {What was planned} | {What's now requested} |
+
+---
+
+## 2. Impact Assessment
+
+**Affected Stories:**
+| Story | Current State | Impact |
+|-------|--------------|--------|
+| STORY-{ID} | {Bouncing / QA Passed / ...} | {Must restart Dev / Spec update only / Blocked} |
+
+**Sprint Impact:**
+- {Does this delay the sprint? By how much?}
+- {Does this invalidate completed work?}
+- {Does this require new stories?}
+
+**Risk:**
+- {What could go wrong if we make this change?}
+- {What could go wrong if we DON'T make this change?}
+
+---
+
+## 3. Decision
+
+> Filled by human after reviewing the impact assessment.
+
+**Decision:** {Approved / Rejected / Deferred to S-{XX}}
+
+**Rationale:** {Why this decision}
+
+**Conditions:** {Any constraints on the approved change}
+
+---
+
+## 4. Execution Plan
+
+> Filled after decision is approved.
+
+- **Stories affected:** {Which stories need spec updates}
+- **New stories needed:** {If any — add to backlog or current sprint}
+- **Bounce impact:** {Which passes reset — Dev only / Dev + QA / full restart}
+- **Timeline:** {Can it fit in current sprint or deferred?}
+
+---
+
+## Change Log
+
+| Date | Author | Change |
+|------|--------|--------|
+| {YYYY-MM-DD} | {name} | Created |

package/templates/sprint.md

@@ -86,16 +86,30 @@ V-Bounce State: Draft / Refinement / Ready to Bounce
 - **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}
+### Execution Mode
+> L1 → Fast Track (Dev → DevOps, skip QA/Arch). L2 → Fast Track only with human approval below. L3/L4 → Full Bounce always.
+
+| Story | Label | Mode | Human Approved? |
+|-------|-------|------|-----------------|
+| STORY-XXX-YY | L2 | Full Bounce / Fast Track | — / Yes |
+
+### Shared File Map
+> Stories touching the same files MUST merge sequentially (first-in wins). Flag these during planning.
+
+| File / Module | Stories Touching It | Merge Order |
+|---------------|--------------------:|-------------|
+| `{src/path/file.ts}` | STORY-A, STORY-B | A before B |
 
 ### Dependency Chain
-> Stories that MUST run sequentially (depends_on relationships).
+> Stories that MUST run sequentially (depends_on OR shared files).
 
 | Story | Depends On | Reason |
 |-------|-----------|--------|
-| STORY-XXX-YY | STORY-XXX-YY | {why sequential} |
+| STORY-XXX-YY | STORY-XXX-YY | {depends_on / shared file / data dependency} |
+
+### Risk Flags
+- {Sprint-specific risks pulled from Risk Registry}
+- {External dependency risks}
 
 ---