npm - specweave - Versions diffs - 1.0.593 → 2.0.3 - Mend

specweave 1.0.593 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1420) hide show

package/plugins/specweave/commands/jira-cleanup-duplicates.md DELETED Viewed

@@ -1,218 +0,0 @@
----
-description: Clean up duplicate JIRA issues for a Feature. Finds issues with duplicate titles and closes all except the first created issue.
-justification: |
-  CRITICAL INCIDENT RESPONSE TOOL - DO NOT DELETE!
-  Why This Command Exists:
-  - Prevention systems work for single-process execution
-  - Multiple parallel Claude Code instances bypass all prevention (file-based cache, no distributed locking)
-  - JIRA API race conditions: Time gap between "check exists" and "create issue" allows duplicates
-  - Historical duplicates from pre-v0.33.0 users (before prevention was added)
-  Evidence of Need:
-  - GitHub had 123 duplicate issues incident (cleaned to 29 unique) - same risk exists for JIRA
-  - Parallel execution creates race conditions that prevention CANNOT solve
-  - Industry standard: Prevention + Detection + Cleanup (defense in depth)
-  When to Delete:
-  - ONLY if distributed locking implemented
-  - AND parallel execution tested (100+ concurrent syncs with zero duplicates)
-  - AND zero duplicates for 6+ months in production
----
-# Clean Up Duplicate JIRA Issues
-**CRITICAL**: This command detects and closes duplicate JIRA issues created by multiple syncs.
-## Usage
-```bash
-sw-jira:cleanup-duplicates <feature-id> [--dry-run]
-```
-## What It Does
-**Duplicate Detection & Cleanup**:
-1. **Find all issues** for the Feature (JQL search by Feature ID in summary)
-2. **Group by summary** (detect duplicates)
-3. **For each duplicate group**:
-   - Keep the **FIRST created** issue (oldest created date)
-   - Close all **LATER** issues with comment: "Duplicate of PROJ-XXX"
-4. **Update Feature README** with correct issue keys
-## Examples
-### Dry Run (No Changes)
-```bash
-sw-jira:cleanup-duplicates FS-031 --dry-run
-```
-**Output**:
-```
-Scanning for duplicates in Feature FS-031...
-   Found 25 total issues
-   Detected 10 duplicate groups:
-   Group 1: "[FS-031] External Tool Status Synchronization"
-      - PROJ-250 (KEEP) - Created 2025-11-10
-      - PROJ-255 (CLOSE) - Created 2025-11-11 - DUPLICATE
-      - PROJ-260 (CLOSE) - Created 2025-11-12 - DUPLICATE
-   Group 2: "[FS-031] Multi-Project JIRA Sync"
-      - PROJ-251 (KEEP) - Created 2025-11-10
-      - PROJ-256 (CLOSE) - Created 2025-11-11 - DUPLICATE
-   ...
-Dry run complete!
-   Total issues: 25
-   Duplicate groups: 10
-   Issues to close: 15
-This was a DRY RUN - no changes made.
-   Run without --dry-run to actually close duplicates.
-```
-### Actual Cleanup
-```bash
-sw-jira:cleanup-duplicates FS-031
-```
-**Output**:
-```
-Scanning for duplicates in Feature FS-031...
-   Found 25 total issues
-   Detected 10 duplicate groups
-CONFIRM: Close 15 duplicate issues? [y/N]
-> y
-Closing duplicates...
-   Closed PROJ-255 (duplicate of PROJ-250)
-   Closed PROJ-256 (duplicate of PROJ-251)
-   Closed PROJ-260 (duplicate of PROJ-250)
-   ...
-Updating Feature README frontmatter...
-   Updated frontmatter with correct issue keys
-Cleanup complete!
-   Closed: 15 duplicates
-   Kept: 10 original issues
-```
-## Arguments
-- `<feature-id>` - Feature ID (e.g., `FS-031` or just `031`)
-- `--dry-run` - Preview changes without actually closing issues (optional)
-## Safety Features
-- **Confirmation prompt**: Asks before closing issues (unless --dry-run)
-- **Dry run mode**: Preview changes safely
-- **Keeps oldest issue**: Preserves the first created issue
-- **Adds closure comment**: Links to the original issue
-- **Updates metadata**: Fixes Feature README frontmatter
-## What Gets Closed
-**Closed issues**:
-- Duplicate summaries (second, third, etc. occurrences)
-- Transitioned to "Won't Do" or "Closed" with comment: "Duplicate of PROJ-XXX"
-- Original issue kept open (or maintains its status)
-**Example comment on closed duplicate**:
-```markdown
-h2. Duplicate of PROJ-250
-This issue was automatically closed by SpecWeave cleanup because it is a duplicate.
-The original issue (PROJ-250) contains the same content and should be used for tracking instead.
-Auto-closed by SpecWeave Duplicate Cleanup
-```
-## Requirements
-1. **JIRA API token** configured (`JIRA_API_TOKEN`)
-2. **JIRA email** configured (`JIRA_EMAIL`)
-3. **JIRA domain** configured (`JIRA_DOMAIN`)
-4. **Write access** to project (for closing issues)
-5. **Feature folder exists** at `.specweave/docs/internal/specs/FS-XXX-name/`
-## When to Use
-**Use this command when**:
-- You see multiple issues with the same summary in JIRA
-- Feature sync ran multiple times and created duplicates
-- Feature README frontmatter got corrupted and reset
-- Post-sync validation warns about duplicates
-**Example warning that triggers this**:
-```
-WARNING: 10 duplicate(s) detected!
-   Run cleanup command to resolve:
-   sw-jira:cleanup-duplicates FS-031
-```
-## Architecture
-**Duplicate Detection Logic**:
-1. JQL query for issues with Feature ID in summary
-2. Group issues by **exact summary match**
-3. Within each group, sort by **created date** (ascending)
-4. Keep **first issue** (oldest = first created)
-5. Transition **all others** to closed status
-**Why oldest created?**:
-- Older issues were created first
-- Preserves chronological order
-- Maintains links from old documentation
-- JIRA keys can be reordered, created date is immutable
-## JQL Query Pattern
-```jql
-summary ~ "[FS-031]" ORDER BY created ASC
-```
-## Related Commands
-- `sw-jira:sync` - Sync Feature to JIRA (with duplicate detection)
-- `sw-jira:reconcile` - Reconcile issue states
-- `sw:validate` - Validate increment completeness
-## Implementation
-**File**: `plugins/specweave-jira/lib/jira-duplicate-detector.ts`
-**Class**: `JiraDuplicateDetector`
-**Algorithm** (3-phase protection):
-1. **Detection**: JQL query for existing issues matching pattern
-2. **Verification**: Count check to detect duplicates after creation
-3. **Reflection**: Auto-close duplicates automatically
-For manual cleanup:
-1. JQL query for all issues with Feature ID
-2. Group by summary (Map<string, JiraIssue[]>)
-3. Filter groups with >1 issue (duplicates)
-4. For each duplicate group:
-   - Keep first issue (oldest created)
-   - Transition others to "Won't Do" via JIRA REST API
-## Next Steps
-After cleanup:
-1. **Verify cleanup**: JQL query `summary ~ "[FS-031]"`
-2. **Check Feature FEATURE.md**: Verify frontmatter has correct issue keys
-3. **Re-run sync**: `sw-jira:sync` (should show no duplicates)
-4. **Duplicate detection**: Automatically enabled via JiraDuplicateDetector
----
-**SAFE TO USE**: This command is idempotent and safe to run multiple times.

package/plugins/specweave/commands/jira-close.md DELETED Viewed

@@ -1,294 +0,0 @@
----
-description: Close JIRA issue when increment complete
----
-# Close JIRA Issue Command
-**Usage**: `sw-jira:close <increment-id>`
-**Purpose**: Close JIRA issue and add completion summary
----
-## Command Behavior
-When user runs this command, Claude should:
-### 1. Check Permission Gate (MANDATORY FIRST STEP)
-**Before ANY JIRA API calls**, check if status updates are allowed:
-```typescript
-// Read .specweave/config.json
-const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
-const canUpdateExternal = config?.sync?.settings?.canUpdateExternalItems ?? false;
-const canUpdateStatus = config?.sync?.settings?.canUpdateStatus ?? false;
-// Close requires both permissions (write to close, status to change state)
-if (!canUpdateExternal || !canUpdateStatus) {
-  const missing = [];
-  if (!canUpdateExternal) missing.push('canUpdateExternalItems');
-  if (!canUpdateStatus) missing.push('canUpdateStatus');
-  console.log(`
-❌ Permission Denied
-Closing JIRA issues requires these permissions:
-${missing.map(p => `  - sync.settings.${p} = false (required: true)`).join('\n')}
-To enable, update .specweave/config.json:
-{
-  "sync": {
-    "settings": {
-      "canUpdateExternalItems": true,
-      "canUpdateStatus": true
-    }
-  }
-}
-`);
-  return;
-}
-```
-### 2. Resolve JIRA Profile
-Use the increment's stored profile or fall back to global defaultProfile/activeProfile:
-```typescript
-// Load increment metadata
-const metadataPath = `.specweave/increments/${incrementId}/metadata.json`;
-const metadata = JSON.parse(await fs.readFile(metadataPath, 'utf-8'));
-// Priority: increment profile > global defaultProfile > activeProfile
-let profileName = metadata?.external_sync?.jira?.profile;
-if (!profileName) {
-  profileName = config?.sync?.defaultProfile ?? config?.sync?.activeProfile;
-}
-// Validate profile exists
-const profileConfig = config?.sync?.profiles?.[profileName];
-if (!profileConfig || profileConfig.provider !== 'jira') {
-  console.log(`❌ JIRA profile "${profileName}" not found`);
-  return;
-}
-const { domain, projectKey } = profileConfig.config;
-```
-### 3. Validate Increment Completion
-Before closing, verify the increment is actually complete:
-```typescript
-// Check tasks.md for completion
-const tasksPath = `.specweave/increments/${incrementId}/tasks.md`;
-const tasksContent = await fs.readFile(tasksPath, 'utf-8');
-const totalTasks = (tasksContent.match(/### T-\d+/g) || []).length;
-const completedTasks = (tasksContent.match(/\[x\] completed/gi) || []).length;
-if (completedTasks < totalTasks) {
-  console.log(`
-⚠️ Increment not complete
-Tasks: ${completedTasks}/${totalTasks} completed
-Cannot close JIRA issue until all tasks are done.
-Complete remaining tasks first, then re-run this command.
-`);
-  return;
-}
-```
-### 4. Validate Issue Is Linked
-```typescript
-// Check for linked issue
-const issueKey = metadata?.external_sync?.jira?.issueKey
-  || metadata?.external_ids?.jira?.epic;
-if (!issueKey) {
-  console.log(`
-⚠️ No JIRA issue linked
-This increment is not linked to a JIRA issue.
-First create an issue with: sw-jira:create ${incrementId}
-`);
-  return;
-}
-```
-### 5. Invoke JIRA Manager Skill
-```
-Use Skill tool: Skill({ skill: "sw-jira:jira-sync", args: "Close JIRA issue for completed increment {increment-id}.
-IMPORTANT:
-- Permission verified: canUpdateExternalItems=true, canUpdateStatus=true
-- Using profile: {profileName} (domain: {domain}, project: {projectKey})
-- Issue key: {issueKey}
-Steps:
-1. Validate: All tasks in tasks.md complete
-2. Generate: Completion summary (duration, deliverables)
-3. Load issue key from metadata.json
-4. GET available transitions from /rest/api/3/issue/{issueKey}/transitions
-5. Find transition to 'Done' or 'Closed' status
-6. POST transition: /rest/api/3/issue/{issueKey}/transitions
-7. POST final comment with summary
-8. Display: Closure confirmation with profile used"
-```
-### 6. Display Result
-```
-✅ Closed JIRA Issue
-Issue: {issueKey}
-Profile: {profileName}
-  Domain: {domain}
-  Project: {projectKey}
-Increment: {increment-id}
-Status: 100% complete ({total}/{total} tasks)
-Duration: {days} days
-Summary posted to JIRA issue
-URL: https://{domain}/browse/{issueKey}
-```
----
-## Permission Requirements
-This command requires **both** permissions:
-| Permission | Required | Purpose |
-|------------|----------|---------|
-| canUpdateExternalItems | true | Write to JIRA issue |
-| canUpdateStatus | true | Transition issue state to Done/Closed |
----
-## Example Output
-### Success
-```
-User: sw-jira:close 0005-payment-integration
-Claude:
-Checking permissions...
-  canUpdateExternalItems: true
-  canUpdateStatus: true
-Resolving JIRA profile...
-  Using: jira-my-project (from increment)
-  Domain: company.atlassian.net
-  Project: MYPROJ
-Validating completion...
-  Tasks: 10/10 complete
-Closing issue...
-✅ Closed JIRA Issue MYPROJ-123
-Profile: jira-my-project
-Increment: 0005-payment-integration
-Status: 100% complete (10/10 tasks)
-Duration: 3 days
-Summary posted to JIRA issue
-URL: https://company.atlassian.net/browse/MYPROJ-123
-```
-### Permission Denied
-```
-User: sw-jira:close 0005
-Claude:
-Checking permissions...
-  canUpdateExternalItems: false
-  canUpdateStatus: false
-❌ Permission Denied
-Closing JIRA issues requires:
-  - sync.settings.canUpdateExternalItems = true
-  - sync.settings.canUpdateStatus = true
-Update .specweave/config.json to enable these permissions.
-```
-### Incomplete Increment
-```
-User: sw-jira:close 0005
-Claude:
-Checking permissions...
-  canUpdateExternalItems: true
-  canUpdateStatus: true
-Validating completion...
-⚠️ Increment not complete
-Tasks: 6/10 completed
-Cannot close JIRA issue until all tasks are done.
-Complete remaining tasks:
-  - T-007: Add refund functionality
-  - T-008: Implement subscriptions
-  - T-009: Add analytics
-  - T-010: Security audit
-```
-### No Issue Linked
-```
-User: sw-jira:close 0005
-Claude:
-Checking linked issue...
-⚠️ No JIRA issue linked
-This increment is not linked to a JIRA issue.
-First create an issue with: sw-jira:create 0005
-```
----
-## Metadata Updates
-After successful closure, the increment's `metadata.json` will be updated:
-```json
-{
-  "external_sync": {
-    "jira": {
-      "profile": "jira-my-project",
-      "issueKey": "MYPROJ-123",
-      "issueUrl": "https://company.atlassian.net/browse/MYPROJ-123",
-      "status": "Done",
-      "closedAt": "2025-12-07T04:30:00Z",
-      "lastSyncedAt": "2025-12-07T04:30:00Z"
-    }
-  }
-}
-```
----
-## Related
-| Command | Purpose |
-|---------|---------|
-| `sw-jira:pull` | Pull changes from JIRA |
-| `sw-jira:push` | Push progress to JIRA |
-| `sw-jira:sync` | Two-way sync |
-| `sw-jira:create` | Create JIRA issue |
-| `sw-jira:status` | Check sync status |

package/plugins/specweave/commands/jira-create.md DELETED Viewed

@@ -1,195 +0,0 @@
----
-description: Create JIRA issue from SpecWeave increment
----
-# Create JIRA Issue Command
-**Usage**: `sw-jira:create <increment-id>`
-**Purpose**: Create an Epic or Story in JIRA from a SpecWeave increment
----
-## Command Behavior
-When user runs this command, Claude should:
-### 1. Check Permission Gate (MANDATORY FIRST STEP)
-**Before ANY JIRA API calls**, check if write operations are allowed:
-```typescript
-// Read .specweave/config.json
-const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
-const canUpdateExternal = config?.sync?.settings?.canUpdateExternalItems ?? false;
-if (!canUpdateExternal) {
-  // STOP HERE - Permission denied
-  console.log(`
-❌ Permission Denied
-JIRA write operations are disabled.
-Setting: sync.settings.canUpdateExternalItems = false
-To enable, update .specweave/config.json:
-{
-  "sync": {
-    "settings": {
-      "canUpdateExternalItems": true
-    }
-  }
-}
-`);
-  return; // DO NOT proceed to create issue
-}
-```
-If `canUpdateExternalItems` is `false`, display the error and **STOP**. Do not invoke the JIRA Manager agent.
-### 2. Resolve JIRA Profile
-Use the increment's stored profile or fall back to global defaultProfile/activeProfile:
-```typescript
-// Load increment metadata
-const metadata = JSON.parse(await fs.readFile(
-  `.specweave/increments/${incrementId}/metadata.json`, 'utf-8'
-));
-// Check for increment-specific profile
-let profileName = metadata?.external_sync?.jira?.profile;
-// Fall back to global defaultProfile (v0.31.0+) or activeProfile (legacy)
-if (!profileName) {
-  profileName = config?.sync?.defaultProfile ?? config?.sync?.activeProfile;
-}
-// Get profile config
-const profileConfig = config?.sync?.profiles?.[profileName];
-if (!profileConfig || profileConfig.provider !== 'jira') {
-  console.log(`❌ Profile "${profileName}" not found or not a JIRA profile`);
-  return;
-}
-const { domain, projectKey } = profileConfig.config;
-```
-### 3. Validate Prerequisites
-- Check JIRA plugin installed
-- Check JIRA_API_TOKEN and JIRA_EMAIL environment variables set
-- Check JIRA profile has domain and projectKey
-### 4. Invoke JIRA Manager Skill
-```
-Use Skill tool: Skill({ skill: "sw-jira:jira-sync", args: "Create JIRA issue for increment {increment-id}.
-IMPORTANT: Permission already verified (canUpdateExternalItems=true).
-Use profile: {profileName} (domain: {domain}, project: {projectKey})
-Steps:
-1. Read .specweave/increments/{increment-id}/spec.md
-2. Extract title and description
-3. Use JIRA domain: {domain}, project key: {projectKey}
-4. Create Epic via JIRA REST API (POST /rest/api/3/issue)
-5. Store issue key in increment metadata.json external_sync.jira.issueKey
-6. Store profile name in metadata.json external_sync.jira.profile
-7. Display: Issue Key, URL, and confirmation"
-```
-### 5. Display Result
-```
-✅ Created JIRA Epic
-Issue: PROJ-123
-URL: https://{domain}/browse/PROJ-123
-Profile: {profileName}
-Linked to increment: {increment-id}
-```
----
-## Permission Denied Output
-If `canUpdateExternalItems` is false:
-```
-❌ Permission Denied: JIRA Write Operations Disabled
-Your configuration prevents creating/updating JIRA issues.
-Current setting:
-  sync.settings.canUpdateExternalItems = false
-To enable JIRA writes:
-1. Edit .specweave/config.json
-2. Set sync.settings.canUpdateExternalItems to true
-3. Re-run this command
-This setting was configured during 'specweave init'.
-```
----
-## Example Usage
-```
-User: sw-jira:create 0005-payment-integration
-# If permission granted:
-Claude: Checking JIRA permissions...
-        ✓ canUpdateExternalItems: true
-        Resolving JIRA profile...
-        ✓ Using profile: jira-my-project (from increment)
-        ✓ Domain: company.atlassian.net
-        ✓ Project: MYPROJ
-        Creating issue...
-        [Invokes JIRA Manager Agent]
-        ✅ Created JIRA Epic MYPROJ-123
-        URL: https://company.atlassian.net/browse/MYPROJ-123
-# If permission denied:
-Claude: Checking JIRA permissions...
-        ❌ Permission Denied
-        sync.settings.canUpdateExternalItems = false
-        To enable: Edit .specweave/config.json and set canUpdateExternalItems to true
-```
----
-## Metadata Updates
-After successful creation, the increment's `metadata.json` will be updated:
-```json
-{
-  "external_sync": {
-    "jira": {
-      "profile": "jira-my-project",
-      "issueKey": "MYPROJ-123",
-      "issueUrl": "https://company.atlassian.net/browse/MYPROJ-123",
-      "lastSyncedAt": "2025-12-07T04:30:00Z"
-    }
-  }
-}
-```
----
-## Related
-| Command | Purpose |
-|---------|---------|
-| `sw-jira:pull` | Pull changes from JIRA |
-| `sw-jira:push` | Push progress to JIRA |
-| `sw-jira:sync` | Two-way sync |
-| `sw-jira:status` | Check sync status |
-| `sw-jira:close` | Close issue when complete |