specweave 0.21.3 → 0.22.2

package/CLAUDE.md

@@ -24,21 +24,23 @@ Users receive a different CLAUDE.md via the template system.
 /SESSION-SUMMARY-2025-10-28.md         # NO! Goes to increment reports/
 /ADR-006-DEEP-ANALYSIS.md              # NO! Goes to .specweave/docs/internal/architecture/adr/
 /ANALYSIS-MULTI-TOOL-COMPARISON.md     # NO! Goes to increment reports/
+/QUICK-START.md                        # NO! Goes to increment reports/
 /migration-helper.sh                   # NO! Goes to increment scripts/
 /execution.log                         # NO! Goes to increment logs/
 
 ✅ CORRECT - INCREMENT FOLDERS:
 .specweave/increments/0004-plugin-architecture/
-├── spec.md                            # Spec files (core 3)
+├── spec.md                            # ⚠️ ONLY THESE 3 FILES in root!
 ├── plan.md
 ├── tasks.md                           # Tasks with embedded tests
-├── reports/                           # ✅ PUT REPORTS HERE!
+├── reports/                           # ✅ ALL REPORTS HERE!
 │   ├── PLUGIN-MIGRATION-COMPLETE.md   # ✅ Completion reports
 │   ├── SESSION-SUMMARY.md             # ✅ Session summaries
+│   ├── QUICK-START.md                 # ✅ Quick start guides
 │   └── ANALYSIS-*.md                  # ✅ Analysis files
-├── scripts/                           # ✅ PUT SCRIPTS HERE!
+├── scripts/                           # ✅ ALL SCRIPTS HERE!
 │   └── migration-helper.sh            # ✅ Helper scripts
-└── logs/                              # ✅ PUT LOGS HERE!
+└── logs/                              # ✅ ALL LOGS HERE!
     └── execution.log                  # ✅ Execution logs
 
 .specweave/docs/internal/architecture/ # ✅ PUT ADRS/DIAGRAMS HERE!
@@ -48,6 +50,215 @@ Users receive a different CLAUDE.md via the template system.
 
 **Before committing, ALWAYS check**: `git status` - If you see `.md` files in root, MOVE THEM!
 
+### 📁 Increment Structure Rules (MANDATORY)
+
+**ONLY 3 files allowed in increment root**:
+1. ✅ `spec.md` - Specification
+2. ✅ `plan.md` - Implementation plan
+3. ✅ `tasks.md` - Tasks with embedded tests
+
+**Everything else MUST be in subfolders**:
+- `reports/` - Session summaries, completion reports, analysis files, quick-start guides
+- `scripts/` - Helper scripts, migrations, utilities
+- `logs/` - Execution logs, debug output, temp files
+
+**Examples of files that belong in subfolders**:
+- `QUICK-START.md` → `reports/QUICK-START.md`
+- `SESSION-NOTES.md` → `reports/SESSION-NOTES.md`
+- `ULTRATHINK-*.md` → `reports/ULTRATHINK-*.md`
+- `validation.sh` → `scripts/validation.sh`
+- `debug.log` → `logs/debug.log`
+
+**Why this matters**:
+- ✅ Clean, predictable structure
+- ✅ Easy to find files by type
+- ✅ No increment root clutter
+- ✅ Consistent across all increments
+
+---
+
+## 🛡️ CRITICAL: NEVER DELETE .specweave/ DIRECTORIES!
+
+**⛔ MASS DELETION PROTECTION IS ACTIVE ⛔**
+
+**PROTECTED DIRECTORIES**:
+- `.specweave/docs/` - All project documentation (internal + public)
+- `.specweave/increments/` - All increment history and specifications
+
+**WHAT THIS MEANS**:
+- ❌ **NEVER** run `rm -rf .specweave/docs` or `rm -rf .specweave/increments`
+- ❌ **NEVER** delete more than 50 files in these directories at once
+- ✅ Pre-commit hook will **BLOCK** accidental mass deletions
+- ✅ If intentional, bypass with `git commit --no-verify`
+
+**WHY THIS EXISTS**:
+On 2025-11-17, an accidental mass deletion occurred (1,200+ files). All files were recovered via `git restore`, but this protection prevents future incidents.
+
+**IF YOU ACCIDENTALLY DELETE**:
+```bash
+# Immediately restore:
+git restore .specweave/
+
+# Verify restoration:
+git status
+```
+
+**See**: `.specweave/increments/0039/reports/ACCIDENTAL-DELETION-RECOVERY-2025-11-17.md`
+
+---
+
+## 🚨 CRITICAL: DANGEROUS TEST CLEANUP OPERATIONS!
+
+**⛔ WARNING: Test cleanup can cause CATASTROPHIC deletion ⛔**
+
+**INCIDENT**: On 2025-11-18, during increment 0042 (test infrastructure cleanup), a bash command nearly deleted the entire `tests/integration/` directory (209 test files). The command failed due to working directory confusion, but demonstrated the EXACT catastrophic risk identified in ultrathink analysis.
+
+**THE DANGER**:
+```bash
+# ❌ EXTREMELY DANGEROUS (can delete entire test suite):
+cd tests/integration
+find . -maxdepth 1 -type d ... -exec rm -rf {} +
+# Risk: Working directory confusion + no confirmation = catastrophic deletion
+
+# ❌ DANGEROUS (no verification):
+find tests/integration -type d -exec rm -rf {} +
+# Risk: Too broad, deletes everything
+
+# ❌ DANGEROUS (assumes pwd):
+rm -rf tests/integration/*/
+# Risk: If pwd is wrong, deletes unintended directories
+```
+
+**SAFE APPROACH** (MANDATORY for test cleanup):
+```bash
+# ✅ STEP 1: Verify working directory (ALWAYS FIRST!)
+pwd
+# Must output: /Users/antonabyzov/Projects/github/specweave
+
+# ✅ STEP 2: DRY RUN (list only, NO deletion)
+find tests/integration -maxdepth 1 -type d \
+  ! -name "integration" \
+  ! -name "core" ! -name "features" ! -name "external-tools" ! -name "generators" \
+  -print
+# Review output MANUALLY before proceeding
+
+# ✅ STEP 3: Count directories to delete
+find tests/integration -maxdepth 1 -type d \
+  ! -name "integration" \
+  ! -name "core" ! -name "features" ! -name "external-tools" ! -name "generators" \
+  -print | wc -l
+# Verify count matches expectations
+
+# ✅ STEP 4: Manual confirmation (REQUIRED)
+echo "About to delete XX directories. Type 'DELETE' to confirm:"
+read confirmation
+if [ "$confirmation" != "DELETE" ]; then
+  echo "Cancelled"
+  exit 1
+fi
+
+# ✅ STEP 5: Execute deletion (ONLY after all checks pass)
+find tests/integration -maxdepth 1 -type d \
+  ! -name "integration" \
+  ! -name "core" ! -name "features" ! -name "external-tools" ! -name "generators" \
+  -exec rm -rf {} +
+
+# ✅ STEP 6: Verify results
+ls tests/integration/
+find tests/integration -name "*.test.ts" | wc -l
+
+# ✅ STEP 7: Run tests (MANDATORY)
+npm run test:integration
+```
+
+**MANDATORY SAFETY RULES**:
+1. ✅ **ALWAYS** verify `pwd` before ANY deletion command
+2. ✅ **ALWAYS** use dry-run (`-print`) before `-exec rm`
+3. ✅ **ALWAYS** count directories/files before deletion
+4. ✅ **ALWAYS** require manual confirmation for deletion
+5. ✅ **ALWAYS** verify results after deletion
+6. ✅ **ALWAYS** run tests after structural changes
+7. ✅ **NEVER** use `rm -rf` without multiple safety checks
+
+**WHY THIS MATTERS**:
+- 🔴 One wrong command = entire test suite deleted
+- 🔴 213 unsafe `process.cwd()` patterns exist in tests (increment 0042 audit)
+- 🔴 Working directory confusion is COMMON
+- 🔴 Recovery requires git restore (assumes uncommitted changes)
+- 🔴 If changes committed, recovery requires time-consuming rollback
+
+**LESSONS FROM INCIDENT 0042**:
+1. **Dry-run is NOT optional** - Always list before deleting
+2. **Working directory matters** - Verify pwd FIRST
+3. **Confirmation prevents accidents** - Require manual "DELETE" confirmation
+4. **Test after changes** - Structural changes can break tests
+5. **Incremental commits** - Commit after each phase (easier rollback)
+
+**IF CATASTROPHIC DELETION OCCURS**:
+```bash
+# Immediately restore from git (if not committed):
+git restore tests/
+
+# If committed, restore from previous commit:
+git log --oneline -- tests/
+git checkout <previous-commit-hash> -- tests/
+
+# Verify restoration:
+find tests -name "*.test.ts" | wc -l
+npm run test:all
+```
+
+**REFERENCES**:
+- Incident report: `.specweave/increments/0042-test-infrastructure-cleanup/reports/CATASTROPHIC-DELETION-INCIDENT-2025-11-18.md`
+- Ultrathink analysis: `.specweave/increments/0041-living-docs-test-fixes/reports/ULTRATHINK-TEST-DUPLICATION-ANALYSIS-2025-11-18.md`
+- Safe cleanup approach: Increment 0042 Phase 1 tasks
+
+**NEVER delete test directories without following ALL safety steps above!**
+
+---
+
+## ⚠️ CRITICAL: NEVER USE `specweave init . --force` FOR REINSTALLS!
+
+**⛔ COMMON MISTAKE THAT DELETES ALL DATA ⛔**
+
+**THE DANGER**:
+```bash
+# ❌ DANGEROUS (deletes ALL increments and docs):
+specweave init . --force
+
+# What --force actually does:
+# 1. Skips all confirmation prompts
+# 2. AUTOMATICALLY DELETES .specweave/ entirely
+# 3. Loses all increments, docs, and history
+# 4. No backup unless you create one manually
+```
+
+**SAFE ALTERNATIVES**:
+```bash
+# ✅ SAFE - Update files, keep all data:
+specweave init .
+# When prompted, select: "Continue working"
+
+# ✅ SAFE - Always interactive, never deletes:
+npx specweave init .
+```
+
+**WHY THIS MATTERS**:
+- Documentation used to recommend `--force` for troubleshooting (FIXED in v0.21.4+)
+- Users followed the docs and lost all their work
+- Now `--force` has multiple safeguards:
+  - ⚠️ BIG RED WARNING before deletion
+  - ✅ ALWAYS requires confirmation (even in force mode)
+  - 📦 Automatic backup created before deletion
+  - 🔒 Pre-commit hook blocks accidental commits
+
+**IF YOU NEED A FRESH START**:
+1. Backup first: `cp -r .specweave .specweave.backup-$(date +%Y%m%d)`
+2. Run: `specweave init .` (select "Fresh start" option)
+3. Or: `specweave init . --force` (requires confirmation + creates auto-backup)
+
+**NEVER use `--force` unless you want to DELETE EVERYTHING!**
+
 ---
 
 ## Tool Support
@@ -353,12 +564,204 @@ npm run build              # Compile TypeScript
 
 ### Testing
 
+**Test Framework**: **Vitest** (migrated from Jest on 2025-11-17)
+
 ```bash
-npm test                    # Unit tests
-npm run test:integration    # Integration tests (includes build verification)
+npm test                    # Smoke tests (quick validation)
+npm run test:unit           # Unit tests with Vitest
+npm run test:integration    # Integration tests with Vitest
 npm run test:e2e            # E2E tests (Playwright)
+npm run test:all            # All tests
+npm run test:coverage       # Coverage report
+```
+
+**Why Vitest?**
+- ✅ ESM-native (no tsconfig hacks)
+- ✅ Faster than Jest
+- ✅ Better TypeScript integration
+- ✅ Native import.meta.url support
+- ✅ Modern, actively maintained
+
+**Test Organization** (4 categories):
+- `tests/unit/` - Pure logic tests (no I/O) - **Vitest**
+- `tests/plugin-validation/` - Plugin structure contracts
+- `tests/integration/` - 4 semantic categories - **Vitest**:
+  - `external-tools/` - GitHub, JIRA, ADO, Kafka sync
+  - `core/` - Core framework + workflows
+  - `generators/` - Code generation (frontend, backend, ML)
+  - `features/` - Feature plugins (Figma, i18n, diagrams, etc.)
+- `tests/e2e/` - Full user scenarios - **Playwright**
+
+**Test Naming Convention** (standardized 2025-11-18):
+- ✅ ALL tests use `.test.ts` extension (unit, integration, E2E)
+- ❌ NEVER use `.spec.ts` extension (deprecated)
+- **Why**: Consistent glob patterns, simpler test discovery, aligned with Vitest conventions
+
+**Writing Tests**:
+```typescript
+// Import from vitest (NOT jest)
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// Mocking
+vi.mock('fs/promises');
+const mockFn = vi.fn();
+vi.clearAllMocks();
+```
+
+**Details**: `.specweave/docs/internal/architecture/TEST-ORGANIZATION-PROPOSAL.md`
+
+### Test Isolation (CRITICAL - Prevents .specweave/ Deletion!)
+
+**🚨 MANDATORY FOR ALL TESTS creating .specweave/ structures:**
+
+**THE PROBLEM**: Tests using `process.cwd()` can accidentally delete the project `.specweave/` folder containing all your work!
+
+**CORRECT PATTERN** (ALWAYS use this):
+```typescript
+import * as os from 'os';
+import * as path from 'path';
+
+// ✅ SAFE: Uses isolated temp directory
+const testRoot = path.join(os.tmpdir(), 'test-name-' + Date.now());
+```
+
+**DANGEROUS PATTERN** (NEVER use this):
+```typescript
+// ❌ DANGER: Creates directories in project root!
+const testRoot = path.join(process.cwd(), '.test-something');
+const testPath = path.join(__dirname, '..', '.specweave', 'increments');
 ```
 
+### Vitest Mock Best Practices
+
+**🚨 MANDATORY FOR ALL TESTS using mocks:**
+
+**CORRECT PATTERN** (vi.mocked() for type-safe mocks):
+```typescript
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import fs from 'fs-extra';
+
+// Mock fs-extra BEFORE using it
+vi.mock('fs-extra');
+
+// Type-safe mocked functions
+const mockReadFile = vi.mocked(fs.readFile);
+const mockWriteFile = vi.mocked(fs.writeFile);
+const mockExistsSync = vi.mocked(fs.existsSync);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockExistsSync.mockReturnValue(true);
+  mockReadFile.mockResolvedValue('content');
+});
+```
+
+**DANGEROUS PATTERN** (NEVER use this):
+```typescript
+// ❌ WRONG: Invalid anyed<> syntax (pre-Vitest migration)
+const mockFs = fs as anyed<typeof fs> & {
+  readFile: anyedFunction<typeof fs.readFile>;
+};
+// This causes TypeScript errors and test failures!
+```
+
+**Why This Matters**:
+1. `vi.mocked()` provides full type safety
+2. Catches mock setup errors at compile time
+3. Works correctly with Vitest's mock system
+4. Prevents runtime "Cannot read properties of undefined" errors
+
+**Common Mock Gotchas**:
+- Always call `vi.clearAllMocks()` in beforeEach
+- Use `mockResolvedValue` for async functions
+- Use `mockReturnValue` for sync functions
+- Check that mocks are actually called: `expect(mockFn).toHaveBeenCalled()`
+
+### Testing Best Practices & Anti-Patterns
+
+**Lessons from fixing 72+ test failures (2025-11-17 Vitest migration)**
+
+#### Critical Rules (Will Fail Tests)
+
+```typescript
+// ❌ WRONG                           // ✅ CORRECT
+require('../src/module')              import { Module } from '../src/module.js'
+jest.fn()                             vi.fn()
+jest.mock()                           vi.mock()
+fs as anyed<typeof fs>                vi.mocked(fs.readFile)
+const mock = vi.fn()                  vi.mock('mod', () => ({
+vi.mock('mod', () => ({ mock }))        method: vi.fn()  // inline!
+                                      }))
+mockReadJson.mockResolvedValue(arr)   mockReadJson.mockResolvedValue([...arr])  // copy!
+```
+
+#### Quick Template
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+vi.mock('fs-extra', () => ({ default: { readFile: vi.fn() } }));
+import fs from 'fs-extra';
+
+describe('Feature', () => {
+  const mockReadFile = vi.mocked(fs.readFile);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockReadFile.mockResolvedValue('data');
+  });
+
+  it('works', async () => {
+    const result = await MyModule.doSomething();
+    expect(mockReadFile).toHaveBeenCalled();
+  });
+});
+```
+
+#### Pre-Commit Checklist
+
+- [ ] ES6 imports (NOT require())
+- [ ] vi.* APIs (NOT jest.*)
+- [ ] vi.mocked() for mocks (NOT anyed<>)
+- [ ] Inline mock factories (NO external variables)
+- [ ] Array copies in mocks (NO shared references)
+- [ ] vi.clearAllMocks() in beforeEach()
+
+**Full guide**: `tests/test-template.test.ts`
+
+**Why This Matters**:
+1. Tests create mock `.specweave/` structures for testing
+2. Cleanup uses `fs.rm(testRoot, { recursive: true })`
+3. If `testRoot` points to project root → **DELETES REAL .specweave/!**
+4. You lose all increments, docs, and history
+
+**Use Test Utilities** (RECOMMENDED):
+```typescript
+import { createIsolatedTestDir, createSpecweaveStructure } from '../test-utils/isolated-test-dir';
+
+test('my test', async () => {
+  const { testDir, cleanup } = await createIsolatedTestDir('my-test');
+
+  try {
+    // Setup .specweave structure in isolated directory
+    await createSpecweaveStructure(testDir);
+
+    // Test code here - NEVER touches project .specweave/
+    const incrementPath = path.join(testDir, '.specweave', 'increments', '0001-test');
+    // ...
+  } finally {
+    await cleanup(); // ALWAYS cleanup
+  }
+});
+```
+
+**Protection Layers**:
+1. ✅ **Pre-commit hook**: Blocks commits with dangerous test patterns
+2. ✅ **Test utilities**: `tests/test-utils/isolated-test-dir.ts`
+3. ✅ **Documentation**: This section
+
+**Related Incident**: 2025-11-17 - Multiple `.specweave/` deletions traced to dangerous test patterns
+**Root Cause Analysis**: `.specweave/increments/0037/reports/DELETION-ROOT-CAUSE-2025-11-17.md`
+
 ### Build Health Checks
 
 **CRITICAL**: TypeScript ES Modules require specific practices:

package/README.md

@@ -14,14 +14,14 @@ The framework that turns solo builders into unicorn-level engineering teams.
 
 ## 📊 Engineering Metrics (DORA)
 
-[![Deploy Frequency](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.deploymentFrequency.value&label=Deploy%20Frequency&suffix=/month&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
-[![Lead Time](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.leadTime.value&label=Lead%20Time&suffix=h&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
-[![Change Failure Rate](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.changeFailureRate.value&label=Change%20Failure%20Rate&suffix=%25&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
-[![MTTR](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.mttr.value&label=MTTR&suffix=min&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
+[![Deploy Frequency](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/.specweave/metrics/dora-latest.json&query=$.metrics.deploymentFrequency.value&label=Deploy%20Frequency&suffix=/month&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
+[![Lead Time](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/.specweave/metrics/dora-latest.json&query=$.metrics.leadTime.value&label=Lead%20Time&suffix=h&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
+[![Change Failure Rate](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/.specweave/metrics/dora-latest.json&query=$.metrics.changeFailureRate.value&label=Change%20Failure%20Rate&suffix=%25&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
+[![MTTR](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/.specweave/metrics/dora-latest.json&query=$.metrics.mttr.value&label=MTTR&suffix=min&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
 
 **SpecWeave builds SpecWeave using SpecWeave.** These are real metrics from our own development.
 
-**[→ Live Dashboard](https://spec-weave.com/docs/metrics)** | **[→ Detailed Report](https://github.com/anton-abyzov/specweave/blob/develop/metrics/dora-report.md)**
+**[→ Live Dashboard](https://spec-weave.com/docs/metrics)** | **[→ Detailed Report](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/metrics/dora-report.md)**
 
 ---
 
@@ -232,8 +232,18 @@ Claude implements Task 1:
 # Install SpecWeave
 npm install -g specweave
 
-# Initialize new project
+# Initialize with Strategic Init (AI-powered research)
 specweave init my-project
+
+# Strategic Init guides you through 6 phases:
+# Phase 1: Vision & Market Research
+# Phase 2: Scaling & Performance Goals
+# Phase 3: Data & Compliance Detection
+# Phase 4: Budget & Cloud Credits
+# Phase 5: Methodology & Organization
+# Phase 6: Repository Selection (optional)
+
+# Result: Architecture recommendation, team plan, cost estimates
 cd my-project
 
 # Start building
@@ -242,6 +252,15 @@ cd my-project
 /specweave:done 0001                        # Complete increment
 ```
 
+### Multi-Project Setup
+```bash
+# Initialize with multiple projects
+specweave init --projects backend,frontend,mobile
+
+# Tasks automatically split by project keyword detection
+# Each project gets its own user stories and GitHub issues
+```
+
 ### Brownfield (Existing Project)
 ```bash
 # Initialize SpecWeave in existing project
@@ -255,7 +274,7 @@ specweave init .
 /specweave:increment "Add dark mode"
 ```
 
-**[→ Complete Quickstart Guide](https://spec-weave.com/docs/guides/getting-started/quickstart)**
+**[→ Complete Quickstart Guide](https://spec-weave.com/docs/guides/getting-started/quickstart)** | **[→ Strategic Init Guide](https://spec-weave.com/docs/guides/strategic-init)**
 
 ---
 
@@ -296,12 +315,23 @@ specweave init .
 
 ## Key Features
 
+### Strategic Init - AI-Powered Architecture Planning (NEW!)
+
+- 🎯 **Research-Driven Discovery** - Answer 6 phases of questions about your product
+- 🏗️ **Architecture Recommendations** - Tech stack, scaling strategy, cost projections
+- 🔒 **Compliance Detection** - Auto-detects 30+ standards (HIPAA, GDPR, SOC2, etc.)
+- 👥 **Smart Team Planning** - Current and future team structure, hiring roadmap
+- ☁️ **Cloud Credits Discovery** - AWS Activate, Azure Startup, GCP eligibility
+- 📦 **Repository Selection** - Batch select 1-100+ repos with intelligent routing
+
+### Production Features
+
 - 🤖 **AI-Native Enterprise Sync** - Claude updates JIRA/GitHub/ADO automatically (bidirectional!)
 - 📚 **Living Documentation** - Auto-updates after every task (no manual sync!)
 - 🧪 **Test-Aware Planning** - Embedded tests in BDD format (Given/When/Then)
 - 🎯 **Disciplined Progress** - Can't start increment N+1 until N is DONE
 - ⏸️ **Intelligent Pausing** - Auto-detects blockers, pauses with context, resumes when ready
-- 🔄 **Smart Reopen (NEW!)** - Report "broken" → Auto-detects what to reopen, respects WIP limits
+- 🔄 **Smart Reopen** - Report "broken" → Auto-detects what to reopen, respects WIP limits
 - 👥 **Multi-Project Tracking** - Unlimited JIRA/ADO/GitHub repos, intelligent routing
 - 🤖 **AI Agents** - PM, Architect, Quality Judge guide your work
 - 🔧 **CI/CD Auto-Fix** - Workflow failures auto-fixed by Claude (just mention `@claude`)

package/bin/specweave.js

@@ -311,20 +311,17 @@ async function checkForDuplicates() {
     const report = await detectAllDuplicates(process.cwd());
 
     if (report.duplicateCount > 0) {
-      console.log(chalk.yellow('\n⚠️  WARNING: Duplicate increments detected!\n'));
+      console.log(chalk.yellow('\n⚠️  Duplicate increment(s) detected:\n'));
 
       for (const duplicate of report.duplicates) {
-        console.log(chalk.yellow(`  Increment ${duplicate.incrementNumber} exists in multiple locations:`));
+        console.log(chalk.dim(`  ${duplicate.incrementNumber}:`));
         for (const location of duplicate.locations) {
-          const indicator = location === duplicate.recommendedWinner ? chalk.green('✓ (recommended)') : chalk.red('✗');
-          console.log(`    ${indicator} ${location.name} [${location.status}] - ${location.path}`);
+          const indicator = location === duplicate.recommendedWinner ? chalk.green('→') : chalk.red('✗');
+          console.log(`    ${indicator} ${location.name} [${location.status}]`);
         }
-        console.log(chalk.dim(`    Reason: ${duplicate.resolutionReason}\n`));
       }
 
-      console.log(chalk.yellow('  Resolution:'));
-      console.log(chalk.dim('    Run /specweave:fix-duplicates to automatically resolve conflicts'));
-      console.log(chalk.dim('    or manually delete/archive the losing versions\n'));
+      console.log(chalk.dim('\n  Run /specweave:fix-duplicates to resolve\n'));
     }
   } catch (error) {
     // Silently ignore errors (don't block CLI startup)

package/dist/plugins/specweave-github/lib/CodeValidator.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Code Validator
+ *
+ * Validates that completed tasks have actual code implementation.
+ * Prevents marking tasks as complete when:
+ * - Files don't exist
+ * - Files are empty or have trivial content
+ * - Implementation is incomplete
+ *
+ * Used by GitHub sync to enforce code-completion discipline.
+ *
+ * @module CodeValidator
+ */
+/**
+ * File validation result
+ */
+export interface FileValidationResult {
+    path: string;
+    exists: boolean;
+    hasContent: boolean;
+    lineCount: number;
+    reason?: string;
+}
+/**
+ * Task validation result
+ */
+export interface TaskValidationResult {
+    taskId: string;
+    valid: boolean;
+    files: FileValidationResult[];
+    reason?: string;
+}
+/**
+ * CodeValidator options
+ */
+export interface CodeValidatorOptions {
+    minLines?: number;
+    minChars?: number;
+    projectRoot?: string;
+}
+export declare class CodeValidator {
+    private options;
+    constructor(options?: CodeValidatorOptions);
+    /**
+     * Validate that code exists for a task
+     *
+     * Extracts file paths from task description and verifies:
+     * 1. Files exist
+     * 2. Files have meaningful content
+     * 3. Files are not just stubs
+     *
+     * @param taskDescription - Task description with file paths
+     * @param taskId - Task ID for error messages
+     * @returns Validation result
+     */
+    validateTask(taskDescription: string, taskId: string): Promise<TaskValidationResult>;
+    /**
+     * Validate a single file
+     *
+     * @param filePath - Path to file (relative or absolute)
+     * @returns File validation result
+     */
+    validateFile(filePath: string): Promise<FileValidationResult>;
+    /**
+     * Extract file paths from task description
+     *
+     * Supports multiple formats:
+     * - **Files**: src/foo.ts, src/bar.ts
+     * - **Files to create**: src/foo.ts
+     * - **Files to modify**: src/bar.ts
+     * - Inline code blocks with file paths
+     *
+     * @param description - Task description text
+     * @returns Array of file paths
+     */
+    extractFilePaths(description: string): string[];
+    /**
+     * Batch validate multiple tasks
+     *
+     * @param tasks - Array of {taskId, description}
+     * @returns Array of validation results
+     */
+    validateTasks(tasks: Array<{
+        taskId: string;
+        description: string;
+    }>): Promise<TaskValidationResult[]>;
+    /**
+     * Get summary of validation results
+     *
+     * @param results - Array of task validation results
+     * @returns Summary statistics
+     */
+    summarizeResults(results: TaskValidationResult[]): {
+        total: number;
+        valid: number;
+        invalid: number;
+        noFiles: number;
+        invalidTasks: string[];
+    };
+}
+//# sourceMappingURL=CodeValidator.d.ts.map

package/dist/plugins/specweave-github/lib/CodeValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeValidator.d.ts","sourceRoot":"","sources":["../../../../plugins/specweave-github/lib/CodeValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAiC;gBAEpC,OAAO,GAAE,oBAAyB;IAQ9C;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsC1F;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA4EnE;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE;IAuC/C;;;;;OAKG;IACG,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAS3G;;;;;OAKG;IACH,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG;QACjD,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,EAAE,CAAC;KACxB;CAeF"}