archiving tracks

conductor/archive/tier4_auto_patching_20260306/spec.md

@@ -0,0 +1,142 @@
+# Track Specification: Advanced Tier 4 QA Auto-Patching (tier4_auto_patching_20260306)
+
+## Overview
+Elevate Tier 4 from log summarizer to auto-patcher. When verification tests fail, Tier 4 generates a unified diff patch. GUI displays side-by-side diff; user clicks Apply Patch to resume pipeline.
+
+## Current State Audit
+
+### Already Implemented (DO NOT re-implement)
+
+#### Tier 4 Analysis (ai_client.py)
+- **`run_tier4_analysis(stderr: str) -> str`**: Analyzes error, returns summary
+- **Prompt**: Uses `mma_prompts.PROMPTS["tier4_error_triage"]`
+- **Output**: Text analysis, no code generation
+
+#### Error Interception (shell_runner.py)
+- **`run_powershell()`**: Accepts `qa_callback` parameter
+- **On failure**: Calls `qa_callback(stderr)` and appends to output
+- **Integrated**: `ai_client._run_script()` passes `qa_callback`
+
+#### MCP Tools (mcp_client.py)
+- **`set_file_slice()`**: Replace line range in file
+- **`py_update_definition()`**: Replace class/function via AST
+- **`edit_file()`**: String replacement in file
+- **No diff generation or patch application**
+
+### Gaps to Fill (This Track's Scope)
+- Tier 4 doesn't generate patches
+- No diff visualization in GUI
+- No patch application mechanism
+- No rollback capability
+
+## Architectural Constraints
+
+### Safe Preview
+- Patches MUST be previewed before application
+- User MUST see exactly what will change
+- No automatic application without approval
+
+### Atomic Application
+- Patch applies all changes or none
+- If partial application fails, rollback
+
+### Rollback Support
+- Backup created before patch
+- User can undo applied patch
+- Backup stored temporarily
+
+## Architecture Reference
+
+### Key Integration Points
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `src/ai_client.py` | ~700-750 | `run_tier4_analysis()` |
+| `src/shell_runner.py` | 50-100 | `run_powershell()` with qa_callback |
+| `src/mcp_client.py` | 300-350 | `set_file_slice()`, `edit_file()` |
+| `src/gui_2.py` | 2400-2500 | Confirmation dialogs pattern |
+
+### Proposed Patch Workflow
+
+```
+1. Test fails → stderr captured
+2. Tier 4 analyzes → generates unified diff
+3. GUI shows diff viewer with Apply/Reject buttons
+4. User clicks Apply:
+   a. Backup original file(s)
+   b. Apply patch via subprocess or difflib
+   c. Verify patch applied cleanly
+   d. If fails, restore from backup
+5. Pipeline resumes with patched code
+```
+
+### Unified Diff Format
+
+```diff
+--- a/src/target_file.py
++++ b/src/target_file.py
+@@ -10,5 +10,6 @@
+ def existing_function():
+-    old_line
++    new_line
++    additional_line
+```
+
+## Functional Requirements
+
+### FR1: Patch Generation
+- Tier 4 prompt enhanced to generate unified diff
+- Output format: standard `diff -u` format
+- Include file path in diff header
+- Multiple files supported
+
+### FR2: Diff Viewer GUI
+- Side-by-side or unified view
+- Color-coded additions (green) and deletions (red)
+- Line numbers visible
+- Scrollable for large diffs
+
+### FR3: Apply Button
+- Creates backup: `file.py.backup`
+- Applies patch: `patch -p1 < diff.patch` or Python difflib
+- Verifies success
+- Shows confirmation or error
+
+### FR4: Rollback
+- Restore from backup if patch fails
+- Manual rollback button after successful patch
+- Backup deleted after explicit user action
+
+## Non-Functional Requirements
+
+| Requirement | Constraint |
+|-------------|------------|
+| Patch Generation | <5s for typical errors |
+| Diff Rendering | <100ms for 100-line diff |
+| Backup Storage | Temp dir, cleaned on exit |
+
+## Testing Requirements
+
+### Unit Tests
+- Test diff generation format
+- Test patch application logic
+- Test backup/rollback
+
+### Integration Tests (via `live_gui` fixture)
+- Trigger test failure, verify patch generated
+- Apply patch, verify file changed correctly
+- Rollback, verify file restored
+
+## Out of Scope
+- Automatic patch application (always requires approval)
+- Patch conflict resolution (reject if conflict)
+- Multi-file patch coordination
+
+## Acceptance Criteria
+- [ ] Tier 4 generates valid unified diff on test failure
+- [ ] GUI displays readable side-by-side diff
+- [ ] User can approve/reject patch
+- [ ] Approved patches applied correctly
+- [ ] Rollback available on failure
+- [ ] Backup files cleaned up
+- [ ] 1-space indentation maintained