Epic (post-v0.5): low-context mode — frequent intelligent compaction for lower-tier local models (reviews stay complete via split packages)

[mfittko]

Post-v0.5 epic. Not a 0.5 blocker — scheduled after the release. Builds on the model-agnostic property (the intro article/deck #979/#973) and extends it downward: make the loop usable with lower-tier local models that have small context windows, via a low-context mode with frequent, automatic, intelligent context compaction.

Why

The loop is already model-agnostic for top-tier open-source models. The remaining barrier for smaller local models is context: long sessions overflow modest windows and weaker long-context handling degrades quality. But the dev-loop already externalizes its state — the startup resolver, the handoff envelope (requiredReads/nextAction/stopRules/acceptance), the outer-loop checkpoint, gate-coordination state, the retrospective checkpoint. Those artifacts are the durable memory, so the conversational context can be kept small and rebuilt deterministically per step.

Goal

A low-context mode in which the loop:

1. compacts the working context frequently and automatically (at natural boundaries — each handoff, gate step, phase) rather than only on overflow;
2. compacts intelligently — preserve the load-bearing state (current handoff envelope, AC/DoD, open findings, ratified decisions) and drop transient detail, leaning on the deterministic artifacts as the source of truth;
3. keeps work units small so each issue/phase fits the model's working set (see the LOC-scoping AC);
4. fits a small context budget (target: a lower-tier local model's window), with correctness coming from the artifacts, not accumulated history.

Proposed phases (to refine when scheduled)

• LC1 — Compaction policy + low-context config mode + work-sizing. A knob (e.g. context.lowContextMode / budget thresholds), a deterministic policy for when to compact and what to keep vs drop, and a refinement-time work-size budget (the ~1k-LOC scoping below).
• LC2 — Artifact-backed context assembly. Rebuild the minimal working context each step from the loop's deterministic artifacts (handoff envelope, checkpoints, gate state) so history can be pruned without losing the thread.
• LC3 — Complete-but-split reviews + intelligent carry + validation + docs. Keep reviews complete under a small budget by splitting into packages (+ extra rounds for cross-area concerns); summarize the must-carry items; validate a representative phase completes within a small budget on a lower-tier local model; document the mode + a worked example.

Acceptance criteria (epic-level)

• A low-context mode exists and is configurable; with it on, the loop compacts at boundaries automatically (not only on overflow).
• Compaction is intelligent: load-bearing state survives; the loop resumes/continues from artifacts after a compaction with no loss of the thread.
• Work units are scoped down for low-tier local execution. Issues/phases are decomposed so a phase's change set ideally stays below ~1k LOC. Refinement flags a phase whose projected change set would exceed that budget and splits it (the waterfall decomposition targets sub-1k-LOC phases), so each unit fits a small-context model's working set — and its complete-but-split review. The ~1k LOC is the target/guardrail, not a hard reject; a justified overage is surfaced, not silently accepted.
• Reviews stay COMPLETE in low-context mode. When context is sparse, the gate fan-out / Copilot review is split into smaller review packages (per-angle, or per-file/section chunks that each fit the budget) and the results recombined — reviews are never truncated, sampled, or skipped to save context.
• Cross-area concerns get their own round. If reviewing a single package would require shifting context to other areas (a cross-cutting dependency that does not fit that package's slice), the loop spawns an additional, focused review round for that concern — assembling the context it needs — rather than evaluating it partially or dropping it.
• A representative phase completes within a small context budget (documented target) suitable for a lower-tier local model.
• Docs + a worked example; no regression to the normal (full-context) mode.

Non-goals

Replacing the model-agnostic work (this builds on it); changing the gate/merge contracts (review completeness is preserved — only the packaging adapts); a hard LOC reject that blocks legitimately-atomic larger changes (it is a scoping guardrail with surfaced overages); committing to a specific model.

Decisions baked in

Post-v0.5; leans on the loop's existing state-externalization as the durable memory; small context demands small work units (sub-1k-LOC scoping) AND complete reviews (split packages + cross-area rounds) — coverage and correctness are never traded for context; refine into LC1–LC3 when scheduled.