specweave 0.17.15 → 0.18.0

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

@@ -1,26 +1,18 @@
 #!/usr/bin/env bash
 #
-# update-status-line.sh
+# update-status-line.sh (Simplified)
 #
-# Updates the status line cache with current increment progress.
-# Called by post-task-completion hook.
+# Updates status line cache with current increment progress.
+# Shows: [increment-name] ████░░░░ X/Y tasks (Z open)
 #
-# Performance: 10-50ms (runs async in hook, user doesn't wait)
+# Logic:
+# 1. Scan all metadata.json for status=active/in-progress/planning
+# 2. Take first (oldest) as current increment
+# 3. Count all active/in-progress/planning as openCount
+# 4. Parse current increment's tasks.md for progress
+# 5. Write to cache
 #
-# Cache format (.specweave/state/status-line.json):
-# {
-#   "incrementId": "0017-sync-architecture-fix",
-#   "incrementName": "sync-architecture-fix",
-#   "totalTasks": 30,
-#   "completedTasks": 15,
-#   "percentage": 50,
-#   "currentTask": {
-#     "id": "T-016",
-#     "title": "Update documentation"
-#   },
-#   "lastUpdate": "2025-11-10T15:30:00Z",
-#   "lastModified": 1699632600
-# }
+# Performance: 50-100ms (runs async, user doesn't wait)
 
 set -euo pipefail
 
@@ -39,126 +31,102 @@ find_project_root() {
 
 PROJECT_ROOT=$(find_project_root)
 CACHE_FILE="$PROJECT_ROOT/.specweave/state/status-line.json"
-STATE_FILE="$PROJECT_ROOT/.specweave/state/active-increment.json"
+INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
+TMP_FILE="$PROJECT_ROOT/.specweave/state/.status-line-tmp.txt"
 
 # Ensure state directory exists
 mkdir -p "$PROJECT_ROOT/.specweave/state"
 
-# Check if there's an active increment
-if [[ ! -f "$STATE_FILE" ]]; then
-  # No active increment = clear cache
-  echo '{}' > "$CACHE_FILE"
-  exit 0
-fi
+# Step 1: Find all open increments (active/in-progress/planning)
+# Write to temp file: "timestamp increment_id"
+> "$TMP_FILE"
 
-# Get active increment ID
-INCREMENT_ID=$(jq -r '.id // empty' "$STATE_FILE" 2>/dev/null || echo "")
-if [[ -z "$INCREMENT_ID" ]]; then
-  echo '{}' > "$CACHE_FILE"
-  exit 0
+if [[ -d "$INCREMENTS_DIR" ]]; then
+  for metadata in "$INCREMENTS_DIR"/*/metadata.json; do
+    if [[ -f "$metadata" ]]; then
+      status=$(jq -r '.status // ""' "$metadata" 2>/dev/null || echo "")
+
+      # Check if increment is open (active, in-progress, or planning)
+      if [[ "$status" == "active" ]] || [[ "$status" == "in-progress" ]] || [[ "$status" == "planning" ]]; then
+        increment_id=$(basename "$(dirname "$metadata")")
+        created=$(jq -r '.created // ""' "$metadata" 2>/dev/null || echo "1970-01-01T00:00:00Z")
+
+        # Write to temp file
+        echo "$created $increment_id" >> "$TMP_FILE"
+      fi
+    fi
+  done
 fi
 
-TASKS_FILE="$PROJECT_ROOT/.specweave/increments/$INCREMENT_ID/tasks.md"
+# Step 2: Count open increments
+OPEN_COUNT=$(wc -l < "$TMP_FILE" | tr -d ' ')
 
-# No tasks file yet? (Planning phase)
-if [[ ! -f "$TASKS_FILE" ]]; then
-  echo '{}' > "$CACHE_FILE"
+if [[ $OPEN_COUNT -eq 0 ]]; then
+  # No open increments
+  jq -n '{
+    current: null,
+    openCount: 0,
+    lastUpdate: (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
+  }' > "$CACHE_FILE"
+  rm -f "$TMP_FILE"
   exit 0
 fi
 
-# Get tasks.md mtime for invalidation detection
-if [[ "$OSTYPE" == "darwin"* ]]; then
-  # macOS
-  MTIME=$(stat -f %m "$TASKS_FILE" 2>/dev/null || echo 0)
-else
-  # Linux
-  MTIME=$(stat -c %Y "$TASKS_FILE" 2>/dev/null || echo 0)
-fi
+# Step 3: Sort by timestamp (oldest first) and take first
+CURRENT_INCREMENT=$(sort "$TMP_FILE" | head -1 | awk '{print $2}')
 
-# Parse tasks.md (THIS is the slow part: 10-50ms)
-# Support both ## T- and ### T- formats (flexible task heading levels)
-TOTAL_TASKS=$(grep -cE '^##+ T-' "$TASKS_FILE" 2>/dev/null || echo 0)
+# Clean up temp file
+rm -f "$TMP_FILE"
 
-# Remove any whitespace/newlines and ensure integer
-TOTAL_TASKS=$(echo "$TOTAL_TASKS" | tr -d '\n\r ' | grep -E '^[0-9]+$' || echo 0)
+# Step 4: Parse current increment's tasks.md for progress
+TASKS_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/tasks.md"
+TOTAL_TASKS=0
+COMPLETED_TASKS=0
+PERCENTAGE=0
 
-# Support both checkbox formats:
-# 1. Standard: [x] at line start
-# 2. Inline: **Status**: [x] (in task body)
-COMPLETED_TASKS_STANDARD=$(grep -c '^\[x\]' "$TASKS_FILE" 2>/dev/null || echo 0)
-COMPLETED_TASKS_INLINE=$(grep -c 'Status\*\*: \[x\]' "$TASKS_FILE" 2>/dev/null || echo 0)
+if [[ -f "$TASKS_FILE" ]]; then
+  # Count total tasks (## T- or ### T- headings)
+  TOTAL_TASKS=$(grep -cE '^##+ T-' "$TASKS_FILE" 2>/dev/null || echo 0)
+  TOTAL_TASKS=$(echo "$TOTAL_TASKS" | tr -d '\n\r ' || echo 0)
 
-# Remove any whitespace/newlines and ensure integer
-COMPLETED_TASKS_STANDARD=$(echo "$COMPLETED_TASKS_STANDARD" | tr -d '\n\r ' | grep -E '^[0-9]+$' || echo 0)
-COMPLETED_TASKS_INLINE=$(echo "$COMPLETED_TASKS_INLINE" | tr -d '\n\r ' | grep -E '^[0-9]+$' || echo 0)
+  # Count completed tasks (both checkbox formats)
+  # Format 1: [x] at line start
+  COMPLETED_STANDARD=$(grep -c '^\[x\]' "$TASKS_FILE" 2>/dev/null || echo 0)
+  COMPLETED_STANDARD=$(echo "$COMPLETED_STANDARD" | tr -d '\n\r ' || echo 0)
 
-COMPLETED_TASKS=$((COMPLETED_TASKS_STANDARD + COMPLETED_TASKS_INLINE))
+  # Format 2: **Status**: [x] inline
+  COMPLETED_INLINE=$(grep -c '\*\*Status\*\*: \[x\]' "$TASKS_FILE" 2>/dev/null || echo 0)
+  COMPLETED_INLINE=$(echo "$COMPLETED_INLINE" | tr -d '\n\r ' || echo 0)
 
-# Calculate percentage
-if [[ "$TOTAL_TASKS" -gt 0 ]]; then
-  PERCENTAGE=$(( COMPLETED_TASKS * 100 / TOTAL_TASKS ))
-else
-  PERCENTAGE=0
-fi
+  COMPLETED_TASKS=$((COMPLETED_STANDARD + COMPLETED_INLINE))
 
-# Find current task (first incomplete task)
-# Strategy: Find first [ ] checkbox (either format), then get the task heading above it
-# Try standard format first (checkbox at line start)
-CURRENT_TASK_LINE=$(grep -B1 '^\[ \]' "$TASKS_FILE" 2>/dev/null | grep -E '^##+ T-' | head -1 || echo "")
-
-# If not found, try inline format (**Status**: [ ])
-if [[ -z "$CURRENT_TASK_LINE" ]]; then
-  # Find line with **Status**: [ ], then look backward for task heading
-  TASK_LINE_NUM=$(grep -n '\*\*Status\*\*: \[ \]' "$TASKS_FILE" 2>/dev/null | head -1 | cut -d: -f1 || echo "")
-  if [[ -n "$TASK_LINE_NUM" ]]; then
-    # Get lines before the status line and find the task heading
-    CURRENT_TASK_LINE=$(head -n "$TASK_LINE_NUM" "$TASKS_FILE" | grep -E '^##+ T-' | tail -1 || echo "")
+  # Calculate percentage
+  if [[ $TOTAL_TASKS -gt 0 ]]; then
+    PERCENTAGE=$((COMPLETED_TASKS * 100 / TOTAL_TASKS))
   fi
 fi
-CURRENT_TASK_ID=""
-CURRENT_TASK_TITLE=""
-
-if [[ -n "$CURRENT_TASK_LINE" ]]; then
-  # Extract task ID (T-NNN)
-  CURRENT_TASK_ID=$(echo "$CURRENT_TASK_LINE" | grep -o 'T-[0-9][0-9]*' || echo "")
-
-  # Extract task title (after "## T-NNN: ")
-  # Use parameter expansion to remove prefix
-  TEMP="${CURRENT_TASK_LINE#*: }"
-  CURRENT_TASK_TITLE=$(echo "$TEMP" | head -c 50)
-fi
 
-# Extract increment name (remove leading 4-digit number and dash)
-INCREMENT_NAME=$(echo "$INCREMENT_ID" | sed 's/^[0-9]\{4\}-//')
-
-# Build current task JSON
-if [[ -n "$CURRENT_TASK_ID" ]]; then
-  CURRENT_TASK_JSON=$(jq -n \
-    --arg id "$CURRENT_TASK_ID" \
-    --arg title "$CURRENT_TASK_TITLE" \
-    '{id: $id, title: $title}')
-else
-  CURRENT_TASK_JSON="null"
-fi
+# Step 5: Extract increment name (remove 4-digit prefix)
+INCREMENT_NAME=$(echo "$CURRENT_INCREMENT" | sed 's/^[0-9]\{4\}-//')
 
-# Write cache atomically using jq
+# Step 6: Write cache
 jq -n \
-  --arg id "$INCREMENT_ID" \
+  --arg id "$CURRENT_INCREMENT" \
   --arg name "$INCREMENT_NAME" \
-  --argjson total "$TOTAL_TASKS" \
   --argjson completed "$COMPLETED_TASKS" \
+  --argjson total "$TOTAL_TASKS" \
   --argjson percentage "$PERCENTAGE" \
-  --argjson task "$CURRENT_TASK_JSON" \
-  --argjson mtime "$MTIME" \
+  --argjson openCount "$OPEN_COUNT" \
   '{
-    incrementId: $id,
-    incrementName: $name,
-    totalTasks: $total,
-    completedTasks: $completed,
-    percentage: $percentage,
-    currentTask: $task,
-    lastUpdate: (now | strftime("%Y-%m-%dT%H:%M:%SZ")),
-    lastModified: $mtime
+    current: {
+      id: $id,
+      name: $name,
+      completed: $completed,
+      total: $total,
+      percentage: $percentage
+    },
+    openCount: $openCount,
+    lastUpdate: (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
   }' > "$CACHE_FILE"
 
 exit 0

package/plugins/specweave/hooks/post-increment-planning.sh

@@ -396,15 +396,31 @@ create_github_issue() {
     return 1
   fi
 
-  # Extract increment number from ID (e.g., "0016-self-reflection-system" -> "0016")
-  local inc_number=$(echo "$increment_id" | grep -o '^[0-9]*')
+  # Extract creation date from metadata.json and format as FS-YY-MM-DD
+  local issue_prefix="FS-UNKNOWN"
+  if [ -f "$metadata_file" ]; then
+    # Extract created date (format: "2025-11-12T12:46:00Z")
+    local created_date=$(cat "$metadata_file" 2>/dev/null | grep -o '"created"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([^"]*\)".*/\1/')
+    if [ -n "$created_date" ]; then
+      # Extract YY-MM-DD from date (e.g., "2025-11-12" -> "25-11-12")
+      local year=$(echo "$created_date" | cut -d'-' -f1 | cut -c3-4)  # "2025" -> "25"
+      local month=$(echo "$created_date" | cut -d'-' -f2)              # "11"
+      local day=$(echo "$created_date" | cut -d'-' -f3 | cut -d'T' -f1) # "12T..." -> "12"
+      issue_prefix="FS-${year}-${month}-${day}"
+      log_debug "Using date-based prefix from metadata: $issue_prefix"
+    else
+      log_debug "No created date in metadata, using fallback"
+    fi
+  else
+    log_debug "No metadata.json found, using fallback prefix"
+  fi
 
   log_debug "Creating issue for repo: $repo"
-  log_debug "Title: [INC-$inc_number] $title"
+  log_debug "Title: [$issue_prefix] $title"
 
   # Generate issue body
   local issue_body=$(cat <<EOF
-# [INC-$inc_number] $title
+# [$issue_prefix] $title
 
 **Status**: Planning → Implementation
 **Priority**: P1
@@ -436,43 +452,65 @@ EOF
   local temp_body=$(mktemp)
   echo "$issue_body" > "$temp_body"
 
-  # Create GitHub issue
-  log_debug "Calling gh issue create..."
+  # Create GitHub issue with FULL DUPLICATE PROTECTION
+  log_debug "Creating issue with DuplicateDetector (global protection)..."
 
-  local gh_output=$(gh issue create \
+  # Call Node.js wrapper script with DuplicateDetector
+  local node_output=$(node scripts/create-github-issue-with-protection.js \
+    --title "[$issue_prefix] $title" \
+    --body "$issue_body" \
+    --pattern "[$issue_prefix]" \
+    --labels "specweave,increment" \
     --repo "$repo" \
-    --title "[INC-$inc_number] $title" \
-    --body-file "$temp_body" \
-    --label "specweave,increment" \
     2>&1)
 
-  local gh_status=$?
+  local node_status=$?
 
   # Clean up temp file
   rm -f "$temp_body"
 
-  if [ $gh_status -ne 0 ]; then
-    log_error "gh issue create failed: $gh_output"
+  if [ $node_status -ne 0 ]; then
+    log_error "DuplicateDetector failed: $node_output"
     return 1
   fi
 
-  # Extract issue number from output (format: "https://github.com/owner/repo/issues/123")
-  local issue_number=$(echo "$gh_output" | grep -o '/issues/[0-9]*' | grep -o '[0-9]*')
-  local issue_url=$(echo "$gh_output" | grep 'https://github.com')
+  # Parse JSON output using jq (if available) or fallback to grep
+  local issue_number=""
+  local issue_url=""
+  local duplicates_found=0
+  local duplicates_closed=0
+  local was_reused="false"
+
+  if command -v jq >/dev/null 2>&1; then
+    issue_number=$(echo "$node_output" | jq -r '.issue.number')
+    issue_url=$(echo "$node_output" | jq -r '.issue.url')
+    duplicates_found=$(echo "$node_output" | jq -r '.duplicatesFound // 0')
+    duplicates_closed=$(echo "$node_output" | jq -r '.duplicatesClosed // 0')
+    was_reused=$(echo "$node_output" | jq -r '.wasReused // false')
+  else
+    # Fallback: grep-based parsing
+    issue_number=$(echo "$node_output" | grep -o '"number"[[:space:]]*:[[:space:]]*[0-9]*' | grep -o '[0-9]*')
+    issue_url=$(echo "$node_output" | grep -o '"url"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([^"]*\)".*/\1/')
+  fi
 
   if [ -z "$issue_number" ]; then
-    log_error "Could not extract issue number from gh output: $gh_output"
+    log_error "Could not extract issue number from DuplicateDetector output"
+    log_debug "Output was: $node_output"
     return 1
   fi
 
-  if [ -z "$issue_url" ]; then
-    # Construct URL manually if extraction failed
-    issue_url="https://github.com/$repo/issues/$issue_number"
+  # Log results with duplicate detection info
+  if [ "$was_reused" = "true" ]; then
+    log_info "  ♻️  Using existing issue #$issue_number (duplicate prevention)"
+  else
+    log_info "  📝 Issue #$issue_number created"
   fi
-
-  log_info "  📝 Issue #$issue_number created"
   log_info "  🔗 $issue_url"
 
+  if [ "$duplicates_found" -gt 0 ]; then
+    log_info "  🛡️  Duplicates detected: $duplicates_found (auto-closed: $duplicates_closed)"
+  fi
+
   # Create or update metadata.json
   local current_timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
@@ -658,21 +696,55 @@ EOF
   if [ "$auto_create" = "true" ]; then
     log_info "  📦 Auto-create enabled, checking for GitHub CLI..."
 
-    # Check if gh CLI is available
-    if ! command -v gh >/dev/null 2>&1; then
-      log_info "  ⚠️  GitHub CLI (gh) not found, skipping issue creation"
-      log_debug "Install: https://cli.github.com/"
-    else
-      log_info "  ✓ GitHub CLI found"
-      log_info ""
-      log_info "🚀 Creating GitHub issue for $increment_id..."
+    # ============================================================================
+    # DUPLICATE DETECTION (v0.14.1+)
+    # ============================================================================
+    # Check if GitHub issue already exists in metadata.json
+    # If exists, skip creation (idempotent operation)
+
+    local metadata_file="$increment_dir/metadata.json"
+    local existing_issue=""
+
+    if [ -f "$metadata_file" ]; then
+      # Extract existing GitHub issue number from metadata
+      existing_issue=$(cat "$metadata_file" 2>/dev/null | \
+        grep -o '"github"[[:space:]]*:[[:space:]]*{[^}]*"issue"[[:space:]]*:[[:space:]]*[0-9]*' | \
+        grep -o '[0-9]*$')
+
+      if [ -n "$existing_issue" ]; then
+        log_info "  ✅ GitHub issue already exists: #$existing_issue"
+        log_info "  ⏭️  Skipping creation (idempotent)"
+        log_debug "Metadata already contains github.issue = $existing_issue"
+
+        # Extract URL if available
+        local existing_url=$(cat "$metadata_file" 2>/dev/null | \
+          grep -o '"url"[[:space:]]*:[[:space:]]*"[^"]*"' | \
+          sed 's/.*"\([^"]*\)".*/\1/')
+
+        if [ -n "$existing_url" ]; then
+          log_info "  🔗 $existing_url"
+        fi
+      fi
+    fi
 
-      # Create issue (non-blocking)
-      if create_github_issue "$increment_id" "$increment_dir"; then
-        log_info "  ✅ GitHub issue created successfully"
+    # Only create if no existing issue found
+    if [ -z "$existing_issue" ]; then
+      # Check if gh CLI is available
+      if ! command -v gh >/dev/null 2>&1; then
+        log_info "  ⚠️  GitHub CLI (gh) not found, skipping issue creation"
+        log_debug "Install: https://cli.github.com/"
       else
-        log_info "  ⚠️  GitHub issue creation failed (non-blocking)"
-        log_debug "Issue creation failed, but continuing execution"
+        log_info "  ✓ GitHub CLI found"
+        log_info ""
+        log_info "🚀 Creating GitHub issue for $increment_id..."
+
+        # Create issue (non-blocking)
+        if create_github_issue "$increment_id" "$increment_dir"; then
+          log_info "  ✅ GitHub issue created successfully"
+        else
+          log_info "  ⚠️  GitHub issue creation failed (non-blocking)"
+          log_debug "Issue creation failed, but continuing execution"
+        fi
       fi
     fi
   else

package/plugins/specweave/lib/hooks/sync-living-docs.js

@@ -27,9 +27,10 @@ async function syncLivingDocs(incrementId) {
       specCopied = result.success;
       changedDocs = result.changedFiles;
     } else {
-      console.log("\u{1F4CB} Using simple sync mode (legacy)");
-      specCopied = await copyIncrementSpecToLivingDocs(incrementId);
-      changedDocs = detectChangedDocs();
+      console.log("\u{1F4CA} Using hierarchical distribution mode (v2.1 - Epic + User Stories)");
+      const result = await hierarchicalDistribution(incrementId);
+      specCopied = result.success;
+      changedDocs = result.changedFiles;
     }
     if (changedDocs.length === 0 && !specCopied) {
       console.log("\u2139\uFE0F  No living docs changed");
@@ -43,43 +44,47 @@ async function syncLivingDocs(incrementId) {
   }
 }
 async function intelligentSyncLivingDocs(incrementId, config) {
+  console.log("   \u26A0\uFE0F  Intelligent sync not yet fully implemented");
+  console.log("   Falling back to hierarchical distribution mode...");
+  return await hierarchicalDistribution(incrementId);
+}
+async function hierarchicalDistribution(incrementId) {
   try {
-    const { syncIncrement } = await import("../../../../src/core/living-docs/index.js");
-    console.log("   \u{1F4D6} Parsing and classifying spec sections...");
-    const result = await syncIncrement(incrementId, {
-      verbose: false,
-      // We'll log our own summary
-      dryRun: false,
-      parser: {
-        preserveCodeBlocks: true,
-        preserveLinks: true,
-        preserveImages: true
-      },
-      distributor: {
-        generateFrontmatter: true,
-        preserveOriginal: config.livingDocs?.intelligent?.preserveOriginal ?? true
-      },
-      linker: {
-        generateBacklinks: config.livingDocs?.intelligent?.generateCrossLinks ?? true,
-        updateExisting: true
-      }
+    const { SpecDistributor } = await import("../../../../src/core/living-docs/index.js");
+    console.log("   \u{1F4CA} Parsing and distributing spec into hierarchical structure...");
+    const projectRoot = process.cwd();
+    const distributor = new SpecDistributor(projectRoot, {
+      overwriteExisting: false,
+      createBackups: true
     });
-    console.log(`   \u2705 Intelligent sync complete:`);
-    console.log(`      Project: ${result.project.name} (${(result.project.confidence * 100).toFixed(0)}% confidence)`);
-    console.log(`      Files created: ${result.distribution.summary.filesCreated}`);
-    console.log(`      Files updated: ${result.distribution.summary.filesUpdated}`);
-    console.log(`      Cross-links: ${result.links.length}`);
-    console.log(`      Duration: ${result.duration}ms`);
-    const changedFiles = [
-      ...result.distribution.created.map((f) => f.path),
-      ...result.distribution.updated.map((f) => f.path)
-    ];
+    const result = await distributor.distribute(incrementId);
+    if (!result.success) {
+      console.error(`   \u274C Distribution failed with errors:`);
+      for (const error of result.errors) {
+        console.error(`      - ${error}`);
+      }
+      return { success: false, changedFiles: [] };
+    }
+    console.log(`   \u2705 Hierarchical distribution complete:`);
+    console.log(`      Epic ID: ${result.specId}`);
+    console.log(`      User Stories: ${result.totalStories}`);
+    console.log(`      Files created: ${result.totalFiles}`);
+    console.log(`      Epic: ${path.basename(result.epicPath)}`);
+    console.log(`      User story files: ${result.userStoryPaths.length}`);
+    if (result.warnings.length > 0) {
+      console.log(`   \u26A0\uFE0F  Warnings:`);
+      for (const warning of result.warnings) {
+        console.log(`      - ${warning}`);
+      }
+    }
+    const changedFiles = [result.epicPath, ...result.userStoryPaths];
     return {
-      success: result.success,
+      success: true,
       changedFiles
     };
   } catch (error) {
-    console.error(`   \u274C Intelligent sync failed: ${error}`);
+    console.error(`   \u274C Hierarchical distribution failed: ${error}`);
+    console.error(error.stack);
     console.error("   Falling back to simple sync mode...");
     const copied = await copyIncrementSpecToLivingDocs(incrementId);
     return {
@@ -88,7 +93,107 @@ async function intelligentSyncLivingDocs(incrementId, config) {
     };
   }
 }
+async function extractAndMergeLivingDocs(incrementId) {
+  try {
+    const {
+      parseIncrementSpec,
+      parseLivingDocsSpec,
+      extractSpecId,
+      mergeUserStories,
+      generateRelatedDocsLinks,
+      writeLivingDocsSpec
+    } = await import("../../../../src/utils/spec-parser.js");
+    const projectRoot = process.cwd();
+    const incrementSpecPath = path.join(projectRoot, ".specweave", "increments", incrementId, "spec.md");
+    if (!fs.existsSync(incrementSpecPath)) {
+      console.log(`\u26A0\uFE0F  Increment spec not found: ${incrementSpecPath}`);
+      return false;
+    }
+    console.log(`   \u{1F4D6} Parsing increment spec: ${incrementId}`);
+    const incrementSpec = await parseIncrementSpec(incrementSpecPath);
+    if (incrementSpec.userStories.length === 0) {
+      console.log(`\u2139\uFE0F  No user stories found in increment spec, skipping sync`);
+      return false;
+    }
+    console.log(`   \u2705 Found ${incrementSpec.userStories.length} user stories in increment`);
+    const specId = incrementSpec.implementsSpec || extractSpecId(incrementId);
+    const livingDocsDir = path.join(projectRoot, ".specweave", "docs", "internal", "specs", "default");
+    const livingDocsPath = path.join(livingDocsDir, `${specId}-${incrementId.replace(/^\d+-/, "")}.md`);
+    const livingDocsExists = fs.existsSync(livingDocsPath);
+    if (livingDocsExists) {
+      console.log(`   \u{1F4DA} Living docs spec exists, merging user stories...`);
+      const livingSpec = await parseLivingDocsSpec(livingDocsPath);
+      const mergedStories = mergeUserStories(
+        livingSpec.userStories,
+        incrementSpec.userStories,
+        incrementId
+      );
+      const newStoriesCount = mergedStories.length - livingSpec.userStories.length;
+      const existingEntry = livingSpec.implementationHistory.find((e) => e.increment === incrementId);
+      if (!existingEntry) {
+        livingSpec.implementationHistory.push({
+          increment: incrementId,
+          stories: incrementSpec.userStories.map((s) => s.id),
+          status: "complete",
+          date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+        });
+      } else {
+        existingEntry.status = "complete";
+        existingEntry.date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+      }
+      livingSpec.userStories = mergedStories;
+      livingSpec.lastUpdated = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+      await writeLivingDocsSpec(livingDocsPath, livingSpec);
+      console.log(`   \u2705 Merged ${newStoriesCount} new user stories into living docs`);
+      console.log(`   \u2705 Updated implementation history for ${incrementId}`);
+    } else {
+      console.log(`   \u{1F4DD} Creating new living docs spec: ${specId}`);
+      const relatedDocs = generateRelatedDocsLinks(incrementSpec, projectRoot);
+      const livingSpec = {
+        id: specId,
+        title: incrementSpec.title,
+        featureArea: extractFeatureArea(incrementSpec.title),
+        overview: incrementSpec.overview,
+        userStories: incrementSpec.userStories.map((story) => ({
+          ...story,
+          implementedIn: incrementId,
+          status: "complete"
+        })),
+        implementationHistory: [
+          {
+            increment: incrementId,
+            stories: incrementSpec.userStories.map((s) => s.id),
+            status: "complete",
+            date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+          }
+        ],
+        relatedDocs,
+        externalLinks: {},
+        priority: incrementSpec.priority,
+        status: "active",
+        created: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+        lastUpdated: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+      };
+      await fs.ensureDir(livingDocsDir);
+      await writeLivingDocsSpec(livingDocsPath, livingSpec);
+      console.log(`   \u2705 Created new living docs spec: ${specId}`);
+      console.log(`   \u2705 Added ${incrementSpec.userStories.length} user stories`);
+      console.log(`   \u2705 Generated links to ${relatedDocs.architecture.length} architecture docs`);
+      console.log(`   \u2705 Generated links to ${relatedDocs.adrs.length} ADRs`);
+    }
+    return true;
+  } catch (error) {
+    console.error(`\u274C Error extracting/merging living docs: ${error}`);
+    console.error(error.stack);
+    return false;
+  }
+}
+function extractFeatureArea(title) {
+  return title.replace(/^(Increment \d+:\s*)?/, "").trim();
+}
 async function copyIncrementSpecToLivingDocs(incrementId) {
+  console.warn("\u26A0\uFE0F  Using deprecated copyIncrementSpecToLivingDocs (simple mode)");
+  console.warn("   Consider enabling intelligent mode to avoid duplication");
   try {
     const incrementSpecPath = path.join(process.cwd(), ".specweave", "increments", incrementId, "spec.md");
     const livingDocsPath = path.join(process.cwd(), ".specweave", "docs", "internal", "specs", `spec-${incrementId}.md`);