specweave 1.0.301 → 1.0.304

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

@@ -10,7 +10,7 @@
  * Creates ONE issue PER user story file from specs/{project}/FS-XXX/us-*.md
  */
 
-import { readdir, readFile, writeFile } from 'fs/promises';
+import { readdir, readFile, writeFile, mkdir } from 'fs/promises';
 import { existsSync } from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -54,6 +54,9 @@ export class GitHubFeatureSync {
   private calculator: CompletionCalculator;
   private token?: string;
 
+  // Cached default branch for the sync session (one API call per session)
+  private defaultBranch: string | null = null;
+
   // SYNC LOCK: Prevent concurrent syncs of the same feature
   // Maps featureId → last sync timestamp
   private static syncLocks: Map<string, number> = new Map();
@@ -68,6 +71,33 @@ export class GitHubFeatureSync {
     this.token = getGitHubAuthFromProject(projectRoot).token;
   }
 
+  /**
+   * Detect the default branch from the GitHub API.
+   * Caches the result per sync session to avoid repeated API calls.
+   * Falls back to 'main' if API call fails.
+   */
+  private async detectDefaultBranch(): Promise<string> {
+    if (this.defaultBranch) {
+      return this.defaultBranch;
+    }
+
+    const owner = this.client.getOwner();
+    const repo = this.client.getRepo();
+
+    const result = await execFileNoThrow('gh', [
+      'api', `repos/${owner}/${repo}`, '--jq', '.default_branch'
+    ], { env: this.getGhEnv() });
+
+    if (result.exitCode === 0 && result.stdout.trim()) {
+      this.defaultBranch = result.stdout.trim();
+    } else {
+      console.warn(`   ⚠️  Failed to detect default branch, falling back to 'main': ${result.stderr}`);
+      this.defaultBranch = 'main';
+    }
+
+    return this.defaultBranch;
+  }
+
   /**
    * Get environment object with GH_TOKEN for gh CLI commands.
    * This ensures the token from .env is passed to all gh operations,
@@ -163,6 +193,10 @@ export class GitHubFeatureSync {
     let issuesCreated = 0;
     let issuesUpdated = 0;
 
+    // Detect default branch once per sync session
+    const detectedBranch = await this.detectDefaultBranch();
+    console.log(`   🌿 Default branch: ${detectedBranch}`);
+
     for (const userStory of userStories) {
       console.log(`\n   🔹 Processing ${userStory.id}: ${userStory.title}`);
 
@@ -170,7 +204,7 @@ export class GitHubFeatureSync {
       const repoInfo = {
         owner: this.client.getOwner(),
         repo: this.client.getRepo(),
-        branch: 'develop'  // TODO: detect from git
+        branch: detectedBranch
       };
 
       const builder = new UserStoryIssueBuilder(
@@ -294,7 +328,8 @@ export class GitHubFeatureSync {
   }
 
   /**
-   * Find Feature folder in specs directory
+   * Find Feature folder in specs directory.
+   * Falls back to auto-creating from increment spec.md if living docs don't exist.
    */
   private async findFeatureFolder(featureId: string): Promise<string | null> {
     // v5.0.0+: NO _features folder - features live in project folders
@@ -315,9 +350,296 @@ export class GitHubFeatureSync {
       return legacyFolder;
     }
 
+    // FALLBACK (v1.0.302): Auto-create feature folder from increment spec.md
+    // Most increments never get living docs created, so sync silently fails.
+    // This makes sync self-healing by creating minimal living docs on-the-fly.
+    console.log(`   ℹ️  Feature folder not found in living docs, attempting auto-create from spec.md...`);
+    const created = await this.createFeatureFolderFromSpec(featureId, projectFolders);
+    if (created) {
+      return created;
+    }
+
     return null;
   }
 
+  /**
+   * Find the increment folder for a given feature ID.
+   * Converts FS-271 -> finds 0271-xxx-xxx/ in .specweave/increments/
+   */
+  private async findIncrementFolder(featureId: string): Promise<string | null> {
+    const numMatch = featureId.match(/FS-0*(\d+)E?/i);
+    if (!numMatch) return null;
+
+    const num = parseInt(numMatch[1], 10);
+    const paddedNum = String(num).padStart(4, '0');
+
+    const incrementsDir = path.join(this.projectRoot, '.specweave/increments');
+    if (!existsSync(incrementsDir)) return null;
+
+    const entries = await readdir(incrementsDir);
+    const match = entries.find(e => e.startsWith(paddedNum + '-'));
+    if (!match) return null;
+
+    return path.join(incrementsDir, match);
+  }
+
+  /**
+   * Auto-create a feature folder (FEATURE.md + us-NNN.md files) from an
+   * increment's spec.md. This enables GitHub sync even when the living docs
+   * builder hasn't run yet.
+   */
+  private async createFeatureFolderFromSpec(
+    featureId: string,
+    projectFolders: string[]
+  ): Promise<string | null> {
+    try {
+      const incrementFolder = await this.findIncrementFolder(featureId);
+      if (!incrementFolder) {
+        console.log(`   ⚠️  No increment folder found for ${featureId}`);
+        return null;
+      }
+
+      const specPath = path.join(incrementFolder, 'spec.md');
+      if (!existsSync(specPath)) {
+        console.log(`   ⚠️  No spec.md found in ${path.basename(incrementFolder)}`);
+        return null;
+      }
+
+      const specContent = await readFile(specPath, 'utf-8');
+
+      // Parse frontmatter
+      const fmMatch = specContent.match(/^---\n([\s\S]*?)\n---/);
+      if (!fmMatch) {
+        console.log(`   ⚠️  spec.md has no YAML frontmatter`);
+        return null;
+      }
+
+      const frontmatter = yaml.parse(fmMatch[1]);
+      const title = frontmatter.title || path.basename(incrementFolder).replace(/^\d+-/, '');
+      const status = frontmatter.status || 'active';
+      const priority = frontmatter.priority || 'P2';
+      const created = frontmatter.created || new Date().toISOString().split('T')[0];
+      const incrementId = frontmatter.increment || path.basename(incrementFolder);
+
+      // Determine target project folder from spec.md user stories or first available
+      let targetProjectFolder = projectFolders[0]; // Default: first project folder
+      const projectMatch = specContent.match(/\*\*Project\*\*:\s*(\S+)/);
+      if (projectMatch) {
+        const projectName = projectMatch[1];
+        const matchingFolder = projectFolders.find(f => path.basename(f) === projectName);
+        if (matchingFolder) {
+          targetProjectFolder = matchingFolder;
+        }
+      }
+
+      if (!targetProjectFolder) {
+        console.log(`   ⚠️  No project folder available for feature creation`);
+        return null;
+      }
+
+      // Create feature folder
+      const featureFolder = path.join(targetProjectFolder, featureId);
+      await mkdir(featureFolder, { recursive: true });
+
+      // Parse user stories from spec.md body
+      const userStories = this.parseUserStoriesFromSpec(specContent, featureId);
+
+      // Create FEATURE.md
+      const featureMd = this.buildFeatureMd(featureId, title, status, priority, created, incrementId, userStories);
+      await writeFile(path.join(featureFolder, 'FEATURE.md'), featureMd, 'utf-8');
+
+      // Create us-NNN.md files
+      for (const us of userStories) {
+        const usFilename = `us-${us.id.replace('US-', '').padStart(3, '0')}-${this.slugify(us.title)}.md`;
+        const usMd = this.buildUserStoryMd(us, featureId, incrementId);
+        await writeFile(path.join(featureFolder, usFilename), usMd, 'utf-8');
+      }
+
+      console.log(`   ✅ Auto-created feature folder with ${userStories.length} user stories`);
+      return featureFolder;
+    } catch (error) {
+      console.log(`   ⚠️  Failed to auto-create feature folder: ${(error as Error).message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Parse user stories from spec.md markdown content.
+   */
+  private parseUserStoriesFromSpec(
+    specContent: string,
+    featureId: string
+  ): Array<{
+    id: string;
+    title: string;
+    priority: string;
+    project: string;
+    storyText: string;
+    acceptanceCriteria: string[];
+    status: string;
+  }> {
+    const stories: Array<{
+      id: string;
+      title: string;
+      priority: string;
+      project: string;
+      storyText: string;
+      acceptanceCriteria: string[];
+      status: string;
+    }> = [];
+
+    // Match ### US-NNN: Title (Priority) sections
+    const usRegex = /### (US-\d+):\s*(.+?)(?:\s*\((P\d)\))?\s*\n([\s\S]*?)(?=\n### US-|\n## |\n---\s*\n### US-|$)/g;
+    let match;
+
+    while ((match = usRegex.exec(specContent)) !== null) {
+      const usId = match[1];
+      const rawTitle = match[2].trim();
+      const priority = match[3] || 'P2';
+      const body = match[4];
+
+      // Skip template placeholders
+      if (rawTitle === '[Story Title]') continue;
+
+      // Extract project
+      const projectMatch = body.match(/\*\*Project\*\*:\s*(\S+)/);
+      const project = projectMatch ? projectMatch[1] : 'specweave';
+
+      // Extract story text (As a... I want... So that...)
+      const storyMatch = body.match(/\*\*As a\*\*\s+([\s\S]*?)(?=\n\*\*Acceptance Criteria|$)/);
+      const storyText = storyMatch ? storyMatch[1].trim() : '';
+
+      // Extract acceptance criteria
+      const acs: string[] = [];
+      const acRegex = /- \[[ x]\] \*\*AC-[^*]+\*\*:\s*(.+)/g;
+      let acMatch;
+      while ((acMatch = acRegex.exec(body)) !== null) {
+        acs.push(acMatch[0]);
+      }
+
+      // Determine status from ACs
+      const totalAcs = acs.length;
+      const completedAcs = acs.filter(ac => ac.startsWith('- [x]')).length;
+      let status = 'not-started';
+      if (totalAcs > 0 && completedAcs === totalAcs) status = 'complete';
+      else if (completedAcs > 0) status = 'active';
+
+      stories.push({
+        id: usId,
+        title: rawTitle,
+        priority,
+        project,
+        storyText,
+        acceptanceCriteria: acs,
+        status,
+      });
+    }
+
+    return stories;
+  }
+
+  /**
+   * Build FEATURE.md content matching the living docs format.
+   */
+  private buildFeatureMd(
+    featureId: string,
+    title: string,
+    status: string,
+    priority: string,
+    created: string,
+    incrementId: string,
+    userStories: Array<{ id: string; title: string }>
+  ): string {
+    const now = new Date().toISOString().split('T')[0];
+    const mappedStatus = status === 'planned' ? 'planning'
+      : status === 'completed' || status === 'done' ? 'complete'
+      : status === 'active' || status === 'in-progress' ? 'active'
+      : 'planning';
+
+    const fm: Record<string, unknown> = {
+      id: featureId,
+      title,
+      type: 'feature',
+      status: mappedStatus,
+      priority,
+      created,
+      lastUpdated: now,
+      tldr: title,
+      complexity: 'medium',
+      auto_created: true,
+    };
+
+    const yamlFm = yaml.stringify(fm);
+
+    let body = `\n# ${title}\n\n## TL;DR\n\n**What**: ${title}\n**Status**: ${mappedStatus} | **Priority**: ${priority}\n**User Stories**: ${userStories.length}\n\n## Overview\n\n${title}\n\n## Implementation History\n\n| Increment | Status |\n|-----------|--------|\n| [${incrementId}](../../../../../increments/${incrementId}/spec.md) | ${mappedStatus} |\n\n## User Stories\n`;
+
+    for (const us of userStories) {
+      body += `\n- [${us.id}: ${us.title}](./${us.id.toLowerCase()}.md)`;
+    }
+
+    return `---\n${yamlFm}---${body}\n`;
+  }
+
+  /**
+   * Build us-NNN.md content matching the living docs format.
+   */
+  private buildUserStoryMd(
+    us: {
+      id: string;
+      title: string;
+      priority: string;
+      project: string;
+      storyText: string;
+      acceptanceCriteria: string[];
+      status: string;
+    },
+    featureId: string,
+    incrementId: string
+  ): string {
+    const now = new Date().toISOString().split('T')[0];
+
+    const fm: Record<string, unknown> = {
+      id: us.id,
+      feature: featureId,
+      title: us.title,
+      status: us.status,
+      priority: us.priority,
+      created: now,
+      project: us.project,
+    };
+
+    const yamlFm = yaml.stringify(fm);
+
+    let body = `\n# ${us.id}: ${us.title}\n\n**Feature**: [${featureId}](./FEATURE.md)\n\n`;
+
+    if (us.storyText) {
+      body += `${us.storyText}\n\n`;
+    }
+
+    body += `---\n\n## Acceptance Criteria\n\n`;
+
+    if (us.acceptanceCriteria.length > 0) {
+      body += us.acceptanceCriteria.join('\n') + '\n';
+    } else {
+      body += `- [ ] **AC-${us.id.replace('US-', 'US')}-01**: Pending specification\n`;
+    }
+
+    body += `\n---\n\n## Implementation\n\n**Increment**: [${incrementId}](../../../../../increments/${incrementId}/spec.md)\n`;
+
+    return `---\n${yamlFm}---${body}\n`;
+  }
+
+  /**
+   * Convert a title to a URL-safe slug.
+   */
+  private slugify(text: string): string {
+    return text
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .substring(0, 60);
+  }
+
   /**
    * Backfill increment metadata.json with GitHub issue reference (v1.0.240)
    *
@@ -467,9 +789,13 @@ export class GitHubFeatureSync {
     // CRITICAL: Check if milestone already exists before creating
     // NOTE: Must use per_page=100 to handle repos with 30+ milestones (GitHub default is 30)
     // BUG FIX: Without pagination, milestone #31+ won't be found → false "not found" → HTTP 422 duplicate error
+    // FIX (v1.0.302): Use explicit owner/repo from config, not :owner/:repo which resolves from git remote
+    const owner = this.client.getOwner();
+    const repo = this.client.getRepo();
+
     const existingResult = await execFileNoThrow('gh', [
       'api',
-      'repos/:owner/:repo/milestones?per_page=100&state=all',
+      `repos/${owner}/${repo}/milestones?per_page=100&state=all`,
       '--jq',
       `.[] | select(.title == "${title}") | {number, html_url}`,
     ], { env: this.getGhEnv() });
@@ -496,7 +822,7 @@ export class GitHubFeatureSync {
 
     const result = await execFileNoThrow('gh', [
       'api',
-      'repos/:owner/:repo/milestones',
+      `repos/${owner}/${repo}/milestones`,
       '-X',
       'POST',
       '-f',
@@ -677,7 +1003,9 @@ export class GitHubFeatureSync {
       acsPercentage: number;
       tasksPercentage: number;
       acsTotal?: number;
+      acsCompleted?: number;
       tasksTotal?: number;
+      tasksCompleted?: number;
       frontmatterStatus?: string;
     }
   ): Promise<void> {
@@ -759,6 +1087,26 @@ export class GitHubFeatureSync {
       } else {
         console.warn(`      ⚠️  Failed to add label ${newStatusLabel}: ${result.stderr}`);
       }
+
+      // Step 3: Auto-close issue when status:complete and issue still OPEN
+      // This ensures closure happens atomically with the label update,
+      // preventing issues like #1198 where label is applied but issue stays open
+      if (newStatusLabel === 'status:complete' && issueData.state.toLowerCase() !== 'closed') {
+        try {
+          const completionComment = this.calculator.buildCompletionComment(completion as any);
+          await execFileNoThrow('gh', [
+            'issue',
+            'close',
+            issueNumber.toString(),
+            '--comment',
+            completionComment,
+          ], { env: this.getGhEnv() });
+          console.log(`      ✅ Auto-closed issue #${issueNumber} (status:complete)`);
+        } catch (closeError) {
+          // Non-blocking: close failure shouldn't break sync
+          console.warn(`      ⚠️  Failed to auto-close issue #${issueNumber}: ${(closeError as Error).message}`);
+        }
+      }
     } catch (error) {
       // Non-blocking: Label update failure shouldn't break sync
       console.warn(`      ⚠️  Failed to update status labels: ${(error as Error).message}`);

package/plugins/specweave-github/lib/user-story-content-builder.js

@@ -36,11 +36,13 @@ class UserStoryContentBuilder {
    * Build GitHub issue body from user story content
    *
    * @param githubRepo Optional GitHub repo in format "owner/repo" for generating URLs
+   * @param branch Optional branch name for URL generation (defaults to 'main')
    */
-  async buildIssueBody(githubRepo) {
+  async buildIssueBody(githubRepo, branch) {
     const content = await this.parse();
     let body = "";
     const repo = githubRepo || await this.detectGitHubRepo();
+    const branchName = branch || "main";
     const completedACs = content.acceptanceCriteria.filter((ac) => ac.completed).length;
     const totalACs = content.acceptanceCriteria.length;
     const completedTasks = content.tasks.filter((t) => t.status).length;
@@ -83,7 +85,7 @@ class UserStoryContentBuilder {
     const usFilename = path.basename(this.userStoryPath);
     if (repo) {
       const relativePath = this.userStoryPath.replace(this.projectRoot, "").replace(/^\//, "");
-      body += `\u{1F4C4} View full story: [\`${usFilename}\`](https://github.com/${repo}/tree/develop/${relativePath})
+      body += `\u{1F4C4} View full story: [\`${usFilename}\`](https://github.com/${repo}/tree/${branchName}/${relativePath})
 
 `;
     }
@@ -128,7 +130,7 @@ class UserStoryContentBuilder {
 `;
       if (content.incrementId) {
         if (repo) {
-          body += `**Increment**: [${content.incrementId}](https://github.com/${repo}/tree/develop/.specweave/increments/${content.incrementId})
+          body += `**Increment**: [${content.incrementId}](https://github.com/${repo}/tree/${branchName}/.specweave/increments/${content.incrementId})
 
 `;
         } else {
@@ -142,7 +144,7 @@ class UserStoryContentBuilder {
         let taskLink = task.link;
         if (repo && taskLink.startsWith("../../")) {
           const relativePath = taskLink.replace(/^\.\.\/\.\.\//, ".specweave/");
-          taskLink = `https://github.com/${repo}/tree/develop/${relativePath}`;
+          taskLink = `https://github.com/${repo}/tree/${branchName}/${relativePath}`;
         }
         body += `- ${checkbox} [${task.id}: ${task.title}](${taskLink})
 `;

package/plugins/specweave-github/lib/user-story-content-builder.ts

@@ -110,14 +110,16 @@ export class UserStoryContentBuilder {
    * Build GitHub issue body from user story content
    *
    * @param githubRepo Optional GitHub repo in format "owner/repo" for generating URLs
+   * @param branch Optional branch name for URL generation (defaults to 'main')
    */
-  async buildIssueBody(githubRepo?: string): Promise<string> {
+  async buildIssueBody(githubRepo?: string, branch?: string): Promise<string> {
     const content = await this.parse();
 
     let body = '';
 
     // Detect GitHub repo from git remote if not provided
     const repo = githubRepo || await this.detectGitHubRepo();
+    const branchName = branch || 'main';
 
     // ❌ REMOVED: Metadata header (Feature, Status, Priority)
     // WHY: GitHub has NATIVE fields for this (labels, milestones)
@@ -160,7 +162,7 @@ export class UserStoryContentBuilder {
       const relativePath = this.userStoryPath
         .replace(this.projectRoot, '')
         .replace(/^\//, '');
-      body += `📄 View full story: [\`${usFilename}\`](https://github.com/${repo}/tree/develop/${relativePath})\n\n`;
+      body += `📄 View full story: [\`${usFilename}\`](https://github.com/${repo}/tree/${branchName}/${relativePath})\n\n`;
     }
 
     body += `---\n\n`;
@@ -196,7 +198,7 @@ export class UserStoryContentBuilder {
 
       if (content.incrementId) {
         if (repo) {
-          body += `**Increment**: [${content.incrementId}](https://github.com/${repo}/tree/develop/.specweave/increments/${content.incrementId})\n\n`;
+          body += `**Increment**: [${content.incrementId}](https://github.com/${repo}/tree/${branchName}/.specweave/increments/${content.incrementId})\n\n`;
         } else {
           body += `**Increment**: ${content.incrementId}\n\n`;
         }
@@ -208,7 +210,7 @@ export class UserStoryContentBuilder {
         let taskLink = task.link;
         if (repo && taskLink.startsWith('../../')) {
           const relativePath = taskLink.replace(/^\.\.\/\.\.\//, '.specweave/');
-          taskLink = `https://github.com/${repo}/tree/develop/${relativePath}`;
+          taskLink = `https://github.com/${repo}/tree/${branchName}/${relativePath}`;
         }
         body += `- ${checkbox} [${task.id}: ${task.title}](${taskLink})\n`;
       }

package/plugins/specweave-github/lib/user-story-issue-builder.js

@@ -322,21 +322,36 @@ User Story ID: ${frontmatter.id}`
     sections.push("");
     if (this.repoOwner && this.repoName) {
       const baseUrl = `https://github.com/${this.repoOwner}/${this.repoName}/blob/${this.branch}`;
-      const pathMatch = this.userStoryPath.match(/specs\/([^/]+)\/FS-\d+\//);
-      const projectFolder = pathMatch ? pathMatch[1] : "default";
-      sections.push(`- **Feature Spec**: [${this.featureId}](${baseUrl}/.specweave/docs/internal/specs/${projectFolder}/${this.featureId}/FEATURE.md)`);
-      const relativeUSPath = path.relative(this.projectRoot, this.userStoryPath);
-      sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${baseUrl}/${relativeUSPath})`);
       const incrementMatch = implMatch?.[1]?.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
-      if (incrementMatch) {
-        const incrementId = incrementMatch[1];
+      const incrementId = incrementMatch ? incrementMatch[1] : null;
+      if (incrementId) {
+        sections.push(`- **Feature Spec**: [${this.featureId}](${baseUrl}/.specweave/increments/${incrementId}/spec.md)`);
+      } else {
+        const pathMatch = this.userStoryPath.match(/specs\/([^/]+)\/FS-\d+\//);
+        const projectFolder = pathMatch ? pathMatch[1] : "default";
+        sections.push(`- **Feature Spec**: [${this.featureId}](${baseUrl}/.specweave/docs/internal/specs/${projectFolder}/${this.featureId}/FEATURE.md)`);
+      }
+      if (incrementId) {
+        sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${baseUrl}/.specweave/increments/${incrementId}/spec.md)`);
+      } else {
+        const relativeUSPath = path.relative(this.projectRoot, this.userStoryPath);
+        sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${baseUrl}/${relativeUSPath})`);
+      }
+      if (incrementId) {
         sections.push(`- **Increment**: [${incrementId}](${baseUrl}/.specweave/increments/${incrementId})`);
       }
     } else {
-      const pathMatch = this.userStoryPath.match(/specs\/([^/]+)\/FS-\d+\//);
-      const projectFolder = pathMatch ? pathMatch[1] : "default";
-      sections.push(`- **Feature Spec**: [${this.featureId}](../.specweave/docs/internal/specs/${projectFolder}/${this.featureId}/FEATURE.md)`);
-      sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${this.userStoryPath})`);
+      const incrementMatch = implMatch?.[1]?.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+      const incrementId = incrementMatch ? incrementMatch[1] : null;
+      if (incrementId) {
+        sections.push(`- **Feature Spec**: [${this.featureId}](.specweave/increments/${incrementId}/spec.md)`);
+        sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](.specweave/increments/${incrementId}/spec.md)`);
+      } else {
+        const pathMatch = this.userStoryPath.match(/specs\/([^/]+)\/FS-\d+\//);
+        const projectFolder = pathMatch ? pathMatch[1] : "default";
+        sections.push(`- **Feature Spec**: [${this.featureId}](../.specweave/docs/internal/specs/${projectFolder}/${this.featureId}/FEATURE.md)`);
+        sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${this.userStoryPath})`);
+      }
     }
     sections.push("");
     sections.push("---");

package/plugins/specweave-github/lib/user-story-issue-builder.ts

@@ -520,34 +520,52 @@ export class UserStoryIssueBuilder {
     sections.push('');
 
     // Generate proper GitHub blob URLs
-    // v5.0.0+: Features live in project folders, NOT _features
+    // v1.0.302 FIX: Use increment paths instead of living docs paths.
+    // Living docs (/.specweave/docs/internal/specs/) only exist in the umbrella repo,
+    // so links to them return 404 in the target repo. Increment spec.md is always pushed.
     if (this.repoOwner && this.repoName) {
       const baseUrl = `https://github.com/${this.repoOwner}/${this.repoName}/blob/${this.branch}`;
 
-      // Extract project from user story path: specs/{project}/FS-XXX/us-*.md
-      const pathMatch = this.userStoryPath.match(/specs\/([^/]+)\/FS-\d+\//);
-      const projectFolder = pathMatch ? pathMatch[1] : 'default';
-
-      // Feature Spec link
-      sections.push(`- **Feature Spec**: [${this.featureId}](${baseUrl}/.specweave/docs/internal/specs/${projectFolder}/${this.featureId}/FEATURE.md)`);
+      // Extract increment ID from Implementation section (if available)
+      const incrementMatch = implMatch?.[1]?.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+      const incrementId = incrementMatch ? incrementMatch[1] : null;
+
+      // Feature Spec link: point to increment spec.md (always exists in target repo)
+      if (incrementId) {
+        sections.push(`- **Feature Spec**: [${this.featureId}](${baseUrl}/.specweave/increments/${incrementId}/spec.md)`);
+      } else {
+        // Fallback to living docs path when no increment ID available
+        const pathMatch = this.userStoryPath.match(/specs\/([^/]+)\/FS-\d+\//);
+        const projectFolder = pathMatch ? pathMatch[1] : 'default';
+        sections.push(`- **Feature Spec**: [${this.featureId}](${baseUrl}/.specweave/docs/internal/specs/${projectFolder}/${this.featureId}/FEATURE.md)`);
+      }
 
-      // User Story File link (relative to project root)
-      const relativeUSPath = path.relative(this.projectRoot, this.userStoryPath);
-      sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${baseUrl}/${relativeUSPath})`);
+      // User Story File link: point to increment spec.md (always exists in target repo)
+      if (incrementId) {
+        sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${baseUrl}/.specweave/increments/${incrementId}/spec.md)`);
+      } else {
+        const relativeUSPath = path.relative(this.projectRoot, this.userStoryPath);
+        sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${baseUrl}/${relativeUSPath})`);
+      }
 
-      // Increment link (extracted from Implementation section)
-      const incrementMatch = implMatch?.[1]?.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
-      if (incrementMatch) {
-        const incrementId = incrementMatch[1];
+      // Increment link (always points to the increment folder in the target repo)
+      if (incrementId) {
         sections.push(`- **Increment**: [${incrementId}](${baseUrl}/.specweave/increments/${incrementId})`);
       }
     } else {
       // Fallback to relative links if repo info not provided
-      // v5.0.0+: Features live in project folders, NOT _features
-      const pathMatch = this.userStoryPath.match(/specs\/([^/]+)\/FS-\d+\//);
-      const projectFolder = pathMatch ? pathMatch[1] : 'default';
-      sections.push(`- **Feature Spec**: [${this.featureId}](../.specweave/docs/internal/specs/${projectFolder}/${this.featureId}/FEATURE.md)`);
-      sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${this.userStoryPath})`);
+      const incrementMatch = implMatch?.[1]?.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+      const incrementId = incrementMatch ? incrementMatch[1] : null;
+
+      if (incrementId) {
+        sections.push(`- **Feature Spec**: [${this.featureId}](.specweave/increments/${incrementId}/spec.md)`);
+        sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](.specweave/increments/${incrementId}/spec.md)`);
+      } else {
+        const pathMatch = this.userStoryPath.match(/specs\/([^/]+)\/FS-\d+\//);
+        const projectFolder = pathMatch ? pathMatch[1] : 'default';
+        sections.push(`- **Feature Spec**: [${this.featureId}](../.specweave/docs/internal/specs/${projectFolder}/${this.featureId}/FEATURE.md)`);
+        sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${this.userStoryPath})`);
+      }
     }
 
     sections.push('');