zhongwei/gh-anton-abyzov-specweave-plugins-specweave-github

Files

Zhongwei Li 712abd45e8 Initial commit

2025-11-29 17:56:38 +08:00

3.7 KiB

Raw Blame History

name, description

name	description
specweave-github:reconcile	Reconcile GitHub issue states with increment statuses. Fixes drift by closing issues for completed increments and reopening issues for resumed increments.

GitHub Status Reconciliation

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

Usage

/specweave-github:reconcile [options]

Options

--dry-run: Preview changes without making them
--verbose: Show detailed output for each issue checked

What It Does

Scans all non-archived increments
Compares metadata.json status with GitHub issue state
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'),
});

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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Dry Run Mode

/specweave-github:reconcile --dry-run

Shows what would be changed without making any modifications:

  ❌ Issue #771 (0066-import-wizard/US-003): OPEN but should be CLOSED
     [DRY RUN] Would close issue #771

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

Requirements

GitHub CLI (gh) installed and authenticated
sync.github.enabled = true in config.json
sync.settings.canUpdateExternalItems = true in config.json

/specweave-github:status: View sync status for increments
/specweave-github:sync: Manual sync to GitHub
/specweave:done: Close increment (triggers auto-close)
/specweave:resume: Resume increment (now triggers auto-reopen)

3.7 KiB Raw Blame History