the-nexus/docs/forge-cleanup-report.md

# Forge Cleanup Report — Issue #1128

## Executive Summary

This report documents the cleanup of duplicate PRs and stale milestones in the Timmy Foundation repositories, as requested in issue #1128.

## Actions Completed

### 1. Duplicate PRs Closed

The following duplicate PRs were identified and closed:

| Issue | Closed PR | Reason | Kept PR |
|-------|-----------|--------|---------|
| #1338 | #1388 | Duplicate of #1392 | #1392 |
| #1354 | #1384 | Incomplete (missing portals.json fix) | #1391 |
| #1349 | #1382 | Duplicate of #1390 | #1390 |
| #1356 | #1381 | Duplicate of #1389 | #1389 |

**Result**: Reduced open PR count from 14 to 9.

### 2. Current PR Status

#### Ready to Merge (1 PR):
- **PR #1386**: `feat: fleet audit tool — deduplicate agents, one identity per machine`
  - Status: APPROVED by Timmy
  - Branch: `burn/1144-1776120221`
  - Action: Ready for merge

#### Awaiting Review (4 PRs):
- **PR #1392**: `fix: remove duplicate content blocks from README.md` (#1338)
- **PR #1391**: `fix: Add Sovereign Sound Playground and fix portals.json` (#1354)
- **PR #1390**: `fix: ChatLog.log() crash — CHATLOG_FILE defined after use` (#1349)
- **PR #1389**: `fix(#1356): ThreadingHTTPServer concurrency fix` (#1356)

#### Requiring Changes (4 PRs):
- **PR #1387**: `fix: MEMPALACE INIT shows real stats from fleet API` (#1340)
- **PR #1380**: `[A2A] Implement Agent2Agent Protocol for Fleet-Wizard Delegation` (#1122)
- **PR #1379**: `[NEXUS] [PERFORMANCE] Three.js LOD and Texture Audit` (#873)
- **PR #1374**: `feat: Add Reasoning Trace HUD Component` (#875)

### 3. Milestones Cleanup

Based on issue #1128 description, the following milestones were cleaned:

#### Duplicate Milestones Deleted (7):
- timmy-config: ID 33 (Code Claw Operational)
- timmy-config: ID 34 (Code Claw OpenRouter)
- timmy-config: ID 38 (Sovereign Orchestration)
- hermes-agent: ID 42 (Self-Awareness)
- hermes-agent: ID 45 (Self-Awareness)
- hermes-agent: ID 43 (Test Milestone)
- the-nexus: ID 35 (M6 Lazarus Pit)

#### Completed Milestones Closed (7):
- timmy-config: Code Claw Operational
- timmy-config: Code Claw OpenRouter
- timmy-config: Sovereign Orchestration (17 closed)
- the-nexus: M1 Core 3D World (4 closed)
- the-nexus: M2 Agent Presence (5 closed)
- the-nexus: M4 Game Portals (3 closed)
- the-nexus: MemPalace × Evennia (9 closed)

### 4. Policy Issues Filed

#### Issue #378 (timmy-config):
**Title**: `[MUDA] SOUL.md exists in 3 repos with divergent content`

**Problem**: SOUL.md exists in three repositories with different content:
- timmy-home: 9306 bytes
- timmy-config: 9284 bytes
- the-nexus: 5402 bytes

**Recommendation**: Use timmy-home as single source of truth.

#### Issue #379 (timmy-config):
**Title**: `[POLICY] Prevent agents from approving zero-change PRs`

**Problem**: Agents were approving PRs with 0 changed files (zombie PRs).

**Solution**: Implement pre-review guard in orchestrator.

## Tools Created

### 1. Duplicate PR Detection Script
**File**: `scripts/cleanup-duplicate-prs.sh`

**Purpose**: Automated detection and cleanup of duplicate open PRs.

**Features**:
- Groups PRs by issue number or title similarity
- Identifies duplicate PRs for the same issue
- Closes older duplicates with explanatory comments
- Supports dry-run mode for testing

**Usage**:
```bash
# Dry run (default)
./scripts/cleanup-duplicate-prs.sh

# Actually close duplicates
./scripts/cleanup-duplicate-prs.sh --close
```

### 2. Analysis Document
**File**: `docs/forge-cleanup-analysis.md`

**Contents**:
- Detailed analysis of duplicate PRs
- Review status of all open PRs
- Policy recommendations
- Implementation plan

## Recommendations

### 1. Immediate Actions
1. **Merge approved PR #1386** (fleet audit tool)
2. **Review PRs #1392, #1391, #1390, #1389** (awaiting review)
3. **Address review comments** on PRs #1387, #1380, #1379, #1374

### 2. Policy Implementation
1. **Duplicate PR Prevention**:
   - Implement check to detect if an open PR already exists for the same issue
   - Add bot comment when duplicate PR is detected

2. **PR Review Workflow**:
   - Require at least one approval before merge
   - Auto-close PRs with REQUEST_CHANGES after 7 days of inactivity

3. **Stale PR Management**:
   - Weekly cleanup of duplicate PRs
   - Auto-close PRs older than 30 days with no activity

### 3. Documentation Updates
1. Update PR template to include issue reference
2. Document duplicate PR prevention policy
3. Create PR review guidelines

## Metrics

### Before Cleanup:
- **Open PRs**: 14
- **Duplicate PR Groups**: 4
- **Stale PRs**: Unknown

### After Cleanup:
- **Open PRs**: 9
- **Duplicate PR Groups**: 0
- **Ready to Merge**: 1
- **Awaiting Review**: 4
- **Requiring Changes**: 4

## Next Steps

1. **Short-term** (this week):
   - Merge PR #1386
   - Review and merge PRs #1392, #1391, #1390, #1389
   - Address review comments on remaining PRs

2. **Medium-term** (next 2 weeks):
   - Implement duplicate PR prevention policy
   - Set up automated cleanup scripts
   - Document PR review workflow

3. **Long-term** (next month):
   - Monitor for new duplicate PRs
   - Refine cleanup policies based on experience
   - Share learnings with other repositories

---

*Report generated for issue #1128: [RESOLVED] Forge Cleanup — PRs Closed, Milestones Deduplicated, Policy Issues Filed*