@sandrinio/vbounce 1.5.0 → 1.7.0

package/brains/windsurf/.windsurfrules

@@ -0,0 +1,30 @@
+# V-Bounce OS — Windsurf Rules
+
+This project uses V-Bounce OS. You are operating in Tier 4 (Awareness) mode.
+
+## Before Writing Code
+
+1. Read `LESSONS.md` at the project root — treat as hard constraints
+2. Read the Story spec you're implementing (§1 + §3)
+3. Check `brains/CLAUDE.md` for full process context
+
+## Document Rules
+
+- Planning documents in `product_plans/` follow strict templates in `templates/`
+- Agent reports in `.bounce/reports/` MUST have YAML frontmatter
+- Never modify `brains/`, `skills/`, or `templates/` without recording in `brains/CHANGELOG.md`
+
+## State Management
+
+```bash
+vbounce state show            # where is the sprint right now?
+vbounce validate report <f>   # is this report valid?
+vbounce doctor                # is the framework healthy?
+```
+
+## Critical Rules
+
+- Read LESSONS.md before coding. No exceptions.
+- No gold-plating. Implement exactly what's specified.
+- Reports are the only agent handoff. No direct agent communication.
+- YAML frontmatter is mandatory on all agent reports.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrinio/vbounce",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "V-Bounce OS: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
   "type": "module",
   "bin": {
@@ -40,10 +40,8 @@
     "docs"
   ],
   "dependencies": {
-    "@lancedb/lancedb": "^0.26.2",
-    "@xenova/transformers": "^2.17.2",
     "commander": "^14.0.3",
     "js-yaml": "^4.1.1",
     "marked": "^17.0.3"
   }
-}
+}

package/scripts/close_sprint.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * close_sprint.mjs
+ * Sprint close automation — validates, archives, updates state.json.
+ *
+ * Usage:
+ *   ./scripts/close_sprint.mjs S-05
+ */
+
+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 args = process.argv.slice(2);
+if (args.length < 1) {
+  console.error('Usage: close_sprint.mjs S-XX');
+  process.exit(1);
+}
+
+const sprintId = args[0];
+if (!/^S-\d{2}$/.test(sprintId)) {
+  console.error(`ERROR: sprint_id "${sprintId}" must match S-XX format`);
+  process.exit(1);
+}
+
+const sprintNum = sprintId.replace('S-', '');
+const stateFile = path.join(ROOT, '.bounce', 'state.json');
+
+// 1. Read state.json
+if (!fs.existsSync(stateFile)) {
+  console.error(`ERROR: .bounce/state.json not found`);
+  process.exit(1);
+}
+
+const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+
+if (state.sprint_id !== sprintId) {
+  console.error(`ERROR: state.json is for sprint ${state.sprint_id}, not ${sprintId}`);
+  process.exit(1);
+}
+
+// 2. Check all stories are terminal
+const activeStories = Object.entries(state.stories || {}).filter(
+  ([, s]) => !['Done', 'Escalated', 'Parking Lot'].includes(s.state)
+);
+
+if (activeStories.length > 0) {
+  console.warn(`⚠  ${activeStories.length} stories are not in a terminal state:`);
+  activeStories.forEach(([id, s]) => console.warn(`   - ${id}: ${s.state}`));
+  console.warn('   Proceed? These stories will be left incomplete.');
+}
+
+// 3. Create archive directory
+const archiveDir = path.join(ROOT, '.bounce', 'archive', sprintId);
+fs.mkdirSync(archiveDir, { recursive: true });
+
+// 4. Move sprint report if it exists
+const reportSrc = path.join(ROOT, '.bounce', `sprint-report-${sprintId}.md`);
+const reportLegacy = path.join(ROOT, '.bounce', 'sprint-report.md');
+const reportDst = path.join(archiveDir, `sprint-report-${sprintId}.md`);
+
+if (fs.existsSync(reportSrc)) {
+  fs.copyFileSync(reportSrc, reportDst);
+  console.log(`✓ Archived sprint report → .bounce/archive/${sprintId}/sprint-report-${sprintId}.md`);
+} else if (fs.existsSync(reportLegacy)) {
+  fs.copyFileSync(reportLegacy, reportDst);
+  console.log(`✓ Archived sprint report → .bounce/archive/${sprintId}/sprint-report-${sprintId}.md`);
+}
+
+// 5. Update state.json
+state.last_action = `Sprint ${sprintId} closed`;
+state.updated_at = new Date().toISOString();
+fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+console.log(`✓ Updated state.json`);
+
+// 6. Print manual steps
+const sprintPlanPath = `product_plans/sprints/sprint-${sprintNum}`;
+const archivePath = `product_plans/archive/sprints/sprint-${sprintNum}`;
+
+console.log('');
+console.log('Manual steps remaining:');
+console.log(`  1. Archive sprint plan folder:`);
+console.log(`     mv ${sprintPlanPath}/ ${archivePath}/`);
+console.log(`  2. Update Delivery Plan §4 Completed Sprints with a summary row`);
+console.log(`  3. Remove delivered stories from Delivery Plan §3 Backlog`);
+console.log(`  4. Delete sprint branch (after merge to main):`);
+console.log(`     git branch -d sprint/${sprintId}`);
+console.log(`  5. Run: vbounce trends && vbounce suggest ${sprintId}`);
+console.log('');
+console.log(`✓ Sprint ${sprintId} closed.`);

package/scripts/complete_story.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+/**
+ * complete_story.mjs
+ * Mark a story as Done — updates Sprint Plan §1 + §4, and state.json atomically.
+ *
+ * Usage:
+ *   ./scripts/complete_story.mjs STORY-005-02 --qa-bounces 1 --arch-bounces 0 --correction-tax 5 --notes "Missing validation fixed"
+ */
+
+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, '..');
+
+function parseArgs(argv) {
+  const result = { storyId: null, qaBounces: 0, archBounces: 0, correctionTax: '0%', notes: '' };
+  const args = argv.slice(2);
+  result.storyId = args[0];
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--qa-bounces') result.qaBounces = parseInt(args[++i], 10) || 0;
+    else if (args[i] === '--arch-bounces') result.archBounces = parseInt(args[++i], 10) || 0;
+    else if (args[i] === '--correction-tax') result.correctionTax = args[++i] + (args[i].includes('%') ? '' : '%');
+    else if (args[i] === '--notes') result.notes = args[++i];
+  }
+  return result;
+}
+
+const { storyId, qaBounces, archBounces, correctionTax, notes } = parseArgs(process.argv);
+
+if (!storyId) {
+  console.error('Usage: complete_story.mjs STORY-ID [--qa-bounces N] [--arch-bounces N] [--correction-tax N] [--notes "text"]');
+  process.exit(1);
+}
+
+// 1. Update state.json
+const stateFile = path.join(ROOT, '.bounce', 'state.json');
+if (!fs.existsSync(stateFile)) {
+  console.error('ERROR: .bounce/state.json not found');
+  process.exit(1);
+}
+const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+if (!state.stories[storyId]) {
+  console.error(`ERROR: Story "${storyId}" not found in state.json`);
+  process.exit(1);
+}
+state.stories[storyId].state = 'Done';
+state.stories[storyId].qa_bounces = qaBounces;
+state.stories[storyId].arch_bounces = archBounces;
+state.stories[storyId].worktree = null;
+state.last_action = `${storyId} completed`;
+state.updated_at = new Date().toISOString();
+fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+console.log(`✓ Updated state.json: ${storyId} → Done`);
+
+// 2. Find sprint plan
+const sprintNum = state.sprint_id.replace('S-', '');
+const sprintPlanPath = path.join(ROOT, 'product_plans', 'sprints', `sprint-${sprintNum}`, `sprint-${sprintNum}.md`);
+
+if (!fs.existsSync(sprintPlanPath)) {
+  console.warn(`⚠  Sprint plan not found at ${sprintPlanPath}. Update §1 and §4 manually.`);
+  process.exit(0);
+}
+
+let content = fs.readFileSync(sprintPlanPath, 'utf8');
+
+// 3. Update §1 table — find the row with storyId and change V-Bounce State to Done
+const tableRowRegex = new RegExp(`(\\|[^|]*\\|[^|]*${storyId.replace(/[-]/g, '[-]')}[^|]*\\|[^|]*\\|[^|]*\\|)([^|]+)(\\|[^|]*\\|)`, 'g');
+let updated = false;
+content = content.replace(tableRowRegex, (match, before, stateCell, after) => {
+  updated = true;
+  return `${before} Done ${after}`;
+});
+
+if (!updated) {
+  console.warn(`⚠  Could not find ${storyId} row in §1 table. Update V-Bounce State manually.`);
+}
+
+// 4. Add row to §4 Execution Log
+const logStart = '<!-- EXECUTION_LOG_START -->';
+const logEnd = '<!-- EXECUTION_LOG_END -->';
+const newRow = `| ${storyId} | Done | ${qaBounces} | ${archBounces} | ${correctionTax} | ${notes || '—'} |`;
+
+if (content.includes(logStart)) {
+  // Find the table in the execution log section and append a row
+  const startIdx = content.indexOf(logStart);
+  const endIdx = content.indexOf(logEnd);
+
+  if (endIdx > startIdx) {
+    const before = content.substring(0, endIdx);
+    const after = content.substring(endIdx);
+
+    // Check if header row exists, if not add it
+    const section = before.substring(startIdx);
+    if (!section.includes('| Story |')) {
+      const headerRow = `\n| Story | Final State | QA Bounces | Arch Bounces | Correction Tax | Notes |\n|-------|-------------|------------|--------------|----------------|-------|`;
+      content = before + headerRow + '\n' + newRow + '\n' + after;
+    } else {
+      content = before + newRow + '\n' + after;
+    }
+    console.log(`✓ Added row to §4 Execution Log`);
+  }
+} else {
+  // Append §4 section at end
+  content += `\n\n<!-- EXECUTION_LOG_START -->\n## 4. Execution Log\n\n| Story | Final State | QA Bounces | Arch Bounces | Correction Tax | Notes |\n|-------|-------------|------------|--------------|----------------|-------|\n${newRow}\n<!-- EXECUTION_LOG_END -->\n`;
+  console.log(`✓ Created §4 Execution Log with first row`);
+}
+
+fs.writeFileSync(sprintPlanPath, content);
+console.log(`✓ Updated sprint plan: ${storyId} Done`);
+console.log(`\n  QA bounces: ${qaBounces} | Arch bounces: ${archBounces} | Correction tax: ${correctionTax}`);

package/scripts/doctor.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * doctor.mjs
+ * V-Bounce OS Health Check — validates all configs, templates, state files
+ * Usage: vbounce doctor
+ */
+
+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 checks = [];
+let issueCount = 0;
+
+function pass(msg) {
+  checks.push(`  ✓ ${msg}`);
+}
+
+function fail(msg, fix) {
+  checks.push(`  ✗ ${msg}${fix ? `\n    → Fix: ${fix}` : ''}`);
+  issueCount++;
+}
+
+function warn(msg) {
+  checks.push(`  ⚠ ${msg}`);
+}
+
+// Check LESSONS.md
+if (fs.existsSync(path.join(ROOT, 'LESSONS.md'))) {
+  pass('LESSONS.md exists');
+} else {
+  fail('LESSONS.md missing', 'Create LESSONS.md at project root');
+}
+
+// Check templates
+const requiredTemplates = ['sprint.md', 'delivery_plan.md', 'sprint_report.md', 'story.md', 'epic.md', 'charter.md', 'roadmap.md', 'risk_registry.md'];
+const templatesDir = path.join(ROOT, 'templates');
+let templateCount = 0;
+for (const t of requiredTemplates) {
+  if (fs.existsSync(path.join(templatesDir, t))) templateCount++;
+  else fail(`templates/${t} missing`, `Create from V-Bounce OS template`);
+}
+if (templateCount === requiredTemplates.length) pass(`templates/ complete (${templateCount}/${requiredTemplates.length})`);
+
+// Check .bounce directory
+if (fs.existsSync(path.join(ROOT, '.bounce'))) {
+  pass('.bounce/ directory exists');
+
+  // Check state.json
+  const stateFile = path.join(ROOT, '.bounce', 'state.json');
+  if (fs.existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      pass(`state.json valid (sprint ${state.sprint_id}, ${Object.keys(state.stories || {}).length} stories)`);
+    } catch (e) {
+      fail('state.json exists but is invalid JSON', 'Run: vbounce validate state');
+    }
+  } else {
+    warn('state.json not found — run: vbounce sprint init S-XX D-XX');
+  }
+} else {
+  warn('.bounce/ directory missing — run: vbounce sprint init S-XX D-XX');
+}
+
+// Check brain files
+const brainFiles = [
+  ['brains/CLAUDE.md', 'Tier 1 (Claude Code)'],
+  ['brains/GEMINI.md', 'Tier 2 (Gemini CLI)'],
+  ['brains/AGENTS.md', 'Tier 2 (Codex CLI)'],
+];
+for (const [f, tier] of brainFiles) {
+  if (fs.existsSync(path.join(ROOT, f))) pass(`Brain file: ${f} (${tier})`);
+  else fail(`Brain file: ${f} missing`, `Run: vbounce init --tool ${f.includes('GEMINI') ? 'gemini' : f.includes('AGENTS') ? 'codex' : 'claude'}`);
+}
+
+// Check optional brain files
+const optionalBrains = [
+  ['brains/copilot/copilot-instructions.md', 'copilot'],
+  ['brains/windsurf/.windsurfrules', 'windsurf'],
+];
+for (const [f, tool] of optionalBrains) {
+  if (fs.existsSync(path.join(ROOT, f))) pass(`Brain file: ${f} (Tier 4)`);
+  else warn(`Brain file: ${f} not found (optional) — run: vbounce init --tool ${tool}`);
+}
+
+// Check skills
+const requiredSkills = ['agent-team', 'doc-manager', 'lesson', 'vibe-code-review', 'react-best-practices', 'write-skill', 'improve'];
+const skillsDir = path.join(ROOT, 'skills');
+let skillCount = 0;
+for (const s of requiredSkills) {
+  const skillFile = path.join(skillsDir, s, 'SKILL.md');
+  if (fs.existsSync(skillFile)) skillCount++;
+  else fail(`skills/${s}/SKILL.md missing`);
+}
+if (skillCount === requiredSkills.length) pass(`Skills: ${skillCount}/${requiredSkills.length} installed`);
+
+// Check scripts
+const requiredScripts = [
+  'validate_report.mjs', 'update_state.mjs', 'validate_state.mjs',
+  'validate_sprint_plan.mjs', 'validate_bounce_readiness.mjs',
+  'init_sprint.mjs', 'close_sprint.mjs', 'complete_story.mjs',
+  'prep_qa_context.mjs', 'prep_arch_context.mjs', 'prep_sprint_context.mjs',
+  'prep_sprint_summary.mjs', 'sprint_trends.mjs', 'suggest_improvements.mjs',
+  'hotfix_manager.sh'
+];
+const scriptsDir = path.join(ROOT, 'scripts');
+let scriptCount = 0;
+for (const s of requiredScripts) {
+  if (fs.existsSync(path.join(scriptsDir, s))) scriptCount++;
+  else fail(`scripts/${s} missing`);
+}
+if (scriptCount === requiredScripts.length) pass(`Scripts: ${scriptCount}/${requiredScripts.length} available`);
+
+// Check product_plans structure
+if (fs.existsSync(path.join(ROOT, 'product_plans'))) {
+  pass('product_plans/ directory exists');
+} else {
+  warn('product_plans/ directory missing — create it to store planning documents');
+}
+
+// Check vbounce.config.json
+if (fs.existsSync(path.join(ROOT, 'vbounce.config.json'))) {
+  pass('vbounce.config.json found');
+} else {
+  warn('vbounce.config.json not found — using default context limits');
+}
+
+// Print results
+console.log('\nV-Bounce OS Health Check');
+console.log('========================');
+checks.forEach(c => console.log(c));
+console.log('');
+if (issueCount === 0) {
+  console.log('✓ All checks passed.');
+} else {
+  console.log(`Issues: ${issueCount}`);
+  console.log('Run suggested commands to fix.');
+}
+
+process.exit(issueCount > 0 ? 1 : 0);

package/scripts/init_gate_config.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# init_gate_config.sh — Auto-detect project stack and generate .bounce/gate-checks.json
+# Usage: ./scripts/init_gate_config.sh [project-path]
+#
+# Run once during project setup or when the improve skill suggests new checks.
+# Safe to re-run — merges with existing config (preserves custom checks).
+
+set -euo pipefail
+
+PROJECT_PATH="${1:-.}"
+PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+CONFIG_PATH="${PROJECT_PATH}/.bounce/gate-checks.json"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${CYAN}V-Bounce OS Gate Config Initializer${NC}"
+echo -e "Project: ${PROJECT_PATH}"
+echo ""
+
+# ── Detect stack ─────────────────────────────────────────────────────
+
+LANGUAGE="unknown"
+FRAMEWORK="unknown"
+TEST_RUNNER="unknown"
+BUILD_CMD=""
+LINT_CMD=""
+TEST_CMD=""
+
+# Language detection
+if [[ -f "${PROJECT_PATH}/tsconfig.json" ]]; then
+  LANGUAGE="typescript"
+elif [[ -f "${PROJECT_PATH}/package.json" ]]; then
+  LANGUAGE="javascript"
+elif [[ -f "${PROJECT_PATH}/pyproject.toml" || -f "${PROJECT_PATH}/setup.py" || -f "${PROJECT_PATH}/requirements.txt" ]]; then
+  LANGUAGE="python"
+elif [[ -f "${PROJECT_PATH}/Cargo.toml" ]]; then
+  LANGUAGE="rust"
+elif [[ -f "${PROJECT_PATH}/go.mod" ]]; then
+  LANGUAGE="go"
+elif [[ -f "${PROJECT_PATH}/build.gradle" || -f "${PROJECT_PATH}/pom.xml" ]]; then
+  LANGUAGE="java"
+elif [[ -f "${PROJECT_PATH}/Package.swift" ]]; then
+  LANGUAGE="swift"
+fi
+
+echo -e "Language: ${GREEN}${LANGUAGE}${NC}"
+
+# Framework detection (JS/TS ecosystem)
+if [[ -f "${PROJECT_PATH}/package.json" ]]; then
+  PKG_CONTENT=$(cat "${PROJECT_PATH}/package.json")
+
+  if echo "$PKG_CONTENT" | grep -q '"next"'; then FRAMEWORK="nextjs"
+  elif echo "$PKG_CONTENT" | grep -q '"react"'; then FRAMEWORK="react"
+  elif echo "$PKG_CONTENT" | grep -q '"vue"'; then FRAMEWORK="vue"
+  elif echo "$PKG_CONTENT" | grep -q '"svelte"'; then FRAMEWORK="svelte"
+  elif echo "$PKG_CONTENT" | grep -q '"express"'; then FRAMEWORK="express"
+  elif echo "$PKG_CONTENT" | grep -q '"fastify"'; then FRAMEWORK="fastify"
+  elif echo "$PKG_CONTENT" | grep -q '"@angular/core"'; then FRAMEWORK="angular"
+  fi
+
+  # Test runner
+  if echo "$PKG_CONTENT" | grep -q '"vitest"'; then TEST_RUNNER="vitest"
+  elif echo "$PKG_CONTENT" | grep -q '"jest"'; then TEST_RUNNER="jest"
+  elif echo "$PKG_CONTENT" | grep -q '"mocha"'; then TEST_RUNNER="mocha"
+  elif echo "$PKG_CONTENT" | grep -q '"ava"'; then TEST_RUNNER="ava"
+  fi
+
+  # Commands from scripts
+  BUILD_CMD=$(node -e "try{const p=require('${PROJECT_PATH}/package.json');console.log(p.scripts&&p.scripts.build||'')}catch(e){}" 2>/dev/null || echo "")
+  LINT_CMD=$(node -e "try{const p=require('${PROJECT_PATH}/package.json');console.log(p.scripts&&p.scripts.lint||'')}catch(e){}" 2>/dev/null || echo "")
+  TEST_CMD=$(node -e "try{const p=require('${PROJECT_PATH}/package.json');const t=p.scripts&&p.scripts.test||'';if(t&&!t.includes('no test specified'))console.log(t);else console.log('')}catch(e){}" 2>/dev/null || echo "")
+elif [[ "$LANGUAGE" == "python" ]]; then
+  if command -v pytest &>/dev/null; then TEST_RUNNER="pytest"; fi
+  if command -v ruff &>/dev/null; then LINT_CMD="ruff check ."; fi
+elif [[ "$LANGUAGE" == "rust" ]]; then
+  TEST_RUNNER="cargo"
+  BUILD_CMD="cargo build"
+  LINT_CMD="cargo clippy"
+elif [[ "$LANGUAGE" == "go" ]]; then
+  TEST_RUNNER="go"
+  BUILD_CMD="go build ./..."
+  LINT_CMD="golangci-lint run"
+fi
+
+echo -e "Framework: ${GREEN}${FRAMEWORK}${NC}"
+echo -e "Test runner: ${GREEN}${TEST_RUNNER}${NC}"
+[[ -n "$BUILD_CMD" ]] && echo -e "Build: ${GREEN}${BUILD_CMD}${NC}"
+[[ -n "$LINT_CMD" ]] && echo -e "Lint: ${GREEN}${LINT_CMD}${NC}"
+echo ""
+
+# ── Generate config ──────────────────────────────────────────────────
+
+# Build QA checks array
+QA_CHECKS='[
+    { "id": "tests_exist", "enabled": true, "description": "Verify test files exist for modified source files" },
+    { "id": "tests_pass", "enabled": true, "description": "Run test suite" },
+    { "id": "build", "enabled": true, "description": "Run build command" },
+    { "id": "lint", "enabled": true, "description": "Run linter" },
+    { "id": "no_debug_output", "enabled": true, "description": "No debug statements in modified files" },
+    { "id": "no_todo_fixme", "enabled": true, "description": "No TODO/FIXME in modified files" },
+    { "id": "exports_have_docs", "enabled": true, "description": "Exported symbols have doc comments" }
+  ]'
+
+# Build Architect checks array
+ARCH_CHECKS='[
+    { "id": "tests_exist", "enabled": true, "description": "Verify test files exist for modified source files" },
+    { "id": "tests_pass", "enabled": true, "description": "Run test suite" },
+    { "id": "build", "enabled": true, "description": "Run build command" },
+    { "id": "lint", "enabled": true, "description": "Run linter" },
+    { "id": "no_debug_output", "enabled": true, "description": "No debug statements in modified files" },
+    { "id": "no_todo_fixme", "enabled": true, "description": "No TODO/FIXME in modified files" },
+    { "id": "exports_have_docs", "enabled": true, "description": "Exported symbols have doc comments" },
+    { "id": "no_new_deps", "enabled": true, "description": "No new dependencies without review" },
+    { "id": "file_size", "enabled": true, "max_lines": 500, "description": "Source files under 500 lines" }
+  ]'
+
+# Write config
+mkdir -p "$(dirname "$CONFIG_PATH")"
+
+cat > "$CONFIG_PATH" << HEREDOC
+{
+  "version": 1,
+  "detected_stack": {
+    "language": "${LANGUAGE}",
+    "framework": "${FRAMEWORK}",
+    "test_runner": "${TEST_RUNNER}",
+    "build_cmd": "${BUILD_CMD}",
+    "lint_cmd": "${LINT_CMD}",
+    "test_cmd": "${TEST_CMD}"
+  },
+  "qa_checks": ${QA_CHECKS},
+  "arch_checks": ${ARCH_CHECKS},
+  "custom_checks": []
+}
+HEREDOC
+
+echo -e "${GREEN}Generated: ${CONFIG_PATH}${NC}"
+echo ""
+echo "Universal checks enabled. To add project-specific checks:"
+echo "  1. Run sprints and let agents collect Process Feedback"
+echo "  2. Use the 'improve' skill to propose new checks"
+echo "  3. Or manually add entries to the custom_checks array"
+echo ""
+echo -e "Example custom check (add to custom_checks):"
+echo '  { "id": "custom_grep", "gate": "arch", "enabled": true,'
+echo '    "pattern": "var\\(--my-prefix-", "glob": "*.tsx",'
+echo '    "should_find": false, "description": "No raw CSS vars in components" }'

package/scripts/init_sprint.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+/**
+ * init_sprint.mjs
+ * Sprint setup automation — creates state.json, sprint plan dir, and prints git commands.
+ *
+ * Usage:
+ *   ./scripts/init_sprint.mjs S-06 D-02 --stories STORY-011-05,STORY-005-01,STORY-005-02
+ */
+
+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 args = process.argv.slice(2);
+
+if (args.length < 2) {
+  console.error('Usage: init_sprint.mjs S-XX D-NN [--stories STORY-ID1,STORY-ID2,...]');
+  process.exit(1);
+}
+
+const sprintId = args[0]; // e.g. S-06
+const deliveryId = args[1]; // e.g. D-02
+
+if (!/^S-\d{2}$/.test(sprintId)) {
+  console.error(`ERROR: sprint_id "${sprintId}" must match S-XX format`);
+  process.exit(1);
+}
+if (!/^D-\d{2}$/.test(deliveryId)) {
+  console.error(`ERROR: delivery_id "${deliveryId}" must match D-NN format`);
+  process.exit(1);
+}
+
+const storiesArg = args.indexOf('--stories');
+const storyIds = storiesArg !== -1 ? args[storiesArg + 1].split(',') : [];
+
+// 1. Create .bounce/ directory
+const bounceDir = path.join(ROOT, '.bounce');
+fs.mkdirSync(bounceDir, { recursive: true });
+fs.mkdirSync(path.join(bounceDir, 'archive'), { recursive: true });
+fs.mkdirSync(path.join(bounceDir, 'reports'), { recursive: true });
+
+// 2. Create state.json
+const stateFile = path.join(bounceDir, 'state.json');
+if (fs.existsSync(stateFile)) {
+  console.warn(`⚠  state.json already exists. Overwriting...`);
+}
+
+const sprintNum = sprintId.replace('S-', '');
+const stories = {};
+for (const id of storyIds) {
+  stories[id.trim()] = {
+    state: 'Draft',
+    qa_bounces: 0,
+    arch_bounces: 0,
+    worktree: null
+  };
+}
+
+const state = {
+  sprint_id: sprintId,
+  delivery_id: deliveryId,
+  sprint_plan: `product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md`,
+  delivery_plan: `product_plans/strategy/${deliveryId}_DELIVERY_PLAN.md`,
+  stories,
+  phase: 'Phase 1',
+  last_action: `Sprint ${sprintId} initialized`,
+  updated_at: new Date().toISOString()
+};
+
+fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+console.log(`✓ Created .bounce/state.json`);
+
+// 3. Create sprint plan directory
+const sprintDir = path.join(ROOT, 'product_plans', 'sprints', `sprint-${sprintNum}`);
+fs.mkdirSync(sprintDir, { recursive: true });
+
+const sprintPlanFile = path.join(sprintDir, `sprint-${sprintNum}.md`);
+if (!fs.existsSync(sprintPlanFile)) {
+  // Copy from template
+  const templateFile = path.join(ROOT, 'templates', 'sprint.md');
+  if (fs.existsSync(templateFile)) {
+    let content = fs.readFileSync(templateFile, 'utf8');
+    // Replace placeholders
+    content = content.replace(/sprint-\{XX\}/g, `sprint-${sprintNum}`);
+    content = content.replace(/S-\{XX\}/g, sprintId);
+    content = content.replace(/D-\{NN\}/g, deliveryId);
+    content = content.replace(/status: "Planning \/ Active \/ Completed"/, 'status: "Planning"');
+    // Strip instructions block
+    content = content.replace(/<instructions>[\s\S]*?<\/instructions>\n\n/, '');
+    fs.writeFileSync(sprintPlanFile, content);
+    console.log(`✓ Created product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md`);
+  } else {
+    // Create minimal sprint plan
+    const minimal = `---\nsprint_id: "${sprintId}"\nsprint_goal: "TBD"\ndates: "TBD"\nstatus: "Planning"\ndelivery: "${deliveryId}"\n---\n\n# Sprint ${sprintId} Plan\n\n## 1. Active Scope\n\n| Priority | Story | Epic | Label | V-Bounce State | Blocker |\n|----------|-------|------|-------|----------------|---------|\n${storyIds.map((id, i) => `| ${i + 1} | ${id.trim()} | — | L2 | Draft | — |`).join('\n')}\n\n### Escalated / Parking Lot\n- (none)\n\n---\n\n## 2. Execution Strategy\n\n### Phase Plan\n- **Phase 1 (parallel)**: ${storyIds.join(', ')}\n\n### Risk Flags\n- (TBD)\n\n---\n\n## 3. Sprint Open Questions\n\n| Question | Options | Impact | Owner | Status |\n|----------|---------|--------|-------|--------|\n\n---\n\n<!-- EXECUTION_LOG_START -->\n## 4. Execution Log\n\n| Story | Final State | QA Bounces | Arch Bounces | Correction Tax | Notes |\n|-------|-------------|------------|--------------|----------------|-------|\n<!-- EXECUTION_LOG_END -->\n`;
+    fs.writeFileSync(sprintPlanFile, minimal);
+    console.log(`✓ Created product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md (minimal — template not found)`);
+  }
+} else {
+  console.log(`  Sprint plan already exists: product_plans/sprints/sprint-${sprintNum}/sprint-${sprintNum}.md`);
+}
+
+// 4. Print git commands (don't execute)
+console.log('');
+console.log('Run these git commands to initialize the sprint branch:');
+console.log(`  git checkout -b sprint/${sprintId} main`);
+if (storyIds.length > 0) {
+  console.log('');
+  console.log('Then create worktrees for each story:');
+  storyIds.forEach(id => {
+    const trimmed = id.trim();
+    console.log(`  git worktree add .worktrees/${trimmed} -b story/${trimmed} sprint/${sprintId}`);
+    console.log(`  mkdir -p .worktrees/${trimmed}/.bounce/{tasks,reports}`);
+  });
+}
+
+console.log('');
+console.log(`✓ Sprint ${sprintId} initialized. Stories: ${storyIds.length > 0 ? storyIds.join(', ') : 'none (add manually)'}`);