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.