/reconcile

description: Reconcile increment ID collisions after multi-developer merge. Renumbers conflicting increments based on modification dates.
disable-model-invocation: true

Reconcile Increment IDs

**Post-merge command for multi-developer workflows.** When multiple developers create increments with the same ID on different branches, run this after merging to resolve collisions by renumbering.

Philosophy

**Renumber, don't delete.** Unlike `sw:fix-duplicates` which removes duplicates, this command:

• Keeps ALL increments intact
• Renumbers the "later" ones (by modification date) to next available IDs
• Updates all references (metadata, living docs, external sync)
• Creates audit trail of what was renamed

When to Use

Run after merging branches that may have created increments with same IDs:

git checkout main
git merge feature-branch-a
git merge feature-branch-b
sw:reconcile           # Fix any ID collisions
git add . && git commit -m "reconcile: fix increment ID collisions"

Usage

# Detect and fix all ID collisions (interactive)
sw:reconcile

# Preview what would change (dry-run)
sw:reconcile --dry-run

# Auto-fix without confirmation
sw:reconcile --force

# Check specific increment number
sw:reconcile 0001

Options

• `<increment-number>`: Optional. Check only collisions for specific number (e.g., "0001")
• `--dry-run`: Show what would change without making modifications
• `--force`: Skip confirmation prompts (for CI/scripts)
• `--by-commit`: Use git commit date instead of file modification date for ordering

How It Works

Step 1: Detection

Scans ALL increment directories for ID collisions:

• `.specweave/increments/NNNN-*` (active)
• `.specweave/increments/_archive/NNNN-*`
• `.specweave/increments/_abandoned/NNNN-*`
• `.specweave/increments/_paused/NNNN-*`

**Collision detection**:

• Same base number (e.g., two `0001E-*` folders)
• OR same number with different E-suffix (e.g., `0001-*` and `0001E-*`)

Step 2: Chronological Ordering

Uses file modification dates to determine which increment came first:

0001E-auth-feature/      modified: 2026-01-15 10:00
0001E-payment-feature/   modified: 2026-01-20 14:30  ← LATER (renumber)

**Date sources (priority order)**: 1. `metadata.json` → `created` field 2. `spec.md` file modification time 3. Directory modification time 4. Git first commit date (if `--by-commit`)

Step 3: Renumbering

The "later" increment gets renumbered to next available ID:

BEFORE:
  0001E-auth-feature/        (Jan 15)
  0001E-payment-feature/     (Jan 20)

AFTER:
  0001E-auth-feature/        (kept as 0001E)
  0002E-payment-feature/     (renumbered to 0002E)

Step 4: Reference Updates

Updates ALL references to the renumbered increment:

**Local Files:** 1. **metadata.json** - Updates `id` field, adds `reconcileHistory` entry 2. **spec.md frontmatter** - Updates `increment:` field 3. **Living docs** - Renames `FS-XXX` folders in `.specweave/docs/internal/specs/`

• Updates `FEATURE.md` frontmatter and content
• Updates all `us-*.md` user story files

**External Tools (automatically updated via API):** 4. **GitHub**:

• Milestone titles containing old feature ID
• Issue titles with `[FS-XXX]` prefix
• Uses `gh` CLI for updates

5. **JIRA**:

• Epic/story summary (title) containing old feature ID
• Uses JIRA REST API v3

6. **ADO**:

• Feature/user story `System.Title` field
• Uses ADO REST API

Step 5: Audit Report

Creates `reports/RECONCILE-{timestamp}.md` documenting:

• Original ID → New ID mapping
• Which references were updated
• Modification dates used for ordering

Examples

Example 1: Two External Imports Collision

Two developers imported issues from JIRA, both got 0001E:

sw:reconcile

**Output**:

🔄 Scanning for ID collisions...

Found 1 collision:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Collision: Base ID 0001E (2 increments)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Increments (ordered by modification date):
  1. 0001E-auth-feature           (2026-01-15) → KEEP
  2. 0001E-payment-feature        (2026-01-20) → RENUMBER to 0002E

Proceeding with reconciliation...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Collisions found: 1
Increments renumbered: 1
References updated: 7

📦 Operations performed:

  ✓ 0001E-payment-feature → 0002E-payment-feature
    Feature: FS-001E → FS-002E
    Updated:
      ✓ metadata: Renamed folder
      ✓ metadata: Updated id field in metadata.json
      ✓ spec: Updated increment field in spec.md
      ✓ living-docs: Renamed FS-001E → FS-002E
      ✓ github: Updated issue #45 title: FS-001E → FS-002E
      ✓ jira: Updated PROJ-123 summary: FS-001E → FS-002E
      ✓ ado: Updated work item #789 title: FS-001E → FS-002E

📝 Report saved to: .specweave/increments/reports/RECONCILE-20260201-120000.md

💡 Next steps:
  1. Review the changes
  2. git add . && git commit -m "reconcile: fix ID collisions"
  3. Run sw-github:sync or sw-jira:sync to update external tools

Example 2: Dry-Run Preview

sw:reconcile --dry-run

**Output**:

[DRY RUN] Scanning for ID collisions...

Found 2 collisions:

Collision 1: Base ID 0001E
  [DRY RUN] Would keep: 0001E-auth-feature (2026-01-15)
  [DRY RUN] Would renumber: 0001E-payment-feature → 0002E-payment-feature

Collision 2: Base ID 0005
  [DRY RUN] Would keep: 0005-user-profile (2026-01-10)
  [DRY RUN] Would renumber: 0005-dashboard → 0006-dashboard

Summary:
  Would renumber: 2 increments
  Would update: 8 references

Run without --dry-run to apply changes.

Example 3: Three-Way Collision

Three developers created 0001E increments:

sw:reconcile

**Output**:

Collision: Base ID 0001E (3 increments)

Increments (ordered by modification date):
  1. 0001E-auth-feature      (2026-01-10) → KEEP as 0001E
  2. 0001E-payment-feature   (2026-01-15) → RENUMBER to 0002E
  3. 0001E-user-prof