Timmy-time-dashboard/docs/adr/021-self-upgrade-approval-queue.md

ADR 021: Self-Upgrade Approval Queue

Status

Proposed

Context

The self-modification system (src/self_modify/loop.py) can generate code changes autonomously. However, it currently either:

• Applies changes immediately (risky)
• Requires manual git review (slow)

We need an approval queue where changes are staged for human review before application.

Decision

Implement a dashboard-based approval queue for self-modifications with the following states: proposed → approved | rejected → applied | failed

Architecture

State Machine

                    ┌─────────────┐
                    │   PROPOSED  │
                    └──────┬──────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
           ▼               ▼               ▼
    ┌────────────┐  ┌────────────┐  ┌────────────┐
    │  APPROVED  │  │  REJECTED  │  │  EXPIRED   │
    └──────┬─────┘  └────────────┘  └────────────┘
           │
           ▼
    ┌────────────┐
    │  APPLIED   │
    └──────┬─────┘
           │
           ▼
    ┌────────────┐
    │   FAILED   │
    └────────────┘

Components

1. Database Table (upgrades table)

   CREATE TABLE upgrades (
       id TEXT PRIMARY KEY,
       status TEXT NOT NULL,  -- proposed, approved, rejected, applied, failed
       proposed_at TEXT NOT NULL,
       approved_at TEXT,
       applied_at TEXT,
       rejected_at TEXT,
       branch_name TEXT NOT NULL,
       description TEXT NOT NULL,
       files_changed TEXT,  -- JSON array
       diff_preview TEXT,   -- Short diff for review
       test_results TEXT,   -- JSON: {passed: bool, output: str}
       error_message TEXT,
       approved_by TEXT     -- For audit
   );
   

2. Self-Modify Loop (src/self_modify/loop.py)

   • On change proposal: Create proposed entry, stop
   • On approval: Checkout branch, apply changes, run tests, commit
   • On rejection: Cleanup branch, mark rejected

3. Dashboard UI (/self-modify/queue)

   • List all proposed changes
   • Show diff preview
   • Approve/Reject buttons
   • Show test results
   • History of past upgrades

4. API Endpoints

   • GET /self-modify/queue - List pending upgrades
   • POST /self-modify/queue/{id}/approve - Approve upgrade
   • POST /self-modify/queue/{id}/reject - Reject upgrade
   • GET /self-modify/queue/{id}/diff - View full diff

Integration Points

Existing: Self-Modify Loop

• Currently: Proposes change → applies immediately (or fails)
• New: Proposes change → creates DB entry → waits for approval

Existing: Dashboard

• New page: Upgrade Queue
• New nav item: "UPGRADES" with badge showing pending count

Existing: Event Log

• Logs: upgrade.proposed, upgrade.approved, upgrade.applied, upgrade.failed

Security Considerations

1. Approval Authentication - Consider requiring password/PIN for approval
2. Diff Size Limits - Reject diffs >10k lines (prevents DoS)
3. Test Requirement - Must pass tests before applying
4. Rollback - Keep previous commit SHA for rollback

Approval Flow

# 1. System proposes upgrade
upgrade = UpgradeQueue.propose(
    description="Fix bug in task assignment",
    branch_name="self-modify/fix-task-001",
    files_changed=["src/swarm/coordinator.py"],
    diff_preview="@@ -123,7 +123,7 @@...",
)
# Status: PROPOSED

# 2. Human reviews in dashboard
# - Views diff
# - Sees test results (auto-run on propose)
# - Clicks APPROVE or REJECT

# 3. If approved
upgrade.apply()  # Status: APPLIED or FAILED

# 4. If rejected
upgrade.reject()  # Status: REJECTED, branch deleted

UI Design

Upgrade Queue Page (/self-modify/queue)

┌─────────────────────────────────────────┐
│ PENDING UPGRADES (2)                    │
├─────────────────────────────────────────┤
│                                         │
│ Fix bug in task assignment      [VIEW]  │
│ Branch: self-modify/fix-task-001        │
│ Files: coordinator.py                   │
│ Tests: ✓ Passed                         │
│ [APPROVE]  [REJECT]                     │
│                                         │
│ Add memory search feature       [VIEW]  │
│ Branch: self-modify/memory-002          │
│ Files: memory/vector_store.py           │
│ Tests: ✗ Failed (1 error)               │
│ [APPROVE]  [REJECT]                     │
│                                         │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ UPGRADE HISTORY                         │
├─────────────────────────────────────────┤
│ ✓ Fix auth bug           APPLIED 2h ago │
│ ✗ Add new route          FAILED  5h ago │
│ ✗ Change config          REJECTED 1d ago│
└─────────────────────────────────────────┘

Consequences

Positive

• Human oversight prevents bad changes
• Audit trail of all modifications
• Test-before-apply prevents broken states
• Rejection is clean (no lingering branches)

Negative

• Adds friction to self-modification
• Requires human availability for urgent fixes
• Database storage for upgrade history

Mitigations

• Auto-approve after 24h for low-risk changes (configurable)
• Urgent changes can bypass queue (with logging)
• Prune old history after 90 days

Implementation Plan

1. Create src/upgrades/models.py - Database schema and ORM
2. Create src/upgrades/queue.py - Queue management logic
3. Modify src/self_modify/loop.py - Integrate with queue
4. Create dashboard routes - UI for approval
5. Create templates - Queue page, diff view
6. Add event logging for upgrades
7. Write tests for full workflow

Dependencies

• Existing src/self_modify/loop.py
• New database table upgrades
• Existing Event Log system