vbounce-engine 2.5.1

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

@@ -0,0 +1,97 @@
+# Discovery Phase — Spike Execution Protocol
+
+> On-demand reference from agent-team/SKILL.md. When and how to run discovery spikes for ambiguous work.
+
+## When Discovery Triggers
+
+1. **Epic-level 🔴 ambiguity** — detected during Epic creation or review via the doc-manager ambiguity assessment rubric.
+2. **Story labeled L4** — transitioning to Probing/Spiking state. L4 stories MUST have at least one linked spike before they can progress.
+3. **Blocking Open Questions** — Epic §8 has items marked "Blocking" with no ADR or prior decision.
+
+## Spike Lifecycle
+
+```
+Open → Investigating → Findings Ready → Validated → Closed
+```
+
+| Status | Who Acts | What Happens |
+|--------|----------|-------------|
+| **Open** | Team Lead | Spike created from `.vbounce/templates/spike.md`, linked in Epic §9 |
+| **Investigating** | Developer | Code exploration, prototyping, benchmarks. Fills §4 Findings and §5 Decision |
+| **Findings Ready** | Developer → Architect | Developer marks complete. Awaiting Architect validation |
+| **Validated** | Architect | Confirms findings against Safe Zone and ADRs. PASS → Validated. FAIL → back to Investigating |
+| **Closed** | Team Lead | All §7 Affected Documents checked off. Findings propagated to Epic, Roadmap, Risk Registry |
+
+## Execution Protocol
+
+### Step 1: Create Spike (Team Lead)
+
+1. Identify the blocking unknown (from Epic §8 Open Questions or 🔴 ambiguity signals)
+2. Create spike document from `.vbounce/templates/spike.md`
+3. Fill §1 Question, §2 Constraints, §3 Approach
+4. Set status → Open
+5. Link spike in parent Epic §9 Artifact Links
+6. Set time box (default: 4 hours for focused questions, 1 day for broader exploration)
+
+### Step 2: Investigate (Developer)
+
+1. Read the spike §1 Question, §2 Constraints, §3 Approach
+2. Read parent Epic §4 Technical Context for existing knowledge
+3. Investigate using the specified approach (code exploration, prototyping, benchmarks, doc research)
+4. Fill §4 Findings with evidence and data
+5. Fill §5 Decision with chosen approach, rationale, and rejected alternatives
+6. Mark §5 ADR Required if the decision is architectural
+7. Fill §6 Residual Risk if unknowns remain
+8. Set status → Findings Ready
+
+### Step 3: Validate (Architect)
+
+1. Read the spike §4 Findings and §5 Decision
+2. Validate against:
+   - Safe Zone compliance (no unauthorized patterns or libraries)
+   - Existing ADRs in Roadmap §3 (no contradictions)
+   - Risk profile (§6 Residual Risk is acceptable)
+3. If **PASS** → status → Validated
+4. If **FAIL** → provide specific feedback, status remains Findings Ready, Developer re-investigates
+
+### Step 4: Close & Propagate (Team Lead)
+
+1. Walk through §7 Affected Documents checklist:
+   - Update Epic §4 Technical Context with findings
+   - Mark Epic §8 Open Questions as resolved
+   - Add spike reference to Epic §9 Artifact Links
+   - If §5 ADR Required → create new ADR row in Roadmap §3
+   - If §6 Residual Risk has entries → add to Risk Registry §1
+   - If story-level spike → update Story §3 Implementation Guide
+2. Check off all items in §7
+3. Set status → Closed
+4. Parent story transitions: Probing/Spiking → Refinement
+
+## Timing Rules
+
+- Spikes happen during **planning/refinement**, NOT during sprint execution
+- No worktrees needed — spikes produce documents, not code
+- Time box is enforced — if the time box expires without findings, the spike is escalated to the human with a status report
+- Prototypes created during spikes are **throwaway** — they are NOT committed to any branch
+
+## What Spikes Are NOT
+
+- **Not production code.** Spikes produce findings and decisions, not shippable code.
+- **Not QA/DevOps passes.** No bounce sequence, no gate reports, no merge operations.
+- **Not a worktree activity.** Spikes are document-level work, not branch-level work.
+- **Not open-ended research.** Every spike has a time box and a specific question. If the question is too broad, split into multiple spikes.
+
+## Integration with Bounce Sequence
+
+Spikes gate the transition from Probing/Spiking → Refinement → Ready to Bounce:
+
+```
+Story (L4 / 🔴) → Probing/Spiking
+  └── Spike(s) created
+      └── Developer investigates → Architect validates → Team Lead propagates
+          └── All spikes Validated/Closed
+              └── Story ambiguity updated (should now be 🟡 or 🟢)
+                  └── Story → Refinement → Ready to Bounce
+```
+
+No story may enter Ready to Bounce while it has linked spikes in Open, Investigating, or Findings Ready status.

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/.vbounce/{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,85 @@
+# Mid-Sprint 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 | Template |
+|----------|-----------|---------|----------|
+| **Bug** | Something built (or pre-existing) is broken | "Login crashes when email has a plus sign" | `.vbounce/templates/bug.md` (or `.vbounce/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" | `.vbounce/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" | `.vbounce/templates/change_request.md` |
+
+### How to Decide
+
+```
+Is existing behavior broken?
+  YES → Bug
+    Is it L1 (1-2 files, trivial)? → Hotfix Path (.vbounce/templates/hotfix.md)
+    Is it larger? → Bug Report (.vbounce/templates/bug.md) → fix task in current sprint
+  NO  → Is the user adding/removing/changing a requirement?
+          YES → Scope Change (.vbounce/templates/change_request.md)
+          NO  → Is the user correcting an ambiguity in the spec?
+                  YES → Spec Clarification (update story inline, no template)
+                  NO  → Approach Change (.vbounce/templates/change_request.md)
+```
+
+## Step 2 — Route
+
+| 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 triage event MUST be logged in the Sprint Plan `sprint-{XX}.md` §4 Execution Log:
+
+```
+| {Story or N/A} | {Category} | 0 | 0 | — | CR: {One-line description} |
+```
+
+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 triage events:
+
+| 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, 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 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/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/.vbounce/reports/` |
+| QA FAIL (first bounce) | `STORY-001-01-login-qa-bounce1.md` | `.worktrees/STORY-001-01-login/.vbounce/reports/` |
+| Dev fix (second pass) | `STORY-001-01-login-dev-bounce2.md` | `.worktrees/STORY-001-01-login/.vbounce/reports/` |
+| QA PASS | `STORY-001-01-login-qa-bounce2.md` | `.worktrees/STORY-001-01-login/.vbounce/reports/` |
+| Architect | `STORY-001-01-login-arch.md` | `.worktrees/STORY-001-01-login/.vbounce/reports/` |
+| DevOps merge | `STORY-001-01-login-devops.md` | `.vbounce/archive/S-{XX}/STORY-001-01-login/` |
+
+## Sprint-Level Files
+
+| Report | Filename | Location |
+|--------|----------|----------|
+| Sprint DevOps | `sprint-S-{XX}-devops.md` | `.vbounce/archive/S-{XX}/` |
+| Sprint Scribe | `sprint-S-{XX}-scribe.md` | `.vbounce/archive/S-{XX}/` |
+| Sprint Report (active) | `sprint-report-S-{XX}.md` | `.vbounce/` (gitignored) |
+| Sprint Report (archived) | `sprint-report-S-{XX}.md` | `.vbounce/archive/S-{XX}/` (committed) |
+| Sprint Context Pack | `sprint-context-S-{XX}.md` | `.vbounce/` (gitignored) |
+| Sprint Summary | `sprint-summary-S-{XX}.md` | `.vbounce/` (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)