docs: Context Rotation harness-side V0 plan

[3ndym10n]

Summary

Planning-only (docs-only) design for harness-side Context Rotation V0 in the Hermes/Virgil runtime.

Designs how the runtime should:

1. detect oversized conversations,
2. request or build a compact checkpoint,
3. start a fresh internal conversation/thread,
4. inject the checkpoint,
5. continue safely,
6. stop retrying immediately on usage_limit_reached.

Grounded in the real codebase seams (agent/context_engine.py, agent/context_compressor.py, agent/conversation_loop.py, agent/error_classifier.py, agent/agent_runtime_helpers.py, gateway/run.py, gateway/session.py, gateway/slash_commands.py, gateway/config.py, and the Virgil precedent in gateway/virgil_preflight_gate.py).

Per Cogitator NousResearch#831: the live detect/rotate/inject/continue loop belongs in the Hermes/Virgil harness; Cogitator will later supply the checkpoint builder, bridge, and hard usage-limit classification. This plan defines the harness seam those plug into, plus a harness-local fallback so V0 can ship first.

Scope

• Docs only. One new file: docs/CONTEXT_ROTATION_HARNESS_V0_PLAN.md.
• No runtime code, tests, provider config, secrets, or services changed.
• Feature ships behind a flag, default off.

Contents

Six-step loop design · exact files/functions · token-counting locations · recommended thresholds (rotate at 0.90, above the 0.75 compress watermark) · checkpoint build + injection · /new vs auto-rotation relationship · usage_limit_reached retry short-circuit · feature flag (default off) · required tests · rollout plan · rollback boundary · forbidden surfaces · risk class · recommended 3-PR implementation prompt.

Validation

• git diff --check → clean
• git status --short → exactly one file added: docs/CONTEXT_ROTATION_HARNESS_V0_PLAN.md

🤖 Generated with Claude Code

[github-actions]

🔎 Lint report: docs/context-rotation-harness-v0-plan vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 10927 on HEAD, 10927 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 5728 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.