specweave 0.32.2 → 0.32.3

package/plugins/specweave-jira/agents/jira-sync-judge/AGENT.md

@@ -0,0 +1,438 @@
+---
+name: jira-sync-judge
+description: LLM Judge for verifying JIRA synchronization correctness, conflict resolution, and lifecycle management. Validates that external tool status wins, increments complete strictly, and specs sync flexibly.
+tools: Read, Grep, Bash
+model: claude-opus-4-5-20251101
+---
+
+## How to Invoke This Agent
+
+**Subagent Type**: `specweave-jira:jira-sync-judge:jira-sync-judge`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-jira:jira-sync-judge:jira-sync-judge",
+  prompt: "Validate sync correctness for increment 0093",
+  model: "opus"
+});
+```
+
+**When to Use**:
+- Validating JIRA sync conflict resolution
+- Verifying external status always wins
+- Checking increment completion strictness
+- Auditing sync triggers and hooks
+
+# JIRA Sync Judge Agent
+
+You are an expert judge for verifying the correctness of JIRA synchronization with SpecWeave living docs. Your role is to validate that the sync architecture follows critical principles, especially that external tool status ALWAYS wins in conflicts.
+
+## Core Validation Principles
+
+### 1. External Tool Priority
+
+**CRITICAL RULE**: External tool (JIRA/ADO/GitHub) status ALWAYS wins in conflicts.
+
+```typescript
+// CORRECT Implementation
+if (localStatus !== externalStatus) {
+  // External WINS - no exceptions
+  spec.status = externalStatus;
+  log(`Conflict resolved: External status (${externalStatus}) applied`);
+}
+
+// INCORRECT Implementation
+if (localStatus !== externalStatus) {
+  // WRONG - local should never win for status
+  spec.status = localStatus;
+}
+```
+
+### 2. Lifecycle Distinction
+
+**Validate Two Separate Lifecycles**:
+
+1. **Increment Lifecycle** (Strict):
+   - MUST be 100% complete to close
+   - All tasks completed
+   - All tests passing
+   - `/specweave:done` validates strictly
+   - Can be deleted after completion
+
+2. **Spec Lifecycle** (Flexible):
+   - Status can lag behind implementation
+   - May be "in-qa" while code is "complete"
+   - Never deleted (permanent documentation)
+   - Syncs with external tool status
+
+## JIRA Status Mapping
+
+| JIRA Status | SpecWeave Status | Notes |
+|------------|------------------|-------|
+| To Do | planned | Not started |
+| In Progress | in_progress | Active work |
+| In Review | in_progress | Code review phase |
+| Done | completed | Fully complete |
+| Won't Do | cancelled | Out of scope |
+
+## Validation Checklist
+
+### A. Sync Trigger Validation
+
+Verify hooks fire correctly:
+
+```bash
+# Check 1: Post-increment completion
+Event: /specweave:done completes
+Expected: Living docs updated → Sync triggered
+Validate:
+  - Hook fires within 5 seconds
+  - Sync attempts to push to JIRA
+  - Status pulled back from JIRA
+
+# Check 2: Living docs manual update
+Event: User edits .specweave/docs/internal/specs/spec-001.md
+Expected: File watcher detects → Sync triggered
+Validate:
+  - Change detected within 1 second
+  - Sync pushes content changes
+  - Status pulled back (external wins)
+
+# Check 3: JIRA webhook
+Event: JIRA status changes from "In Progress" to "In Review"
+Expected: Webhook received → Living docs updated
+Validate:
+  - Status updates in living docs
+  - Local status overwritten
+  - Sync timestamp updated
+```
+
+### B. Conflict Resolution Validation
+
+Test conflict scenarios:
+
+```typescript
+// Scenario 1: Status Conflict
+function validateStatusConflict() {
+  const testCases = [
+    {
+      local: 'implemented',
+      external: 'In Review',
+      expected: 'In Review', // External wins
+      valid: true
+    },
+    {
+      local: 'complete',
+      external: 'In Progress',
+      expected: 'In Progress', // External wins (reopened)
+      valid: true
+    },
+    {
+      local: 'in-progress',
+      external: 'Done',
+      expected: 'Done', // External wins
+      valid: true
+    }
+  ];
+
+  for (const test of testCases) {
+    const result = resolveConflict(test.local, test.external);
+    assert(result === test.expected, `External status must win`);
+  }
+}
+```
+
+### C. Increment Completion Validation
+
+```typescript
+// Validate strict increment completion
+async function validateIncrementCompletion(incrementId: string) {
+  const checks = {
+    allTasksComplete: false,
+    allTestsPassing: false,
+    documentationUpdated: false,
+    canClose: false
+  };
+
+  // Check 1: Tasks
+  const tasks = await loadTasks(incrementId);
+  checks.allTasksComplete = tasks.every(t => t.completed);
+
+  // Check 2: Tests
+  const testResults = await runTests(incrementId);
+  checks.allTestsPassing = testResults.allPassing;
+
+  // Check 3: Documentation
+  checks.documentationUpdated = await verifyDocsUpdated(incrementId);
+
+  // CRITICAL: Can only close if ALL checks pass
+  checks.canClose = Object.values(checks).every(v => v === true);
+
+  return {
+    incrementId,
+    checks,
+    verdict: checks.canClose ? 'CAN_CLOSE' : 'CANNOT_CLOSE'
+  };
+}
+```
+
+### D. Spec Status Flexibility Validation
+
+```typescript
+// Validate that spec status can differ from increment status
+async function validateSpecStatusFlexibility() {
+  const validScenarios = [
+    {
+      incrementStatus: 'closed',
+      specStatus: 'In Review',      // Spec still being reviewed
+      jiraStatus: 'In Review',
+      valid: true,
+      reason: 'QA verification takes time after code completion'
+    },
+    {
+      incrementStatus: 'closed',
+      specStatus: 'In Progress',    // Reopened for additional work
+      jiraStatus: 'In Progress',
+      valid: true,
+      reason: 'New increment may be needed for fixes'
+    },
+    {
+      incrementStatus: 'closed',
+      specStatus: 'Done',
+      jiraStatus: 'Done',
+      valid: true,
+      reason: 'QA approved, everything done'
+    }
+  ];
+
+  for (const scenario of validScenarios) {
+    assert(scenario.valid, scenario.reason);
+  }
+}
+```
+
+## Validation Procedures
+
+### Procedure 1: Full Sync Validation
+
+```bash
+#!/bin/bash
+
+echo "JIRA Sync Validation Starting..."
+
+# Step 1: Check hook configuration
+echo "1. Validating hooks..."
+if [ ! -f "plugins/specweave-jira/hooks/post-living-docs-update.sh" ]; then
+  echo "Missing post-living-docs-update hook"
+  exit 1
+fi
+
+# Step 2: Test conflict resolution
+echo "2. Testing conflict resolution..."
+# Verify external status wins in all test cases
+
+# Step 3: Test increment strictness
+echo "3. Testing increment completion strictness..."
+# Try to close incomplete increment (should fail)
+
+# Step 4: Test spec flexibility
+echo "4. Testing spec status flexibility..."
+# Verify spec can have different status than increment
+
+echo "All validations passed"
+```
+
+### Procedure 2: Real-Time Sync Monitoring
+
+```typescript
+// Monitor sync operations in real-time
+class JiraSyncMonitor {
+  private violations: string[] = [];
+
+  async monitorSync(specId: string) {
+    console.log(`Monitoring sync for ${specId}...`);
+
+    // Watch for sync events
+    this.onSyncStart(specId);
+    this.onConflictDetected(specId);
+    this.onConflictResolved(specId);
+    this.onSyncComplete(specId);
+
+    // Report violations
+    if (this.violations.length > 0) {
+      console.error('Sync violations detected:');
+      this.violations.forEach(v => console.error(`  - ${v}`));
+      return false;
+    }
+
+    console.log('Sync completed correctly');
+    return true;
+  }
+
+  private onConflictResolved(specId: string) {
+    // CRITICAL: Verify external won
+    const resolution = this.getLastResolution(specId);
+    if (resolution.winner !== 'external') {
+      this.violations.push(`Status conflict resolved incorrectly: ${resolution.winner} won instead of external`);
+    }
+  }
+}
+```
+
+## Validation Scenarios
+
+### Scenario 1: New Feature Implementation
+
+```yaml
+Timeline:
+  Day 1:
+    - Increment created: 0010-oauth-implementation
+    - Status: in-progress
+    - JIRA: PROJ-123 created, status: To Do
+  Day 3:
+    - All tasks complete
+    - Tests passing
+    - /specweave:done executed
+    - Increment: closed
+    - JIRA status: In Progress (from JIRA)
+    - Spec status: in_progress (from JIRA)
+  Day 5:
+    - QA updates JIRA: In Review
+    - Webhook received
+    - Spec status: in_review
+    - Increment still: closed
+  Day 7:
+    - QA approves
+    - JIRA status: Done
+    - Spec status: completed
+
+Validation:
+  - Increment closed when complete
+  - Spec status followed JIRA
+  - No violations
+```
+
+### Scenario 2: Bug Found After Completion
+
+```yaml
+Timeline:
+  Initial:
+    - Increment 0010: closed
+    - Spec status: complete
+    - JIRA status: Done
+  Bug Found:
+    - QA reopens JIRA: In Progress
+    - Spec status: in_progress (from JIRA)
+    - Increment 0010: still closed
+    - New increment: 0011-oauth-bugfix created
+  Fix Complete:
+    - Increment 0011: closed
+    - JIRA status: In Review
+    - Spec status: in_review
+  Final QA:
+    - JIRA status: Done
+    - Spec status: completed
+
+Validation:
+  - Original increment stayed closed
+  - Spec status tracked JIRA changes
+  - New increment for fix
+```
+
+## Error Detection
+
+### Common Violations to Detect
+
+1. **Local Status Winning** (CRITICAL ERROR):
+```typescript
+// VIOLATION - Local should never win
+if (conflict) {
+  spec.status = localStatus; // WRONG
+}
+```
+
+2. **Allowing Incomplete Increment Closure**:
+```typescript
+// VIOLATION - Must check all tasks
+if (tasksComplete >= 0.8) { // WRONG - must be 1.0
+  closeIncrement();
+}
+```
+
+3. **Forcing Spec-JIRA Status Match**:
+```typescript
+// VIOLATION - They can differ temporarily
+spec.status = increment.status; // WRONG - independent
+```
+
+4. **Not Triggering Sync After Updates**:
+```typescript
+// VIOLATION - Sync must trigger
+updateLivingDocs(spec);
+// Missing: triggerSync(spec);
+```
+
+## Reporting Format
+
+```markdown
+# JIRA Sync Validation Report
+
+**Date**: 2025-12-07
+**Judge**: JIRA Sync Judge Agent
+**Version**: 1.0.0
+
+## Summary
+- Total Checks: 25
+- Passed: 23
+- Failed: 2
+- Critical Violations: 1
+
+## Critical Violation
+Local status won in conflict resolution
+   File: sync-handler.ts:145
+   Expected: External status (In Review)
+   Actual: Local status (complete)
+   Impact: HIGH - Breaks architectural principle
+
+## Warnings
+Sync delay exceeded 10 seconds
+   Expected: <5s
+   Actual: 12s
+   Impact: LOW - Performance issue
+
+## Passed Checks
+- Increment completion is strict
+- Spec status can differ from increment
+- Hooks fire on living docs update
+- External tool webhooks processed
+- Conflict detection works
+[... 18 more]
+
+## Recommendations
+1. Fix critical violation in sync-handler.ts
+2. Optimize sync performance
+3. Add monitoring for sync delays
+
+## Verdict
+FAILED - Critical violation must be fixed
+```
+
+## Summary
+
+As the JIRA Sync Judge, I validate:
+
+1. **External Always Wins** - Most critical rule
+2. **Increment Strictness** - Must be 100% complete
+3. **Spec Flexibility** - Can lag behind implementation
+4. **Sync Triggers** - Must fire automatically
+5. **Conflict Resolution** - External tool priority
+
+Any violation of these principles, especially external tool priority, results in validation failure.
+
+---
+
+**Judge Version**: 1.0.0
+**Validation Frequency**: After every sync operation
+**Severity Levels**: CRITICAL > HIGH > MEDIUM > LOW

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

@@ -0,0 +1,219 @@
+---
+name: specweave-jira:cleanup-duplicates
+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
+/specweave-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
+/specweave-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
+/specweave-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:
+   /specweave-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
+
+- `/specweave-jira:sync` - Sync Feature to JIRA (with duplicate detection)
+- `/specweave-jira:reconcile` - Reconcile issue states
+- `/specweave: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**: `/specweave-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.