@sandrinio/vbounce 1.8.0 → 2.0.0

package/scripts/suggest_improvements.mjs

@@ -2,7 +2,11 @@
 
 /**
  * suggest_improvements.mjs
- * Generates improvement suggestions from sprint trends + lessons.
+ * Generates human-readable improvement suggestions from:
+ *   1. Improvement manifest (post_sprint_improve.mjs output)
+ *   2. Sprint trends
+ *   3. LESSONS.md
+ *
  * Overwrites (not appends) to prevent stale suggestion accumulation.
  *
  * Usage:
@@ -14,6 +18,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -26,41 +31,76 @@ if (!sprintId) {
 
 const today = new Date().toISOString().split('T')[0];
 
-// 1. Read trends if available
+// ---------------------------------------------------------------------------
+// 0. Run post_sprint_improve.mjs to generate fresh manifest
+// ---------------------------------------------------------------------------
+
+const analyzerScript = path.join(__dirname, 'post_sprint_improve.mjs');
+if (fs.existsSync(analyzerScript)) {
+  console.log('Running post-sprint improvement analyzer...');
+  const result = spawnSync(process.execPath, [analyzerScript, sprintId], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+  if (result.status !== 0) {
+    console.warn('⚠ Analyzer returned non-zero — continuing with available data.');
+  }
+  console.log('');
+}
+
+// ---------------------------------------------------------------------------
+// 1. Read improvement manifest (from post_sprint_improve.mjs)
+// ---------------------------------------------------------------------------
+
+const manifestPath = path.join(ROOT, '.bounce', 'improvement-manifest.json');
+let manifest = null;
+if (fs.existsSync(manifestPath)) {
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    console.warn('⚠ Could not parse improvement-manifest.json');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Read trends if available
+// ---------------------------------------------------------------------------
+
 const trendsFile = path.join(ROOT, '.bounce', 'trends.md');
 let trendsContent = null;
 if (fs.existsSync(trendsFile)) {
   trendsContent = fs.readFileSync(trendsFile, 'utf8');
 }
 
-// 2. Read LESSONS.md
+// ---------------------------------------------------------------------------
+// 3. Read LESSONS.md
+// ---------------------------------------------------------------------------
+
 const lessonsFile = path.join(ROOT, 'LESSONS.md');
 let lessonCount = 0;
 let oldLessons = [];
 if (fs.existsSync(lessonsFile)) {
   const lines = fs.readFileSync(lessonsFile, 'utf8').split('\n');
-  // Count lessons by counting ### entries
   const lessonEntries = lines.filter(l => /^###\s+\[\d{4}-\d{2}-\d{2}\]/.test(l));
   lessonCount = lessonEntries.length;
 
-  // Flag lessons older than 90 days
   const cutoff = new Date();
   cutoff.setDate(cutoff.getDate() - 90);
   oldLessons = lessonEntries.filter(entry => {
     const dateMatch = entry.match(/\[(\d{4}-\d{2}-\d{2})\]/);
-    if (dateMatch) {
-      return new Date(dateMatch[1]) < cutoff;
-    }
+    if (dateMatch) return new Date(dateMatch[1]) < cutoff;
     return false;
   });
 }
 
-// 3. Read improvement-log for rejected items (to avoid re-suggesting)
+// ---------------------------------------------------------------------------
+// 4. Read improvement-log for rejected items
+// ---------------------------------------------------------------------------
+
 const improvementLog = path.join(ROOT, '.bounce', 'improvement-log.md');
 let rejectedItems = [];
 if (fs.existsSync(improvementLog)) {
   const logContent = fs.readFileSync(improvementLog, 'utf8');
-  // Simple extraction: look for table rows in "Rejected" section
   const rejectedMatch = logContent.match(/## Rejected\n[\s\S]*?(?=\n## |$)/);
   if (rejectedMatch) {
     rejectedItems = rejectedMatch[0].split('\n')
@@ -70,7 +110,10 @@ if (fs.existsSync(improvementLog)) {
   }
 }
 
-// 4. Parse sprint stats from trends
+// ---------------------------------------------------------------------------
+// 5. Parse sprint stats from trends
+// ---------------------------------------------------------------------------
+
 let lastSprintStats = null;
 if (trendsContent) {
   const rows = trendsContent.split('\n').filter(l => l.match(/^\| S-\d{2} \|/));
@@ -86,18 +129,90 @@ if (trendsContent) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// 6. Build suggestions
+// ---------------------------------------------------------------------------
+
 const suggestions = [];
 let itemNum = 1;
 
-// 5. Generate suggestions based on data
+// Impact level badge
+function badge(impact) {
+  const badges = {
+    P0: '🔴 P0 Critical',
+    P1: '🟠 P1 High',
+    P2: '🟡 P2 Medium',
+    P3: '⚪ P3 Low',
+  };
+  return badges[impact?.level] || '⚪ Unrated';
+}
+
+// --- Manifest-driven suggestions (retro + lessons + effectiveness) ---
+if (manifest && manifest.proposals) {
+  for (const proposal of manifest.proposals) {
+    // Skip previously rejected
+    if (rejectedItems.some(r => proposal.title.includes(r))) continue;
+
+    if (proposal.source === 'retro') {
+      suggestions.push({
+        num: itemNum++,
+        category: 'Retro',
+        impact: proposal.impact,
+        title: proposal.title,
+        detail: [
+          `**Area:** ${proposal.area}`,
+          `**Source Agent:** ${proposal.sourceAgent}`,
+          `**Severity:** ${proposal.severity}`,
+          proposal.recurring ? `**Recurring:** Yes — found in ${proposal.recurrenceSprints.join(', ')} (${proposal.recurrenceCount}x)` : null,
+          `**Suggested Fix:** ${proposal.suggestedFix}`,
+        ].filter(Boolean).join('\n'),
+        target: mapAreaToTarget(proposal.area),
+        effort: proposal.severity === 'Blocker' ? 'Medium' : 'Low',
+      });
+    } else if (proposal.source === 'lesson') {
+      suggestions.push({
+        num: itemNum++,
+        category: 'Lesson → Automation',
+        impact: proposal.impact,
+        title: proposal.title,
+        detail: [
+          `**Rule:** ${proposal.rule}`,
+          `**What happened:** ${proposal.whatHappened}`,
+          `**Active for:** ${proposal.ageSprints} sprint(s) (since ${proposal.lessonDate})`,
+          `**Automation type:** ${proposal.automationType}`,
+          `**Action:** ${proposal.automationDetail?.action}`,
+          `**Rationale:** ${proposal.automationDetail?.rationale}`,
+        ].filter(Boolean).join('\n'),
+        target: mapAutomationTypeToTarget(proposal.automationType),
+        effort: proposal.automationDetail?.effort || 'Low',
+      });
+    } else if (proposal.source === 'effectiveness_check') {
+      suggestions.push({
+        num: itemNum++,
+        category: 'Effectiveness',
+        impact: proposal.impact,
+        title: proposal.title,
+        detail: [
+          `**Status:** ${proposal.detail}`,
+          `**Originally applied in:** ${proposal.appliedInSprint}`,
+          '**Action:** Re-examine the original fix — it did not resolve the underlying issue.',
+        ].join('\n'),
+        target: 'Review original improvement in .bounce/improvement-log.md',
+        effort: 'Medium',
+      });
+    }
+  }
+}
+
+// --- Metric-driven suggestions (from trends) ---
 if (lastSprintStats) {
   if (lastSprintStats.firstPassRate < 80) {
     suggestions.push({
       num: itemNum++,
-      category: 'Process',
+      category: 'Metrics',
+      impact: { level: 'P1', label: 'High' },
       title: `Low first-pass rate (${lastSprintStats.firstPassRate}%)`,
       detail: `First-pass rate was below 80% in ${lastSprintStats.sprintId}. This suggests spec ambiguity or insufficient context packs.`,
-      recommendation: 'Add spec quality gate to `validate_bounce_readiness.mjs`: check Story §1 word count > 50 and §2 has ≥ 2 Gherkin scenarios.',
       target: 'scripts/validate_bounce_readiness.mjs',
       effort: 'Low',
     });
@@ -106,10 +221,10 @@ if (lastSprintStats) {
   if (lastSprintStats.avgTax > 10) {
     suggestions.push({
       num: itemNum++,
-      category: 'Process',
+      category: 'Metrics',
+      impact: { level: 'P1', label: 'High' },
       title: `High correction tax (${lastSprintStats.avgTax}% average)`,
-      detail: 'Average correction tax exceeded 10%, indicating significant human intervention was needed.',
-      recommendation: 'Auto-flag stories with more than 3 files expected in Sprint Plan §2 Risk Flags. Consider splitting before bouncing.',
+      detail: 'Average correction tax exceeded 10%, indicating significant human intervention.',
       target: 'skills/agent-team/SKILL.md Step 1',
       effort: 'Low',
     });
@@ -118,70 +233,117 @@ if (lastSprintStats) {
   if (lastSprintStats.avgBounces > 0.5) {
     suggestions.push({
       num: itemNum++,
-      category: 'Process',
+      category: 'Metrics',
+      impact: { level: 'P2', label: 'Medium' },
       title: `High bounce rate (${lastSprintStats.avgBounces} avg per story)`,
-      detail: 'Run `vbounce trends` to see root cause breakdown and identify recurring patterns.',
-      recommendation: 'Review root_cause field in archived QA/Arch FAIL reports to identify systemic issues.',
+      detail: 'Run `vbounce trends` to see root cause breakdown.',
       target: 'scripts/sprint_trends.mjs',
       effort: 'Low',
     });
   }
 }
 
-// Old lessons suggestion
+// --- Lesson graduation ---
 if (oldLessons.length > 0) {
   const notRejected = oldLessons.filter(l => !rejectedItems.some(r => l.includes(r)));
   if (notRejected.length > 0) {
     suggestions.push({
       num: itemNum++,
-      category: 'Framework',
-      title: `${notRejected.length} lessons older than 90 days`,
+      category: 'Graduation',
+      impact: { level: 'P2', label: 'Medium' },
+      title: `${notRejected.length} lesson(s) older than 90 days — graduation candidates`,
       detail: notRejected.map(l => `  - ${l}`).join('\n'),
-      recommendation: 'Review these lessons. Lessons not triggered in 3+ sprints should be archived to LESSONS_ARCHIVE.md. Lessons proven over 3+ sprints should be graduated to agent configs.',
-      target: 'LESSONS.md',
-      effort: 'Trivial',
+      target: 'LESSONS.md → brains/claude-agents/',
+      effort: 'Low',
     });
   }
 }
 
-// General framework suggestions
-suggestions.push({
-  num: itemNum++,
-  category: 'Framework',
-  title: 'Review lesson graduation candidates',
-  detail: `You have ${lessonCount} lessons in LESSONS.md. Lessons proven over 3+ sprints should graduate to permanent agent config rules.`,
-  recommendation: 'Run a review: which lessons have prevented recurrences for 3+ sprints? Graduate those to `.claude/agents/*.md` or `brains/claude-agents/*.md`.',
-  target: 'LESSONS.md + brains/claude-agents/',
-  effort: 'Low',
-});
-
+// --- Health check ---
 suggestions.push({
   num: itemNum++,
   category: 'Health',
+  impact: { level: 'P3', label: 'Low' },
   title: 'Run vbounce doctor',
-  detail: 'Verify the V-Bounce OS installation is healthy after this sprint.',
-  recommendation: 'Run: `vbounce doctor` — checks brain files, templates, scripts, state.json validity.',
+  detail: 'Verify the V-Bounce Engine installation is healthy after this sprint.',
   target: 'scripts/doctor.mjs',
   effort: 'Trivial',
 });
 
-// 6. Format output
+// ---------------------------------------------------------------------------
+// 7. Format output
+// ---------------------------------------------------------------------------
+
+function mapAreaToTarget(area) {
+  const map = {
+    'Templates': 'templates/*.md',
+    'Agent Handoffs': 'brains/claude-agents/*.md',
+    'RAG Pipeline': 'scripts/prep_*.mjs',
+    'Skills': 'skills/*/SKILL.md',
+    'Process Flow': 'skills/agent-team/SKILL.md',
+    'Tooling & Scripts': 'scripts/*',
+  };
+  return map[area] || area;
+}
+
+function mapAutomationTypeToTarget(type) {
+  const map = {
+    'gate_check': '.bounce/gate-checks.json OR scripts/pre_gate_runner.sh',
+    'script': 'scripts/',
+    'template_field': 'templates/*.md',
+    'agent_config': 'brains/claude-agents/*.md',
+  };
+  return map[type] || type;
+}
+
 const suggestionBlocks = suggestions.map(s => {
-  const rejectedNote = rejectedItems.some(r => s.title.includes(r)) ? '\n> ⚠ This was previously rejected — skipping.' : '';
-  return `### ${s.num}. [${s.category}] ${s.title}${rejectedNote}
+  return `### ${s.num}. [${badge(s.impact)}] [${s.category}] ${s.title}
 ${s.detail}
 
-**Recommendation:** ${s.recommendation}
 **Target:** \`${s.target}\`
 **Effort:** ${s.effort}`;
 }).join('\n\n---\n\n');
 
+// Impact level reference
+const impactRef = `## Impact Levels
+
+| Level | Label | Meaning | Timeline |
+|-------|-------|---------|----------|
+| **P0** | 🔴 Critical | Blocks agent work or causes incorrect output | Fix before next sprint |
+| **P1** | 🟠 High | Causes rework — bounces, wasted tokens, repeated manual steps | Fix this improvement cycle |
+| **P2** | 🟡 Medium | Friction that slows agents but does not block | Fix within 2 sprints |
+| **P3** | ⚪ Low | Polish — nice-to-have, batch with other improvements | Batch when convenient |`;
+
+// Summary stats
+const summarySection = manifest ? `## Summary
+
+| Source | Count |
+|--------|-------|
+| Retro (§5 findings) | ${manifest.summary.bySource.retro} |
+| Lesson → Automation | ${manifest.summary.bySource.lesson} |
+| Effectiveness checks | ${manifest.summary.bySource.effectiveness_check} |
+| Metric-driven | ${suggestions.filter(s => s.category === 'Metrics').length} |
+| **Total** | **${suggestions.length}** |
+
+| Impact | Count |
+|--------|-------|
+| 🔴 P0 Critical | ${manifest.summary.byImpact.P0} |
+| 🟠 P1 High | ${manifest.summary.byImpact.P1 + suggestions.filter(s => s.category === 'Metrics' && s.impact.level === 'P1').length} |
+| 🟡 P2 Medium | ${manifest.summary.byImpact.P2 + suggestions.filter(s => s.category === 'Metrics' && s.impact.level === 'P2').length} |
+| ⚪ P3 Low | ${manifest.summary.byImpact.P3 + suggestions.filter(s => s.category === 'Health').length} |` : '';
+
 const output = [
   `# Improvement Suggestions (post ${sprintId})`,
   `> Generated: ${today}. Review each item. Approved items are applied by the Lead at sprint boundary.`,
   `> Rejected items go to \`.bounce/improvement-log.md\` with reason.`,
   `> Applied items go to \`.bounce/improvement-log.md\` under Applied.`,
   '',
+  impactRef,
+  '',
+  summarySection,
+  '',
+  '---',
+  '',
   suggestionBlocks || '_No suggestions generated — all metrics look healthy!_',
   '',
   '---',
@@ -192,9 +354,10 @@ const output = [
   `- **Defer** → Record in \`.bounce/improvement-log.md\` under Deferred`,
   '',
   `> Framework changes (brains/, skills/, templates/) are applied at sprint boundaries only — never mid-sprint.`,
+  `> Use \`/improve\` skill to have the Team Lead apply approved changes with brain-file sync.`,
 ].join('\n');
 
 const outputFile = path.join(ROOT, '.bounce', 'improvement-suggestions.md');
-fs.writeFileSync(outputFile, output); // overwrite, not append
+fs.writeFileSync(outputFile, output);
 console.log(`✓ Improvement suggestions written to .bounce/improvement-suggestions.md`);
 console.log(`  ${suggestions.length} suggestion(s) generated`);

package/scripts/validate_report.mjs

@@ -3,7 +3,7 @@
 /**
  * validate_report.mjs
  * 
- * Strict YAML Frontmatter validation for V-Bounce OS Agent Reports.
+ * Strict YAML Frontmatter validation for V-Bounce Engine Agent Reports.
  * Fails loudly if an agent hallucinates formatting or omits required fields,
  * so the orchestrator can bounce the prompt back.
  */

package/scripts/verify_framework.mjs

@@ -63,7 +63,7 @@ const EXPECTED_PROMPT_SIGNATURES = {
 
 function main() {
     console.log("===========================================");
-    console.log(" V-Bounce OS: Framework Integrity Check");
+    console.log(" V-Bounce Engine: Framework Integrity Check");
     console.log("===========================================\n");
 
     let hasErrors = false;

package/skills/agent-team/SKILL.md

@@ -176,24 +176,25 @@ Examples:
 ## The Bounce Sequence
 
 ### Step 0: Sprint Setup
+
+**Prerequisite:** Sprint Planning (Phase 2) must be complete. The Sprint Plan must be in "Confirmed" status with human approval before proceeding.
+
 ```
 1. Cut sprint branch from main:
    git checkout -b sprint/S-01 main
    mkdir -p .bounce/archive
 
-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 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.
+2. Verify Sprint Plan:
+   - Sprint Plan status must be "Confirmed" (human-approved in Phase 2)
+   - §0 Sprint Readiness Gate must be fully checked
+   - §3 Sprint Open Questions must have no unresolved blocking items
+   If any check fails, return to Phase 2 (Sprint Planning).
 
-4. If vdocs/_manifest.json exists, read it.
+3. If vdocs/_manifest.json exists, read it.
    Understand what's already documented — this informs which stories
    may require doc updates after the sprint.
 
-5. Triage Requests: If an incoming task is an L1 Trivial change (1-2 files),
-   use the **Hotfix Path**:
+4. **Hotfix Path** (L1 Trivial tasks only — triaged during Phase 1):
    a. Create `HOTFIX-{Date}-{Name}.md` using the template.
    b. Delegate to Developer (no worktree needed if acting on active branch).
    c. Developer runs `hotfix_manager.sh ledger "{Title}" "{Description}"` after implementation.
@@ -201,26 +202,35 @@ Examples:
    e. DevOps runs `hotfix_manager.sh sync` to update any active story worktrees.
    f. Update Delivery Plan Status to "Done".
 
-6. **Gate Config Check**:
+5. **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):
+6. **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.
 
-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"
+7. Update sprint-{XX}.md: Status → "Active"
 ```
 
+**Note:** Risk assessment, dependency checks, scope selection, and execution mode decisions all happen during Sprint Planning (Phase 2), not here. Step 0 executes the confirmed plan.
+
+### Step 0.5: Discovery Check (L4 / 🔴 Stories Only)
+
+Before moving any story to Ready to Bounce:
+
+1. For each story with `complexity_label: L4` or `ambiguity: 🔴 High`:
+   - Check for linked spikes in `product_plans/backlog/EPIC-{NNN}_{name}/SPIKE-*.md`
+   - If no spikes exist → create them (invoke doc-manager ambiguity rubric)
+   - If spikes exist but are not Validated/Closed → execute discovery sub-flow
+   - See `skills/agent-team/references/discovery.md`
+
+2. Once all spikes are Validated/Closed:
+   - Update story `ambiguity` frontmatter (should now be 🟡 or 🟢)
+   - Transition: Probing/Spiking → Refinement → Ready to Bounce
+
 ### Step 1: Story Initialization
 For each story with V-Bounce State "Ready to Bounce":
 ```bash
@@ -313,6 +323,18 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.bounce/{tasks,reports}
 ```
 Update sprint-{XX}.md: V-Bounce State → "Done"
 
+### Step 5.5: Immediate Lesson Recording
+After each story merge, before proceeding to the next story:
+```
+1. Read Dev report — check `lessons_flagged` field
+2. Read QA report — check for lessons flagged during validation
+3. For each flagged lesson:
+   - Present to the human for approval
+   - If approved → record to LESSONS.md immediately (follow lesson skill format)
+   - If rejected → note as "No" in Sprint Report §4
+4. Do NOT defer this to Step 7 — context decays fast
+```
+
 ### Step 6: Sprint Integration Audit
 After ALL stories are merged into `sprint/S-01`:
 ```
@@ -336,12 +358,12 @@ After ALL stories are merged into `sprint/S-01`:
      ```
 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.
-   Do NOT proceed to Sprint Release until every lesson has a status of "Yes" or "No".
-   Stale lessons lose context — approve them while the sprint is fresh.
-   Present each lesson to the human and record approved ones to LESSONS.md immediately.
-6. After approval → Spawn devops subagent for Sprint Release:
+5. **Lesson Review (non-blocking):**
+   Most lessons should already be recorded to LESSONS.md during Step 5.5.
+   Review §4 of the Sprint Report — confirm all flagged lessons have a status.
+   If any lessons were missed during Step 5.5, present them now and record approved ones.
+   This is a review step, not a first-time approval gate.
+6. After review → Spawn devops subagent for Sprint Release:
    - Merge sprint/S-01 → main (--no-ff)
    - Tag release: v{VERSION}
    - Run full test suite + build + lint on main
@@ -501,6 +523,7 @@ If merging story branch into sprint branch creates conflicts:
 - **Check risks before bouncing.** Read RISK_REGISTRY.md at sprint start. Flag high-severity risks that affect planned stories.
 - **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.
+- **Resolve discovery before bouncing.** L4 stories and 🔴 ambiguity stories MUST complete spikes before entering the bounce sequence. See `skills/agent-team/references/discovery.md`.
 
 ## Keywords
 

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 `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 `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.