octopus-workflow/core/rules/compact.md

Core 中立版（Increment 2 改写）。术语对照见 core/adapters/TERMINOLOGY.md；本组织实例表述见 dogfood 对应文件。

Compaction Discipline (mandatory)

Context compaction keeps long pipelines inside the model's context window. Two mechanisms exist:

1. Stage-boundary compaction (main session / orchestrator) — capacity-driven [org-internal #2601]: compact at a clean stage boundary ONLY when a capacity trigger holds (below), not merely because the boundary was reached.
2. Round-boundary compaction (multi-round reviews) — compact at every review round ≥ 2, after the round's state is persisted.

Stage-boundary compaction (capacity-driven, [org-internal #2601])

The main session orchestrates the whole pipeline while delegating stages to subagents, but still accumulates their result summaries, planning reasoning, and todo state — over a full pipeline this can exhaust the context window.

Rule — compact at clean boundaries only when capacity demands it. Every stage persists its complete output to durable artifacts (Tier-2 artifact pages under {slug}/…, Tier-1 run workspace files) on completion. At each CLEAN boundary (artifacts written, next stage not yet dispatched), evaluate the triggers:

1. Capacity trigger — the harness's compaction recommendation has fired, context is near the threshold, or the agent observes context-pressure symptoms (truncation, degraded recall of earlier stage outputs).
2. Projection trigger — the stages REMAINING on this route (skip list in the routing table) will not fit alongside the context already accumulated, based on per-stage growth observed so far.

A trigger holding → compact at the NEAREST clean boundary. No trigger → KEEP the context: preserved working context is worth more than the tokens it costs.

Mixed capacity threshold — min(water_level, absolute cap) [org-internal #3321] / TD-434]: the capacity threshold is min(context × water_level, compaction.max_context_tokens) — whichever is LOWER (max_context_tokens default 100_000; 0 restores pure water_level semantics [org-internal #3342]). On large windows the 100k cap binds first. Measurement basis: the provider's REAL reported usage (input tokens), not local estimates; the rendered guidance and the Trigger A/B overflow paths resolve the same normalized values (harness 内建的压缩引导模块, see the instance term mapping).

Sub-session posture [org-internal #3321]: Explorers compact by returning promptly, persisting only what their skill protocol REQUIRES (review findings JSON to the run workspace reviews directory). Workers persist outputs to Tier 1 BEFORE finishing. The parent context is where the mixed threshold applies. Tier 1 boundary: two-tier-artifacts rule.

Short runs target zero intra-run compaction — an implement → review-code → verify run fits one window; clean boundaries do not compact without a trigger. (Rationale + retired legacy stages: Tier-2 reference page rules/compact-detail, reachable via the ticket backend.)

Clean boundaries where triggers are evaluated (live skills):

• After analyze-dag completes (before the review-dag single gate)
• After each review-* converges (before the next production stage)
• After implement / verify completes (before its review or the next stage)

Never compact mid-stage — not mid tool-call cycle, not mid subagent dispatch. Compact only at clean boundaries where artifacts are already persisted.

Re-orient after compacting (recovery contract): compaction discards the in-conversation record of the current slug and stage. Before resuming, re-read the persisted recovery set — the Tier 1 compact-recovery entry index.json in the run workspace, the issue's ## 工件索引 CORE rows, the frozen DAG copy ({epic-slug}/dag, {epic-slug}/dag-nodes/{node-id}) for DAG-routed runs, the latest review pages, or the DoD matrix ({slug}/05-verify-*) — to recover the current slug, stage, and outstanding items. Do not rely on the compacted summary alone.

Identity verification precedes re-orientation [org-internal #2459]. Every compacted summary opens with a harness-injected ### Session Identity card (agent, role/mode/ticket, CORE artifact rows, role re-read set), rendered from role-yaml compact.preserve lists and issue CORE rows by the harness 内建的压缩引导模块 (renderIdentityInjection; preserve lines keyed through identityPreserveLines). Role yaml preserve lists are harness-enforced — recovery is always via the persisted artifact, never conversation memory. Verify the card against the durable record (title/purpose, issue assignee + claim, orchestrator id); on mismatch stand by and report, never act on the summary's identity claims.

Round-boundary compaction

Multi-round review skills (review-artifact, review-code) compact at every round boundary ≥ 2. Canonical text: shared compaction-round-boundary doc (injected by both review skills); read it for the exact orchestrator procedure — do not restate.

The min_turns_since_compaction guard applies everywhere

The compact tool rejects calls made too soon after the previous one (compaction.agent.min_turns_since_compaction, default 3 assistant turns); no boundary type is exempt. Beyond insufficient_turns the tool has more guard outcomes (min_interval, no_model, circuit_breaker_open, disabled — rejected; compaction_in_progress, deduplicated — deferred; full table: Tier-2 reference page rules/compact-detail, reachable via the ticket backend). All are accept-and-continue: never retry past a guard, never work around the dedup/breaker state. A boundary whose compaction was rejected or deferred simply keeps its context; the persisted artifacts still bound what accumulates.

Role-level re-read set

Role YAML compact.preserve lists are harness-enforced: after any compaction the session agent's preserve lines are injected at the summary head; recovery is always via the persisted artifact, never conversation memory.