@sandrinio/vbounce 1.5.0 → 1.7.0

package/scripts/validate_bounce_readiness.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * validate_bounce_readiness.mjs
+ * Pre-bounce gate check — verifies a story is ready to bounce.
+ *
+ * Usage:
+ *   ./scripts/validate_bounce_readiness.mjs STORY-005-02
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+const storyId = process.argv[2];
+if (!storyId) {
+  console.error('Usage: validate_bounce_readiness.mjs STORY-ID');
+  process.exit(1);
+}
+
+const errors = [];
+const warnings = [];
+
+// 1. Check state.json
+const stateFile = path.join(ROOT, '.bounce', 'state.json');
+if (!fs.existsSync(stateFile)) {
+  errors.push('.bounce/state.json not found — run: vbounce sprint init S-XX D-XX');
+} else {
+  const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  if (!state.stories[storyId]) {
+    errors.push(`Story "${storyId}" not found in state.json`);
+  } else {
+    const story = state.stories[storyId];
+    if (story.state !== 'Ready to Bounce') {
+      errors.push(`Story state is "${story.state}" — must be "Ready to Bounce" before bouncing`);
+    }
+  }
+}
+
+// 2. Find sprint plan
+const sprintsDir = path.join(ROOT, 'product_plans', 'sprints');
+let sprintPlanFound = false;
+if (fs.existsSync(sprintsDir)) {
+  const sprintDirs = fs.readdirSync(sprintsDir);
+  for (const dir of sprintDirs) {
+    const planFile = path.join(sprintsDir, dir, `${dir}.md`);
+    if (fs.existsSync(planFile)) {
+      sprintPlanFound = true;
+      break;
+    }
+  }
+}
+if (!sprintPlanFound) {
+  warnings.push('No active Sprint Plan found in product_plans/sprints/');
+}
+
+// 3. Find story spec
+let storyFile = null;
+function findFile(dir, id) {
+  if (!fs.existsSync(dir)) return null;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      const found = findFile(path.join(dir, e.name), id);
+      if (found) return found;
+    } else if (e.name.includes(id)) {
+      return path.join(dir, e.name);
+    }
+  }
+  return null;
+}
+
+storyFile = findFile(path.join(ROOT, 'product_plans'), storyId);
+if (!storyFile) {
+  errors.push(`Story spec not found for "${storyId}" in product_plans/`);
+} else {
+  const storyContent = fs.readFileSync(storyFile, 'utf8');
+
+  // Check for §1, §2, §3
+  const hasSpec = /##\s*(1\.|§1|The Spec)/i.test(storyContent);
+  const hasCriteria = /##\s*(2\.|§2|The Truth|Acceptance)/i.test(storyContent);
+  const hasGuide = /##\s*(3\.|§3|Implementation)/i.test(storyContent);
+
+  if (!hasSpec) errors.push(`Story ${storyId}: §1 (spec) section not found`);
+  if (!hasCriteria) errors.push(`Story ${storyId}: §2 (acceptance criteria) section not found`);
+  if (!hasGuide) errors.push(`Story ${storyId}: §3 (implementation guide) section not found`);
+
+  // Check for minimum content in each section
+  const specMatch = storyContent.match(/##\s*(1\.|§1|The Spec)[^\n]*\n([\s\S]*?)(?=\n##|\n---|\Z)/i);
+  if (specMatch && specMatch[2].trim().length < 30) {
+    warnings.push(`Story ${storyId}: §1 spec section appears very short — verify it's complete`);
+  }
+}
+
+// 4. Check worktree
+const worktreeDir = path.join(ROOT, '.worktrees', storyId);
+if (!fs.existsSync(worktreeDir)) {
+  warnings.push(`.worktrees/${storyId}/ not found — create with: git worktree add .worktrees/${storyId} -b story/${storyId} sprint/S-XX`);
+}
+
+// Print results
+console.log(`Bounce readiness check: ${storyId}`);
+console.log('');
+
+if (errors.length === 0 && warnings.length === 0) {
+  console.log(`✓ ${storyId} is READY TO BOUNCE`);
+  process.exit(0);
+}
+
+if (warnings.length > 0) {
+  warnings.forEach(w => console.warn(`  ⚠  ${w}`));
+}
+
+if (errors.length > 0) {
+  errors.forEach(e => console.error(`  ✗ ${e}`));
+  console.error(`\nNOT READY: Fix ${errors.length} error(s) before bouncing ${storyId}`);
+  process.exit(1);
+} else {
+  console.log(`  ✓ ${storyId} is ready (with warnings)`);
+  process.exit(0);
+}

package/scripts/validate_report.mjs

@@ -13,15 +13,21 @@ import path from 'path';
 import yaml from 'js-yaml';
 
 // Defined schemas for each report type
+const ROOT_CAUSE_ENUM = [
+    'missing_tests', 'missing_validation', 'spec_ambiguity', 'adr_violation',
+    'gold_plating', 'logic_error', 'integration_gap', 'type_error',
+    'state_management', 'error_handling', 'coupling', 'duplication'
+];
+
 const SCHEMAS = {
     dev: ['status', 'correction_tax', 'tokens_used', 'tests_written', 'files_modified', 'lessons_flagged'],
     qa: {
         base: ['status', 'bounce_count', 'tokens_used', 'bugs_found', 'gold_plating_detected'],
-        conditional: { 'FAIL': ['failed_scenarios'] }
+        conditional: { 'FAIL': ['failed_scenarios', 'root_cause'] }
     },
     arch: {
         base: ['status', 'tokens_used'],
-        conditional: { 'PASS': ['safe_zone_score', 'ai_isms_detected', 'regression_risk'], 'FAIL': ['bounce_count', 'critical_failures'] }
+        conditional: { 'PASS': ['safe_zone_score', 'ai_isms_detected', 'regression_risk'], 'FAIL': ['bounce_count', 'critical_failures', 'root_cause'] }
     },
     devops: {
         base: ['type', 'status', 'tokens_used'],
@@ -45,6 +51,29 @@ function validateDev(data) {
     if (!Array.isArray(data.files_modified)) throw new Error(`DEV_SCHEMA_ERROR: 'files_modified' must be an array.`);
 }
 
+function validateBugsArray(bugs, prefix) {
+    if (!Array.isArray(bugs)) throw new Error(`${prefix}: 'bugs' must be an array.`);
+    bugs.forEach((bug, i) => {
+        const bugRequired = ['scenario', 'expected', 'actual', 'files', 'severity'];
+        const bugMissing = bugRequired.filter(k => !(k in bug));
+        if (bugMissing.length > 0) throw new Error(`${prefix}: bugs[${i}] missing keys: ${bugMissing.join(', ')}`);
+        if (!Array.isArray(bug.files)) throw new Error(`${prefix}: bugs[${i}].files must be an array.`);
+        const validSeverities = ['Critical', 'High', 'Medium', 'Low'];
+        if (!validSeverities.includes(bug.severity)) throw new Error(`${prefix}: bugs[${i}].severity must be one of: ${validSeverities.join(', ')}`);
+    });
+}
+
+function validateFailuresArray(failures, prefix) {
+    if (!Array.isArray(failures)) throw new Error(`${prefix}: 'failures' must be an array.`);
+    const validDimensions = ['Architectural Consistency', 'Error Handling', 'Data Flow', 'Duplication', 'Test Quality', 'Coupling'];
+    failures.forEach((f, i) => {
+        const fRequired = ['dimension', 'severity', 'what_wrong', 'fix_required'];
+        const fMissing = fRequired.filter(k => !(k in f));
+        if (fMissing.length > 0) throw new Error(`${prefix}: failures[${i}] missing keys: ${fMissing.join(', ')}`);
+        if (!validDimensions.includes(f.dimension)) throw new Error(`${prefix}: failures[${i}].dimension must be one of: ${validDimensions.join(', ')}`);
+    });
+}
+
 function validateQA(data) {
     const missing = SCHEMAS.qa.base.filter(k => !(k in data));
     if (missing.length > 0) throw new Error(`QA_SCHEMA_ERROR: Missing required keys: ${missing.join(', ')}`);
@@ -52,6 +81,10 @@ function validateQA(data) {
     if (data.status === 'FAIL') {
         const conditionalMissing = SCHEMAS.qa.conditional.FAIL.filter(k => !(k in data));
         if (conditionalMissing.length > 0) throw new Error(`QA_SCHEMA_ERROR: 'FAIL' status requires keys: ${conditionalMissing.join(', ')}`);
+        if (data.root_cause && !ROOT_CAUSE_ENUM.includes(data.root_cause)) {
+            throw new Error(`QA_SCHEMA_ERROR: Invalid root_cause '${data.root_cause}'. Must be one of: ${ROOT_CAUSE_ENUM.join(', ')}`);
+        }
+        if ('bugs' in data) validateBugsArray(data.bugs, 'QA_SCHEMA_ERROR');
     }
 }
 
@@ -62,6 +95,10 @@ function validateArch(data) {
     const s = data.status === 'PASS' ? 'PASS' : 'FAIL';
     const conditionalMissing = SCHEMAS.arch.conditional[s].filter(k => !(k in data));
     if (conditionalMissing.length > 0) throw new Error(`ARCH_SCHEMA_ERROR: '${s}' status requires keys: ${conditionalMissing.join(', ')}`);
+    if (s === 'FAIL' && data.root_cause && !ROOT_CAUSE_ENUM.includes(data.root_cause)) {
+        throw new Error(`ARCH_SCHEMA_ERROR: Invalid root_cause '${data.root_cause}'. Must be one of: ${ROOT_CAUSE_ENUM.join(', ')}`);
+    }
+    if (s === 'FAIL' && 'failures' in data) validateFailuresArray(data.failures, 'ARCH_SCHEMA_ERROR');
 }
 
 function validateDevops(data) {

package/scripts/validate_sprint_plan.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * validate_sprint_plan.mjs
+ * Validates a Sprint Plan markdown file structure and cross-checks with state.json.
+ *
+ * Usage:
+ *   ./scripts/validate_sprint_plan.mjs product_plans/sprints/sprint-05/sprint-05.md
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+const filePath = process.argv[2];
+if (!filePath) {
+  console.error('Usage: validate_sprint_plan.mjs <path-to-sprint-plan.md>');
+  process.exit(1);
+}
+
+const absPath = path.resolve(filePath);
+if (!fs.existsSync(absPath)) {
+  console.error(`ERROR: File not found: ${absPath}`);
+  process.exit(1);
+}
+
+const content = fs.readFileSync(absPath, 'utf8');
+const errors = [];
+const warnings = [];
+
+// 1. Extract YAML frontmatter
+const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+if (!fmMatch) {
+  errors.push('Missing YAML frontmatter (--- delimiters)');
+} else {
+  let fm;
+  try {
+    fm = yaml.load(fmMatch[1]);
+  } catch (e) {
+    errors.push(`Invalid YAML frontmatter: ${e.message}`);
+    fm = {};
+  }
+
+  const required = ['sprint_id', 'sprint_goal', 'dates', 'status', 'delivery'];
+  for (const f of required) {
+    if (!fm[f]) errors.push(`Frontmatter missing required field: "${f}"`);
+  }
+
+  // 2. Cross-check with state.json
+  const stateFile = path.join(ROOT, '.bounce', 'state.json');
+  if (fs.existsSync(stateFile)) {
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+
+    // Find story IDs in §1 table
+    const tableRowRegex = /\|\s*\d+\s*\|\s*\[?(STORY-[\w-]+)/g;
+    const planStoryIds = new Set();
+    let m;
+    while ((m = tableRowRegex.exec(content)) !== null) {
+      planStoryIds.add(m[1]);
+    }
+
+    const stateStoryIds = new Set(Object.keys(state.stories || {}));
+
+    // Check for stories in plan but not in state
+    for (const id of planStoryIds) {
+      if (!stateStoryIds.has(id)) {
+        warnings.push(`Story ${id} is in Sprint Plan §1 but NOT in state.json`);
+      }
+    }
+
+    // Check for stories in state but not in plan
+    for (const id of stateStoryIds) {
+      if (!planStoryIds.has(id)) {
+        warnings.push(`Story ${id} is in state.json but NOT in Sprint Plan §1`);
+      }
+    }
+  }
+
+  // 3. Check §4 Execution Log if sprint is Completed
+  if (fm.status === 'Completed') {
+    if (!content.includes('<!-- EXECUTION_LOG_START -->') && !content.includes('## 4.') && !content.includes('## §4')) {
+      errors.push('Sprint is Completed but §4 Execution Log section is missing');
+    }
+  }
+}
+
+// 4. Check §1 table columns
+if (!content.includes('| Priority |') && !content.includes('|Priority|')) {
+  errors.push('§1 Active Scope table missing or malformed (expected "Priority" column header)');
+}
+if (!content.includes('V-Bounce State')) {
+  errors.push('§1 Active Scope table missing "V-Bounce State" column');
+}
+
+// Print results
+console.log(`Validating: ${filePath}`);
+if (errors.length === 0 && warnings.length === 0) {
+  console.log('✓ Sprint Plan is valid');
+  process.exit(0);
+}
+
+if (warnings.length > 0) {
+  console.warn('Warnings:');
+  warnings.forEach(w => console.warn(`  ⚠  ${w}`));
+}
+
+if (errors.length > 0) {
+  console.error('Errors:');
+  errors.forEach(e => console.error(`  ✗ ${e}`));
+  process.exit(1);
+} else {
+  process.exit(0);
+}

package/scripts/validate_state.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+/**
+ * validate_state.mjs
+ * Validates .bounce/state.json schema.
+ * Usage: ./scripts/validate_state.mjs
+ * Also exportable: import { validateState } from './validate_state.mjs'
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const STATE_FILE = path.join(ROOT, '.bounce', 'state.json');
+
+const VALID_STATES = [
+  'Draft', 'Refinement', 'Ready to Bounce', 'Bouncing',
+  'QA Passed', 'Architect Passed', 'Done', 'Escalated', 'Parking Lot'
+];
+
+/**
+ * Validates a state object. Returns { valid, errors }.
+ * @param {object} state
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateState(state) {
+  const errors = [];
+
+  if (!state || typeof state !== 'object') {
+    return { valid: false, errors: ['state.json must be a JSON object'] };
+  }
+
+  if (!state.sprint_id || !/^S-\d{2}$/.test(state.sprint_id)) {
+    errors.push(`sprint_id "${state.sprint_id}" must match S-XX format (e.g. S-05)`);
+  }
+
+  if (!state.delivery_id || !/^D-\d{2}$/.test(state.delivery_id)) {
+    errors.push(`delivery_id "${state.delivery_id}" must match D-NN format (e.g. D-02)`);
+  }
+
+  if (!state.stories || typeof state.stories !== 'object') {
+    errors.push('stories field must be an object');
+  } else {
+    for (const [id, story] of Object.entries(state.stories)) {
+      if (!VALID_STATES.includes(story.state)) {
+        errors.push(`Story ${id}: invalid state "${story.state}". Must be one of: ${VALID_STATES.join(', ')}`);
+      }
+      if (typeof story.qa_bounces !== 'number' || !Number.isInteger(story.qa_bounces) || story.qa_bounces < 0) {
+        errors.push(`Story ${id}: qa_bounces must be a non-negative integer, got "${story.qa_bounces}"`);
+      }
+      if (typeof story.arch_bounces !== 'number' || !Number.isInteger(story.arch_bounces) || story.arch_bounces < 0) {
+        errors.push(`Story ${id}: arch_bounces must be a non-negative integer, got "${story.arch_bounces}"`);
+      }
+      if (story.state === 'Done' && story.worktree) {
+        errors.push(`Story ${id}: state is "Done" but worktree "${story.worktree}" is still set (should be null)`);
+      }
+    }
+  }
+
+  if (state.updated_at) {
+    const d = new Date(state.updated_at);
+    if (isNaN(d.getTime())) {
+      errors.push(`updated_at "${state.updated_at}" is not a valid ISO 8601 timestamp`);
+    }
+  } else {
+    errors.push('updated_at field is required');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// CLI entry point
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  if (!fs.existsSync(STATE_FILE)) {
+    console.error(`ERROR: ${STATE_FILE} not found. Run: vbounce sprint init S-XX D-XX`);
+    process.exit(1);
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+  } catch (e) {
+    console.error(`ERROR: state.json is not valid JSON — ${e.message}`);
+    process.exit(1);
+  }
+
+  const { valid, errors } = validateState(state);
+
+  if (valid) {
+    console.log(`VALID: state.json — sprint ${state.sprint_id}, ${Object.keys(state.stories || {}).length} stories`);
+    process.exit(0);
+  } else {
+    console.error('INVALID: state.json has errors:');
+    errors.forEach(e => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+}

package/skills/agent-team/SKILL.md

@@ -61,12 +61,12 @@ repo/                                   ← main working directory
 │
 └── .bounce/
     ├── reports/                        ← active working reports (GITIGNORED)
-    ├── sprint-report.md                ← current sprint report (GITIGNORED)
+    ├── sprint-report-S-{XX}.md          ← current sprint report (GITIGNORED)
     └── archive/                        ← completed sprint history (COMMITTED TO GIT)
         └── S-01/
             ├── STORY-001-01/           ← all agent reports for this story
-            ├── sprint-report.md        ← final sprint report
-            └── sprint-devops.md        ← release report
+            ├── sprint-report-S-{XX}.md  ← final sprint report
+            └── sprint-S-{XX}-devops.md  ← release report
 ```
 
 ### V-Bounce State → Git Operations
@@ -154,7 +154,7 @@ For tools without native subagent support (Cursor, Codex, Gemini, Antigravity):
 
 **After story completes:** Reports are archived to the shared `.bounce/archive/S-{XX}/STORY-{ID}-{StoryName}/` in the main repo before the worktree is removed.
 
-**Sprint Report:** Always written to `.bounce/sprint-report.md` in the main repo (not in any worktree).
+**Sprint Report:** Always written to `.bounce/sprint-report-S-{XX}.md` in the main repo (not in any worktree).
 
 ### Report File Naming
 
@@ -201,20 +201,24 @@ 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. **Dependency Check & Execution Mode**:
+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.
      
-8. Update sprint-{XX}.md: Status → "Active"
+9. Update sprint-{XX}.md: Status → "Active"
 ```
 
 ### Step 1: Story Initialization
@@ -245,11 +249,18 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.bounce/{tasks,reports}
 
 ### Step 3: QA Pass
 ```
+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}-{StoryName}-qa-bounce{N}.md)
    - Increment bounce counter
@@ -262,8 +273,14 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.bounce/{tasks,reports}
 
 ### Step 4: Architect Pass
 ```
+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:
@@ -286,7 +303,7 @@ mkdir -p .worktrees/STORY-{ID}-{StoryName}/.bounce/{tasks,reports}
    - Pre-merge checks (worktree clean, gate reports verified)
    - 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}-{StoryName}/STORY-{ID}-{StoryName}-devops.md
 4. If merge conflicts:
@@ -310,7 +327,7 @@ After ALL stories are merged into `sprint/S-01`:
 ```
 1. Read all archived reports in .bounce/archive/S-{XX}/
 2. **Sum the `tokens_used` field** from every agent report to calculate the sprint's total resource cost.
-3. Generate Sprint Report to .bounce/sprint-report.md:
+3. Generate Sprint Report to .bounce/sprint-report-S-{XX}.md:
    - Ensure the Sprint Report starts with a YAML frontmatter block containing:
      ```yaml
      ---
@@ -330,9 +347,9 @@ After ALL stories are merged into `sprint/S-01`:
    - Run full test suite + build + lint on main
    - Sprint branch cleanup
    - Environment verification (if applicable)
-   - DevOps writes Sprint Release Report to .bounce/archive/S-{XX}/sprint-devops.md
+   - DevOps writes Sprint Release Report to .bounce/archive/S-{XX}/sprint-S-{XX}-devops.md
 6. Lead finalizes:
-   - Move sprint-report.md to .bounce/archive/S-{XX}/
+   - Move sprint-report-S-{XX}.md to .bounce/archive/S-{XX}/
    - Record lessons (with user approval)
    - Update delivery_plan.md to reflect the completed sprint.
 7. **Framework Self-Assessment** (aggregated from agent reports):
@@ -403,15 +420,18 @@ When ALL sprints in a delivery (release) are done:
 
 The Team Lead MUST update the active `sprint-{XX}.md` at every state transition. This is the source of truth for execution.
 
-| Action | Sprint Plan Update |
-|--------|---------------------|
-| Worktree created | §1 Active Scope: V-Bounce State → "Bouncing" |
-| Dev report written | No update (still "Bouncing") |
-| QA passes | §1 Active Scope: V-Bounce State → "QA Passed" |
-| Architect passes | §1 Active Scope: V-Bounce State → "Architect Passed" |
-| DevOps merges story | §1 Active Scope: V-Bounce State → "Done" |
-| Escalated | §1 Escalated table |
-| DevOps merges sprint | Update `delivery_plan.md` to flag sprint delivered |
+| Action | Sprint Plan Update | Delivery Plan Update |
+|--------|-------------------|--------------------|
+| Worktree created | §1: V-Bounce State → "Bouncing" | **Nothing** — Sprint Plan is source of truth |
+| Dev report written | No update (still "Bouncing") | **Nothing** |
+| QA passes | §1: V-Bounce State → "QA Passed" | **Nothing** |
+| Architect passes | §1: V-Bounce State → "Architect Passed" | **Nothing** |
+| DevOps merges story | §1: V-Bounce State → "Done". §4: Add Execution Log row (via `vbounce story complete`) | **Nothing** |
+| Escalated | §1: Move story to Escalated section | **Nothing** |
+| Sprint CLOSES | Status → "Completed" in frontmatter | §2: sprint → Completed. §4: add summary. §3: remove delivered stories |
+
+> **Key rule**: The Delivery Plan is updated ONLY at sprint close, never during active bouncing.
+> See `skills/agent-team/references/delivery-sync.md` for full sync rules.
 
 ---
 
@@ -431,6 +451,21 @@ When QA bounce count >= 3 OR Architect bounce count >= 3:
 - **If returned to Refinement:** The spec has been rewritten. You MUST reset the QA and Architect bounce counters to 0 for this story.
 - If killed: `git worktree remove`, branch preserved unmerged
 
+### Mid-Sprint Change Requests
+When the user provides input mid-bounce that isn't a direct answer to an agent question (e.g., "this is broken", "change the approach", "I meant X not Y"), the Team Lead MUST triage it before acting.
+
+> See `skills/agent-team/references/mid-sprint-triage.md` for the full triage flow, routing rules, and logging requirements.
+
+**Quick reference — categories:**
+| Category | Route | Bounce Impact |
+|----------|-------|---------------|
+| **Bug** | Hotfix or bug-fix task in current story | No bounce increment |
+| **Spec Clarification** | Update Story spec, continue bounce | No impact |
+| **Scope Change** | Pause, update spec, confirm with user | Resets Dev pass |
+| **Approach Change** | Update §3 Implementation Guide, re-delegate | Resets Dev pass |
+
+Every change request is logged in `sprint-{XX}.md` §4 Execution Log with event type `CR` and reported in Sprint Report §2.1.
+
 ### Mid-Sprint Strategic Changes
 Charter and Roadmap are typically **frozen** during active sprints. However, if an emergency requires modifying them:
 1. You MUST pause active bouncing across all stories.
@@ -453,7 +488,7 @@ If merging story branch into sprint branch creates conflicts:
 - **Reports are the only handoff.** No agent communicates with another directly.
 - **One bounce = one report.** Every agent pass produces exactly one report file.
 - **Archive before remove.** Always copy reports to shared archive before removing a worktree.
-- **Sync the Delivery Plan.** Update V-Bounce state at EVERY transition. The Delivery Plan is the source of truth.
+- **Sync the Sprint Plan.** Update V-Bounce State in sprint-{XX}.md §1 at EVERY transition. The Sprint Plan is the source of truth DURING the sprint. The Delivery Plan is updated at sprint boundaries only — see `skills/agent-team/references/delivery-sync.md`.
 - **Track bounce counts.** QA and Architect bounces are tracked separately per story.
 - **Git tracking rules.** `.worktrees/`, `.bounce/reports/`, and `.bounce/sprint-report.md` are gitignored (ephemeral). `.bounce/archive/` is **committed to git** (permanent audit trail).
 - **Check risks before bouncing.** Read RISK_REGISTRY.md at sprint start. Flag high-severity risks that affect planned stories.

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

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