# RAG Phase 4 Sync Fix — Implementation Plan (2026-06-10)

> **For Tier 3 workers:** Steps use checkbox (`- [ ]`) syntax. Scope is 1-2 line surgical fix. Do not refactor `_do_rag_sync` more than necessary.

**Goal:** Fix `tests/test_rag_phase4_final_verify.py::test_phase4_final_verify` so `rag_status` reaches `'ready'` after the test configures RAG via the Hook API.

**Tech Stack:** Python 3.11+, pytest.

**HARD CONSTRAINTS:**
- **NEVER** use `git checkout -- <file>`, `git restore`, `git reset` (AGENTS.md HARD BAN)
- 1-space indent, CRLF, type hints
- 1 atomic commit
- No "while we're at it" refactors

---

## Phase 1: Diagnose and fix

### Task 1.1: Diagnose the failure mode

- [ ] **Step 1.1.1: Read the exact current code**
  Use `manual-slop_py_get_skeleton` or `manual-slop_get_file_slice` on `src/app_controller.py:1463-1500` and `src/rag_engine.py:88-180`.

- [ ] **Step 1.1.2: Add temporary diagnostic logging**
  Add 1-line stderr prints in `_do_rag_sync` to see what's happening:
  - After `if token != self._rag_sync_token: return`: print f"[RAG_DIAG] stale token {token} != current {self._rag_sync_token}, returning"
  - Before `self._set_rag_status("initializing...")`: print f"[RAG_DIAG] running sync for token {token}"
  - After setting status to "ready": print f"[RAG_DIAG] set status to 'ready' for token {token}"
  - In the except branch: print the exception (the existing code already does this)

  Use `manual-slop_edit_file` to add the diagnostic lines.

- [ ] **Step 1.1.3: Run the failing test in isolation**
  ```powershell
  cd C:\projects\manual_slop; uv run pytest tests/test_rag_phase4_final_verify.py::test_phase4_final_verify -v --timeout=120 -s 2>&1 | Tee-Object -FilePath "tests/artifacts/rag_diag_20260610.log" | Select-Object -Last 80
  ```
  Expected: see the diagnostic output in stderr.

- [ ] **Step 1.1.4: Read the diagnostic log and predict the failure mode**
  Open `tests/artifacts/rag_diag_20260610.log` and look for `[RAG_DIAG]` lines. Determine:
  - Did the worker for the latest token run?
  - Did it set status to "ready" or did it error?
  - Was there a race condition where multiple workers ran but the last one never completed?

### Task 1.2: Apply the fix

- [ ] **Step 1.2.1: Apply the fix in src/app_controller.py or src/rag_engine.py**
  Based on Step 1.1.4's diagnosis, apply a 1-2 line fix. Most likely candidates:
  - (a) Force the last worker to actually run by serializing them in the io_pool (not feasible without restructuring)
  - (b) Use a `threading.Semaphore(1)` to ensure only ONE RAG sync runs at a time
  - (c) Remove the coalescing complexity — each setter just runs sync directly
  - (d) Fix the RAGEngine init to handle missing sentence-transformers gracefully (e.g., fall back to a mock provider)

- [ ] **Step 1.2.2: Remove the diagnostic logging**
  After the fix is verified, remove the `[RAG_DIAG]` lines from `src/app_controller.py`. (Diagnostic code does not ship in production per AGENTS.md.)

- [ ] **Step 1.2.3: Verify syntax**
  ```powershell
  cd C:\projects\manual_slop; uv run python -c "import ast; ast.parse(open('src/app_controller.py').read()); print('OK')"
  ```

- [ ] **Step 1.2.4: Verify import**
  ```powershell
  cd C:\projects\manual_slop; uv run python -c "from src.app_controller import AppController; print('import OK')"
  ```

### Task 1.3: Verify in isolation

- [ ] **Step 1.3.1: Run the RAG test in isolation**
  ```powershell
  cd C:\projects\manual_slop; uv run pytest tests/test_rag_phase4_final_verify.py::test_phase4_final_verify -v --timeout=120
  ```
  Expected: 1/1 pass.

### Task 1.4: Verify in batch

- [ ] **Step 1.4.1: Run all 4 sim tests in isolation (regression check)**
  ```powershell
  cd C:\projects\manual_slop; uv run pytest tests/test_extended_sims.py -v --timeout=300
  ```
  Expected: 4/4 pass.

- [ ] **Step 1.4.2: Run the full tier-3-live_gui batch (authoritative)**
  ```powershell
  cd C:\projects\manual_slop; uv run .\scripts\run_tests_batched.py 2>&1 | Tee-Object -FilePath "tests/artifacts/post_rag_fix_batch_20260610.log" | Select-Object -Last 50
  ```
  Expected: tier-1 5/5, tier-2 5/5, tier-3 either completes fully or only halts on a DIFFERENT (unrelated) pre-existing failure.

### Task 1.5: Checkpoint commit

- [ ] **Step 1.5.1: Commit the fix**
  ```powershell
  cd C:\projects\manual_slop; git add src/app_controller.py src/rag_engine.py
  git commit -m "fix(rag): [describe the actual fix]"
  $h = git log -1 --format='%H'
  git notes add -m "..." $h
  ```

- [ ] **Step 1.5.2: Checkpoint commit with batch log**
  ```powershell
  cd C:\projects\manual_slop; git add -f tests/artifacts/post_rag_fix_batch_20260610.log
  git commit -m "conductor(checkpoint): RAG phase 4 sync fix complete"
  $h = git log -1 --format='%H'
  git notes add -m "..." $h
  ```

---

## Final Verification

- [ ] `test_rag_phase4_final_verify.py::test_phase4_final_verify` passes in isolation
- [ ] 4 sim tests in `test_extended_sims.py` pass in isolation (regression)
- [ ] Full tier-3-live_gui batch: at least gets past `test_rag_phase4_final_verify`
- [ ] 1 atomic commit + 1 checkpoint

## Track Done

After the fix and verification, the track is DONE.
