specweave 0.22.12 → 0.22.14

package/plugins/specweave/lib/hooks/sync-cache.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * Sync Performance Cache Module
+ *
+ * Provides caching layer for living docs sync to meet <500ms target.
+ * Caches:
+ * - Parsed tasks.md content
+ * - File modification timestamps
+ * - US-Task mappings
+ *
+ * Part of increment 0047-us-task-linkage (T-012).
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import crypto from 'crypto';
+
+/**
+ * In-memory cache with TTL
+ */
+class SyncCache {
+  constructor() {
+    this.cache = new Map();
+    this.ttl = 60000; // 60 seconds default TTL
+  }
+
+  /**
+   * Get cached value
+   *
+   * @param {string} key - Cache key
+   * @returns {any|null} Cached value or null if expired/missing
+   */
+  get(key) {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if expired
+    if (Date.now() > entry.expiry) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Set cached value
+   *
+   * @param {string} key - Cache key
+   * @param {any} value - Value to cache
+   * @param {number} ttl - Time to live in milliseconds (optional)
+   */
+  set(key, value, ttl = this.ttl) {
+    this.cache.set(key, {
+      value,
+      expiry: Date.now() + ttl
+    });
+  }
+
+  /**
+   * Invalidate cache entry
+   *
+   * @param {string} key - Cache key
+   */
+  invalidate(key) {
+    this.cache.delete(key);
+  }
+
+  /**
+   * Clear all cache
+   */
+  clear() {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache size
+   *
+   * @returns {number} Number of cached entries
+   */
+  size() {
+    return this.cache.size;
+  }
+}
+
+// Global cache instance
+const globalCache = new SyncCache();
+
+/**
+ * Get file hash for change detection
+ *
+ * @param {string} filePath - Path to file
+ * @returns {string} SHA256 hash of file content
+ */
+export function getFileHash(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return crypto.createHash('sha256').update(content).digest('hex');
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Get cached parsed tasks.md
+ *
+ * @param {string} tasksPath - Path to tasks.md
+ * @param {Function} parser - Parser function to call if cache miss
+ * @returns {any} Parsed tasks (from cache or fresh)
+ */
+export function getCachedTasks(tasksPath, parser) {
+  // Generate cache key from file path + hash
+  const fileHash = getFileHash(tasksPath);
+
+  if (!fileHash) {
+    // File doesn't exist, call parser directly
+    return parser(tasksPath);
+  }
+
+  const cacheKey = `tasks:${tasksPath}:${fileHash}`;
+
+  // Try to get from cache
+  const cached = globalCache.get(cacheKey);
+
+  if (cached) {
+    // Cache hit
+    return cached;
+  }
+
+  // Cache miss - parse and cache
+  const parsed = parser(tasksPath);
+  globalCache.set(cacheKey, parsed);
+
+  return parsed;
+}
+
+/**
+ * Get cached US file metadata
+ *
+ * @param {string} usFilePath - Path to US file
+ * @returns {object|null} Metadata object or null if file doesn't exist
+ */
+export function getCachedUSMetadata(usFilePath) {
+  try {
+    const stats = fs.statSync(usFilePath);
+    const cacheKey = `us-metadata:${usFilePath}`;
+
+    const cached = globalCache.get(cacheKey);
+
+    if (cached && cached.mtime === stats.mtimeMs) {
+      // File hasn't changed, return cached metadata
+      return cached.metadata;
+    }
+
+    // File changed or not in cache - read and cache
+    const content = fs.readFileSync(usFilePath, 'utf-8');
+    const metadata = {
+      mtime: stats.mtimeMs,
+      metadata: {
+        path: usFilePath,
+        size: content.length,
+        tasksSectionExists: content.includes('## Tasks'),
+        acCount: (content.match(/- \[[x ]\] \*\*AC-US\d+-\d{2}\*\*/g) || []).length
+      }
+    };
+
+    globalCache.set(cacheKey, metadata);
+
+    return metadata.metadata;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Batch file operations to reduce I/O
+ *
+ * @param {Array<{path: string, content: string}>} updates - Files to update
+ * @returns {Promise<void>}
+ */
+export async function batchFileUpdates(updates) {
+  // Group updates by directory to optimize disk I/O
+  const updatesByDir = new Map();
+
+  updates.forEach(({ path: filePath, content }) => {
+    const dir = path.dirname(filePath);
+
+    if (!updatesByDir.has(dir)) {
+      updatesByDir.set(dir, []);
+    }
+
+    updatesByDir.get(dir).push({ path: filePath, content });
+  });
+
+  // Write files sequentially within same directory (better disk I/O)
+  for (const [dir, fileUpdates] of updatesByDir.entries()) {
+    // Ensure directory exists once per directory
+    await fs.ensureDir(dir);
+
+    // Write all files in this directory
+    await Promise.all(
+      fileUpdates.map(({ path: filePath, content }) =>
+        fs.writeFile(filePath, content, 'utf-8')
+      )
+    );
+  }
+}
+
+/**
+ * Check if sync is needed for a US file
+ *
+ * @param {string} usFilePath - Path to US file
+ * @param {Array} tasks - Tasks for this US
+ * @param {string} tasksPath - Path to tasks.md
+ * @returns {boolean} True if sync is needed
+ */
+export function needsSync(usFilePath, tasks, tasksPath) {
+  try {
+    // Check if US file exists
+    if (!fs.existsSync(usFilePath)) {
+      return false; // File doesn't exist, can't sync
+    }
+
+    // Get file modification times
+    const usStats = fs.statSync(usFilePath);
+    const tasksStats = fs.statSync(tasksPath);
+
+    // If tasks.md is newer than US file, sync is needed
+    if (tasksStats.mtimeMs > usStats.mtimeMs) {
+      return true;
+    }
+
+    // Check cache for last sync result
+    const cacheKey = `sync-result:${usFilePath}`;
+    const cached = globalCache.get(cacheKey);
+
+    if (cached) {
+      // Compare task list with cached
+      const currentTaskIds = tasks.map(t => t.id).sort().join(',');
+      const cachedTaskIds = cached.taskIds;
+
+      if (currentTaskIds === cachedTaskIds) {
+        // Task list unchanged, no sync needed
+        return false;
+      }
+    }
+
+    // Default: sync is needed
+    return true;
+  } catch (error) {
+    // If error checking, assume sync is needed
+    return true;
+  }
+}
+
+/**
+ * Record sync result for incremental sync
+ *
+ * @param {string} usFilePath - Path to US file
+ * @param {Array} tasks - Tasks that were synced
+ */
+export function recordSync(usFilePath, tasks) {
+  const cacheKey = `sync-result:${usFilePath}`;
+  const taskIds = tasks.map(t => t.id).sort().join(',');
+
+  globalCache.set(cacheKey, {
+    taskIds,
+    timestamp: Date.now()
+  });
+}
+
+/**
+ * Get cache statistics
+ *
+ * @returns {object} Cache stats
+ */
+export function getCacheStats() {
+  return {
+    size: globalCache.size(),
+    entries: Array.from(globalCache.cache.keys())
+  };
+}
+
+/**
+ * Clear cache (for testing)
+ */
+export function clearCache() {
+  globalCache.clear();
+}
+
+export default globalCache;

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

@@ -37,6 +37,23 @@ async function syncLivingDocs(incrementId) {
       return;
     }
     console.log(`\u{1F4C4} Changed/created ${changedDocs.length} file(s)`);
+
+    // ========================================================================
+    // CHECK PERMISSION: canUpdateExternalItems (v0.24.0 - Three-Permission Architecture)
+    // ========================================================================
+    // This permission controls whether SpecWeave can UPDATE externally-created items
+    // (full content: title, description, ACs, tasks, comments).
+    // If false, living docs sync happens locally but doesn't push to external tools.
+    const canUpdateExternal = config.sync?.settings?.canUpdateExternalItems ?? false;
+
+    if (!canUpdateExternal) {
+      console.log("\u2139\uFE0F  GitHub sync skipped (canUpdateExternalItems = false)");
+      console.log("   Living docs updated locally only");
+      console.log("   To enable: Set sync.settings.canUpdateExternalItems = true in config.json");
+      console.log("\u2705 Living docs sync complete (local only)\n");
+      return;
+    }
+
     await syncToGitHub(incrementId, changedDocs);
     console.log("\u2705 Living docs sync complete\n");
   } catch (error) {
@@ -77,6 +94,18 @@ async function hierarchicalDistribution(incrementId) {
     console.log("   \u{1F4CA} Syncing increment to living docs structure...");
     const projectRoot = process.cwd();
 
+    // ========================================================================
+    // USE FEATURE ID FROM ENVIRONMENT (NEW in v0.23.0 - Increment 0047)
+    // ========================================================================
+    // If FEATURE_ID is provided via environment variable (extracted from spec.md),
+    // use it directly instead of auto-generating. This ensures correct traceability.
+    const explicitFeatureId = process.env.FEATURE_ID;
+    if (explicitFeatureId) {
+      console.log(`   \u{1F4CE} Using explicit feature ID from spec.md: ${explicitFeatureId}`);
+    } else {
+      console.log("   \u{1F504} Feature ID will be auto-generated from increment number");
+    }
+
     // Create logger adapter for LivingDocsSync
     const logger = {
       log: (msg) => console.log(`   ${msg}`),
@@ -87,7 +116,9 @@ async function hierarchicalDistribution(incrementId) {
     const sync = new LivingDocsSync(projectRoot, { logger });
     const result = await sync.syncIncrement(incrementId, {
       dryRun: false,
-      force: false
+      force: false,
+      // Pass explicit feature ID if available (v0.23.0+)
+      explicitFeatureId: explicitFeatureId || undefined
     });
 
     if (!result.success) {

package/plugins/specweave/lib/hooks/sync-us-tasks.js

@@ -14,6 +14,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import { parseTasksWithUSLinks, getAllTasks } from '../../../../dist/src/generators/spec/task-parser.js';
 import { glob } from 'glob';
+import { getCachedTasks, needsSync, recordSync, batchFileUpdates } from './sync-cache.js';
 
 /**
  * Sync tasks from tasks.md to living docs User Story files
@@ -36,10 +37,10 @@ export async function syncUSTasksToLivingDocs(incrementId, projectRoot, featureI
       return { success: true, updatedFiles: [], errors: [] };
     }
 
-    // Parse tasks with US linkage
+    // Parse tasks with US linkage (with caching for performance)
     let tasksByUS;
     try {
-      tasksByUS = parseTasksWithUSLinks(tasksPath);
+      tasksByUS = getCachedTasks(tasksPath, parseTasksWithUSLinks);
     } catch (error) {
       console.error(`   ❌ Failed to parse tasks.md:`, error.message);
       return { success: false, updatedFiles: [], errors: [error.message] };
@@ -59,6 +60,7 @@ export async function syncUSTasksToLivingDocs(incrementId, projectRoot, featureI
 
     const updatedFiles = [];
     const errors = [];
+    const filesToUpdate = []; // Batch file updates
 
     // For each User Story with tasks, update its living docs file
     for (const [usId, tasks] of Object.entries(tasksByUS)) {
@@ -73,12 +75,19 @@ export async function syncUSTasksToLivingDocs(incrementId, projectRoot, featureI
           continue;
         }
 
+        // Incremental sync: Check if sync is needed
+        if (!needsSync(usFilePath, tasks, tasksPath)) {
+          console.log(`   ⏭️  ${usId} unchanged, skipping sync`);
+          continue;
+        }
+
         // Update US file with task list
-        const updated = await updateUSFile(usFilePath, tasks, incrementId);
+        const result = await updateUSFile(usFilePath, tasks, incrementId);
 
-        if (updated) {
-          updatedFiles.push(usFilePath);
-          console.log(`   ✓ Updated ${usId} with ${tasks.length} tasks`);
+        if (result.updated) {
+          filesToUpdate.push({ path: usFilePath, content: result.content });
+          recordSync(usFilePath, tasks); // Cache sync result for next run
+          console.log(`   ✓ Prepared update for ${usId} (${tasks.length} tasks)`);
         }
       } catch (error) {
         console.error(`   ❌ Error updating ${usId}:`, error.message);
@@ -86,6 +95,12 @@ export async function syncUSTasksToLivingDocs(incrementId, projectRoot, featureI
       }
     }
 
+    // Batch write all file updates (reduce I/O)
+    if (filesToUpdate.length > 0) {
+      await batchFileUpdates(filesToUpdate);
+      updatedFiles.push(...filesToUpdate.map(f => f.path));
+    }
+
     if (updatedFiles.length > 0) {
       console.log(`   ✅ Updated ${updatedFiles.length} User Story file(s)`);
     } else {
@@ -144,7 +159,7 @@ async function findUSFile(projectRoot, projectId, featureId, usId) {
  * @param {string} usFilePath - Path to US markdown file
  * @param {Array} tasks - Tasks linked to this US
  * @param {string} incrementId - Increment ID
- * @returns {Promise<boolean>} True if file was updated
+ * @returns {Promise<{updated: boolean, content: string}>} Update result
  */
 async function updateUSFile(usFilePath, tasks, incrementId) {
   let content = await fs.readFile(usFilePath, 'utf-8');
@@ -173,12 +188,7 @@ async function updateUSFile(usFilePath, tasks, incrementId) {
     updated = true;
   }
 
-  // Write updated content
-  if (updated) {
-    await fs.writeFile(usFilePath, content, 'utf-8');
-  }
-
-  return updated;
+  return { updated, content };
 }
 
 /**

package/plugins/specweave-ado/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave-ado",
-  "version": "0.1.0",
+  "version": "0.22.14",
   "description": "Azure DevOps integration for SpecWeave - sync increments with ADO work items, track progress, and manage project workflows",
   "author": {
     "name": "SpecWeave Team",

package/plugins/specweave-ado/lib/conflict-resolver.ts

@@ -402,7 +402,7 @@ export async function loadSpecMetadata(specPath: string): Promise<SpecMetadata>
 }
 
 /**
- * Perform bidirectional sync with conflict resolution
+ * Perform three-permission sync with conflict resolution
  */
 export async function performBidirectionalSync(
   specPath: string,

package/plugins/specweave-alternatives/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-alternatives",
   "description": "Compare SpecWeave with BMAD, spec-kit, openspec, and other spec-driven frameworks. Get gap analysis, feature comparison, and strategic recommendations to choose the best framework for your needs.",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-backend/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-backend",
   "description": "Backend API development for Node.js, Python, and .NET stacks. Includes Express, NestJS, FastAPI, Django, Flask, ASP.NET Core, and Entity Framework Core. Focus on REST APIs, authentication, database operations, and background services.",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-confluent/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-confluent",
   "description": "Confluent Cloud integration for SpecWeave - Schema Registry, ksqlDB, Kafka Connect, Flink, stream processing, and enterprise Kafka features",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-cost-optimizer/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-cost-optimizer",
   "description": "Cloud cost optimization and platform comparison. Analyzes infrastructure requirements and recommends cheapest cloud platform (Hetzner, Vercel, AWS, Railway, Fly.io, DigitalOcean). Shows cost breakdown and savings calculations.",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-diagrams/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-diagrams",
   "description": "Architecture diagram generation with Mermaid following C4 Model conventions. Creates C4 Context/Container/Component diagrams, sequence diagrams, ER diagrams, and deployment diagrams. SpecWeave-aware for HLD/LLD documentation.",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-docs/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-docs",
   "description": "Documentation generation and spec-driven workflows. Includes Docusaurus site generation from SpecWeave structure, spec-driven brainstorming for feature ideation, and spec-driven debugging. Focus on living documentation and knowledge management.",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-docs-preview/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-docs-preview",
   "description": "Interactive documentation preview with Docusaurus. Launch local dev server to view living documentation in beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagrams. Build static sites for deployment.",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-figma/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-figma",
   "description": "Design-to-code workflow patterns for Figma (MCP-first). Requires Figma MCP server. Extracts design tokens, generates components (React/Angular/Vue/Svelte), scaffolds tests. Uses Atomic Design and TypeScript.",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-frontend/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-frontend",
   "description": "Frontend development for React, Vue, and Angular projects. Includes Next.js 14+ App Router support, design system architecture (Atomic Design), and UI component best practices. Focus on modern frontend patterns and performance.",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-github/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-github",
   "description": "GitHub Issues integration for SpecWeave increments. Bidirectional sync between SpecWeave increments and GitHub Issues. Automatically creates issues from increments, tracks progress, and closes issues on completion. Uses GitHub CLI (gh) for seamless integration.",
-  "version": "1.0.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave-github/hooks/post-task-completion.sh

@@ -201,35 +201,50 @@ else
 fi
 
 # ============================================================================
-# EPIC GITHUB ISSUE SYNC (Update Epic issue with fresh task progress)
+# EPIC GITHUB ISSUE SYNC (DEPRECATED v0.24.0+)
+# ============================================================================
+#
+# ⚠️  DEPRECATED: SpecWeave now syncs ONLY at User Story level.
+#
+# Feature/Epic-level issues are no longer updated.
+# Use /specweave-github:sync instead to sync User Story issues.
+#
+# To re-enable (NOT recommended):
+#   export SPECWEAVE_ENABLE_EPIC_SYNC=true
+#
+# @see .specweave/increments/0047-us-task-linkage/reports/GITHUB-TITLE-FORMAT-FIX-PLAN.md
 # ============================================================================
 
-echo "[$(date)] [GitHub] 🔄 Checking for Epic GitHub issue update..." >> "$DEBUG_LOG" 2>/dev/null || true
+if [ "$SPECWEAVE_ENABLE_EPIC_SYNC" = "true" ]; then
+  echo "[$(date)] [GitHub] 🔄 Checking for Epic GitHub issue update (DEPRECATED)..." >> "$DEBUG_LOG" 2>/dev/null || true
 
-# Find active increment ID
-ACTIVE_INCREMENT=$(ls -t .specweave/increments/ | grep -v '^\.' | while read inc; do
-  if [ -f ".specweave/increments/$inc/metadata.json" ]; then
-    STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' ".specweave/increments/$inc/metadata.json" 2>/dev/null | sed 's/.*"\([^"]*\)".*/\1/' || true)
-    if [ "$STATUS" = "active" ]; then
-      echo "$inc"
-      break
+  # Find active increment ID
+  ACTIVE_INCREMENT=$(ls -t .specweave/increments/ | grep -v '^\.' | while read inc; do
+    if [ -f ".specweave/increments/$inc/metadata.json" ]; then
+      STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' ".specweave/increments/$inc/metadata.json" 2>/dev/null | sed 's/.*"\([^"]*\)".*/\1/' || true)
+      if [ "$STATUS" = "active" ]; then
+        echo "$inc"
+        break
+      fi
+    fi
+  done | head -1)
+
+  if [ -n "$ACTIVE_INCREMENT" ]; then
+    echo "[$(date)] [GitHub] 🎯 Active increment: $ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Run Epic sync script (silently, errors logged to debug log)
+    if [ -f "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" ]; then
+      echo "[$(date)] [GitHub] 🚀 Updating Epic GitHub issue (DEPRECATED)..." >> "$DEBUG_LOG" 2>/dev/null || true
+      "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" "$ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>&1 || true
+      echo "[$(date)] [GitHub] ⚠️  Epic sync is deprecated. Use /specweave-github:sync instead." >> "$DEBUG_LOG" 2>/dev/null || true
+    else
+      echo "[$(date)] [GitHub] ⚠️  Epic sync script not found, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
     fi
-  fi
-done | head -1)
-
-if [ -n "$ACTIVE_INCREMENT" ]; then
-  echo "[$(date)] [GitHub] 🎯 Active increment: $ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
-
-  # Run Epic sync script (silently, errors logged to debug log)
-  if [ -f "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" ]; then
-    echo "[$(date)] [GitHub] 🚀 Updating Epic GitHub issue..." >> "$DEBUG_LOG" 2>/dev/null || true
-    "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" "$ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>&1 || true
-    echo "[$(date)] [GitHub] ✅ Epic sync complete (see logs for details)" >> "$DEBUG_LOG" 2>/dev/null || true
   else
-    echo "[$(date)] [GitHub] ⚠️  Epic sync script not found, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+    echo "[$(date)] [GitHub] ℹ️  No active increment found, skipping Epic sync" >> "$DEBUG_LOG" 2>/dev/null || true
   fi
 else
-  echo "[$(date)] [GitHub] ℹ️  No active increment found, skipping Epic sync" >> "$DEBUG_LOG" 2>/dev/null || true
+  echo "[$(date)] [GitHub] ℹ️  Epic sync disabled (sync at User Story level only)" >> "$DEBUG_LOG" 2>/dev/null || true
 fi
 
 # ============================================================================

package/plugins/specweave-github/lib/ThreeLayerSyncManager.ts

@@ -1,5 +1,5 @@
 /**
- * Three-Layer Bidirectional Sync Manager
+ * Three-Layer Full Sync Manager (All Permissions Enabled)
  *
  * Handles synchronization across three layers:
  * - Layer 1: GitHub Issue (stakeholder UI)

package/plugins/specweave-github/lib/enhanced-github-sync.js

@@ -108,7 +108,7 @@ async function syncSpecWithEnhancedContent(options) {
       };
     } else {
       const issue = await client.createEpicIssue(
-        `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        `[${baseSpec.project === "_features" ? baseSpec.identifier.display : baseSpec.identifier.compact}] ${baseSpec.title}`,
         description,
         void 0,
         allLabels

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

@@ -185,7 +185,7 @@ export async function syncSpecWithEnhancedContent(
     } else {
       // Create new issue with labels
       const issue = await client.createEpicIssue(
-        `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        `[${baseSpec.project === '_features' ? baseSpec.identifier.display : baseSpec.identifier.compact}] ${baseSpec.title}`,
         description,
         undefined,
         allLabels  // Apply labels at creation

package/plugins/specweave-github/lib/github-spec-content-sync.js

@@ -85,7 +85,8 @@ async function syncSpecContentToGitHub(options) {
 async function createGitHubIssue(client, spec, options) {
   const { specPath, dryRun, verbose } = options;
   try {
-    const title = `[${spec.identifier.compact}] ${spec.title}`;
+    const titleId = spec.project === "_features" ? spec.identifier.display : spec.identifier.compact;
+    const title = `[${titleId}] ${spec.title}`;
     const body = buildExternalDescription(spec);
     if (verbose) {
       console.log(`