specweave 0.22.13 → 0.23.0

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,7 +37,26 @@ async function syncLivingDocs(incrementId) {
       return;
     }
     console.log(`\u{1F4C4} Changed/created ${changedDocs.length} file(s)`);
-    await syncToGitHub(incrementId, changedDocs);
+
+    // ========================================================================
+    // 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;
+    }
+
+    // T-034E: Use FormatPreservationSyncService for origin-aware sync
+    await syncWithFormatPreservation(incrementId);
+
     console.log("\u2705 Living docs sync complete\n");
   } catch (error) {
     console.error("\u274C Error syncing living docs:", error);
@@ -77,6 +96,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 +118,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) {
@@ -303,6 +336,38 @@ if (isMainModule) {
     console.error("\u274C Fatal error:", error);
   });
 }
+
+/**
+ * Sync with format preservation (T-034E)
+ * Routes sync based on origin metadata (external vs internal)
+ */
+async function syncWithFormatPreservation(incrementId) {
+  try {
+    console.log("\n🔄 Using format-preserving sync...");
+
+    const { SyncCoordinator } = await import("../../../../dist/src/sync/sync-coordinator.js");
+
+    const coordinator = new SyncCoordinator({
+      projectRoot: process.cwd(),
+      incrementId
+    });
+
+    const result = await coordinator.syncIncrementCompletion();
+
+    if (result.success) {
+      console.log(`✅ Format-preserving sync complete (${result.syncMode} mode)`);
+      console.log(`   ${result.userStoriesSynced} user story/stories synced`);
+    } else {
+      console.log(`⚠️  Sync completed with ${result.errors.length} error(s)`);
+      result.errors.forEach(err => console.error(`   - ${err}`));
+    }
+  } catch (error) {
+    console.error("⚠️  Format-preserving sync error:", error);
+    console.log("   Falling back to legacy sync...");
+    // Don't fail - just log and continue
+  }
+}
+
 export {
   syncLivingDocs
 };

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

@@ -12,8 +12,9 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import { parseTasksWithUSLinks, getAllTasks } from '../../../../dist/src/generators/spec/task-parser.js';
+import { parseTasksWithUSLinks, getAllTasks } from '../vendor/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,13 +159,20 @@ 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');
   let updated = false;
 
-  // 1. Update task list section
+  // 1. Update origin badge (NEW - T-034)
+  const updatedOrigin = updateOriginBadge(content, usFilePath);
+  if (updatedOrigin !== content) {
+    content = updatedOrigin;
+    updated = true;
+  }
+
+  // 2. Update task list section
   const taskList = generateTaskList(tasks, incrementId);
   const newTasksSection = `## Tasks\n\n${taskList}`;
 
@@ -166,19 +188,183 @@ async function updateUSFile(usFilePath, tasks, incrementId) {
     }
   }
 
-  // 2. Update AC checkboxes based on task completion
+  // 3. Update AC checkboxes based on task completion
   const updatedACs = updateACCheckboxes(content, tasks);
   if (updatedACs !== content) {
     content = updatedACs;
     updated = true;
   }
 
-  // Write updated content
-  if (updated) {
-    await fs.writeFile(usFilePath, content, 'utf-8');
+  return { updated, content };
+}
+
+/**
+ * Update origin badge in User Story file
+ * Detects origin from US ID (E suffix = external)
+ *
+ * @param {string} content - US file content
+ * @param {string} usFilePath - Path to US file
+ * @returns {string} Updated content with origin badge
+ */
+function updateOriginBadge(content, usFilePath) {
+  // Extract US ID from filename (e.g., us-001e-title.md -> US-001E)
+  const filename = path.basename(usFilePath);
+  const usIdMatch = filename.match(/^(us-\d{3}e?)-/i);
+
+  if (!usIdMatch) {
+    return content; // Can't determine US ID, skip
+  }
+
+  const usId = usIdMatch[1].toUpperCase();
+  const isExternal = usId.endsWith('E');
+
+  // Validate origin immutability (prevent internal ↔ external changes)
+  const existingOrigin = extractExistingOrigin(content);
+  if (existingOrigin) {
+    const existingIsExternal = existingOrigin !== 'internal';
+    if (isExternal !== existingIsExternal) {
+      console.log(`   ⚠️  Origin immutable: Cannot change ${usId} from ${existingOrigin} to ${isExternal ? 'external' : 'internal'}`);
+      return content; // Don't modify origin
+    }
   }
 
-  return updated;
+  // Determine origin badge
+  let originBadge;
+  if (isExternal) {
+    // Try to detect external source from metadata
+    const externalSource = detectExternalSource(content);
+    originBadge = getExternalOriginBadge(externalSource, content);
+  } else {
+    originBadge = '🏠 **Internal**';
+  }
+
+  // Check if origin badge already exists
+  const originPattern = /\*\*Origin\*\*:\s*.*/;
+  if (originPattern.test(content)) {
+    // Replace existing origin badge
+    return content.replace(originPattern, `**Origin**: ${originBadge}`);
+  }
+
+  // Add origin badge after frontmatter (if exists) or at beginning
+  const frontmatterEnd = content.match(/^---\n.*?\n---\n/s);
+  if (frontmatterEnd) {
+    const insertPos = frontmatterEnd[0].length;
+    return content.slice(0, insertPos) + `\n**Origin**: ${originBadge}\n\n` + content.slice(insertPos);
+  }
+
+  // No frontmatter, add at beginning after title
+  const titleMatch = content.match(/^#\s+.+\n/);
+  if (titleMatch) {
+    const insertPos = titleMatch[0].length;
+    return content.slice(0, insertPos) + `\n**Origin**: ${originBadge}\n\n` + content.slice(insertPos);
+  }
+
+  // Fallback: add at very beginning
+  return `**Origin**: ${originBadge}\n\n` + content;
+}
+
+/**
+ * Extract existing origin from content (for immutability validation)
+ *
+ * @param {string} content - US file content
+ * @returns {string|null} Existing origin (internal, github, jira, ado) or null
+ */
+function extractExistingOrigin(content) {
+  const originMatch = content.match(/\*\*Origin\*\*:\s*(.+)/);
+  if (!originMatch) {
+    return null;
+  }
+
+  const originText = originMatch[1].toLowerCase();
+  if (originText.includes('internal')) {
+    return 'internal';
+  }
+  if (originText.includes('github')) {
+    return 'github';
+  }
+  if (originText.includes('jira')) {
+    return 'jira';
+  }
+  if (originText.includes('ado') || originText.includes('azure')) {
+    return 'ado';
+  }
+  if (originText.includes('external')) {
+    return 'external'; // Generic external
+  }
+
+  return null;
+}
+
+/**
+ * Detect external source from content metadata
+ *
+ * @param {string} content - US file content
+ * @returns {string} External source (github, jira, ado) or 'unknown'
+ */
+function detectExternalSource(content) {
+  // Check frontmatter for external_source or externalSource
+  const frontmatterMatch = content.match(/^---\n(.*?)\n---/s);
+  if (frontmatterMatch) {
+    const frontmatter = frontmatterMatch[1];
+    if (frontmatter.includes('external_source: github') || frontmatter.includes('externalSource: github')) {
+      return 'github';
+    }
+    if (frontmatter.includes('external_source: jira') || frontmatter.includes('externalSource: jira')) {
+      return 'jira';
+    }
+    if (frontmatter.includes('external_source: ado') || frontmatter.includes('externalSource: ado')) {
+      return 'ado';
+    }
+  }
+
+  // Check for external ID patterns
+  if (content.includes('externalId: GH-') || content.includes('external_id: GH-')) {
+    return 'github';
+  }
+  if (content.includes('externalId: JIRA-') || content.includes('external_id: JIRA-')) {
+    return 'jira';
+  }
+  if (content.includes('externalId: ADO-') || content.includes('external_id: ADO-')) {
+    return 'ado';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Get external origin badge with link if available
+ *
+ * @param {string} source - External source (github, jira, ado)
+ * @param {string} content - US file content
+ * @returns {string} Origin badge markdown
+ */
+function getExternalOriginBadge(source, content) {
+  // Extract external ID and URL from content
+  const externalIdMatch = content.match(/external_?[iI]d:\s*([^\n]+)/);
+  const externalUrlMatch = content.match(/external_?[uU]rl:\s*([^\n]+)/);
+
+  const externalId = externalIdMatch ? externalIdMatch[1].trim() : null;
+  const externalUrl = externalUrlMatch ? externalUrlMatch[1].trim() : null;
+
+  switch (source) {
+    case 'github':
+      if (externalId && externalUrl) {
+        return `🔗 [GitHub ${externalId}](${externalUrl})`;
+      }
+      return '🔗 **GitHub**';
+    case 'jira':
+      if (externalId && externalUrl) {
+        return `🎫 [JIRA ${externalId}](${externalUrl})`;
+      }
+      return '🎫 **JIRA**';
+    case 'ado':
+      if (externalId && externalUrl) {
+        return `📋 [ADO ${externalId}](${externalUrl})`;
+      }
+      return '📋 **Azure DevOps**';
+    default:
+      return '🔗 **External**';
+  }
 }
 
 /**

package/plugins/specweave/lib/hooks/translate-file.js

@@ -6,7 +6,7 @@ import {
   validateTranslation,
   getLanguageName,
   formatCost
-} from "../../../../dist/src/utils/translation.js";
+} from "../vendor/utils/translation.js";
 async function translateFile(options) {
   const { filePath, targetLang, preview, verbose } = options;
   if (!await fs.pathExists(filePath)) {

package/plugins/specweave/lib/hooks/translate-file.ts

@@ -26,7 +26,7 @@ import {
   getLanguageName,
   formatCost,
   type SupportedLanguage,
-} from '../../../../dist/src/utils/translation.js';
+} from '../vendor/utils/translation.js';
 
 /**
  * CLI options

package/plugins/specweave/lib/hooks/update-ac-status.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { ACStatusManager } from "../../../../dist/src/core/increment/ac-status-manager.js";
+import { ACStatusManager } from "../vendor/core/increment/ac-status-manager.js";
 async function updateACStatus(incrementId) {
   try {
     const projectRoot = process.cwd();

package/plugins/specweave/lib/hooks/update-ac-status.ts

@@ -26,7 +26,7 @@
  * - spec.md: - [ ] AC-US1-02 → NO CHANGE (partial completion)
  */
 
-import { ACStatusManager } from '../../../../dist/src/core/increment/ac-status-manager.js';
+import { ACStatusManager } from '../vendor/core/increment/ac-status-manager.js';
 
 /**
  * Main entry point - uses ACStatusManager for sophisticated sync