Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)

core/rules/compact.md

@@ -0,0 +1,112 @@
+> 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.