specweave 1.0.593 → 2.0.3

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

@@ -1,161 +0,0 @@
----
-description: Pull latest changes from Jira (like git pull). Imports status, priority, sprint, and comments.
----
-
-# Jira Pull Command
-
-**Usage**: `sw-jira:pull [increment-id]`
-
-**Purpose**: Pull latest changes from Jira to your local increment (like `git pull`)
-
----
-
-## Quick Start
-
-```bash
-# Pull for current/active increment
-sw-jira:pull
-
-# Pull for specific increment
-sw-jira:pull 0005
-```
-
----
-
-## What Gets Pulled
-
-| Field | Behavior |
-|-------|----------|
-| **Status** | External ALWAYS wins (QA/stakeholder decisions) |
-| **Priority** | External wins (stakeholder prioritization) |
-| **Sprint** | Updated if changed in Jira |
-| **Comments** | New team comments imported to notes |
-| **Assignee** | Updated if changed |
-| **Story Points** | Imported if set |
-
----
-
-## Status Mapping
-
-| Jira Status | SpecWeave Status |
-|-------------|------------------|
-| To Do | draft |
-| In Progress | in-progress |
-| Code Review | implemented |
-| In Review | implemented |
-| QA / Testing | in-qa |
-| Done / Closed | completed |
-| Blocked | blocked |
-| Cancelled | cancelled |
-
----
-
-## Command Behavior
-
-When user runs this command:
-
-### 1. Resolve Increment
-
-```typescript
-const incrementId = args.incrementId || await findActiveIncrement();
-
-const metadata = JSON.parse(await fs.readFile(
-  `.specweave/increments/${incrementId}/metadata.json`, 'utf-8'
-));
-
-const jiraIssueKey = metadata?.external_sync?.jira?.issueKey;
-if (!jiraIssueKey) {
-  console.log(`Not linked to Jira. Link manually or use: sw-jira:sync ${incrementId}`);
-  return;
-}
-```
-
-### 2. Fetch and Apply
-
-```
-Use Skill tool: Skill({ skill: "sw-jira:jira-sync", args: "Pull changes from Jira for increment {increment-id}.
-
-Issue: {jiraIssueKey}
-
-Steps:
-1. Fetch issue {jiraIssueKey} via Jira REST API
-2. Compare Jira status vs local status
-3. Apply conflict resolution (EXTERNAL WINS for status/priority)
-4. Import new comments to increment notes
-5. Update sprint/assignee in metadata
-6. Display what changed"
-```
-
-### 3. Display Changes
-
-```
-Pulled from Jira
-
-Issue: PROJ-123
-Project: My Project
-
-Changes Applied:
-  Status: In Progress -> Done (mapped to: completed)
-  Priority: Medium -> High
-  Sprint: Sprint 23 -> Sprint 24
-  Comments: 3 new imported
-
-Last synced: 2025-12-04 10:30:00
-URL: https://mycompany.atlassian.net/browse/PROJ-123
-```
-
----
-
-## Conflict Resolution
-
-**CRITICAL**: External tool status ALWAYS wins.
-
-| Scenario | Winner | Reason |
-|----------|--------|--------|
-| Status differs | **External** | QA/stakeholder decisions |
-| Priority differs | **External** | Stakeholder prioritization |
-| Sprint differs | **External** | Sprint planning decisions |
-
----
-
-## Examples
-
-### Example 1: Simple Pull
-
-```
-User: sw-jira:pull
-
-Claude:
-Pulling from Jira...
-  Increment: 0005-payment-integration
-  Issue: PROJ-123
-
-Changes Applied:
-  Status: In Progress -> Done (completed)
-
-Pull complete!
-```
-
-### Example 2: Already Up to Date
-
-```
-User: sw-jira:pull 0005
-
-Claude:
-Pulling from Jira...
-  Increment: 0005-payment-integration
-  Issue: PROJ-123
-
-Already up to date!
-Last synced: 5 minutes ago
-```
-
----
-
-## Related Commands
-
-| Command | Purpose |
-|---------|---------|
-| `sw-jira:push` | Push local changes to Jira |
-| `sw-jira:sync` | Two-way sync (pull + push) |
-| `sw-jira:import-boards` | Import Jira boards |

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

@@ -1,167 +0,0 @@
----
-description: Push local progress to Jira (like git push). Updates epic/story with task completion and comments.
----
-
-# Jira Push Command
-
-**Usage**: `sw-jira:push [increment-id]`
-
-**Purpose**: Push local progress to Jira (like `git push`)
-
----
-
-## Quick Start
-
-```bash
-# Push current/active increment
-sw-jira:push
-
-# Push specific increment
-sw-jira:push 0005
-```
-
----
-
-## What Gets Pushed
-
-| Field | Source |
-|-------|--------|
-| **Progress** | Calculated from tasks.md (X/Y tasks, Z%) |
-| **Comment** | Auto-generated with completed tasks list |
-| **Status** | Transition if threshold crossed |
-| **Custom Fields** | Completion % if field exists |
-
----
-
-## Command Behavior
-
-When user runs this command:
-
-### 1. Check Permission Gate
-
-```typescript
-const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
-const canUpdateExternal = config?.sync?.settings?.canUpdateExternalItems ?? false;
-
-if (!canUpdateExternal) {
-  console.log(`
-Permission Denied: Jira writes disabled
-
-To enable: Set sync.settings.canUpdateExternalItems = true
-
-Or use read-only: sw-jira:pull ${incrementId}
-`);
-  return;
-}
-```
-
-### 2. Calculate Progress
-
-```typescript
-const tasksContent = await fs.readFile(
-  `.specweave/increments/${incrementId}/tasks.md`, 'utf-8'
-);
-
-const totalTasks = (tasksContent.match(/### T-\d+/g) || []).length;
-const completedTasks = (tasksContent.match(/\[x\] completed/gi) || []).length;
-const percentage = Math.round((completedTasks / totalTasks) * 100);
-```
-
-### 3. Invoke Push Sync
-
-```
-Use Skill tool: Skill({ skill: "sw-jira:jira-sync", args: "Push progress to Jira for increment {increment-id}.
-
-Issue: {jiraIssueKey}
-Progress: {completedTasks}/{totalTasks} ({percentage}%)
-
-Steps:
-1. Format progress comment with task list
-2. POST comment to Jira issue
-3. Update custom fields if available
-4. Transition status if threshold crossed:
-   - 100% completed -> Done (if canUpdateStatus)
-5. Update sync timestamp in metadata
-6. Display push summary"
-```
-
-### 4. Display Result
-
-```
-Pushed to Jira
-
-Issue: PROJ-123
-Project: My Project
-
-Progress: 6/10 tasks (60%)
-
-Comment posted:
-  "Progress Update: 60% complete
-
-   Recently completed:
-   - T-005: Add payment validation
-   - T-006: Implement refund flow"
-
-Fields updated:
-  Completion: 60%
-
-URL: https://mycompany.atlassian.net/browse/PROJ-123
-```
-
----
-
-## Permission Requirements
-
-| Permission | Required | Purpose |
-|------------|----------|---------|
-| `canUpdateExternalItems` | **true** | Write to Jira |
-| `canUpdateStatus` | optional | Transition issue status |
-
----
-
-## Examples
-
-### Example 1: Simple Push
-
-```
-User: sw-jira:push
-
-Claude:
-Pushing to Jira...
-  Increment: 0005-payment-integration
-  Issue: PROJ-123
-
-Progress: 8/10 tasks (80%)
-Comment posted.
-
-Push complete!
-```
-
-### Example 2: 100% Complete
-
-```
-User: sw-jira:push 0005
-
-Claude:
-Pushing to Jira...
-
-Progress: 10/10 tasks (100%)
-
-Comment posted:
-  "All tasks complete!"
-
-Status transitioned:
-  In Progress -> Done (canUpdateStatus = true)
-
-Ready to close: sw:done 0005
-```
-
----
-
-## Related Commands
-
-| Command | Purpose |
-|---------|---------|
-| `sw-jira:pull` | Pull changes from Jira |
-| `sw-jira:sync` | Two-way sync (pull + push) |
-| `sw-jira:import-boards` | Import Jira boards |

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

@@ -1,122 +0,0 @@
----
-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
-sw-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
-sw-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
-
-- `sw-jira:status`: View sync status for increments
-- `sw-jira:sync`: Manual sync to JIRA
-- `sw:done`: Close increment (triggers auto-close)
-- `sw:resume`: Resume increment (now triggers auto-reopen)

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

@@ -1,212 +0,0 @@
----
-description: Check JIRA sync status for SpecWeave increment
----
-
-# JIRA Status Command
-
-**Usage**: `sw-jira:status <increment-id>`
-
-**Purpose**: Display JIRA sync status and issue details for an increment
-
----
-
-## Command Behavior
-
-When user runs this command, Claude should:
-
-### 1. Read Increment Metadata
-
-```typescript
-// Load increment metadata
-const metadataPath = `.specweave/increments/${incrementId}/metadata.json`;
-const metadata = JSON.parse(await fs.readFile(metadataPath, 'utf-8'));
-
-// Check for linked JIRA issue (check both standard and legacy paths)
-const jiraSync = metadata?.external_sync?.jira || metadata?.external_ids?.jira;
-const issueKey = jiraSync?.issueKey || jiraSync?.epic;
-
-if (!issueKey) {
-  console.log(`
-⚠️ No JIRA issue linked
-
-This increment is not linked to a JIRA issue.
-Create one with: sw-jira:create ${incrementId}
-`);
-  return;
-}
-```
-
-### 2. Resolve JIRA Profile
-
-```typescript
-// Priority: increment profile > global defaultProfile > activeProfile
-let profileName = jiraSync?.profile;
-if (!profileName) {
-  const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
-  profileName = config?.sync?.defaultProfile ?? config?.sync?.activeProfile;
-}
-
-const profileConfig = config?.sync?.profiles?.[profileName];
-const { domain, projectKey } = profileConfig?.config || {};
-```
-
-### 3. Read Local Task Status
-
-```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;
-const completion = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
-```
-
-### 4. Invoke JIRA Manager Skill (Optional - For Live Status)
-
-```
-Use Skill tool: Skill({ skill: "sw-jira:jira-sync", args: "Check JIRA sync status for increment {increment-id}.
-
-Issue Key: {issueKey}
-Profile: {profileName} (domain: {domain})
-
-Steps:
-1. GET issue from JIRA API: /rest/api/3/issue/{issueKey}
-2. Extract: status, priority, assignee, sprint, story points
-3. Compare local vs JIRA status
-4. Detect any sync issues or drift
-5. Display comprehensive status"
-```
-
-### 5. Display Status
-
-```
-JIRA Sync Status
-================
-Increment: {increment-id}
-Issue: {issueKey}
-URL: https://{domain}/browse/{issueKey}
-Status: {jiraStatus}
-Completion: {completion}% ({completedTasks}/{totalTasks} tasks)
-Last Synced: {lastSyncedAt} ({relativeTime})
-Sync Enabled: ✅
-
-Profile: {profileName}
-  Domain: {domain}
-  Project: {projectKey}
-
-Next Sync: Automatic on task completion
-```
-
----
-
-## Example Output
-
-### Issue Linked
-
-```
-User: sw-jira:status 0005-payment-integration
-
-Claude:
-JIRA Sync Status
-================
-Increment: 0005-payment-integration
-Issue: MYPROJ-123
-URL: https://company.atlassian.net/browse/MYPROJ-123
-Status: In Progress
-Completion: 60% (6/10 tasks)
-Last Synced: 2025-12-07 10:30:00 (5 minutes ago)
-Sync Enabled: ✅
-
-Profile: jira-my-project
-  Domain: company.atlassian.net
-  Project: MYPROJ
-
-Priority: High
-Assignee: john.doe
-Sprint: Sprint 42
-
-Next Sync: Automatic on task completion
-```
-
-### No Issue Linked
-
-```
-User: sw-jira:status 0005
-
-Claude:
-JIRA Sync Status
-================
-Increment: 0005-payment-integration
-
-⚠️ No JIRA issue linked
-
-This increment is not linked to a JIRA issue.
-Create one with: sw-jira:create 0005-payment-integration
-```
-
-### Sync Issues Detected
-
-```
-User: sw-jira:status 0005
-
-Claude:
-JIRA Sync Status
-================
-Increment: 0005-payment-integration
-Issue: MYPROJ-123
-URL: https://company.atlassian.net/browse/MYPROJ-123
-Status: In Progress
-Completion: 60% (6/10 tasks)
-Last Synced: 2025-12-05 10:30:00 (2 days ago)
-Sync Enabled: ✅
-
-⚠️ Sync Issues Detected:
-  - Local status: in_progress, JIRA status: Done
-  - Status drift detected - run sw-jira:pull to sync
-
-Profile: jira-my-project
-  Domain: company.atlassian.net
-  Project: MYPROJ
-```
-
----
-
-## Status Information Displayed
-
-| Field | Source | Description |
-|-------|--------|-------------|
-| Issue | metadata.json | JIRA issue key (e.g., PROJ-123) |
-| URL | Constructed | Direct link to JIRA issue |
-| Status | JIRA API | Current issue status |
-| Completion | tasks.md | Local completion percentage |
-| Last Synced | metadata.json | Timestamp of last sync |
-| Profile | metadata/config | Which JIRA profile is used |
-| Priority | JIRA API | Issue priority |
-| Assignee | JIRA API | Current assignee |
-| Sprint | JIRA API | Current sprint assignment |
-
----
-
-## Drift Detection
-
-The status command detects common sync issues:
-
-| Issue | Detection | Resolution |
-|-------|-----------|------------|
-| Status drift | Local vs JIRA status mismatch | `sw-jira:pull` |
-| Stale sync | Last synced > 24 hours ago | `sw-jira:sync` |
-| Missing issue | Issue deleted in JIRA | `sw-jira:create` |
-| Permission denied | canUpdateExternalItems=false | Read-only mode note |
-
----
-
-## 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:close` | Close issue when complete |