specweave 1.0.350 → 1.0.352

package/plugins/specweave-jira/lib/metadata-paths.ts

@@ -0,0 +1,73 @@
+/**
+ * Canonical Metadata Paths for JIRA Issue Keys
+ *
+ * Single source of truth for reading/writing JIRA issue keys in metadata.
+ * All plugin files MUST use these helpers instead of direct property access.
+ *
+ * Canonical path: external_sync.jira.issueKey
+ * Legacy paths (read-only fallback): jira.issue, jira.issueKey
+ *
+ * @module metadata-paths
+ */
+
+/** Canonical dot-path for JIRA issue key in metadata */
+export const CANONICAL_JIRA_KEY_PATH = 'external_sync.jira.issueKey';
+
+/**
+ * Read JIRA issue key from metadata, checking canonical path first
+ * then falling back to legacy paths for backward compatibility.
+ */
+export function readIssueKey(metadata: any): string | null {
+  if (!metadata) return null;
+
+  // Canonical path (preferred)
+  const canonical = metadata?.external_sync?.jira?.issueKey;
+  if (canonical) return canonical;
+
+  // Legacy path: .jira.issue
+  const legacyIssue = metadata?.jira?.issue;
+  if (legacyIssue) return legacyIssue;
+
+  // Legacy path: .jira.issueKey
+  const legacyKey = metadata?.jira?.issueKey;
+  if (legacyKey) return legacyKey;
+
+  return null;
+}
+
+/**
+ * Write JIRA issue key to the canonical metadata path.
+ * Creates intermediate objects if needed.
+ */
+export function writeIssueKey(metadata: any, key: string): any {
+  if (!metadata) metadata = {};
+  if (!metadata.external_sync) metadata.external_sync = {};
+  if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+  metadata.external_sync.jira.issueKey = key;
+  return metadata;
+}
+
+/**
+ * Migrate legacy metadata paths to canonical path.
+ * Reads from legacy, writes to canonical, optionally cleans up legacy keys.
+ */
+export function migrateToCanonical(metadata: any, cleanup: boolean = false): any {
+  if (!metadata) return metadata;
+
+  const existingKey = readIssueKey(metadata);
+  if (!existingKey) return metadata;
+
+  // Write to canonical
+  writeIssueKey(metadata, existingKey);
+
+  // Optionally remove legacy paths
+  if (cleanup) {
+    if (metadata.jira?.issue) delete metadata.jira.issue;
+    if (metadata.jira?.issueKey) delete metadata.jira.issueKey;
+    if (metadata.jira && Object.keys(metadata.jira).length === 0) {
+      delete metadata.jira;
+    }
+  }
+
+  return metadata;
+}

package/plugins/specweave-jira/lib/reorganization-detector.js

@@ -1,6 +1,19 @@
+import * as fs from "fs/promises";
+import * as path from "path";
 class JiraReorganizationDetector {
   constructor(client) {
     this.client = client;
+    /** Track known parent keys for reparent detection */
+    this.previousParents = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Set known parent keys from previous sync metadata.
+   * Call before detectReorganization() to enable accurate reparent detection.
+   */
+  setKnownParents(parents) {
+    for (const [key, parent] of Object.entries(parents)) {
+      this.previousParents.set(key, parent);
+    }
   }
   /**
    * Detect all reorganization events for tracked issues
@@ -117,22 +130,26 @@ class JiraReorganizationDetector {
     return null;
   }
   /**
-   * Detect if issue was moved to different epic
+   * Detect if issue was moved to different epic.
+   *
+   * Requires previousParents map to track known parent keys.
+   * Only fires REPARENTED when the parent actually changed.
    */
   detectReparent(originalKey, issue, lastSyncTimestamp) {
-    const currentParent = issue.fields.parent?.key;
-    if (currentParent && lastSyncTimestamp) {
-      const updatedAt = new Date(issue.fields.updated);
-      const lastSync = new Date(lastSyncTimestamp);
-      if (updatedAt > lastSync) {
-        return {
-          type: "REPARENTED",
-          timestamp: issue.fields.updated,
-          description: `Issue ${originalKey} may have been reparented to ${currentParent}`,
-          originalKeys: [originalKey],
-          toEpic: currentParent
-        };
-      }
+    const currentParent = issue.fields.parent?.key || null;
+    const previousParent = this.previousParents.get(originalKey) || null;
+    if (previousParent !== null && currentParent !== previousParent) {
+      return {
+        type: "REPARENTED",
+        timestamp: issue.fields.updated,
+        description: `Issue ${originalKey} reparented from ${previousParent} to ${currentParent || "none"}`,
+        originalKeys: [originalKey],
+        fromEpic: previousParent,
+        toEpic: currentParent || void 0
+      };
+    }
+    if (currentParent) {
+      this.previousParents.set(originalKey, currentParent);
     }
     return null;
   }
@@ -190,24 +207,85 @@ async function handleReorganization(events, incrementId, projectRoot = process.c
   console.log(`
 \u{1F527} Handling ${events.length} reorganization events...
 `);
+  const metadataPath = path.join(
+    projectRoot,
+    ".specweave",
+    "increments",
+    incrementId,
+    "metadata.json"
+  );
+  let metadata = {};
+  try {
+    metadata = JSON.parse(await fs.readFile(metadataPath, "utf-8"));
+  } catch {
+    console.warn(`   \u26A0\uFE0F  Could not read metadata.json for ${incrementId}`);
+  }
+  if (!metadata.reorganization) {
+    metadata.reorganization = { events: [], lastHandled: null };
+  }
   for (const event of events) {
     switch (event.type) {
-      case "MOVED_PROJECT":
+      case "MOVED_PROJECT": {
+        if (event.newKeys?.[0]) {
+          if (!metadata.external_sync) metadata.external_sync = {};
+          if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+          metadata.external_sync.jira.issueKey = event.newKeys[0];
+          metadata.external_sync.jira.project = event.toProject;
+        }
         console.log(`   \u2713 Updated project mapping: ${event.fromProject} \u2192 ${event.toProject}`);
         break;
-      case "SPLIT":
-        console.log(`   \u2713 Added new story from split: ${event.newKeys?.join(", ")}`);
+      }
+      case "SPLIT": {
+        if (!metadata.external_sync?.jira?.relatedKeys) {
+          if (!metadata.external_sync) metadata.external_sync = {};
+          if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+          metadata.external_sync.jira.relatedKeys = [];
+        }
+        if (event.newKeys) {
+          metadata.external_sync.jira.relatedKeys.push(...event.newKeys);
+        }
+        console.log(`   \u2713 Recorded split: ${event.newKeys?.join(", ")}`);
         break;
-      case "MERGED":
-        console.log(`   \u2713 Marked story as merged: ${event.originalKeys[0]} \u2192 ${event.newKeys?.[0]}`);
+      }
+      case "MERGED": {
+        if (event.newKeys?.[0]) {
+          if (!metadata.external_sync) metadata.external_sync = {};
+          if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+          metadata.external_sync.jira.issueKey = event.newKeys[0];
+          metadata.external_sync.jira.mergedFrom = event.originalKeys[0];
+        }
+        console.log(`   \u2713 Updated merged issue: ${event.originalKeys[0]} \u2192 ${event.newKeys?.[0]}`);
         break;
-      case "REPARENTED":
-        console.log(`   \u2713 Updated epic link: ${event.toEpic}`);
+      }
+      case "REPARENTED": {
+        if (!metadata.external_sync) metadata.external_sync = {};
+        if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+        metadata.external_sync.jira.epicKey = event.toEpic || null;
+        metadata.external_sync.jira.previousEpicKey = event.fromEpic || null;
+        console.log(`   \u2713 Updated epic link: ${event.fromEpic || "none"} \u2192 ${event.toEpic || "none"}`);
         break;
-      case "DELETED":
-        console.log(`   \u26A0\uFE0F  Story deleted from Jira: ${event.originalKeys[0]}`);
+      }
+      case "DELETED": {
+        if (!metadata.external_sync) metadata.external_sync = {};
+        if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+        metadata.external_sync.jira.deleted = true;
+        metadata.external_sync.jira.deletedAt = event.timestamp;
+        console.log(`   \u26A0\uFE0F  Marked as deleted: ${event.originalKeys[0]}`);
         break;
+      }
     }
+    metadata.reorganization.events.push({
+      type: event.type,
+      timestamp: event.timestamp,
+      description: event.description
+    });
+  }
+  metadata.reorganization.lastHandled = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    console.log(`   \u{1F4C4} Updated metadata.json for ${incrementId}`);
+  } catch (err) {
+    console.warn(`   \u26A0\uFE0F  Failed to write metadata: ${err.message}`);
   }
   console.log("\n\u2705 Reorganization handled\n");
 }

package/plugins/specweave-jira/lib/reorganization-detector.ts

@@ -12,6 +12,8 @@
  */
 
 import { JiraClient, JiraIssue } from '../../../src/integrations/jira/jira-client.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
 
 // ============================================================================
 // Types
@@ -54,8 +56,21 @@ export interface ReorganizationDetectionResult {
 // ============================================================================
 
 export class JiraReorganizationDetector {
+  /** Track known parent keys for reparent detection */
+  private previousParents = new Map<string, string>();
+
   constructor(private client: JiraClient) {}
 
+  /**
+   * Set known parent keys from previous sync metadata.
+   * Call before detectReorganization() to enable accurate reparent detection.
+   */
+  setKnownParents(parents: Record<string, string>): void {
+    for (const [key, parent] of Object.entries(parents)) {
+      this.previousParents.set(key, parent);
+    }
+  }
+
   /**
    * Detect all reorganization events for tracked issues
    */
@@ -220,32 +235,34 @@ export class JiraReorganizationDetector {
   }
 
   /**
-   * Detect if issue was moved to different epic
+   * Detect if issue was moved to different epic.
+   *
+   * Requires previousParents map to track known parent keys.
+   * Only fires REPARENTED when the parent actually changed.
    */
   private detectReparent(
     originalKey: string,
     issue: JiraIssue,
     lastSyncTimestamp?: string
   ): ReorganizationEvent | null {
-    // Check if issue has parent (epic)
-    const currentParent = issue.fields.parent?.key;
-
-    // We need to track previous parent from metadata
-    // For now, just detect if parent exists and was recently updated
-    if (currentParent && lastSyncTimestamp) {
-      const updatedAt = new Date(issue.fields.updated);
-      const lastSync = new Date(lastSyncTimestamp);
-
-      if (updatedAt > lastSync) {
-        // Parent might have changed (we'd need to store previous parent to be sure)
-        return {
-          type: 'REPARENTED',
-          timestamp: issue.fields.updated,
-          description: `Issue ${originalKey} may have been reparented to ${currentParent}`,
-          originalKeys: [originalKey],
-          toEpic: currentParent,
-        };
-      }
+    const currentParent = issue.fields.parent?.key || null;
+    const previousParent = this.previousParents.get(originalKey) || null;
+
+    // Only fire REPARENTED if we know the previous parent AND it differs
+    if (previousParent !== null && currentParent !== previousParent) {
+      return {
+        type: 'REPARENTED',
+        timestamp: issue.fields.updated,
+        description: `Issue ${originalKey} reparented from ${previousParent} to ${currentParent || 'none'}`,
+        originalKeys: [originalKey],
+        fromEpic: previousParent,
+        toEpic: currentParent || undefined,
+      };
+    }
+
+    // Update tracked parent for future comparisons
+    if (currentParent) {
+      this.previousParents.set(originalKey, currentParent);
     }
 
     return null;
@@ -313,7 +330,10 @@ export class JiraReorganizationDetector {
 // ============================================================================
 
 /**
- * Handle reorganization events by updating SpecWeave increment
+ * Handle reorganization events by updating SpecWeave increment metadata.
+ *
+ * For each event type, updates local metadata.json to reflect
+ * the reorganization that happened in JIRA.
  */
 export async function handleReorganization(
   events: ReorganizationEvent[],
@@ -326,33 +346,103 @@ export async function handleReorganization(
 
   console.log(`\n🔧 Handling ${events.length} reorganization events...\n`);
 
+  const metadataPath = path.join(
+    projectRoot,
+    '.specweave',
+    'increments',
+    incrementId,
+    'metadata.json'
+  );
+
+  let metadata: any = {};
+  try {
+    metadata = JSON.parse(await fs.readFile(metadataPath, 'utf-8'));
+  } catch {
+    console.warn(`   ⚠️  Could not read metadata.json for ${incrementId}`);
+  }
+
+  // Ensure reorganization log exists
+  if (!metadata.reorganization) {
+    metadata.reorganization = { events: [], lastHandled: null };
+  }
+
   for (const event of events) {
     switch (event.type) {
-      case 'MOVED_PROJECT':
+      case 'MOVED_PROJECT': {
+        // Update tracked project key in metadata
+        if (event.newKeys?.[0]) {
+          if (!metadata.external_sync) metadata.external_sync = {};
+          if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+          metadata.external_sync.jira.issueKey = event.newKeys[0];
+          metadata.external_sync.jira.project = event.toProject;
+        }
         console.log(`   ✓ Updated project mapping: ${event.fromProject} → ${event.toProject}`);
-        // Update metadata with new project/key
         break;
+      }
 
-      case 'SPLIT':
-        console.log(`   ✓ Added new story from split: ${event.newKeys?.join(', ')}`);
-        // Add new user story to spec.md
+      case 'SPLIT': {
+        // Record split — new keys added as related issues
+        if (!metadata.external_sync?.jira?.relatedKeys) {
+          if (!metadata.external_sync) metadata.external_sync = {};
+          if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+          metadata.external_sync.jira.relatedKeys = [];
+        }
+        if (event.newKeys) {
+          metadata.external_sync.jira.relatedKeys.push(...event.newKeys);
+        }
+        console.log(`   ✓ Recorded split: ${event.newKeys?.join(', ')}`);
         break;
+      }
 
-      case 'MERGED':
-        console.log(`   ✓ Marked story as merged: ${event.originalKeys[0]} → ${event.newKeys?.[0]}`);
-        // Update spec.md to mark as merged
+      case 'MERGED': {
+        // Update issue key to the merge target
+        if (event.newKeys?.[0]) {
+          if (!metadata.external_sync) metadata.external_sync = {};
+          if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+          metadata.external_sync.jira.issueKey = event.newKeys[0];
+          metadata.external_sync.jira.mergedFrom = event.originalKeys[0];
+        }
+        console.log(`   ✓ Updated merged issue: ${event.originalKeys[0]} → ${event.newKeys?.[0]}`);
         break;
+      }
 
-      case 'REPARENTED':
-        console.log(`   ✓ Updated epic link: ${event.toEpic}`);
-        // Update metadata
+      case 'REPARENTED': {
+        // Update parent epic key in metadata
+        if (!metadata.external_sync) metadata.external_sync = {};
+        if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+        metadata.external_sync.jira.epicKey = event.toEpic || null;
+        metadata.external_sync.jira.previousEpicKey = event.fromEpic || null;
+        console.log(`   ✓ Updated epic link: ${event.fromEpic || 'none'} → ${event.toEpic || 'none'}`);
         break;
+      }
 
-      case 'DELETED':
-        console.log(`   ⚠️  Story deleted from Jira: ${event.originalKeys[0]}`);
-        // Mark as deleted in spec.md (don't remove, just mark)
+      case 'DELETED': {
+        // Mark issue as deleted (don't remove metadata, just flag)
+        if (!metadata.external_sync) metadata.external_sync = {};
+        if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+        metadata.external_sync.jira.deleted = true;
+        metadata.external_sync.jira.deletedAt = event.timestamp;
+        console.log(`   ⚠️  Marked as deleted: ${event.originalKeys[0]}`);
         break;
+      }
     }
+
+    // Log event for audit trail
+    metadata.reorganization.events.push({
+      type: event.type,
+      timestamp: event.timestamp,
+      description: event.description,
+    });
+  }
+
+  metadata.reorganization.lastHandled = new Date().toISOString();
+
+  // Write updated metadata
+  try {
+    await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    console.log(`   📄 Updated metadata.json for ${incrementId}`);
+  } catch (err) {
+    console.warn(`   ⚠️  Failed to write metadata: ${(err as Error).message}`);
   }
 
   console.log('\n✅ Reorganization handled\n');

package/plugins/specweave-jira/scripts/refresh-cache.js

@@ -17,7 +17,7 @@ async function refreshJiraCache(projectRoot = process.cwd()) {
   }
   console.log(`\u2705 Cleared ${cleared} cache files`);
 }
-if (require.main === module) {
+if (import.meta.url === `file://${process.argv[1]}`) {
   refreshJiraCache().catch(console.error);
 }
 export {

package/plugins/specweave-jira/scripts/refresh-cache.ts

@@ -34,7 +34,7 @@ export async function refreshJiraCache(projectRoot: string = process.cwd()): Pro
   console.log(`✅ Cleared ${cleared} cache files`);
 }
 
-// CLI entry
-if (require.main === module) {
+// CLI entry (ESM-compatible)
+if (import.meta.url === `file://${process.argv[1]}`) {
   refreshJiraCache().catch(console.error);
 }

package/plugins/specweave-jira/skills/jira-resource-validator/SKILL.md

@@ -59,11 +59,9 @@ if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9](
   exit 1
 fi
 
-# Cloud JIRA: must match <subdomain>.atlassian.net
-if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
-  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
-  exit 1
-fi
+# JIRA Cloud and Server/DC are both supported.
+# Cloud domains match <subdomain>.atlassian.net; self-hosted use custom domains.
+# No hard-block — deployment type is auto-detected at runtime.
 ```
 
 ### API Call Pattern (HTTPS only, quoted variables)