specweave 0.22.2 → 0.22.4

package/plugins/specweave/commands/specweave-sync-docs.md

@@ -17,34 +17,60 @@ Arguments provided: [user's arguments]
 
 **Parse the input**:
 - Check for explicit mode: `review`, `update`, or none (auto-detect)
-- Check for increment ID: `0001`, `0002`, etc., or none (find current)
+- Check for increment ID: `0001`, `0002`, etc., or none (sync all - NEW DEFAULT)
+- Check for `--all` flag (explicit sync all)
+
+**NEW DEFAULT BEHAVIOR (v0.23.0+)**:
+- **No arguments** → Sync all increments with spec.md (batch mode)
+- **Specific increment ID** → Sync that increment only
+- **`--all` flag** → Sync all increments (explicit)
 
 **Auto-detect logic**:
 
-1. **If increment ID provided**:
+1. **If no increment ID provided (NEW DEFAULT)**:
    ```bash
-   # Read the increment's spec.md to check status
-   INCREMENT_PATH=".specweave/increments/{increment_id}"
-   STATUS=$(grep "^status:" "$INCREMENT_PATH/spec.md" | cut -d: -f2 | tr -d ' ')
+   # Sync ALL increments with spec.md
+   echo "🔄 Syncing all increments..."
+   npx specweave sync-specs
+   # This will sync all non-archived increments
    ```
 
-2. **If no increment ID provided**:
+2. **If increment ID provided**:
    ```bash
-   # Find the most recent increment
-   LATEST=$(ls -1 .specweave/increments/ | grep -E '^[0-9]{4}' | sort -r | head -1)
+   # Read the increment's spec.md to check status
+   INCREMENT_PATH=".specweave/increments/{increment_id}"
+   STATUS=$(grep "^status:" "$INCREMENT_PATH/spec.md" | cut -d: -f2 | tr -d ' ')
    ```
 
 3. **Determine mode**:
    ```
-   If status = "planned" → REVIEW MODE
-   If status = "in-progress" → UPDATE MODE
-   If status = "completed" → UPDATE MODE
-   If status = "closed" → UPDATE MODE
+   If no increment ID → BATCH SYNC MODE (sync all)
+
+   If increment ID provided:
+     If status = "planned" → REVIEW MODE
+     If status = "in-progress" → UPDATE MODE
+     If status = "completed" → UPDATE MODE
+     If status = "closed" → UPDATE MODE
 
    If explicit mode provided → Use that mode
    ```
 
-**Output**:
+**Output (Batch Mode)**:
+```
+🔄 Syncing all increments...
+
+📚 Syncing 0040-vitest-living-docs-mock-fixes → FS-040...
+   ✅ Synced 3 tasks to US-001
+✅ Synced 0040 → FS-040
+
+📚 Syncing 0041-living-docs-test-fixes → FS-041...
+   ✅ Synced 2 tasks to US-001
+✅ Synced 0041 → FS-041
+
+✅ Sync complete: 15 increments synced, 0 failed
+```
+
+**Output (Single Mode)**:
 ```
 🔍 Detected increment: {increment_id}
 📊 Status: {status}
@@ -243,6 +269,57 @@ Synchronize living documentation in `.specweave/docs/` with learnings and decisi
 
 ### Execution Steps:
 
+#### 0. 🔄 SYNC LIVING SPECS (User Stories, ACs, Tasks) - CRITICAL FIRST STEP
+
+**🚨 MANDATORY: This MUST run FIRST before syncing strategic docs!**
+
+Execute the living specs sync using the TypeScript CLI:
+
+```typescript
+import { syncSpecs } from './dist/src/cli/commands/sync-specs.js';
+
+console.log('═══════════════════════════════════════════════════════');
+console.log('📋 STEP 0: SYNCING LIVING SPECS');
+console.log('═══════════════════════════════════════════════════════\n');
+console.log('🔄 Syncing user stories, acceptance criteria, and tasks...\n');
+
+// Call sync-specs to sync living docs structure
+await syncSpecs(['{increment_id}']);
+
+console.log('\n✅ Living specs synced successfully!');
+console.log('   - User stories created/updated in .specweave/docs/internal/specs/');
+console.log('   - Acceptance criteria synchronized with completion status');
+console.log('   - Tasks linked to user stories\n');
+```
+
+**What this step does**:
+- ✅ Parses increment spec.md and extracts user stories with ACs
+- ✅ Syncs AC completion status from spec.md to user story files
+- ✅ Updates task mappings in user story files
+- ✅ Creates/updates feature files and README
+- ✅ Ensures living specs are in sync BEFORE strategic docs
+
+**Output**:
+```
+🎯 Target increment: {increment_id}
+📁 Increment path: .specweave/increments/{increment_id}
+🔄 Mode: Specs-only sync (Universal Hierarchy)
+
+Processing...
+📚 Syncing {increment_id} → {FS-XXX}...
+   ✅ Synced 3 tasks to US-001
+   ✅ Synced 2 tasks to US-002
+
+✅ Synced {increment_id} → {FS-XXX}
+   Created: 5 files
+
+═══════════════════════════════════════════════════════
+```
+
+**CRITICAL**: If this step fails, STOP and report error. Do not proceed to strategic docs sync.
+
+---
+
 #### 1. Analyze Increment Artifacts
 
 ```bash
@@ -510,7 +587,16 @@ Increment: {increment_id} ({title})
 Status: {status} → Documentation Updated
 
 ───────────────────────────────────────────────────────
-📊 CHANGES SUMMARY
+📋 LIVING SPECS SYNCED (Step 0)
+───────────────────────────────────────────────────────
+
+✅ User Stories: {count} created/updated in .specweave/docs/internal/specs/
+✅ Acceptance Criteria: Synchronized with completion status from spec.md
+✅ Tasks: Linked to user stories with completion tracking
+✅ Feature Files: Created/updated in .specweave/docs/internal/specs/_features/
+
+───────────────────────────────────────────────────────
+📊 STRATEGIC DOCS CHANGES (Steps 1-5)
 ───────────────────────────────────────────────────────
 
 Created:
@@ -544,20 +630,27 @@ To restore: cp {file}.backup {file}
 ───────────────────────────────────────────────────────
 
 1. Review updated documentation:
+   - Living specs: .specweave/docs/internal/specs/
    - Public docs: .specweave/docs/public/
    - Internal docs: .specweave/docs/internal/
    - New ADRs: .specweave/docs/internal/architecture/adr/
 
-2. (Optional) Generate Docusaurus site:
+2. Verify living specs sync:
+   - Check user story files for updated AC checkboxes
+   - Verify tasks are linked correctly
+   - Confirm feature files are up to date
+
+3. (Optional) Generate Docusaurus site:
    - Use 'docusaurus' skill to publish updated docs
 
-3. Commit changes:
+4. Commit changes:
    git add .specweave/docs/
    git commit -m "docs: sync from increment {increment_id}"
 
 ═══════════════════════════════════════════════════════
 
-Documentation is now in sync with increment {increment_id}! 🎉
+ALL documentation is now in sync with increment {increment_id}! 🎉
+(Living specs + Strategic docs)
 ```
 
 ---
@@ -612,20 +705,42 @@ Usage: /specweave:sync-docs [review|update] [increment_id]
 
 ## EXAMPLES
 
-### Example 1: Auto-detect mode for current increment
+### Example 1: Sync all increments (NEW DEFAULT)
 ```
 User: /specweave:sync-docs
 
 Output:
-🔍 Detected increment: 0002
+🔄 Syncing all increments...
+
+📚 Syncing 0040-vitest-living-docs-mock-fixes → FS-040...
+   ✅ Synced 3 tasks to US-001
+✅ Synced 0040 → FS-040
+
+📚 Syncing 0041-living-docs-test-fixes → FS-041...
+   ✅ Synced 2 tasks to US-001
+✅ Synced 0041 → FS-041
+
+📚 Syncing 0042-test-infrastructure-cleanup → FS-042...
+   ✅ Synced 5 tasks to US-002
+✅ Synced 0042 → FS-042
+
+✅ Sync complete: 15 increments synced, 0 failed
+```
+
+### Example 2: Sync specific increment
+```
+User: /specweave:sync-docs 0042
+
+Output:
+🔍 Detected increment: 0042
 📊 Status: completed
 🎯 Mode: UPDATE
 
 Proceeding with UPDATE mode...
-{... executes update mode}
+{... executes update mode for 0042 only}
 ```
 
-### Example 2: Explicit review mode
+### Example 3: Explicit review mode
 ```
 User: /specweave:sync-docs review 0003
 
@@ -637,7 +752,7 @@ Output:
 {... shows strategic documentation summary}
 ```
 
-### Example 3: Explicit update mode with increment
+### Example 4: Explicit update mode with increment
 ```
 User: /specweave:sync-docs update 0002
 

package/plugins/specweave/commands/specweave-update-status.md

@@ -0,0 +1,151 @@
+---
+name: specweave:update-status
+description: Force-update status line cache with latest increment status
+---
+
+# Update Status Line
+
+**Purpose**: Force-refresh status line cache when it appears stale or after making changes.
+
+**Use When**:
+- Status line doesn't reflect recent changes
+- After completing tasks (want to see updated progress immediately)
+- After status transitions (active → completed)
+- Before checking progress with `/specweave:progress`
+- When status line shows outdated information
+
+---
+
+## How It Works
+
+1. **Scan All Increments**
+   - Reads all spec.md files in `.specweave/increments/`
+   - Identifies open increments (status = active/planning/in-progress)
+   - Extracts creation dates from YAML frontmatter
+
+2. **Select Current Increment**
+   - Sorts by creation date (oldest first)
+   - Takes first as current active increment
+   - Counts total open increments
+
+3. **Parse Task Progress**
+   - Reads tasks.md from current increment
+   - Uses TaskCounter for accurate counting (no overcounting)
+   - Calculates: completed, total, percentage
+
+4. **Update Cache**
+   - Writes `.specweave/state/status-line.json`
+   - Atomic write (temp file → rename)
+   - Runs SYNCHRONOUSLY (user waits ~50-100ms)
+
+---
+
+## Usage
+
+```bash
+# Force-update status line (no arguments)
+/specweave:update-status
+```
+
+**Output**:
+```
+✓ Status line cache updated
+```
+
+---
+
+## Example
+
+**Before Update** (stale cache):
+```
+Status Line: [0043] ████░░░░ 5/8 tasks (2 open)
+```
+
+**After Update** (fresh cache):
+```
+Status Line: [0043] ████████ 8/8 tasks (1 open) ✓
+```
+
+---
+
+## Integration with Other Commands
+
+This command is automatically called by:
+
+1. **`/specweave:progress`**
+   - Ensures status line is fresh before showing progress
+   - User always sees accurate completion percentages
+
+2. **`/specweave:done`**
+   - Refreshes status line before PM validation
+   - Ensures final progress is accurate
+
+3. **`/specweave:status`**
+   - Updates cache before showing increment list
+   - Shows current increment status
+
+---
+
+## Technical Details
+
+**Performance**: ~50-100ms (synchronous execution)
+
+**Cache Location**: `.specweave/state/status-line.json`
+
+**Cache Format**:
+```json
+{
+  "current": {
+    "id": "0043-spec-md-desync-fix",
+    "name": "0043-spec-md-desync-fix",
+    "completed": 8,
+    "total": 8,
+    "percentage": 100
+  },
+  "openCount": 1,
+  "lastUpdate": "2025-11-18T15:30:00Z"
+}
+```
+
+**Source of Truth**:
+- Increment status: `spec.md` YAML frontmatter (NOT metadata.json)
+- Task progress: `tasks.md` (TaskCounter for accuracy)
+
+**Atomicity**: Uses temp file → rename pattern to prevent cache corruption
+
+---
+
+## Troubleshooting
+
+**Status line still stale after update?**
+1. Check if `.specweave/state/status-line.json` was modified
+2. Verify spec.md has correct status in YAML frontmatter
+3. Check tasks.md has proper task format (## T-001, etc.)
+
+**Error: "Failed to update status line"**
+- Ensure `.specweave/increments/` exists
+- Check file permissions on `.specweave/state/`
+- Verify spec.md has valid YAML frontmatter
+
+**Cache shows wrong increment?**
+- Status line shows oldest active increment by default
+- Complete older increments first
+- Or check `created` date in spec.md frontmatter
+
+---
+
+## Implementation
+
+**CLI**: `src/cli/update-status-line.ts`
+**Core Logic**: `src/core/status-line/status-line-updater.ts`
+**Hook (async)**: `plugins/specweave/hooks/lib/update-status-line.sh`
+
+**Difference from Hook**:
+- **Command**: SYNCHRONOUS (user waits, sees immediate result)
+- **Hook**: ASYNCHRONOUS (background refresh, no blocking)
+
+Both use same logic, different execution model.
+
+---
+
+**This command ensures status line is ALWAYS fresh when you need it!** ✓

package/plugins/specweave/hooks/lib/update-status-line.sh

@@ -1,16 +1,17 @@
 #!/usr/bin/env bash
 #
-# update-status-line.sh (Simplified)
+# update-status-line.sh (Enhanced with AC Metrics)
 #
 # Updates status line cache with current increment progress.
-# Shows: [increment-name] ████░░░░ X/Y tasks (Z open)
+# Shows: [increment-name] ████░░░░ X/Y tasks | A/B ACs (Z open)
 #
 # Logic:
 # 1. Scan all spec.md for status=active/planning (SOURCE OF TRUTH!)
 # 2. Take first (oldest) as current increment
 # 3. Count all active/planning as openCount
-# 4. Parse current increment's tasks.md for progress
-# 5. Write to cache
+# 4. Parse current increment's tasks.md for task progress
+# 5. Parse current increment's spec.md for AC progress
+# 6. Write to cache
 #
 # Performance: 50-100ms (runs async, user doesn't wait)
 
@@ -105,8 +106,11 @@ if [[ -f "$TASKS_FILE" ]]; then
     TOTAL_TASKS=$(grep -cE '^##+ T-' "$TASKS_FILE" 2>/dev/null || echo 0)
     TOTAL_TASKS=$(echo "$TOTAL_TASKS" | tr -d '\n\r ' || echo 0)
 
-    # Count completed tasks - use most reliable single marker (**Completed**: format)
-    COMPLETED_TASKS=$(grep -c '\*\*Completed\*\*:' "$TASKS_FILE" 2>/dev/null || echo 0)
+    # Count completed tasks - recognize all three completion marker formats:
+    # 1. **Completed**: <date> (preferred format)
+    # 2. **Status**: [x] (legacy format)
+    # 3. [x] at line start (legacy checkbox format)
+    COMPLETED_TASKS=$(grep -cE '(\*\*Completed\*\*:|\*\*Status\*\*:\s*\[x\]|^\[x\])' "$TASKS_FILE" 2>/dev/null || echo 0)
     COMPLETED_TASKS=$(echo "$COMPLETED_TASKS" | tr -d '\n\r ' || echo 0)
 
     # Calculate percentage
@@ -116,19 +120,44 @@ if [[ -f "$TASKS_FILE" ]]; then
   fi
 fi
 
+# Step 4b: Parse spec.md for AC (Acceptance Criteria) progress
+SPEC_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/spec.md"
+TOTAL_ACS=0
+COMPLETED_ACS=0
+OPEN_ACS=0
+
+if [[ -f "$SPEC_FILE" ]]; then
+  # Count total ACs: both checked and unchecked
+  # Pattern: - [ ] **AC- OR - [x] **AC-
+  TOTAL_ACS=$(grep -cE '^- \[(x| )\] \*\*AC-' "$SPEC_FILE" 2>/dev/null || echo 0)
+  TOTAL_ACS=$(echo "$TOTAL_ACS" | tr -d '\n\r ' || echo 0)
+
+  # Count completed ACs (checked)
+  # Pattern: - [x] **AC-
+  COMPLETED_ACS=$(grep -cE '^- \[x\] \*\*AC-' "$SPEC_FILE" 2>/dev/null || echo 0)
+  COMPLETED_ACS=$(echo "$COMPLETED_ACS" | tr -d '\n\r ' || echo 0)
+
+  # Count open ACs (unchecked)
+  # Pattern: - [ ] **AC-
+  OPEN_ACS=$(grep -cE '^- \[ \] \*\*AC-' "$SPEC_FILE" 2>/dev/null || echo 0)
+  OPEN_ACS=$(echo "$OPEN_ACS" | tr -d '\n\r ' || echo 0)
+fi
+
 # Step 5: Extract increment ID and name
 # Format: XXXX-name where XXXX is 4-digit prefix (brackets added by manager)
 INCREMENT_ID=$(echo "$CURRENT_INCREMENT" | grep -oE '^[0-9]{4}')
 INCREMENT_NAME_ONLY=$(echo "$CURRENT_INCREMENT" | sed 's/^[0-9]\{4\}-//')
 INCREMENT_NAME="$INCREMENT_ID-$INCREMENT_NAME_ONLY"
 
-# Step 6: Write cache
+# Step 6: Write cache (now includes AC metrics)
 jq -n \
   --arg id "$CURRENT_INCREMENT" \
   --arg name "$INCREMENT_NAME" \
   --argjson completed "$COMPLETED_TASKS" \
   --argjson total "$TOTAL_TASKS" \
   --argjson percentage "$PERCENTAGE" \
+  --argjson acsCompleted "$COMPLETED_ACS" \
+  --argjson acsTotal "$TOTAL_ACS" \
   --argjson openCount "$OPEN_COUNT" \
   '{
     current: {
@@ -136,7 +165,9 @@ jq -n \
       name: $name,
       completed: $completed,
       total: $total,
-      percentage: $percentage
+      percentage: $percentage,
+      acsCompleted: $acsCompleted,
+      acsTotal: $acsTotal
     },
     openCount: $openCount,
     lastUpdate: (now | strftime("%Y-%m-%dT%H:%M:%SZ"))

package/plugins/specweave/hooks/user-prompt-submit.sh

@@ -342,6 +342,27 @@ if echo "$PROMPT" | grep -qiE "(add|create|implement|build|develop)" && ! echo "
   fi
 fi
 
+# ==============================================================================
+# STATUS LINE REFRESH: Ensure cache is fresh before showing context
+# ==============================================================================
+# Performance: ~50-100ms (acceptable for UX)
+# Frequency: Every user prompt (high coverage)
+# Benefit: Catches ALL edge cases (manual edits, resume, direct changes)
+#
+# Why here? This hook runs on EVERY user prompt, ensuring status line
+# is ALWAYS up-to-date before showing context to the user.
+#
+# Prevents desync scenarios:
+# - Manual spec.md edits (status: planning → active)
+# - /specweave:resume (status: paused → active)
+# - Direct metadata changes (without hook triggers)
+# - File system operations bypassing hooks
+#
+# Background execution: Runs async, doesn't block user prompt
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+
 # ==============================================================================
 # OUTPUT: Approve with context or no context
 # ==============================================================================

package/plugins/specweave/hooks/validate-increment-completion.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+#
+# Pre-commit hook: Validate Increment Completion
+#
+# Prevents commits where increment status="completed" but:
+# - Acceptance criteria are still open (- [ ] **AC-...)
+# - Tasks are still pending (**Status**: [ ] pending)
+#
+# This prevents false completion and data integrity violations.
+#
+# Exit code 0: All completed increments are valid (allow commit)
+# Exit code 1: Invalid completion detected (block commit)
+
+# ANSI colors
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Check if in SpecWeave project
+if [ ! -d ".specweave/increments" ]; then
+  # Not a SpecWeave project, skip validation
+  exit 0
+fi
+
+# Track if any validation failures found
+has_failures=false
+
+# Check all increments
+for increment_dir in .specweave/increments/*/; do
+  # Skip if not a directory
+  [ ! -d "$increment_dir" ] && continue
+
+  increment_id=$(basename "$increment_dir")
+  spec_file="$increment_dir/spec.md"
+  tasks_file="$increment_dir/tasks.md"
+  metadata_file="$increment_dir/metadata.json"
+
+  # Skip if required files don't exist
+  [ ! -f "$spec_file" ] && continue
+  [ ! -f "$tasks_file" ] && continue
+
+  # Get status from spec.md frontmatter
+  spec_status=$(grep -m1 "^status:" "$spec_file" 2>/dev/null | cut -d: -f2 | tr -d ' ')
+
+  # Get status from metadata.json (if exists)
+  metadata_status=""
+  if [ -f "$metadata_file" ]; then
+    metadata_status=$(grep -m1 '"status"' "$metadata_file" 2>/dev/null | cut -d'"' -f4)
+  fi
+
+  # Only validate if status is "completed"
+  if [ "$spec_status" = "completed" ] || [ "$metadata_status" = "completed" ]; then
+    # Count open acceptance criteria (- [ ] **AC-)
+    open_acs=$(grep -c "^- \[ \] \*\*AC-" "$spec_file" 2>/dev/null || echo 0)
+
+    # Count pending tasks (**Status**: [ ] pending)
+    pending_tasks=$(grep -ic "\*\*Status\*\*:\s*\[\s*\]\s*pending" "$tasks_file" 2>/dev/null || echo 0)
+
+    # Validate
+    if [ "$open_acs" -gt 0 ] || [ "$pending_tasks" -gt 0 ]; then
+      has_failures=true
+
+      echo -e "${RED}❌ COMMIT BLOCKED: Invalid completion detected${NC}"
+      echo -e "${YELLOW}Increment: $increment_id${NC}"
+      echo -e "Status: $spec_status (spec.md) / $metadata_status (metadata.json)"
+      echo ""
+
+      if [ "$open_acs" -gt 0 ]; then
+        echo -e "${RED}  • $open_acs acceptance criteria still open${NC}"
+      fi
+
+      if [ "$pending_tasks" -gt 0 ]; then
+        echo -e "${RED}  • $pending_tasks tasks still pending${NC}"
+      fi
+
+      echo ""
+      echo -e "${YELLOW}Fix options:${NC}"
+      echo "  1. Complete the open work before committing"
+      echo "  2. Change status to 'active' or 'paused' in both spec.md and metadata.json"
+      echo ""
+      echo -e "${YELLOW}To see details:${NC}"
+      echo "  cat $spec_file | grep '- \[ \] \*\*AC-'"
+      echo "  cat $tasks_file | grep -i 'Status.*pending'"
+      echo ""
+    fi
+  fi
+done
+
+# Exit with failure if any validation failures
+if [ "$has_failures" = true ]; then
+  echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo -e "${RED}COMMIT BLOCKED: Cannot commit increments with invalid completion${NC}"
+  echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo ""
+  echo -e "${YELLOW}Why this matters:${NC}"
+  echo "  • Prevents false completion (status='completed' with open work)"
+  echo "  • Ensures data integrity (metadata matches reality)"
+  echo "  • Stops misleading status line and GitHub sync"
+  echo ""
+  echo -e "${YELLOW}To fix:${NC}"
+  echo "  1. Complete all open ACs and pending tasks, OR"
+  echo "  2. Change status to 'active'/'paused' in spec.md and metadata.json"
+  echo ""
+  echo -e "${YELLOW}To bypass (NOT RECOMMENDED):${NC}"
+  echo "  git commit --no-verify"
+  echo ""
+  exit 1
+fi
+
+# All validations passed
+echo -e "${GREEN}✅ Completion validation passed${NC}"
+exit 0

package/plugins/specweave/skills/brownfield-analyzer/SKILL.md

@@ -20,9 +20,10 @@ description: Analyzes existing brownfield projects to map documentation structur
 3. **Classify Documents** - Identify PRD, HLD, ADR, Spec, Runbook candidates
 4. **Detect External Tools** - Find Jira, ADO, GitHub project references
 5. **Analyze Diagrams** - Identify architecture diagrams (PNG, SVG, drawio)
-6. **Generate Migration Plan** - Create actionable migration plan with effort estimate
-7. **Suggest Increment Mapping** - Map Jira Epics/ADO Features to SpecWeave Increments
-8. **Support Two Paths** - Quick Start (incremental) OR Comprehensive (upfront) 🆕
+6. **Discover Coding Standards** - Auto-detect naming conventions, patterns, linting rules 🆕
+7. **Generate Migration Plan** - Create actionable migration plan with effort estimate
+8. **Suggest Increment Mapping** - Map Jira Epics/ADO Features to SpecWeave Increments
+9. **Support Two Paths** - Quick Start (incremental) OR Comprehensive (upfront) 🆕
 
 ---
 
@@ -336,6 +337,42 @@ build/**
 - PNG/DrawIO → Suggest Mermaid conversion
 - Estimate: 15-30 minutes per diagram
 
+### Step 4.5: Coding Standards Discovery 🆕
+
+**Auto-detect coding standards from codebase** using code-standards-detective agent.
+
+**Execution**:
+```bash
+# Run during brownfield analysis (automatic)
+# Or manually: /specweave:analyze-standards
+```
+
+**What it discovers**:
+1. **Explicit Standards** - Parse ESLint, Prettier, TypeScript, EditorConfig
+2. **Implicit Standards** - Analyze naming conventions (98% camelCase?), import patterns, function styles
+3. **Anti-Patterns** - Detect console.* usage, hardcoded secrets, large files (>500 lines)
+4. **Type Safety** - Count `any` usage, interface vs type preference
+5. **Error Handling** - Analyze try/catch patterns, custom error classes
+
+**Statistical Analysis**:
+- Confidence levels (HIGH 90%+, MEDIUM 70-89%, LOW 50-69%)
+- Real code examples from codebase
+- Inconsistency warnings
+
+**Output**:
+```
+.specweave/docs/internal/governance/coding-standards-analysis.md
+```
+
+**Benefits**:
+- ✅ New contributors understand project conventions immediately
+- ✅ Documents "tribal knowledge" that only exists in code
+- ✅ Detects security issues (hardcoded secrets, missing validation)
+- ✅ Provides baseline for code quality improvements
+- ✅ Identifies technical debt (large functions, missing error handling)
+
+**Integration**: This step runs automatically during brownfield analysis, providing coding standards context alongside documentation structure.
+
 ### Step 5: Effort Estimation
 
 **Calculate total effort**: