specweave 0.32.0 → 0.32.3

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

@@ -0,0 +1,297 @@
+---
+name: specweave-jira:close
+description: Close JIRA issue when increment complete
+---
+
+# Close JIRA Issue Command
+
+**Usage**: `/specweave-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: /specweave-jira:create ${incrementId}
+`);
+  return;
+}
+```
+
+### 5. Invoke JIRA Manager Agent
+
+```
+Use Task tool with subagent_type: "specweave-jira:jira-manager:jira-manager"
+
+Prompt: "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: /specweave-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: /specweave-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: /specweave-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: /specweave-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: /specweave-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 |
+|---------|---------|
+| `/specweave-jira:pull` | Pull changes from JIRA |
+| `/specweave-jira:push` | Push progress to JIRA |
+| `/specweave-jira:sync` | Two-way sync |
+| `/specweave-jira:create` | Create JIRA issue |
+| `/specweave-jira:status` | Check sync status |

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

@@ -0,0 +1,198 @@
+---
+name: specweave-jira:create
+description: Create JIRA issue from SpecWeave increment
+---
+
+# Create JIRA Issue Command
+
+**Usage**: `/specweave-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 Agent
+
+```
+Use Task tool with subagent_type: "specweave-jira:jira-manager:jira-manager"
+
+Prompt: "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: /specweave-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 |
+|---------|---------|
+| `/specweave-jira:pull` | Pull changes from JIRA |
+| `/specweave-jira:push` | Push progress to JIRA |
+| `/specweave-jira:sync` | Two-way sync |
+| `/specweave-jira:status` | Check sync status |
+| `/specweave-jira:close` | Close issue when complete |

package/plugins/specweave-jira/commands/reconcile.md

@@ -0,0 +1,123 @@
+---
+name: specweave-jira:reconcile
+description: Reconcile JIRA issue states with increment statuses. Fixes drift by closing issues for completed increments and reopening issues for resumed increments.
+---
+
+# JIRA Status Reconciliation
+
+Scan all increments and fix any drift between local metadata.json status and JIRA issue states.
+
+## Usage
+
+```bash
+/specweave-jira:reconcile [options]
+```
+
+## Options
+
+- `--dry-run`: Preview changes without making them
+- `--verbose`: Show detailed output for each issue checked
+
+## What It Does
+
+1. **Scans** all non-archived increments
+2. **Compares** metadata.json status with JIRA issue state
+3. **Fixes** mismatches:
+   - `metadata=completed` + `JIRA=In Progress` → **Close** the issue (transition to Done)
+   - `metadata=in-progress` + `JIRA=Done` → **Reopen** the issue (transition to To Do)
+
+## When to Use
+
+- After manual metadata.json edits
+- After git pulls that changed increment statuses
+- When you notice open issues for completed work
+- As a periodic health check
+
+## Implementation
+
+Run the reconciliation using the JiraReconciler:
+
+```typescript
+import { JiraReconciler } from '../../../src/sync/jira-reconciler.js';
+
+const reconciler = new JiraReconciler({
+  projectRoot: process.cwd(),
+  dryRun: args.includes('--dry-run'),
+});
+
+const result = await reconciler.reconcile();
+
+// Report results
+console.log(`\nReconciliation complete:`);
+console.log(`  Scanned: ${result.scanned} increments`);
+console.log(`  Fixed: ${result.closed} closed, ${result.reopened} reopened`);
+if (result.errors.length > 0) {
+  console.log(`  Errors: ${result.errors.length}`);
+}
+```
+
+## Example Output
+
+```
+📊 Scanning 5 increment(s) for JIRA state drift...
+
+  ✅ Issue PROJ-123 (0056-plugin-fix/US-001): State matches (In Progress)
+  ❌ Issue PROJ-130 (0066-import-wizard/US-003): In Progress but should be CLOSED (status=completed)
+     ✅ Closed issue PROJ-130
+  ❌ Issue PROJ-128 (0063-multi-repo/US-001): CLOSED but should be OPEN (status=in-progress)
+     ✅ Reopened issue PROJ-128
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 JIRA RECONCILIATION SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Increments scanned:  5
+   Mismatches found:    2
+   Issues closed:       1
+   Issues reopened:     1
+   Errors:              0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Dry Run Mode
+
+```bash
+/specweave-jira:reconcile --dry-run
+```
+
+Shows what would be changed without making any modifications:
+
+```
+  ❌ Issue PROJ-130 (0066-import-wizard/US-003): In Progress but should be CLOSED
+     [DRY RUN] Would close issue PROJ-130
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 JIRA RECONCILIATION SUMMARY
+   ⚠️  DRY RUN - No changes were made
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Requirements
+
+- JIRA API token configured (`JIRA_API_TOKEN`)
+- JIRA email configured (`JIRA_EMAIL`)
+- JIRA domain configured (`JIRA_DOMAIN`)
+- `sync.jira.enabled = true` in config.json
+- `sync.settings.canUpdateExternalItems = true` in config.json
+- `sync.settings.canUpdateStatus = true` in config.json
+
+## JIRA Status Mapping
+
+| SpecWeave Status | Expected JIRA Status |
+|-----------------|---------------------|
+| `completed` | Done, Closed, Resolved |
+| `abandoned` | Won't Do, Closed |
+| `in-progress` | In Progress, In Review |
+| `active` | To Do, Open |
+| `planning` | To Do |
+
+## Related Commands
+
+- `/specweave-jira:status`: View sync status for increments
+- `/specweave-jira:sync`: Manual sync to JIRA
+- `/specweave:done`: Close increment (triggers auto-close)
+- `/specweave:resume`: Resume increment (now triggers auto-reopen)