From c7381476e045839b30cac992fac741346f6fdbb3 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason.woltje@uscllc.com>
Date: Fri, 6 Feb 2026 12:44:18 -0600
Subject: [PATCH] feat(orchestrator): Add Two-Phase Completion Protocol

Addresses threshold-satisficing behavior where agent declared success
at 91% and moved on. New protocol requires:

- Bulk Phase (90%): Fast progress on tractable errors
- Polish Phase (100%): Triage remaining into categories
- Phase Boundary Rule: Must complete Polish before proceeding
- Documentation: All deferrals documented with rationale

Transforms "78 errors acceptable" into traceable technical decisions.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/claude/orchestrator.md | 76 +++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/docs/claude/orchestrator.md b/docs/claude/orchestrator.md
index c375597..4a0392b 100644
--- a/docs/claude/orchestrator.md
+++ b/docs/claude/orchestrator.md
@@ -329,6 +329,82 @@ I will resume with {task_id} after compaction.
 
 ---
 
+## Two-Phase Completion Protocol
+
+Each major phase uses a two-phase approach to maximize completion while managing diminishing returns.
+
+### Bulk Phase (Target: 90%)
+
+- Focus on tractable errors
+- Parallelize where possible
+- When 90% reached, transition to Polish (do NOT declare success)
+
+### Polish Phase (Target: 100%)
+
+1. **Inventory:** List all remaining errors with file:line
+2. **Categorize:**
+   | Category | Criteria | Action |
+   |----------|----------|--------|
+   | Quick-win | <5 min, straightforward | Fix immediately |
+   | Medium | 5-30 min, clear path | Fix in order |
+   | Hard | >30 min or uncertain | Attempt 15 min, then document |
+   | Architectural | Requires design change | Document and defer |
+
+3. **Work priority:** Quick-win → Medium → Hard
+4. **Document deferrals** in `docs/deferred-errors.md`:
+
+   ```markdown
+   ## MS-XXX: [Error description]
+
+   - File: path/to/file.ts:123
+   - Error: [exact error message]
+   - Category: Hard | Architectural | Framework Limitation
+   - Reason: [why this is non-trivial]
+   - Suggested approach: [how to fix in future]
+   - Risk: Low | Medium | High
+   ```
+
+5. **Phase complete when:**
+   - All Quick-win/Medium fixed
+   - All Hard attempted (fixed or documented)
+   - Architectural items documented with justification
+
+### Phase Boundary Rule
+
+Do NOT proceed to the next major phase until the current phase reaches Polish completion:
+
+```
+✅ Phase 2 Bulk: 91%
+✅ Phase 2 Polish: 118 errors triaged
+   - 40 medium → fixed
+   - 78 low → EACH documented with rationale
+✅ Phase 2 Complete: Created docs/deferred-errors.md
+→ NOW proceed to Phase 3
+
+❌ WRONG: Phase 2 at 91%, "low priority acceptable", starting Phase 3
+```
+
+### Reporting
+
+When transitioning from Bulk to Polish:
+
+```
+Phase X Bulk Complete: {N}% ({fixed}/{total})
+Entering Polish Phase: {remaining} errors to triage
+```
+
+When Polish Phase complete:
+
+```
+Phase X Complete: {final_pct}% ({fixed}/{total})
+- Quick-wins: {n} fixed
+- Medium: {n} fixed
+- Hard: {n} fixed, {n} documented
+- Framework limitations: {n} documented
+```
+
+---
+
 ## Learning & Retrospective
 
 ### Variance Thresholds