github-reconcile

GitHub Status Reconciliation

Scan all increments and fix any drift between local metadata.json status and GitHub issue states.

Usage

sw-github:reconcile [options]

Options

• --dry-run: Preview changes without making them
• --verbose: Show detailed output for each issue checked
• --full: Deep reconciliation — removes issue search cap (1000 vs 100) and paginates all milestones

What It Does

1. Scans all non-archived increments
2. Compares metadata.json status with GitHub issue state
3. Fixes mismatches:
   • metadata=completed + GH=open → Close the issue
   • metadata=in-progress + GH=closed → Reopen the issue

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 GitHubReconciler:

import { GitHubReconciler } from '../../../src/sync/github-reconciler.js';

const reconciler = new GitHubReconciler({
  projectRoot: process.cwd(),
  dryRun: args.includes('--dry-run'),
  full: args.includes('--full'),
});

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 GitHub state drift...

  ✅ Issue #765 (0056-plugin-fix/US-001): State matches (open)
  ❌ Issue #771 (0066-import-wizard/US-003): OPEN but should be CLOSED (status=completed)
     ✅ Closed issue #771
  ❌ Issue #763 (0063-multi-repo/US-001): CLOSED but should be OPEN (status=in-progress)
     ✅ Reopened issue #763

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