From 8d8db472894acaaa1a90edc0eb6bf7febaf384d4 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason.woltje@uscllc.com>
Date: Fri, 6 Feb 2026 11:41:06 -0600
Subject: [PATCH] docs: Update compaction protocol - agents cannot invoke
 /compact

CRITICAL finding: Agents cannot trigger compaction
- "compact and continue" does NOT work
- Only user typing /compact in CLI works
- Auto-compact at ~95% is too late

Updated protocol:
- Stop at 55-60% context usage
- Output COMPACTION REQUIRED checkpoint
- Wait for user to run /compact and say "continue"

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

diff --git a/docs/claude/orchestrator.md b/docs/claude/orchestrator.md
index b674109..c375597 100644
--- a/docs/claude/orchestrator.md
+++ b/docs/claude/orchestrator.md
@@ -223,8 +223,9 @@ git push
 12. Commit + push: git add docs/tasks.md && git commit && git push
 13. If phase verification task: Run phase retrospective
 14. Check context usage
-15. If >= 60%: Persist learnings, Compact, go to step 1
-16. If < 60%: Go to step 1
+15. If >= 55%: Output COMPACTION REQUIRED checkpoint, STOP, wait for user
+16. If < 55%: Go to step 1
+17. After user runs /compact and says "continue": Go to step 1
 ```
 
 ---
@@ -277,19 +278,54 @@ git push
 
 ## Compaction Protocol
 
-**Threshold:** 60% context usage
+**Threshold:** 55-60% context usage
 
-**Why 60%?** System overhead is ~26%. Real capacity is ~74%. Triggering at 60% = ~81% actual usage — safe margin before the 91-95% emergency wall.
+**CRITICAL:** Agents CANNOT trigger compaction. Only the user typing `/compact` works.
 
-**Compaction steps:**
+- ❌ "compact and continue" does NOT work (agent outputs summary but context is NOT compressed)
+- ❌ Agent cannot invoke `/compact` programmatically
+- ✅ User must type `/compact` directly in the CLI
 
-1. Update docs/tasks.md with all current progress
-2. Commit + push tasks.md
-3. Output summary (completed, quality status, remaining, next task)
-4. Clear detailed worker outputs and execution history from context
-5. Resume with next unblocked task
+**When approaching threshold (55-60%):**
 
-**Compaction does NOT require user permission.**
+1. Complete current task
+2. Persist all state:
+   - Update docs/tasks.md with all progress
+   - Update docs/orchestrator-learnings.json with variances
+   - Commit and push both files
+3. Output checkpoint using this EXACT format:
+
+```
+---
+⚠️ COMPACTION REQUIRED
+
+Context: {X}% — Cannot continue without compaction.
+
+Progress: {completed}/{total} tasks ({percentage}%)
+Next task: {task_id}
+
+State persisted to:
+- docs/tasks.md ✓
+- docs/orchestrator-learnings.json ✓
+
+ACTION REQUIRED:
+1. Type `/compact` in the CLI (not in chat)
+2. After compaction completes, say "continue"
+
+I will resume with {task_id} after compaction.
+---
+```
+
+4. **STOP COMPLETELY** — do not continue working
+5. Wait for user to run `/compact` and say "continue"
+6. Resume from next task
+
+**Rules:**
+
+- Do NOT output a summary and keep working
+- Do NOT claim you can compact yourself
+- Do NOT continue past 60% — the checkpoint is mandatory
+- STOP means STOP — wait for user action
 
 ---
 
@@ -337,9 +373,11 @@ QA automation generates report files in `docs/reports/qa-automation/pending/`. C
 
 1. All tasks in docs/tasks.md are `done`
 2. Critical blocker preventing progress (document and alert)
-3. Absolute context limit reached AND cannot compact further
+3. Context usage >= 55% — output COMPACTION REQUIRED checkpoint and wait
+4. Absolute context limit reached AND cannot compact further
 
 **DO NOT stop to ask "should I continue?"** — the answer is always YES.
+**DO stop at 55-60%** — output the compaction checkpoint and wait for user to run `/compact`.
 
 ---