/ado-reconcile

description: Reconcile Azure DevOps work item states with increment statuses. Fixes drift by closing work items for completed increments and reactivating work items for resumed increments.

Azure DevOps Status Reconciliation

Scan all increments and fix any drift between local metadata.json status and ADO work item states.

Usage

sw-ado:reconcile [options]

Options

• `--dry-run`: Preview changes without making them
• `--verbose`: Show detailed output for each work item checked

What It Does

1. **Scans** all non-archived increments 2. **Compares** metadata.json status with ADO work item state 3. **Fixes** mismatches:

• `metadata=completed` + `ADO=Active` → **Close** the work item
• `metadata=in-progress` + `ADO=Closed` → **Reactivate** the work item

When to Use

• After manual metadata.json edits
• After git pulls that changed increment statuses
• When you notice active work items for completed work
• As a periodic health check

Implementation

Run the reconciliation using the AdoReconciler:

import { AdoReconciler } from '../../../src/sync/ado-reconciler.js';

const reconciler = new AdoReconciler({
  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 ADO state drift...

  ✅ Work Item #1234 (0056-plugin-fix/US-001): State matches (Active)
  ❌ Work Item #1240 (0066-import-wizard/US-003): Active but should be CLOSED (status=completed)
     ✅ Closed work item #1240
  ❌ Work Item #1238 (0063-multi-repo/US-001): CLOSED but should be ACTIVE (status=in-progress)
     ✅ Reactivated work item #1238

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 ADO RECONCILIATION SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Increments scanned:   5
   Mismatches found:     2
   Work items closed:    1
   Work items reopened:  1
   Errors:               0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Dry Run Mode

sw-ado:reconcile --dry-run

Shows what would be changed without making any modifications:

  ❌ Work Item #1240 (0066-import-wizard/US-003): Active but should be CLOSED
     [DRY RUN] Would close work item #1240

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 ADO RECONCILIATION SUMMARY
   ⚠️  DRY RUN - No changes were made
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Requirements

• Azure DevOps PAT configured (`AZURE_DEVOPS_PAT`)
• `sync.ado.enabled = true` in config.json
• `sync.settings.canUpdateExternalItems = true` in config.json

ADO Status Mapping

| SpecWeave Status | Expected ADO State | |-----------------|-------------------| | `completed` | Closed, Done, Resolved | | `abandoned` | Closed, Removed | | `in-progress` | Active, In Progress | | `active` | Active, New | | `planning` | New |

Related Commands

• `sw-ado:status`: View sync status for increments
• `sw-ado:sync`: Manual sync to ADO
• `sw:done`: Close increment (triggers auto-close)
• `sw:resume`: Resume increment (now triggers auto-reopen)