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

Scans all non-archived increments
Compares metadata.json status with ADO work item state
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)

/reconcile