specweave 0.28.0 → 0.28.3

package/plugins/specweave/lib/hooks/sync-increment-closure.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { SyncCoordinator } from "../../../../dist/src/sync/sync-coordinator.js";
+import { consoleLogger } from "../vendor/utils/logger.js";
+async function syncIncrementClosure(incrementId) {
+  try {
+    console.log("\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+    console.log(`\u{1F512} SYNC INCREMENT CLOSURE: ${incrementId}`);
+    console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+    const projectRoot = process.cwd();
+    const coordinator = new SyncCoordinator({
+      projectRoot,
+      incrementId,
+      logger: consoleLogger
+    });
+    const result = await coordinator.syncIncrementClosure();
+    console.log("\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+    if (result.success) {
+      console.log("\u2705 INCREMENT CLOSURE SYNC COMPLETED");
+      console.log(`   Issues closed: ${result.closedIssues.length}`);
+      if (result.closedIssues.length > 0) {
+        console.log(`   Issue numbers: ${result.closedIssues.join(", ")}`);
+      }
+    } else {
+      console.log("\u26A0\uFE0F  INCREMENT CLOSURE SYNC HAD ERRORS");
+      console.log(`   Issues closed: ${result.closedIssues.length}`);
+      console.log(`   Errors: ${result.errors.length}`);
+    }
+    console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n");
+    return {
+      success: result.success,
+      closedIssues: result.closedIssues,
+      errors: result.errors
+    };
+  } catch (error) {
+    console.error("\n\u274C FATAL ERROR in sync increment closure:", error.message);
+    return {
+      success: false,
+      closedIssues: [],
+      errors: [error.message]
+    };
+  }
+}
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  const incrementId = process.argv[2];
+  if (!incrementId) {
+    console.error("Usage: node sync-increment-closure.js <increment-id>");
+    console.error("Example: node sync-increment-closure.js 0059-progressive-plugin");
+    process.exit(1);
+  }
+  syncIncrementClosure(incrementId).then((result) => {
+    if (result.success) {
+      console.log("\n\u2705 Increment closure sync completed successfully");
+      process.exit(0);
+    } else {
+      console.error("\n\u26A0\uFE0F  Increment closure sync had errors (non-blocking)");
+      process.exit(0);
+    }
+  }).catch((error) => {
+    console.error("\n\u274C Fatal error:", error);
+    process.exit(0);
+  });
+}
+export {
+  syncIncrementClosure
+};

package/plugins/specweave/lib/hooks/sync-increment-closure.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Sync Increment Closure Hook (NEW in v0.28.1)
+ *
+ * This script handles the CLOSURE flow for increments - closing GitHub issues
+ * when an increment is marked as "completed".
+ *
+ * CRITICAL FIX: Previously, User Story GitHub issues were CREATED but NEVER CLOSED.
+ * This script ensures proper closure of all related issues.
+ *
+ * Called by: post-increment-completion.sh (after increment status → "completed")
+ *
+ * Flow:
+ * 1. Load SyncCoordinator for the increment
+ * 2. Call syncIncrementClosure() which:
+ *    - Ensures all GitHub issues exist (idempotent)
+ *    - Closes all User Story issues with completion comment
+ * 3. Report results
+ *
+ * Usage:
+ *   node sync-increment-closure.js <increment-id>
+ *
+ * Environment:
+ *   GITHUB_TOKEN - Required for GitHub API access
+ */
+
+import { SyncCoordinator } from '../../../../dist/src/sync/sync-coordinator.js';
+import { consoleLogger } from '../vendor/utils/logger.js';
+
+/**
+ * Main function to sync increment closure
+ */
+async function syncIncrementClosure(incrementId: string): Promise<{
+  success: boolean;
+  closedIssues: number[];
+  errors: string[];
+}> {
+  try {
+    console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log(`🔒 SYNC INCREMENT CLOSURE: ${incrementId}`);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+    const projectRoot = process.cwd();
+
+    const coordinator = new SyncCoordinator({
+      projectRoot,
+      incrementId,
+      logger: consoleLogger
+    });
+
+    const result = await coordinator.syncIncrementClosure();
+
+    console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    if (result.success) {
+      console.log('✅ INCREMENT CLOSURE SYNC COMPLETED');
+      console.log(`   Issues closed: ${result.closedIssues.length}`);
+      if (result.closedIssues.length > 0) {
+        console.log(`   Issue numbers: ${result.closedIssues.join(', ')}`);
+      }
+    } else {
+      console.log('⚠️  INCREMENT CLOSURE SYNC HAD ERRORS');
+      console.log(`   Issues closed: ${result.closedIssues.length}`);
+      console.log(`   Errors: ${result.errors.length}`);
+    }
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+    return {
+      success: result.success,
+      closedIssues: result.closedIssues,
+      errors: result.errors
+    };
+  } catch (error: any) {
+    console.error('\n❌ FATAL ERROR in sync increment closure:', error.message);
+    return {
+      success: false,
+      closedIssues: [],
+      errors: [error.message]
+    };
+  }
+}
+
+// CLI Interface
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  const incrementId = process.argv[2];
+
+  if (!incrementId) {
+    console.error('Usage: node sync-increment-closure.js <increment-id>');
+    console.error('Example: node sync-increment-closure.js 0059-progressive-plugin');
+    process.exit(1);
+  }
+
+  syncIncrementClosure(incrementId)
+    .then((result) => {
+      if (result.success) {
+        console.log('\n✅ Increment closure sync completed successfully');
+        process.exit(0);
+      } else {
+        console.error('\n⚠️  Increment closure sync had errors (non-blocking)');
+        // Exit 0 to not block the hook chain
+        process.exit(0);
+      }
+    })
+    .catch((error) => {
+      console.error('\n❌ Fatal error:', error);
+      // Exit 0 to not block the hook chain
+      process.exit(0);
+    });
+}
+
+export { syncIncrementClosure };

package/plugins/specweave-github/lib/github-client-v2.js

@@ -138,27 +138,51 @@ class GitHubClientV2 {
    * Validate issue title format
    *
    * CRITICAL: Enforces correct data flow architecture
-   * - ✅ CORRECT: "US-XXX: Title" or "FS-YY-MM-DD: Title"
+   * - ✅ CORRECT: "[FS-XXX][US-YYY] Title" (User Story - STANDARD)
+   * - ✅ CORRECT: "[FS-XXX] Title" (Feature-level, rare)
    * - ❌ WRONG: "[Increment XXXX] Title" (deprecated old format)
+   * - ❌ WRONG: "[BUG] Title" (type prefixes are labels, not title)
+   * - ❌ WRONG: "[HOTFIX] Title" (type prefixes are labels, not title)
+   * - ❌ WRONG: "[FEATURE] Title" (type prefixes are labels, not title)
    *
-   * @throws Error if title uses deprecated [Increment XXXX] format
+   * @throws Error if title uses invalid format
    */
   validateIssueTitle(title) {
-    const deprecatedPattern = /\[Increment\s+\d+\]/i;
-    if (deprecatedPattern.test(title)) {
+    const deprecatedIncrementPattern = /\[Increment\s+\d+\]/i;
+    if (deprecatedIncrementPattern.test(title)) {
       throw new Error(
         `\u274C DEPRECATED FORMAT DETECTED: "${title}"
 
 GitHub issues MUST use living docs format:
-  \u2705 CORRECT: "US-XXX: Title" (User Story)
-  \u2705 CORRECT: "FS-YY-MM-DD: Title" (Feature Spec)
+  \u2705 CORRECT: "[FS-XXX][US-YYY] Title" (User Story)
   \u274C WRONG: "[Increment XXXX] Title" (old format)
 
 WHY: Correct data flow is: Increment \u2192 Living Docs \u2192 GitHub
       Living docs are the source of truth for GitHub sync.
 
-FIX: Use /specweave:sync-docs to generate living docs, then sync to GitHub.
-     OR: Use US/FS ID format directly if creating issues manually.`
+FIX: Use /specweave:sync-docs to generate living docs, then sync to GitHub.`
+      );
+    }
+    const typePrefixPattern = /^\[(BUG|HOTFIX|FEATURE|DOCS|REFACTOR|CHORE|EXPERIMENT|Bug|Hotfix|Feature|Docs|Refactor|Chore|Experiment)\]/i;
+    if (typePrefixPattern.test(title)) {
+      const match = title.match(typePrefixPattern);
+      const badPrefix = match ? match[0] : "[TYPE]";
+      throw new Error(
+        `\u274C INVALID TITLE FORMAT: "${title}"
+
+Type prefixes like ${badPrefix} belong as LABELS, not in the title!
+
+GitHub issues MUST use this format:
+  \u2705 CORRECT: "[FS-XXX][US-YYY] Title" (User Story)
+  \u274C WRONG: "${badPrefix} Title" (use 'bug' label instead)
+
+WHY: All SpecWeave issues follow [FS-XXX][US-YYY] format for traceability.
+     Use GitHub labels for categorization (bug, enhancement, etc.).
+
+FIX:
+  1. Link this work to a Feature (FS-XXX) and User Story (US-YYY)
+  2. Use /specweave-github:sync to create issue with correct format
+  3. Add '${match ? match[1].toLowerCase() : "bug"}' as a label instead`
       );
     }
   }

package/plugins/specweave-github/lib/github-client-v2.ts

@@ -196,26 +196,48 @@ export class GitHubClientV2 {
    * Validate issue title format
    *
    * CRITICAL: Enforces correct data flow architecture
-   * - ✅ CORRECT: "US-XXX: Title" or "FS-YY-MM-DD: Title"
+   * - ✅ CORRECT: "[FS-XXX][US-YYY] Title" (User Story - STANDARD)
+   * - ✅ CORRECT: "[FS-XXX] Title" (Feature-level, rare)
    * - ❌ WRONG: "[Increment XXXX] Title" (deprecated old format)
+   * - ❌ WRONG: "[BUG] Title" (type prefixes are labels, not title)
+   * - ❌ WRONG: "[HOTFIX] Title" (type prefixes are labels, not title)
+   * - ❌ WRONG: "[FEATURE] Title" (type prefixes are labels, not title)
    *
-   * @throws Error if title uses deprecated [Increment XXXX] format
+   * @throws Error if title uses invalid format
    */
   private validateIssueTitle(title: string): void {
     // Check for deprecated [Increment XXXX] format
-    const deprecatedPattern = /\[Increment\s+\d+\]/i;
-
-    if (deprecatedPattern.test(title)) {
+    const deprecatedIncrementPattern = /\[Increment\s+\d+\]/i;
+    if (deprecatedIncrementPattern.test(title)) {
       throw new Error(
         `❌ DEPRECATED FORMAT DETECTED: "${title}"\n\n` +
         `GitHub issues MUST use living docs format:\n` +
-        `  ✅ CORRECT: "US-XXX: Title" (User Story)\n` +
-        `  ✅ CORRECT: "FS-YY-MM-DD: Title" (Feature Spec)\n` +
+        `  ✅ CORRECT: "[FS-XXX][US-YYY] Title" (User Story)\n` +
         `  ❌ WRONG: "[Increment XXXX] Title" (old format)\n\n` +
         `WHY: Correct data flow is: Increment → Living Docs → GitHub\n` +
         `      Living docs are the source of truth for GitHub sync.\n\n` +
-        `FIX: Use /specweave:sync-docs to generate living docs, then sync to GitHub.\n` +
-        `     OR: Use US/FS ID format directly if creating issues manually.`
+        `FIX: Use /specweave:sync-docs to generate living docs, then sync to GitHub.`
+      );
+    }
+
+    // Check for type-based prefixes (CRITICAL FIX for issue #749)
+    // These prefixes belong as LABELS, not in the issue title!
+    const typePrefixPattern = /^\[(BUG|HOTFIX|FEATURE|DOCS|REFACTOR|CHORE|EXPERIMENT|Bug|Hotfix|Feature|Docs|Refactor|Chore|Experiment)\]/i;
+    if (typePrefixPattern.test(title)) {
+      const match = title.match(typePrefixPattern);
+      const badPrefix = match ? match[0] : '[TYPE]';
+      throw new Error(
+        `❌ INVALID TITLE FORMAT: "${title}"\n\n` +
+        `Type prefixes like ${badPrefix} belong as LABELS, not in the title!\n\n` +
+        `GitHub issues MUST use this format:\n` +
+        `  ✅ CORRECT: "[FS-XXX][US-YYY] Title" (User Story)\n` +
+        `  ❌ WRONG: "${badPrefix} Title" (use 'bug' label instead)\n\n` +
+        `WHY: All SpecWeave issues follow [FS-XXX][US-YYY] format for traceability.\n` +
+        `     Use GitHub labels for categorization (bug, enhancement, etc.).\n\n` +
+        `FIX:\n` +
+        `  1. Link this work to a Feature (FS-XXX) and User Story (US-YYY)\n` +
+        `  2. Use /specweave-github:sync to create issue with correct format\n` +
+        `  3. Add '${match ? match[1].toLowerCase() : 'bug'}' as a label instead`
       );
     }
   }

package/plugins/specweave-github/lib/github-feature-sync-cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "fs";
+import * as path from "path";
+import { GitHubFeatureSync } from "./github-feature-sync.js";
+import { GitHubClientV2 } from "./github-client-v2.js";
+async function loadGitHubConfig() {
+  const projectRoot = process.cwd();
+  const configPath = path.join(projectRoot, ".specweave/config.json");
+  let owner = process.env.GITHUB_OWNER || "";
+  let repo = process.env.GITHUB_REPO || "";
+  const token = process.env.GITHUB_TOKEN || "";
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (config.sync?.github?.owner && config.sync?.github?.repo) {
+        owner = config.sync.github.owner;
+        repo = config.sync.github.repo;
+      } else if (config.multiProject?.enabled && config.multiProject?.activeProject) {
+        const activeProject = config.multiProject.activeProject;
+        const projectConfig = config.multiProject.projects?.[activeProject];
+        if (projectConfig?.externalTools?.github?.repository) {
+          const parts = projectConfig.externalTools.github.repository.split("/");
+          if (parts.length === 2) {
+            owner = parts[0];
+            repo = parts[1];
+          }
+        }
+      } else if (config.sync?.activeProfile && config.sync?.profiles) {
+        const profile = config.sync.profiles[config.sync.activeProfile];
+        if (profile?.config?.owner && profile?.config?.repo) {
+          owner = profile.config.owner;
+          repo = profile.config.repo;
+        }
+      }
+    } catch (error) {
+      console.error("\u26A0\uFE0F  Failed to parse config.json:", error);
+    }
+  }
+  if (!owner || !repo) {
+    try {
+      const { execSync } = await import("child_process");
+      const remoteUrl = execSync("git remote get-url origin 2>/dev/null", {
+        encoding: "utf-8",
+        cwd: projectRoot
+      }).trim();
+      const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
+      if (match) {
+        owner = owner || match[1];
+        repo = repo || match[2];
+      }
+    } catch {
+    }
+  }
+  if (!token) {
+    console.error("\u274C GITHUB_TOKEN not set");
+    console.error("   Set it in .env file or export GITHUB_TOKEN=ghp_xxx");
+    return null;
+  }
+  if (!owner || !repo) {
+    console.error("\u274C Could not detect GitHub owner/repo");
+    console.error("   Set sync.github.owner and sync.github.repo in .specweave/config.json");
+    return null;
+  }
+  return { owner, repo, token };
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    console.log("Usage: node github-feature-sync-cli.js <feature-id>");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  feature-id   Feature ID (e.g., FS-062)");
+    console.log("");
+    console.log("Environment:");
+    console.log("  GITHUB_TOKEN  Required - GitHub personal access token");
+    console.log("");
+    console.log("Example:");
+    console.log("  GITHUB_TOKEN=ghp_xxx node github-feature-sync-cli.js FS-062");
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+  const featureId = args[0];
+  if (!featureId.match(/^FS-\d+$/i)) {
+    console.error(`\u274C Invalid feature ID: ${featureId}`);
+    console.error("   Expected format: FS-XXX (e.g., FS-062)");
+    process.exit(1);
+  }
+  console.log(`
+\u{1F419} GitHub Feature Sync CLI`);
+  console.log(`   Feature: ${featureId}`);
+  const config = await loadGitHubConfig();
+  if (!config) {
+    process.exit(1);
+  }
+  console.log(`   Repository: ${config.owner}/${config.repo}`);
+  const projectRoot = process.cwd();
+  const specsDir = path.join(projectRoot, ".specweave/docs/internal/specs");
+  const profile = {
+    provider: "github",
+    displayName: "GitHub",
+    config: {
+      owner: config.owner,
+      repo: config.repo,
+      token: config.token
+    },
+    timeRange: {
+      default: "1M",
+      max: "3M"
+    }
+  };
+  const client = new GitHubClientV2(profile);
+  const sync = new GitHubFeatureSync(client, specsDir, projectRoot);
+  try {
+    console.log(`
+\u{1F504} Syncing ${featureId} to GitHub...`);
+    const result = await sync.syncFeatureToGitHub(featureId);
+    console.log(`
+\u2705 Sync complete!`);
+    console.log(`   \u{1F3AF} Milestone: #${result.milestoneNumber}`);
+    console.log(`   \u{1F4DD} Issues created: ${result.issuesCreated}`);
+    console.log(`   \u{1F504} Issues updated: ${result.issuesUpdated}`);
+    console.log(`   \u{1F4DA} User stories processed: ${result.userStoriesProcessed}`);
+    if (result.milestoneUrl) {
+      console.log(`   \u{1F517} ${result.milestoneUrl}`);
+    }
+    process.exit(0);
+  } catch (error) {
+    console.error(`
+\u274C Sync failed:`, error);
+    process.exit(1);
+  }
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * GitHub Feature Sync CLI
+ *
+ * CLI wrapper for GitHubFeatureSync.syncFeatureToGitHub()
+ * Called by post-increment-planning.sh hook to create GitHub issues
+ * after increment creation.
+ *
+ * Usage:
+ *   node github-feature-sync-cli.js <feature-id>
+ *   node github-feature-sync-cli.js FS-062
+ *
+ * Environment:
+ *   GITHUB_TOKEN - Required
+ *   GITHUB_OWNER - Optional (detected from config.json or git remote)
+ *   GITHUB_REPO  - Optional (detected from config.json or git remote)
+ *
+ * @see ADR-0139 (Unified Post-Increment Sync)
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import * as path from 'path';
+import { GitHubFeatureSync } from './github-feature-sync.js';
+import { GitHubClientV2 } from './github-client-v2.js';
+
+interface GitHubConfig {
+  owner: string;
+  repo: string;
+  token: string;
+}
+
+async function loadGitHubConfig(): Promise<GitHubConfig | null> {
+  const projectRoot = process.cwd();
+  const configPath = path.join(projectRoot, '.specweave/config.json');
+
+  let owner = process.env.GITHUB_OWNER || '';
+  let repo = process.env.GITHUB_REPO || '';
+  const token = process.env.GITHUB_TOKEN || '';
+
+  // Try to load from config.json
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+
+      // Method 1: sync.github
+      if (config.sync?.github?.owner && config.sync?.github?.repo) {
+        owner = config.sync.github.owner;
+        repo = config.sync.github.repo;
+      }
+      // Method 2: multiProject.projects[activeProject].externalTools.github
+      else if (config.multiProject?.enabled && config.multiProject?.activeProject) {
+        const activeProject = config.multiProject.activeProject;
+        const projectConfig = config.multiProject.projects?.[activeProject];
+        if (projectConfig?.externalTools?.github?.repository) {
+          const parts = projectConfig.externalTools.github.repository.split('/');
+          if (parts.length === 2) {
+            owner = parts[0];
+            repo = parts[1];
+          }
+        }
+      }
+      // Method 3: sync.profiles[activeProfile]
+      else if (config.sync?.activeProfile && config.sync?.profiles) {
+        const profile = config.sync.profiles[config.sync.activeProfile];
+        if (profile?.config?.owner && profile?.config?.repo) {
+          owner = profile.config.owner;
+          repo = profile.config.repo;
+        }
+      }
+    } catch (error) {
+      console.error('⚠️  Failed to parse config.json:', error);
+    }
+  }
+
+  // Fallback: detect from git remote
+  if (!owner || !repo) {
+    try {
+      const { execSync } = await import('child_process');
+      const remoteUrl = execSync('git remote get-url origin 2>/dev/null', {
+        encoding: 'utf-8',
+        cwd: projectRoot
+      }).trim();
+
+      // Parse GitHub URL (HTTPS or SSH)
+      const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
+      if (match) {
+        owner = owner || match[1];
+        repo = repo || match[2];
+      }
+    } catch {
+      // Git detection failed, continue with what we have
+    }
+  }
+
+  if (!token) {
+    console.error('❌ GITHUB_TOKEN not set');
+    console.error('   Set it in .env file or export GITHUB_TOKEN=ghp_xxx');
+    return null;
+  }
+
+  if (!owner || !repo) {
+    console.error('❌ Could not detect GitHub owner/repo');
+    console.error('   Set sync.github.owner and sync.github.repo in .specweave/config.json');
+    return null;
+  }
+
+  return { owner, repo, token };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log('Usage: node github-feature-sync-cli.js <feature-id>');
+    console.log('');
+    console.log('Arguments:');
+    console.log('  feature-id   Feature ID (e.g., FS-062)');
+    console.log('');
+    console.log('Environment:');
+    console.log('  GITHUB_TOKEN  Required - GitHub personal access token');
+    console.log('');
+    console.log('Example:');
+    console.log('  GITHUB_TOKEN=ghp_xxx node github-feature-sync-cli.js FS-062');
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+
+  const featureId = args[0];
+
+  // Validate feature ID format
+  if (!featureId.match(/^FS-\d+$/i)) {
+    console.error(`❌ Invalid feature ID: ${featureId}`);
+    console.error('   Expected format: FS-XXX (e.g., FS-062)');
+    process.exit(1);
+  }
+
+  console.log(`\n🐙 GitHub Feature Sync CLI`);
+  console.log(`   Feature: ${featureId}`);
+
+  // Load config
+  const config = await loadGitHubConfig();
+  if (!config) {
+    process.exit(1);
+  }
+
+  console.log(`   Repository: ${config.owner}/${config.repo}`);
+
+  // Create client and sync
+  const projectRoot = process.cwd();
+  const specsDir = path.join(projectRoot, '.specweave/docs/internal/specs');
+
+  const profile = {
+    provider: 'github' as const,
+    displayName: 'GitHub',
+    config: {
+      owner: config.owner,
+      repo: config.repo,
+      token: config.token
+    },
+    timeRange: {
+      default: '1M' as const,
+      max: '3M' as const
+    }
+  };
+
+  const client = new GitHubClientV2(profile);
+  const sync = new GitHubFeatureSync(client, specsDir, projectRoot);
+
+  try {
+    console.log(`\n🔄 Syncing ${featureId} to GitHub...`);
+
+    const result = await sync.syncFeatureToGitHub(featureId);
+
+    console.log(`\n✅ Sync complete!`);
+    console.log(`   🎯 Milestone: #${result.milestoneNumber}`);
+    console.log(`   📝 Issues created: ${result.issuesCreated}`);
+    console.log(`   🔄 Issues updated: ${result.issuesUpdated}`);
+    console.log(`   📚 User stories processed: ${result.userStoriesProcessed}`);
+
+    if (result.milestoneUrl) {
+      console.log(`   🔗 ${result.milestoneUrl}`);
+    }
+
+    process.exit(0);
+  } catch (error) {
+    console.error(`\n❌ Sync failed:`, error);
+    process.exit(1);
+  }
+}
+
+// Run CLI
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/plugins/specweave-github/skills/github-issue-standard/SKILL.md

@@ -11,6 +11,49 @@ description: Standard format for ALL GitHub issues created by SpecWeave. Ensures
 - Increments (0001-* folders)
 - Specs (spec-*.md files)
 
+## Issue Title Format (MANDATORY)
+
+### ✅ ONLY Allowed Title Formats
+
+```
+[FS-XXX][US-YYY] User Story Title    ← STANDARD (User Stories)
+[FS-XXX] Feature Title               ← Rare (Feature-level only)
+```
+
+**Examples**:
+- ✅ `[FS-059][US-003] Hook Optimization (P0)`
+- ✅ `[FS-054][US-001] Fix Reopen Desync Bug (P0)`
+- ✅ `[FS-048] Smart Pagination Feature`
+
+### ❌ PROHIBITED Title Formats (NEVER USE)
+
+```
+[BUG] Title                          ← WRONG! Bug is a LABEL, not title prefix
+[HOTFIX] Title                       ← WRONG! Hotfix is a LABEL
+[FEATURE] Title                      ← WRONG! Feature is a LABEL
+[DOCS] Title                         ← WRONG! Docs is a LABEL
+[Increment XXXX] Title               ← DEPRECATED! Old format
+```
+
+**Why?** Type-based prefixes like `[BUG]` break traceability:
+- Cannot link to Feature Spec (FS-XXX)
+- Cannot link to User Story (US-YYY)
+- Violates SpecWeave's data flow: `Increment → Living Docs → GitHub`
+
+**What to do instead?**
+1. Link work to a Feature (FS-XXX) in living docs
+2. Create User Story (US-YYY) under that feature
+3. Use GitHub **labels** for categorization: `bug`, `enhancement`, `hotfix`
+
+### Validation
+
+The GitHub client (`github-client-v2.ts`) enforces this:
+- Rejects titles starting with `[BUG]`, `[HOTFIX]`, `[FEATURE]`, etc.
+- Rejects deprecated `[Increment XXXX]` format
+- Only allows `[FS-XXX][US-YYY]` or `[FS-XXX]` formats
+
+---
+
 ## The Standard Format
 
 ### ✅ Required Elements