specweave 1.0.506 → 1.0.508

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

@@ -1,424 +0,0 @@
-/**
- * User Story Content Builder - GitHub issue content for individual user stories
- *
- * Architecture:
- * - Reads individual us-*.md files from living docs
- * - Extracts ACs and converts to GitHub task checkboxes
- * - Finds and links related tasks from increment tasks.md
- * - Generates rich GitHub issue body with proper formatting
- *
- * Key Features:
- * - Checkable ACs (GitHub task checkboxes)
- * - Task connections (links to increment tasks)
- * - User story description (As a... I want... So that...)
- * - Implementation details
- */
-
-import { readFile } from 'fs/promises';
-import { existsSync } from 'fs';
-import * as path from 'path';
-import * as yaml from 'yaml';
-
-interface UserStoryFrontmatter {
-  id: string;
-  epic: string;
-  title: string;
-  status: 'complete' | 'active' | 'planning' | 'not-started';
-  project: string;
-  priority: string;
-  created: string;
-  completed?: string;
-}
-
-interface AcceptanceCriterion {
-  id: string; // AC-US4-01
-  description: string;
-  completed: boolean;
-  priority: string;
-  testable: boolean;
-}
-
-interface Task {
-  id: string; // T-008
-  title: string;
-  status: boolean; // true = completed
-  link: string; // Link to tasks.md
-}
-
-export interface UserStoryContent {
-  frontmatter: UserStoryFrontmatter;
-  userStoryDescription: {
-    asA: string;
-    iWant: string;
-    soThat: string;
-  } | null;
-  acceptanceCriteria: AcceptanceCriterion[];
-  tasks: Task[];
-  incrementId: string | null;
-  featureId: string; // FS-031
-}
-
-export class UserStoryContentBuilder {
-  private userStoryPath: string;
-  private projectRoot: string;
-
-  constructor(userStoryPath: string, projectRoot: string) {
-    this.userStoryPath = userStoryPath;
-    this.projectRoot = projectRoot;
-  }
-
-  /**
-   * Parse user story file and extract all content
-   */
-  async parse(): Promise<UserStoryContent> {
-    const content = await readFile(this.userStoryPath, 'utf-8');
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-
-    if (!match) {
-      throw new Error('User story file missing YAML frontmatter');
-    }
-
-    const frontmatter = yaml.parse(match[1]) as UserStoryFrontmatter;
-    const bodyContent = content.slice(match[0].length).trim();
-
-    // Extract feature ID from epic or path
-    const featureId = this.extractFeatureId(frontmatter.epic, this.userStoryPath);
-
-    // Extract user story description
-    const userStoryDescription = this.extractUserStoryDescription(bodyContent);
-
-    // Extract acceptance criteria
-    const acceptanceCriteria = this.extractAcceptanceCriteria(bodyContent);
-
-    // Extract increment ID and tasks
-    const incrementId = this.extractIncrementId(bodyContent);
-    const tasks = incrementId
-      ? await this.extractTasks(bodyContent, incrementId, frontmatter.id)
-      : [];
-
-    return {
-      frontmatter,
-      userStoryDescription,
-      acceptanceCriteria,
-      tasks,
-      incrementId,
-      featureId,
-    };
-  }
-
-  /**
-   * 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, 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)
-    // Body should contain ONLY actual work content (ACs, tasks, user story)
-    // See: .specweave/docs/internal/troubleshooting/CRITICAL-remove-metadata-header-from-github-issues.md
-
-    // Progress section (consistency with user-story-issue-builder.ts)
-    const completedACs = content.acceptanceCriteria.filter(ac => ac.completed).length;
-    const totalACs = content.acceptanceCriteria.length;
-    const completedTasks = content.tasks.filter(t => t.status).length;
-    const totalTasks = content.tasks.length;
-    const overallPercentage = (totalACs + totalTasks) > 0
-      ? Math.round(((completedACs + completedTasks) / (totalACs + totalTasks)) * 100)
-      : 0;
-
-    body += `## Progress\n\n`;
-    body += `**Acceptance Criteria**: ${completedACs}/${totalACs} (${totalACs > 0 ? Math.round((completedACs / totalACs) * 100) : 0}%)\n`;
-    body += `**Tasks**: ${completedTasks}/${totalTasks} (${totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0}%)\n`;
-    body += `**Overall**: ${overallPercentage}%\n\n`;
-
-    // Progress bar
-    const filledBlocks = Math.floor(overallPercentage / 5);
-    const emptyBlocks = 20 - filledBlocks;
-    body += `${'█'.repeat(filledBlocks)}${'░'.repeat(emptyBlocks)} ${overallPercentage}%\n\n`;
-    body += `---\n\n`;
-
-    // User Story description
-    body += `## User Story\n\n`;
-    if (content.userStoryDescription) {
-      body += `**As a** ${content.userStoryDescription.asA}\n`;
-      body += `**I want** ${content.userStoryDescription.iWant}\n`;
-      body += `**So that** ${content.userStoryDescription.soThat}\n\n`;
-    } else {
-      body += `*User story description not found*\n\n`;
-    }
-
-    // Link to full user story file (GitHub URL)
-    const usFilename = path.basename(this.userStoryPath);
-    if (repo) {
-      const relativePath = this.userStoryPath
-        .replace(this.projectRoot, '')
-        .replace(/^\//, '');
-      body += `📄 View full story: [\`${usFilename}\`](https://github.com/${repo}/tree/${branchName}/${relativePath})\n\n`;
-    }
-
-    body += `---\n\n`;
-
-    // Acceptance Criteria (checkable!)
-    body += `## Acceptance Criteria\n\n`;
-    if (content.acceptanceCriteria.length > 0) {
-      const completed = content.acceptanceCriteria.filter((ac) => ac.completed).length;
-      const total = content.acceptanceCriteria.length;
-      const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
-      body += `Progress: ${completed}/${total} criteria met (${percentage}%)\n\n`;
-
-      for (const ac of content.acceptanceCriteria) {
-        const checkbox = ac.completed ? '[x]' : '[ ]';
-        const priority = ac.priority ? ` (${ac.priority})` : '';
-        const testable = ac.testable ? ' [testable]' : '';
-        body += `- ${checkbox} **${ac.id}**: ${ac.description}${priority}${testable}\n`;
-      }
-      body += '\n';
-    } else {
-      body += `*No acceptance criteria defined*\n\n`;
-    }
-
-    body += `---\n\n`;
-
-    // Tasks (linked to increment!)
-    body += `## Implementation Tasks\n\n`;
-    if (content.tasks.length > 0) {
-      const completed = content.tasks.filter((t) => t.status).length;
-      const total = content.tasks.length;
-      const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
-      body += `Progress: ${completed}/${total} tasks complete (${percentage}%)\n\n`;
-
-      if (content.incrementId) {
-        if (repo) {
-          body += `**Increment**: [${content.incrementId}](https://github.com/${repo}/tree/${branchName}/.specweave/increments/${content.incrementId})\n\n`;
-        } else {
-          body += `**Increment**: ${content.incrementId}\n\n`;
-        }
-      }
-
-      for (const task of content.tasks) {
-        const checkbox = task.status ? '[x]' : '[ ]';
-        // Convert relative link to GitHub URL if repo is known
-        let taskLink = task.link;
-        if (repo && taskLink.startsWith('../../')) {
-          const relativePath = taskLink.replace(/^\.\.\/\.\.\//, '.specweave/');
-          taskLink = `https://github.com/${repo}/tree/${branchName}/${relativePath}`;
-        }
-        body += `- ${checkbox} [${task.id}: ${task.title}](${taskLink})\n`;
-      }
-      body += '\n';
-    } else {
-      body += `*No tasks defined yet*\n\n`;
-    }
-
-    body += `---\n\n`;
-    body += `🤖 Auto-synced by SpecWeave User Story Sync`;
-
-    return body;
-  }
-
-  /**
-   * Extract feature ID from epic or path
-   */
-  private extractFeatureId(epic: string, filePath: string): string {
-    // Try epic first (e.g., "FS-031")
-    if (epic && epic.startsWith('FS-')) {
-      return epic;
-    }
-
-    // Extract from path: .../specs/default/FS-031/us-001-...md
-    const match = filePath.match(/FS-\d+/);
-    return match ? match[0] : 'FS-UNKNOWN';
-  }
-
-  /**
-   * Extract user story description (As a... I want... So that...)
-   */
-  private extractUserStoryDescription(content: string): {
-    asA: string;
-    iWant: string;
-    soThat: string;
-  } | null {
-    const asAMatch = content.match(/\*\*As a\*\*\s+([^\n]+)/);
-    const iWantMatch = content.match(/\*\*I want\*\*\s+([^\n]+)/);
-    const soThatMatch = content.match(/\*\*So that\*\*\s+([^\n]+)/);
-
-    if (asAMatch && iWantMatch && soThatMatch) {
-      return {
-        asA: asAMatch[1].trim(),
-        iWant: iWantMatch[1].trim(),
-        soThat: soThatMatch[1].trim(),
-      };
-    }
-
-    return null;
-  }
-
-  /**
-   * Extract acceptance criteria from content
-   */
-  private extractAcceptanceCriteria(content: string): AcceptanceCriterion[] {
-    const criteria: AcceptanceCriterion[] = [];
-
-    // Pattern: - [x] **AC-US4-01**: Description (P1, testable)
-    const acPattern =
-      /- \[([ x])\] \*\*AC-US(\d+)-(\d+)\*\*:\s*([^(]+)(?:\(([^)]+)\))?/g;
-
-    let match;
-    while ((match = acPattern.exec(content)) !== null) {
-      const completed = match[1] === 'x';
-      const usNumber = match[2];
-      const acNumber = match[3];
-      const description = match[4].trim();
-      const metadata = match[5] || '';
-
-      criteria.push({
-        id: `AC-US${usNumber}-${acNumber}`,
-        description,
-        completed,
-        priority: metadata.includes('P1') ? 'P1' : metadata.includes('P2') ? 'P2' : '',
-        testable: metadata.includes('testable'),
-      });
-    }
-
-    return criteria;
-  }
-
-  /**
-   * Extract increment ID from Implementation section
-   */
-  private extractIncrementId(content: string): string | null {
-    // Pattern: **Increment**: [0031-external-tool-status-sync](...)
-    const match = content.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
-    return match ? match[1] : null;
-  }
-
-  /**
-   * Extract tasks for this user story from increment tasks.md
-   */
-  private async extractTasks(
-    content: string,
-    incrementId: string,
-    userStoryId: string
-  ): Promise<Task[]> {
-    const tasks: Task[] = [];
-
-    // Find increment folder
-    const incrementFolder = path.join(
-      this.projectRoot,
-      '.specweave',
-      'increments',
-      incrementId
-    );
-
-    if (!existsSync(incrementFolder)) {
-      console.warn(`   ⚠️  Increment folder not found: ${incrementId}`);
-      return [];
-    }
-
-    const tasksPath = path.join(incrementFolder, 'tasks.md');
-    if (!existsSync(tasksPath)) {
-      console.warn(`   ⚠️  tasks.md not found in ${incrementId}`);
-      return [];
-    }
-
-    // Read tasks.md
-    const tasksContent = await readFile(tasksPath, 'utf-8');
-
-    // Extract task links from user story's Implementation section
-    // Format: - [T-008: Create Status Sync Engine](link#t-008-create-status-sync-engine)
-    const taskLinkPattern = /- \[([T-\d]+):\s*([^\]]+)\]/g;
-
-    let match;
-    while ((match = taskLinkPattern.exec(content)) !== null) {
-      const taskId = match[1]; // e.g., "T-008"
-      const taskTitle = match[2].trim();
-
-      // Find task in tasks.md to get completion status
-      // Pattern: ### T-008: Create Status Sync Engine ... **Status**: [x]
-      const taskPattern = new RegExp(
-        `###\\s+${taskId}:\\s*([^\\n]+)[\\s\\S]*?\\*\\*Status\\*\\*:\\s*\\[([x\\s])\\]`,
-        'i'
-      );
-      const taskMatch = tasksContent.match(taskPattern);
-
-      const isCompleted = taskMatch ? taskMatch[2] === 'x' : false;
-
-      // Build link to task in tasks.md
-      const taskAnchor = taskId.toLowerCase() + '-' + taskTitle.toLowerCase().replace(/[^\w\s-]/g, '').replace(/\s+/g, '-');
-      const link = `../../increments/${incrementId}/tasks.md#${taskAnchor}`;
-
-      tasks.push({
-        id: taskId,
-        title: taskTitle,
-        status: isCompleted,
-        link,
-      });
-    }
-
-    return tasks;
-  }
-
-  /**
-   * Extract highest priority from acceptance criteria
-   * Priority order: P1 > P2 > P3
-   */
-  private extractPriorityFromACs(acceptanceCriteria: AcceptanceCriterion[]): string | null {
-    if (acceptanceCriteria.length === 0) {
-      return null;
-    }
-
-    // Check for P1 first (highest priority)
-    if (acceptanceCriteria.some(ac => ac.priority === 'P1')) {
-      return 'P1';
-    }
-
-    // Then P2
-    if (acceptanceCriteria.some(ac => ac.priority === 'P2')) {
-      return 'P2';
-    }
-
-    // Then P3
-    if (acceptanceCriteria.some(ac => ac.priority === 'P3')) {
-      return 'P3';
-    }
-
-    return null; // No priority found
-  }
-
-  /**
-   * Detect GitHub repository from git remote
-   * Returns "owner/repo" format
-   */
-  private async detectGitHubRepo(): Promise<string | null> {
-    try {
-      const { execFileNoThrow } = await import('../../../src/utils/execFileNoThrow.js');
-      const result = await execFileNoThrow('git', ['remote', 'get-url', 'origin']);
-
-      if (result.exitCode !== 0 || !result.stdout) {
-        return null;
-      }
-
-      const remoteUrl = result.stdout.trim();
-
-      // Parse GitHub URL
-      // Formats: git@github.com:owner/repo.git or https://github.com/owner/repo.git
-      const githubMatch = remoteUrl.match(/github\.com[:/](.+\/.+?)(?:\.git)?$/);
-      if (githubMatch) {
-        return githubMatch[1]; // "owner/repo"
-      }
-
-      return null;
-    } catch {
-      return null;
-    }
-  }
-}

package/plugins/specweave-jira/.claude-plugin/plugin.json

@@ -1,20 +0,0 @@
-{
-  "name": "sw-jira",
-  "description": "JIRA integration for SpecWeave increments. Bidirectional sync between SpecWeave increments and JIRA epics/stories. Automatically creates JIRA issues from increments, tracks progress, and updates status.",
-  "version": "1.0.0",
-  "author": {
-    "name": "SpecWeave Team",
-    "url": "https://verified-skill.com"
-  },
-  "homepage": "https://verified-skill.com",
-  "repository": "https://github.com/anton-abyzov/specweave",
-  "license": "MIT",
-  "keywords": [
-    "jira",
-    "atlassian",
-    "integration",
-    "sync",
-    "specweave",
-    "project-management"
-  ]
-}

package/plugins/specweave-jira/PLUGIN.md

@@ -1,28 +0,0 @@
-# JIRA Plugin
-
-**Version**: 1.0.0
-**Author**: SpecWeave Contributors
-**License**: MIT
-
-## Description
-
-JIRA integration plugin for bidirectional synchronization between SpecWeave increments and JIRA epics, stories, and subtasks. Provides expert mapping, resource validation, and sync guidance for teams using JIRA for project management.
-
-## Skills
-
-| Skill | Description |
-|-------|-------------|
-| jira-mapper | Expert mapping of SpecWeave increments to JIRA structure with bidirectional sync and traceability |
-| jira-resource-validator | Validates JIRA projects and boards, auto-creates missing resources with per-project configuration |
-| jira-sync | Sync guidance for SpecWeave increments with JIRA epics and stories |
-
-## Installation
-
-```bash
-vskill add specweave --plugin sw-jira
-```
-
-## Requirements
-
-- SpecWeave core plugin (sw@specweave)
-- JIRA authentication configured

package/plugins/specweave-jira/hooks/README.md

@@ -1,201 +0,0 @@
-# SpecWeave JIRA Plugin Hooks
-
-**Plugin**: `specweave-jira`
-**Location**: `plugins/specweave-jira/hooks/`
-
----
-
-## Purpose
-
-This hook automatically syncs SpecWeave increment progress to JIRA Issues after each task completion.
-
-**Key Features**:
-- ✅ Updates JIRA issue status based on increment progress
-- ✅ Syncs task completion state to JIRA
-- ✅ Bidirectional sync (local → JIRA)
-- ✅ Non-blocking (failures don't stop core workflow)
-- ✅ Self-contained (no dependencies on core plugin)
-
----
-
-## Available Hooks
-
-### 1. `post-task-completion.sh`
-
-**Triggers**: After ANY task is marked complete (via TodoWrite tool)
-
-**Preconditions**:
-- ✅ Active increment exists (`.specweave/increments/####/`)
-- ✅ `metadata.json` has `.jira.issue` field
-- ✅ Node.js installed
-- ✅ JIRA sync script exists (`dist/commands/jira-sync.js`)
-- ✅ JIRA API credentials in `.env`
-
-**Actions**:
-1. Reads increment metadata
-2. Calls JIRA sync script (Node.js)
-3. Updates JIRA issue status
-4. Logs all actions to `.specweave/logs/hooks-debug.log`
-
-**Example Flow**:
-```
-Task T-003 completed in tasks.md
-↓
-Hook fires (PostToolUse + TodoWrite matcher)
-↓
-JIRA sync script updates issue PROJ-123
-↓
-Log: "[JIRA] ✅ JIRA sync complete"
-```
-
-**Dependencies**:
-- Node.js 18+
-- JIRA API credentials (`.env`)
-- `jq` for JSON parsing
-
----
-
-## Configuration
-
-### Hook Registration (`hooks.json`)
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "TodoWrite",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-completion.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Metadata Format
-
-Increments must have `metadata.json` with JIRA issue link:
-
-```json
-{
-  "jira": {
-    "issue": "PROJ-123",
-    "url": "https://company.atlassian.net/browse/PROJ-123",
-    "project": "PROJ"
-  }
-}
-```
-
-### Environment Variables
-
-Required in `.env`:
-
-```bash
-JIRA_HOST=https://company.atlassian.net
-JIRA_EMAIL=user@company.com
-JIRA_API_TOKEN=your_api_token_here
-```
-
----
-
-## Installation
-
-### Automatic (Recommended)
-
-```bash
-npx specweave init my-project
-# Installs all plugins including specweave-jira
-# Hooks auto-register via hooks.json
-```
-
-### Manual (Development)
-
-```bash
-# Install plugin
-/plugin install sw-jira@specweave
-
-# Verify hook registration
-cat ~/.claude/settings.json | grep sw-jira
-```
-
----
-
-## Testing
-
-### Test Hook Independently
-
-```bash
-# Test syntax
-bash -n plugins/specweave-jira/hooks/post-task-completion.sh
-
-# Test execution (requires active increment + JIRA issue)
-./plugins/specweave-jira/hooks/post-task-completion.sh
-```
-
----
-
-## Logging
-
-All JIRA sync actions are logged to:
-
-```
-.specweave/logs/hooks-debug.log
-```
-
-**Example Log Output**:
-```
-[2025-11-10] [JIRA] 🔗 JIRA sync hook fired
-[2025-11-10] [JIRA] 🔄 Syncing to JIRA issue PROJ-123
-[2025-11-10] [JIRA] ✅ JIRA sync complete
-```
-
-**Log Prefixes**:
-- `[JIRA]` - All messages from this hook
-- `🔗` - Hook fired
-- `🔄` - Syncing started
-- `✅` - Success
-- `⚠️` - Warning (non-blocking failure)
-- `ℹ️` - Info (skipped due to precondition)
-
----
-
-## Architecture
-
-### Separation from Core Plugin
-
-**Before (v0.12.x)**:
-```
-Core hook (500+ lines)
-├── JIRA sync  ← Embedded in core!
-```
-
-**After (v0.13.0+)**:
-```
-Core hook (330 lines)      JIRA plugin hook (150 lines)
-├── Core concerns          ├── Check for JIRA issue
-                           ├── Call Node.js sync script
-                           └── Log actions
-```
-
-**Key Benefits**:
-- ✅ **Optional plugin**: JIRA sync only runs if `specweave-jira` installed
-- ✅ **Independent testing**: Test JIRA sync in isolation
-- ✅ **No core dependencies**: Core plugin doesn't depend on JIRA API
-
----
-
-## Related Documentation
-
-- **Core Plugin Hooks**: `plugins/specweave/hooks/README.md`
-- **Architecture Analysis**: `.specweave/increments/0018-strict-increment-discipline-enforcement/reports/HOOKS-ARCHITECTURE-ANALYSIS.md`
-- **JIRA Sync Command**: `plugins/specweave-jira/commands/sync.md`
-
----
-
-**Version**: v0.13.0+
-**Last Updated**: 2025-11-10