specweave 0.21.3 → 0.22.2

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

@@ -134,10 +134,39 @@ class GitHubClientV2 {
   // ==========================================================================
   // Issues
   // ==========================================================================
+  /**
+   * Validate issue title format
+   *
+   * CRITICAL: Enforces correct data flow architecture
+   * - ✅ CORRECT: "US-XXX: Title" or "FS-YY-MM-DD: Title"
+   * - ❌ WRONG: "[Increment XXXX] Title" (deprecated old format)
+   *
+   * @throws Error if title uses deprecated [Increment XXXX] format
+   */
+  validateIssueTitle(title) {
+    const deprecatedPattern = /\[Increment\s+\d+\]/i;
+    if (deprecatedPattern.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)
+  \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.`
+      );
+    }
+  }
   /**
    * Create epic issue (increment-level)
    */
   async createEpicIssue(title, body, milestone, labels = []) {
+    this.validateIssueTitle(title);
     const args = [
       "issue",
       "create",

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

@@ -192,6 +192,34 @@ export class GitHubClientV2 {
   // Issues
   // ==========================================================================
 
+  /**
+   * Validate issue title format
+   *
+   * CRITICAL: Enforces correct data flow architecture
+   * - ✅ CORRECT: "US-XXX: Title" or "FS-YY-MM-DD: Title"
+   * - ❌ WRONG: "[Increment XXXX] Title" (deprecated old format)
+   *
+   * @throws Error if title uses deprecated [Increment XXXX] format
+   */
+  private validateIssueTitle(title: string): void {
+    // Check for deprecated [Increment XXXX] format
+    const deprecatedPattern = /\[Increment\s+\d+\]/i;
+
+    if (deprecatedPattern.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` +
+        `  ❌ 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.`
+      );
+    }
+  }
+
   /**
    * Create epic issue (increment-level)
    */
@@ -201,6 +229,8 @@ export class GitHubClientV2 {
     milestone?: number | string,
     labels: string[] = []
   ): Promise<GitHubIssue> {
+    // Validate title format before creating
+    this.validateIssueTitle(title);
     const args = [
       'issue',
       'create',

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

@@ -192,6 +192,10 @@ ${phaseChecklist}
 
 ## SpecWeave Increment
 
+\u26A0\uFE0F **DEPRECATED FORMAT**: This issue was created using the old increment-based sync.
+
+**Correct data flow**: Increment \u2192 Living Docs \u2192 GitHub
+
 This epic tracks SpecWeave increment \`${metadata.id}\`.
 
 - **Spec**: [\`spec.md\`](${this.getGitHubFileURL("spec.md")})

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

@@ -219,6 +219,9 @@ export class TaskSync {
       });
     }
 
+    // DEPRECATED: This method generates old [Increment XXX] format
+    // It will be blocked by github-client-v2.ts validation
+    // TODO: Remove task-sync.ts entirely - use living docs sync instead
     return `# [Increment ${metadata.id}] ${metadata.title}
 
 **Status**: ${metadata.status}
@@ -234,6 +237,10 @@ ${phaseChecklist}
 
 ## SpecWeave Increment
 
+⚠️ **DEPRECATED FORMAT**: This issue was created using the old increment-based sync.
+
+**Correct data flow**: Increment → Living Docs → GitHub
+
 This epic tracks SpecWeave increment \`${metadata.id}\`.
 
 - **Spec**: [\`spec.md\`](${this.getGitHubFileURL('spec.md')})

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

@@ -84,3 +84,41 @@ export interface GitHubSyncOptions {
   projectName?: string; // Optional: Add issues to GitHub Project (e.g., "SpecWeave v0.4.0")
   fastMode?: boolean; // Skip rate limiting (for increments < 10 tasks)
 }
+
+/**
+ * Three-Layer Sync Types (for bidirectional sync)
+ */
+export interface AcceptanceCriterion {
+  id: string; // e.g., "AC-US1-01"
+  userStoryId: string; // e.g., "US1"
+  description: string;
+  completed: boolean;
+  projects: string[]; // ["backend", "frontend", "mobile"]
+  rawLine: string; // Original markdown line
+}
+
+export interface SyncTask {
+  id: string; // e.g., "T-001"
+  title: string;
+  completed: boolean;
+  completedDate?: string;
+  acIds: string[]; // e.g., ["AC-US1-01", "AC-US1-02"]
+  filePaths?: string[]; // For code validation
+}
+
+export interface SyncChange {
+  type: 'ac' | 'task';
+  id: string;
+  completed: boolean;
+  layer: 'github' | 'living-docs' | 'increment';
+  userStoryPath?: string;
+  incrementPath?: string;
+}
+
+export interface ThreeLayerSyncResult {
+  acsUpdated: number;
+  tasksUpdated: number;
+  tasksReopened: number;
+  conflicts: string[];
+  errors: string[];
+}

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

@@ -1,6 +1,6 @@
-import { EnhancedContentBuilder } from "../../../src/core/sync/enhanced-content-builder.js";
-import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
-import { parseSpecContent } from "../../../src/core/spec-content-sync.js";
+import { EnhancedContentBuilder } from "../../../dist/src/core/sync/enhanced-content-builder.js";
+import { SpecIncrementMapper } from "../../../dist/src/core/sync/spec-increment-mapper.js";
+import { parseSpecContent } from "../../../dist/src/core/spec-content-sync.js";
 import * as path from "path";
 import * as fs from "fs/promises";
 async function syncSpecToJiraWithEnhancedContent(options) {