specweave 0.28.17 → 0.28.20

package/plugins/specweave-ado/lib/ado-status-sync.ts

@@ -18,6 +18,7 @@ import axios, { AxiosInstance } from 'axios';
  */
 export interface ExternalStatus {
   state: string; // e.g., "New", "Active", "Closed"
+  tags?: string[]; // Status tags from config (e.g., ["Planning"], ["In Progress"])
 }
 
 /**
@@ -69,16 +70,17 @@ export class AdoStatusSync {
   }
 
   /**
-   * Update ADO work item state
+   * Update ADO work item state and tags
    *
-   * Uses JSON Patch format to update System.State field.
+   * Uses JSON Patch format to update System.State and System.Tags fields.
+   * Tags are appended to existing tags, not replaced.
    *
    * @param workItemId - ADO work item ID (e.g., 123)
-   * @param status - Desired status
+   * @param status - Desired status with state and optional tags
    */
   async updateStatus(workItemId: number, status: ExternalStatus): Promise<void> {
     // ADO uses JSON Patch format for updates
-    const patch = [
+    const patch: Array<{ op: string; path: string; value: string }> = [
       {
         op: 'add',
         path: '/fields/System.State',
@@ -86,12 +88,54 @@ export class AdoStatusSync {
       }
     ];
 
+    // Add status tags if provided
+    if (status.tags && status.tags.length > 0) {
+      // Fetch current tags to preserve them
+      const currentTags = await this.getCurrentTags(workItemId);
+
+      // Remove old status tags (tags that match known status patterns)
+      const statusTagPatterns = ['Planning', 'In Progress', 'Paused', 'Completed', 'Abandoned', 'On Hold'];
+      const preservedTags = currentTags.filter(
+        tag => !statusTagPatterns.some(pattern => tag.toLowerCase() === pattern.toLowerCase())
+      );
+
+      // Combine preserved tags with new status tags
+      const allTags = [...new Set([...preservedTags, ...status.tags])];
+
+      patch.push({
+        op: 'add',
+        path: '/fields/System.Tags',
+        value: allTags.join('; ')
+      });
+    }
+
     await this.client.patch(
       `/wit/workitems/${workItemId}?api-version=7.0`,
       patch
     );
   }
 
+  /**
+   * Get current tags from ADO work item
+   *
+   * @param workItemId - ADO work item ID
+   * @returns Array of current tags
+   */
+  private async getCurrentTags(workItemId: number): Promise<string[]> {
+    try {
+      const response = await this.client.get(
+        `/wit/workitems/${workItemId}?api-version=7.0&$select=System.Tags`
+      );
+
+      const tagsString = response.data.fields?.['System.Tags'] || '';
+      if (!tagsString) return [];
+
+      return tagsString.split(';').map((tag: string) => tag.trim()).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
   /**
    * Post comment about status change to ADO work item
    *

package/plugins/specweave-alternatives/skills/architecture-alternatives/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: architecture-alternatives
 description: Software architecture patterns and alternatives expert. Covers monolith vs microservices, serverless, event-driven, CQRS, hexagonal architecture, clean architecture, DDD, and architecture decision frameworks. Activates for architecture patterns, monolith, microservices, serverless, event-driven, CQRS, hexagonal architecture, clean architecture, DDD, architecture decisions, system design, scalability patterns.
+allowed-tools: Read, Grep, Glob
 ---
 
 # Architecture Alternatives Expert Skill

package/plugins/specweave-alternatives/skills/bmad-method/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: bmad-method
 description: BMAD (Best, Most Appropriate, Design) technology decision framework expert. Helps evaluate technology alternatives, analyze tradeoffs, calculate TCO, assess vendor lock-in, and make data-driven architecture decisions. Activates for technology choices, stack decisions, database selection, cloud provider comparison, framework evaluation, architecture decisions, BMAD, best practices, most appropriate, design decisions, technology tradeoffs.
+allowed-tools: Read, Grep, Glob
 ---
 
 # BMAD Method Expert Skill

package/plugins/specweave-core/skills/code-quality/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: code-quality
 description: Expert code quality engineering covering clean code principles, SOLID, DRY, KISS, YAGNI, code smells, refactoring patterns, static analysis, linting, code coverage, mutation testing, and software craftsmanship. Activates for code quality, clean code, SOLID principles, code smells, refactoring, technical debt, code review, linting, eslint, prettier, static analysis, code coverage.
+allowed-tools: Read, Grep, Glob
 ---
 
 # Code Quality Expert

package/plugins/specweave-core/skills/design-patterns/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: design-patterns
 description: Expert knowledge of Gang of Four (GoF) design patterns including creational (Singleton, Factory, Builder, Prototype), structural (Adapter, Decorator, Proxy, Facade), and behavioral (Strategy, Observer, Command, Template Method, Chain of Responsibility). Modern TypeScript/JavaScript implementations with real-world use cases. Activates for design patterns, factory pattern, singleton, strategy pattern, observer pattern, decorator pattern, adapter pattern, builder pattern, proxy pattern, facade pattern, template method.
+allowed-tools: Read, Grep, Glob
 ---
 
 # Design Patterns Expert

package/plugins/specweave-core/skills/software-architecture/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: software-architecture
 description: Expert software architecture covering architectural patterns (microservices, monolith, event-driven, CQRS), scalability, distributed systems, CAP theorem, database architecture, API design, system design, domain-driven design (DDD), hexagonal architecture, and architecture decision records (ADRs). Activates for software architecture, system design, microservices, monolith, event-driven, CQRS, scalability, distributed systems, CAP theorem, DDD, hexagonal architecture, ADR.
+allowed-tools: Read, Grep, Glob
 ---
 
 # Software Architecture Expert

package/plugins/specweave-github/commands/specweave-github-cleanup-duplicates.md

@@ -1,6 +1,6 @@
 ---
 name: specweave-github:cleanup-duplicates
-description: Clean up duplicate GitHub issues for an Epic. Finds issues with duplicate titles and closes all except the first created issue.
+description: Clean up duplicate GitHub issues for a Feature. Finds issues with duplicate titles and closes all except the first created issue.
 justification: |
   CRITICAL INCIDENT RESPONSE TOOL - DO NOT DELETE!
 
@@ -193,33 +193,37 @@ The original issue (#250) contains the same content and should be used for track
 
 ## Related Commands
 
-- `/specweave-github:sync-epic` - Sync Epic (now with duplicate detection!)
+- `/specweave-github:sync` - Sync Feature to GitHub (with duplicate detection)
 - `/specweave:validate` - Validate increment completeness
 - `gh issue list` - View all issues (GitHub CLI)
 
 ## Implementation
 
-**File**: `plugins/specweave-github/lib/github-epic-sync.ts`
+**File**: `plugins/specweave-github/lib/duplicate-detector.ts`
 
-**Method**: `cleanupDuplicates(epicId: string, dryRun: boolean)`
+**Class**: `DuplicateDetector`
 
-**Algorithm**:
-1. Search GitHub for all issues with Epic ID
+**Algorithm** (3-phase protection):
+1. **Detection**: Search GitHub for existing issues matching pattern
+2. **Verification**: Count check to detect duplicates after creation
+3. **Reflection**: Auto-close duplicates automatically
+
+For manual cleanup:
+1. Search GitHub for all issues with Feature ID
 2. Group by title (Map<string, number[]>)
 3. Filter groups with >1 issue (duplicates)
 4. For each duplicate group:
    - Keep first issue (lowest number)
    - Close others with gh CLI
-5. Update Epic README frontmatter
 
 ## Next Steps
 
 After cleanup:
 
 1. **Verify cleanup**: `gh issue list --search "[FS-031]"`
-2. **Check Epic README**: Verify frontmatter has correct issue numbers
-3. **Re-run sync**: `/specweave-github:sync-epic FS-031` (should show no duplicates)
-4. **Enable duplicate detection**: Already enabled in v0.18.0+
+2. **Check Feature FEATURE.md**: Verify frontmatter has correct issue numbers
+3. **Re-run sync**: `/specweave-github:sync` (should show no duplicates)
+4. **Duplicate detection**: Automatically enabled via DuplicateDetector
 
 ---
 

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

@@ -5,6 +5,63 @@ description: Synchronize SpecWeave increment with GitHub issue (Multi-Project Su
 
 # Sync Increment with GitHub Issue (Multi-Project)
 
+## ⚠️ CRITICAL: Sync Routing (Read First!)
+
+**Before executing ANY sync, you MUST determine the correct sync path:**
+
+### Step 0: Detect Project Structure
+
+```bash
+# Check for living docs structure
+if [ -d ".specweave/docs/internal/specs" ] && [ -n "$(ls -A .specweave/docs/internal/specs/*/FEATURE.md 2>/dev/null)" ]; then
+    echo "✅ Living docs found → Use Feature Sync"
+else
+    echo "⚠️ No living docs → Use Increment Sync (brownfield)"
+fi
+```
+
+### Sync Path Decision:
+
+| Structure | Command | Issue Format |
+|-----------|---------|--------------|
+| **Living docs exist** (`.specweave/docs/internal/specs/FS-XXX/`) | Use `github-feature-sync-cli.ts` | `[FS-XXX][US-YYY] Title` |
+| **Increment only** (brownfield, no living docs) | Use `github-increment-sync-cli.ts` | `[FS-XXX] Title` with ACs |
+
+### For Brownfield Projects (No Living Docs):
+
+Use the Increment Sync CLI directly:
+
+```bash
+# Set token
+export GITHUB_TOKEN=$(grep GITHUB_TOKEN .env | cut -d'=' -f2)
+
+# Run increment sync
+node dist/plugins/specweave-github/lib/github-increment-sync-cli.js <increment-id>
+
+# Example
+node dist/plugins/specweave-github/lib/github-increment-sync-cli.js 0002
+```
+
+This creates issues with:
+- ✅ Proper format: `[FS-002] Increment Title`
+- ✅ User Stories listed with checkbox headers
+- ✅ All ACs as checkable items
+- ✅ Links to increment files
+
+### For Projects with Living Docs:
+
+Use the Feature Sync CLI:
+
+```bash
+# Run feature sync
+node dist/plugins/specweave-github/lib/github-feature-sync-cli.js <feature-id>
+
+# Example
+node dist/plugins/specweave-github/lib/github-feature-sync-cli.js FS-062
+```
+
+---
+
 Synchronize the current state of a SpecWeave increment with its GitHub issue across multiple repositories. Supports multi-profile management, time range filtering, and rate limit protection.
 
 ## Usage

package/plugins/specweave-github/hooks/.specweave/logs/hooks-debug.log

@@ -1162,3 +1162,77 @@
 [Wed Nov 26 01:29:07 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
 [Wed Nov 26 01:29:07 EST 2025] [GitHub] 🔗 GitHub sync hook fired
 [Wed Nov 26 01:29:07 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 02:36:06 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:25:15 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:25:15 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:25:15 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:25:15 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:25:16 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:25:16 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:27:50 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:27:50 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:27:50 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:27:50 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:27:50 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:27:50 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:12 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:12 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:12 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:12 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:12 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:12 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:12 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:12 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:13 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:13 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:13 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:13 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:13 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:13 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:13 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:13 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:22 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:22 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:22 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:22 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:47:22 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:47:22 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:52:20 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:52:20 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:52:20 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:52:20 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 03:52:20 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 03:52:20 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 08:47:37 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 08:47:37 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 08:47:37 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 08:47:37 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 08:47:37 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 08:47:37 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 08:50:09 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 08:50:09 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 08:50:09 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 08:50:09 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 08:50:09 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 08:50:09 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 08:52:35 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 08:52:35 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 08:52:35 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 08:52:35 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 08:52:36 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 08:52:36 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 12:29:20 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 12:29:20 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 12:29:21 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 12:29:21 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Wed Nov 26 12:29:21 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Wed Nov 26 12:29:21 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync

package/plugins/specweave-github/lib/github-feature-sync.ts

@@ -1,18 +1,13 @@
 /**
  * GitHub Feature Sync - Universal Hierarchy Implementation
  *
- * Architecture (CORRECT):
- * - Feature (FS-033) → GitHub Milestone (Container)
- * - User Story (US-001, US-002, etc.) → GitHub Issue (Trackable item)
- * - Tasks (T-001, T-002, etc.) → Checkboxes in User Story issue body
+ * Architecture:
+ * - Feature (FS-XXX) → GitHub Milestone (Container)
+ * - User Story (US-XXX) → GitHub Issue with format [FS-XXX][US-YYY] Title
+ * - Tasks (T-XXX) → Checkboxes in User Story issue body
  *
- * This implements the TRUE Universal Hierarchy architecture for GitHub.
- *
- * Key Differences from old github-epic-sync.ts:
- * - ❌ OLD: Feature/Increment → GitHub Issue (WRONG!)
- * - ✅ NEW: User Story → GitHub Issue (CORRECT!)
- * - ✅ Creates ONE issue PER user story file (not one per increment)
- * - ✅ Reads us-*.md files from specs/{project}/FS-XXX/
+ * This implements the Universal Hierarchy architecture for GitHub sync.
+ * Creates ONE issue PER user story file from specs/{project}/FS-XXX/us-*.md
  */
 
 import { readdir, readFile, writeFile } from 'fs/promises';