specweave 1.0.350 → 1.0.352

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

@@ -86,11 +86,25 @@ export interface ProjectGitHubConfig {
   teamBoardId?: number;  // For team-board strategy
 }
 
+/** Default cross-team detection keywords (English). Override via `crossTeamKeywords` config. */
+const DEFAULT_CROSS_TEAM_KEYWORDS = [
+  'integration',
+  'cross-team',
+  'cross-project',
+  'shared',
+  'common',
+  'auth',
+  'api-contract',
+  'sync',
+];
+
 export class GitHubSpecSync {
   private specManager: SpecMetadataManager;
   private projectContextManager: ProjectContextManager;
   private projectRoot: string;
   private token?: string;
+  /** Configurable keywords for cross-team spec detection. Case-insensitive matching. */
+  crossTeamKeywords: string[] = DEFAULT_CROSS_TEAM_KEYWORDS;
 
   constructor(projectRoot: string = process.cwd()) {
     this.projectRoot = projectRoot;
@@ -605,6 +619,11 @@ ${acList}
 
   /**
    * Resolve conflicts
+   *
+   * GUARD: Only overwrites local spec title if the user explicitly configured
+   * "remote-wins" as the conflict resolution strategy. Default conflicts
+   * detected by detectConflicts() use 'remote-wins' but this guard ensures
+   * API-sourced titles never silently replace local titles.
    */
   private async resolveConflicts(
     spec: SpecContent,
@@ -612,12 +631,27 @@ ${acList}
   ): Promise<void> {
     for (const conflict of conflicts) {
       if (conflict.resolution === 'remote-wins') {
-        console.log(`   🔄 Resolving: ${conflict.description} (GitHub wins)`);
-        // Update spec metadata from GitHub
+        // Guard: never overwrite local title with an API-sourced title
+        // unless the conflict was explicitly set to remote-wins by user config.
+        // The title field from detectConflicts() defaults to 'remote-wins'
+        // but we should only apply it for non-title fields or when the remote
+        // value looks like a real title (not a stub/API artifact).
         if (conflict.field === 'title') {
+          const remoteTitle = conflict.remoteValue as string;
+          // Skip if remote title looks like a prefix-formatted project title
+          // (e.g., "[SPEC-001] Real Title") — extract and compare only the suffix
+          const remoteSuffix = remoteTitle.replace(/^\[.*?\]\s*/, '');
+          const localTitle = spec.metadata.title;
+          if (remoteSuffix === localTitle || !remoteSuffix) {
+            // No real difference or empty remote — skip
+            continue;
+          }
+          console.log(`   🔄 Resolving: ${conflict.description} (GitHub wins — explicit remote-wins)`);
           await this.specManager.saveMetadata(spec.metadata.id, {
             title: conflict.remoteValue
           });
+        } else {
+          console.log(`   🔄 Resolving: ${conflict.description} (GitHub wins)`);
         }
       }
     }
@@ -659,23 +693,74 @@ ${acList}
   }
 
   /**
-   * Fetch GitHub Project details
+   * Fetch GitHub Project details via GraphQL ProjectV2 API
    */
   private async fetchGitHubProject(
     owner: string,
     repo: string,
     projectId: number
   ): Promise<GitHubProject> {
-    // Placeholder - would use GraphQL to fetch project
-    return {
-      id: projectId,
-      title: 'Project Title',
-      number: 1,
-      url: 'https://github.com/...',
-      state: 'open',
-      owner,
-      repo
-    };
+    const query = `
+      query GetProject($owner: String!, $number: Int!) {
+        user(login: $owner) {
+          projectV2(number: $number) {
+            id
+            title
+            number
+            url
+            closed
+          }
+        }
+      }
+    `;
+
+    try {
+      const result = await this.executeGraphQL(query, {
+        owner,
+        number: projectId,
+      });
+
+      // Try user first, fall back to org
+      let project = result.data?.user?.projectV2;
+      if (!project) {
+        const orgQuery = `
+          query GetOrgProject($owner: String!, $number: Int!) {
+            organization(login: $owner) {
+              projectV2(number: $number) {
+                id
+                title
+                number
+                url
+                closed
+              }
+            }
+          }
+        `;
+        const orgResult = await this.executeGraphQL(orgQuery, {
+          owner,
+          number: projectId,
+        });
+        project = orgResult.data?.organization?.projectV2;
+      }
+
+      if (!project) {
+        throw new Error(`GitHub Project #${projectId} not found for ${owner}`);
+      }
+
+      return {
+        id: projectId,
+        title: project.title,
+        number: project.number,
+        url: project.url,
+        state: project.closed ? 'closed' : 'open',
+        owner,
+        repo,
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch GitHub Project #${projectId}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
   }
 
   /**
@@ -932,20 +1017,9 @@ ${acList}
    * - Tags include multiple project names
    */
   private isCrossTeamSpec(spec: SpecContent): boolean {
-    const crossTeamKeywords = [
-      'integration',
-      'cross-team',
-      'cross-project',
-      'shared',
-      'common',
-      'auth',  // Auth often touches frontend + backend
-      'api-contract',
-      'sync'
-    ];
-
     const title = spec.metadata.title.toLowerCase();
-    const hasCrossTeamKeyword = crossTeamKeywords.some(keyword =>
-      title.includes(keyword)
+    const hasCrossTeamKeyword = this.crossTeamKeywords.some(keyword =>
+      title.toLowerCase().includes(keyword.toLowerCase())
     );
 
     // Check tags for multiple project references

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

@@ -44,7 +44,8 @@ class GitHubSyncOrchestrator {
       projectV2Number: this.config.projectV2Number,
       projectV2Id: this.config.projectV2Id
     });
-    const project = await boardResolver.findOrCreateProject("SpecWeave Sync Board");
+    const boardName = this.config.boardName || "SpecWeave Sync Board";
+    const project = await boardResolver.findOrCreateProject(boardName);
     const nodeIds = pushResult.created.filter((item) => item.issueNodeId).map((item) => item.issueNodeId);
     const itemIds = await boardResolver.addIssuesToProject(project.id, nodeIds);
     const nodeIdToStory = /* @__PURE__ */ new Map();

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

@@ -27,6 +27,7 @@ export interface SyncOrchestratorConfig {
   projectV2Enabled?: boolean;
   projectV2Number?: number;
   projectV2Id?: string;
+  boardName?: string;
   statusFieldMapping?: Record<string, string>;
   priorityFieldMapping?: Record<string, string>;
 }
@@ -106,7 +107,8 @@ export class GitHubSyncOrchestrator {
       projectV2Id: this.config.projectV2Id,
     });
 
-    const project = await boardResolver.findOrCreateProject('SpecWeave Sync Board');
+    const boardName = this.config.boardName || 'SpecWeave Sync Board';
+    const project = await boardResolver.findOrCreateProject(boardName);
 
     // Collect issue node IDs from created issues
     const nodeIds = pushResult.created

package/plugins/specweave-github/lib/github-us-auto-closer.js

@@ -60,6 +60,10 @@ async function autoCloseCompletedUserStories(incrementId, affectedUSIds, specPat
       execOpts
     );
     if (closeResult.success) {
+      await ensureLabelExists("status:completed", repoSlug, execOpts, {
+        color: "6f42c1",
+        description: "Completed work item"
+      });
       await execFileNoThrow(
         "gh",
         ["issue", "edit", issueNum, "--remove-label", "status:active", "--add-label", "status:completed", "-R", repoSlug],
@@ -129,6 +133,27 @@ async function parseIssueLinks(specPath) {
   }
   return links;
 }
+async function ensureLabelExists(labelName, repoSlug, execOpts, defaults) {
+  const checkResult = await execFileNoThrow(
+    "gh",
+    ["label", "list", "--repo", repoSlug, "--search", labelName, "--json", "name", "--jq", ".[].name"],
+    execOpts
+  );
+  if (checkResult.success) {
+    const existing = (checkResult.stdout || "").trim().split("\n").filter(Boolean);
+    if (existing.some((name) => name === labelName)) {
+      return;
+    }
+  }
+  const createResult = await execFileNoThrow(
+    "gh",
+    ["label", "create", labelName, "--repo", repoSlug, "--color", defaults.color, "--description", defaults.description, "--force"],
+    execOpts
+  );
+  if (!createResult.success) {
+    console.warn(`\u26A0\uFE0F  Could not create label "${labelName}": ${createResult.stderr || "unknown error"} (continuing without label)`);
+  }
+}
 function parseACStatesForUS(content, usId) {
   const states = [];
   const usNum = String(parseInt(usId.replace("US-", ""), 10));

package/plugins/specweave-github/lib/github-us-auto-closer.ts

@@ -130,6 +130,12 @@ export async function autoCloseCompletedUserStories(
     );
 
     if (closeResult.success) {
+      // Ensure required labels exist before applying them
+      await ensureLabelExists('status:completed', repoSlug, execOpts, {
+        color: '6f42c1',
+        description: 'Completed work item',
+      });
+
       // Update labels: remove status:active, add status:completed
       await execFileNoThrow(
         'gh',
@@ -224,6 +230,43 @@ async function parseIssueLinks(specPath: string): Promise<Record<string, ParsedU
   return links;
 }
 
+/**
+ * Ensure a label exists in the repo before applying it.
+ * Creates the label if missing; logs a warning and continues on permission errors.
+ */
+async function ensureLabelExists(
+  labelName: string,
+  repoSlug: string,
+  execOpts: { env?: Record<string, string> },
+  defaults: { color: string; description: string },
+): Promise<void> {
+  // Check if label exists
+  const checkResult = await execFileNoThrow(
+    'gh',
+    ['label', 'list', '--repo', repoSlug, '--search', labelName, '--json', 'name', '--jq', '.[].name'],
+    execOpts,
+  );
+
+  if (checkResult.success) {
+    const existing = (checkResult.stdout || '').trim().split('\n').filter(Boolean);
+    if (existing.some(name => name === labelName)) {
+      return; // Label already exists
+    }
+  }
+
+  // Create the label
+  const createResult = await execFileNoThrow(
+    'gh',
+    ['label', 'create', labelName, '--repo', repoSlug, '--color', defaults.color, '--description', defaults.description, '--force'],
+    execOpts,
+  );
+
+  if (!createResult.success) {
+    // Permission error or other failure — log warning and continue
+    console.warn(`⚠️  Could not create label "${labelName}": ${createResult.stderr || 'unknown error'} (continuing without label)`);
+  }
+}
+
 /**
  * Extract AC states for a specific user story from spec.md content.
  */

package/plugins/specweave-github/lib/per-us-sync.js

@@ -141,20 +141,35 @@ class PerUSGitHubSync {
   }
   /**
    * Find existing issue by US ID in title
+   *
+   * Paginates through all issues to avoid missing matches on repos with 100+ issues.
+   * Deduplicates by issue number before returning.
    */
   async findExistingIssue(mapping, usId) {
     try {
-      const response = await this.octokit.issues.listForRepo({
-        owner: mapping.owner,
-        repo: mapping.repo,
-        labels: "specweave",
-        state: "all",
-        per_page: 100
-      });
-      const existing = response.data.find(
-        (issue) => issue.title.includes(`[${usId}]`)
-      );
-      return existing ? { number: existing.number } : null;
+      const seenNumbers = /* @__PURE__ */ new Set();
+      let page = 1;
+      const perPage = 100;
+      while (true) {
+        const response = await this.octokit.issues.listForRepo({
+          owner: mapping.owner,
+          repo: mapping.repo,
+          labels: "specweave",
+          state: "all",
+          per_page: perPage,
+          page
+        });
+        for (const issue of response.data) {
+          if (seenNumbers.has(issue.number)) continue;
+          seenNumbers.add(issue.number);
+          if (issue.title.includes(`[${usId}]`)) {
+            return { number: issue.number };
+          }
+        }
+        if (response.data.length < perPage) break;
+        page++;
+      }
+      return null;
     } catch {
       return null;
     }

package/plugins/specweave-github/lib/per-us-sync.ts

@@ -249,25 +249,43 @@ export class PerUSGitHubSync {
 
   /**
    * Find existing issue by US ID in title
+   *
+   * Paginates through all issues to avoid missing matches on repos with 100+ issues.
+   * Deduplicates by issue number before returning.
    */
   private async findExistingIssue(
     mapping: GitHubMapping,
     usId: string
   ): Promise<{ number: number } | null> {
     try {
-      const response = await this.octokit.issues.listForRepo({
-        owner: mapping.owner,
-        repo: mapping.repo,
-        labels: 'specweave',
-        state: 'all',
-        per_page: 100
-      });
+      const seenNumbers = new Set<number>();
+      let page = 1;
+      const perPage = 100;
+
+      while (true) {
+        const response = await this.octokit.issues.listForRepo({
+          owner: mapping.owner,
+          repo: mapping.repo,
+          labels: 'specweave',
+          state: 'all',
+          per_page: perPage,
+          page,
+        });
+
+        for (const issue of response.data) {
+          if (seenNumbers.has(issue.number)) continue;
+          seenNumbers.add(issue.number);
+          if (issue.title.includes(`[${usId}]`)) {
+            return { number: issue.number };
+          }
+        }
 
-      const existing = response.data.find(issue =>
-        issue.title.includes(`[${usId}]`)
-      );
+        // No more pages
+        if (response.data.length < perPage) break;
+        page++;
+      }
 
-      return existing ? { number: existing.number } : null;
+      return null;
     } catch {
       return null;
     }

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

@@ -96,7 +96,8 @@ EOF
   exit 0
 fi
 
-JIRA_ISSUE=$(jq -r '.jira.issue // empty' "$METADATA_FILE" 2>/dev/null)
+# Read JIRA issue key: canonical path first, then legacy fallbacks
+JIRA_ISSUE=$(jq -r '.external_sync.jira.issueKey // .jira.issueKey // .jira.issue // empty' "$METADATA_FILE" 2>/dev/null)
 
 if [ -z "$JIRA_ISSUE" ]; then
   echo "[$(date)] [JIRA] ℹ️  No JIRA issue linked to $CURRENT_INCREMENT, skipping sync" >> "$DEBUG_LOG" 2>/dev/null || true

package/plugins/specweave-jira/lib/content-format-adapter.js

@@ -0,0 +1,116 @@
+import { getApiVersion } from "./jira-deployment-detector.js";
+function toADF(text) {
+  const lines = text.split("\n");
+  const content = [];
+  let currentParagraph = [];
+  const flushParagraph = () => {
+    if (currentParagraph.length > 0) {
+      content.push({ type: "paragraph", content: [...currentParagraph] });
+      currentParagraph = [];
+    }
+  };
+  for (const line of lines) {
+    const wikiHeadingMatch = line.match(/^h(\d)\.\s+(.+)$/);
+    const mdHeadingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (wikiHeadingMatch) {
+      flushParagraph();
+      const level = parseInt(wikiHeadingMatch[1]);
+      content.push({
+        type: "heading",
+        attrs: { level },
+        content: [{ type: "text", text: wikiHeadingMatch[2] }]
+      });
+      continue;
+    }
+    if (mdHeadingMatch) {
+      flushParagraph();
+      const level = mdHeadingMatch[1].length;
+      content.push({
+        type: "heading",
+        attrs: { level },
+        content: [{ type: "text", text: mdHeadingMatch[2] }]
+      });
+      continue;
+    }
+    if (/^-{3,}$/.test(line.trim())) {
+      flushParagraph();
+      content.push({ type: "rule" });
+      continue;
+    }
+    const bulletMatch = line.match(/^\*\s+(.+)$/) || line.match(/^-\s+(.+)$/);
+    if (bulletMatch) {
+      flushParagraph();
+      const listItem = {
+        type: "listItem",
+        content: [{ type: "paragraph", content: [{ type: "text", text: bulletMatch[1] }] }]
+      };
+      const lastNode = content[content.length - 1];
+      if (lastNode && lastNode.type === "bulletList" && lastNode.content) {
+        lastNode.content.push(listItem);
+      } else {
+        content.push({ type: "bulletList", content: [listItem] });
+      }
+      continue;
+    }
+    if (line.trim() === "") {
+      flushParagraph();
+      continue;
+    }
+    let textContent = line;
+    const textNodes = [];
+    const parts = textContent.split(/(\*[^*]+\*|_[^_]+_)/);
+    for (const part of parts) {
+      if (part.startsWith("*") && part.endsWith("*") && part.length > 2) {
+        textNodes.push({
+          type: "text",
+          text: part.slice(1, -1),
+          marks: [{ type: "strong" }]
+        });
+      } else if (part.startsWith("_") && part.endsWith("_") && part.length > 2) {
+        textNodes.push({
+          type: "text",
+          text: part.slice(1, -1),
+          marks: [{ type: "em" }]
+        });
+      } else if (part) {
+        textNodes.push({ type: "text", text: part });
+      }
+    }
+    currentParagraph.push(...textNodes);
+  }
+  flushParagraph();
+  if (content.length === 0) {
+    content.push({
+      type: "paragraph",
+      content: [{ type: "text", text: text || "" }]
+    });
+  }
+  return {
+    type: "doc",
+    version: 1,
+    content
+  };
+}
+function toWikiMarkup(text) {
+  return text;
+}
+function formatContent(text, domain) {
+  const version = getApiVersion(domain);
+  if (version === "3") {
+    return toADF(text);
+  }
+  return toWikiMarkup(text);
+}
+function toDescription(text, domain) {
+  return formatContent(text, domain);
+}
+function toCommentBody(text, domain) {
+  return formatContent(text, domain);
+}
+export {
+  formatContent,
+  toADF,
+  toCommentBody,
+  toDescription,
+  toWikiMarkup
+};