session-flow: decide plugin-wide whether skills consume the context-guard zone seam (recovered from closed #1571)

[kyle-sexton]

Why this exists

Recovering a deferral that lost its tracker. #1571 was closed as COMPLETED while still carrying an unchecked box:

• Deferred: presence-gated context-guard / rate-limit-guard read. session-flow/orchestrate: plugin-quality audit — decision criteria, defaults, handoff-relay convention #1479 scoped this assess-only. Also worth noting the audit's blindspot: there are zero context-guard references anywhere under plugins/session-flow/, so handoff, keep-going, and running-retro likely share this decision and it should be made once, plugin-wide.

#1479 is also CLOSED. So as of now the decision has no open tracker, and grep -rl context-guard plugins/session-flow/ still returns nothing. This issue is that tracker — it is not new scope.

The gap

context-guard publishes a per-session context-window snapshot at ~/.claude/context-guard/context/<session_id>.json and ships context-zone.sh to reduce it to one word (smart / acceptable / dumb / unknown). It is observability-only by design — its reader contract says consumers decide what to do — and no session-flow skill is a consumer.

That is backwards relative to need: session-flow's skills are precisely the ones whose correctness depends on knowing how degraded the current context is. handoff decides whether it is time to check point, orchestrate decides how much to fan out, keep-going and running-retro both re-enter long sessions. All four currently make that call without reading the one seam that answers it.

Motivating evidence from a live session (2026-07-26)

While orchestrating a multi-lane run, the main session reported its own context usage as "around 40%" to the operator. The operator corrected it: the real figure was 15%.

The session had no measurement — it estimated from a vague sense of elapsed work and stated the guess as fact. Meanwhile context-guard was installed, enabled, and had written a fresh snapshot roughly four minutes earlier:

{"used_percentage":15,"remaining_percentage":85,
 "context_window":{"context_window_size":1000000,"total_input_tokens":150032}}

context-zone.sh <session_id> returned smart. One cat would have produced the correct number.

This is the failure mode the wiring prevents, and it is worth being precise about the shape: the harm was not that the session ran out of room. It was that the session volunteered a fabricated measurement into a decision the operator was relying on — the handoff threshold. A guessed context percentage is worse than no percentage, because it looks like an instrument reading.

Scope — one decision, made once

Per #1571's note, do not solve this in orchestrate alone. At minimum handoff, orchestrate, keep-going, and running-retro share it. Decide plugin-wide:

• Which skills read the seam, and at what point in their flow.
• Presence-gating and fail-open. The snapshot may be absent (setup never ran), stale, or unknown. Per the reader contract there is a 10-minute staleness rule and fail-open capability detection. A skill must degrade to today's behavior, never block or guess.
• What a skill does with a zone, which is the substantive half. handoff has an obvious use (recommend checkpointing on entering a worse zone). orchestrate's is less obvious and must not contradict its own contract — see the constraint below.
• Whether rate-limit-guard's signal rides along, since it publishes to a sibling path and the two tees are already chained in the statusline slot on at least one machine.

Hard constraint carried over from #1571

orchestrate's export brief is "model- and tool-agnostic by construction", so a context-guard read cannot go into the seven imperatives or the export rails without breaking that contract. The skill's existing lane for a machine-specific read is the priming addendum, which export modes already omit for exactly this reason. Any design must respect that split, and the equivalent question needs answering for each other skill rather than assumed.

Relationship to #1475

#1475 ("context-guard: zone-crossing hooks") is the producer side — making context-guard push guidance via hooks. This issue is the consumer side — session-flow skills pulling the existing seam. They are complementary, and the ordering is a genuine open question worth settling early: if #1475 ships zone-crossing injection, some of what a skill would otherwise inline may become unnecessary. Note #1475 is needs-human and work-class: structural, so it may sit for a while; that argues for the pull side not blocking on it.

Acceptance criteria

• A single recorded decision covering all four skills — not a per-skill improvisation
• Presence-gating, staleness, and unknown handling specified; absent seam degrades to current behavior with no new failure mode
• orchestrate's agnostic-export contract demonstrably preserved (machine-specific reads confined to the priming addendum)
• The relationship to context-guard: zone-crossing hooks (advisory/enforcing) + window-class token bands #1475 recorded, so the two do not implement overlapping behavior
• No skill states a context figure it did not read from the seam

Unverified

• Whether a subagent can reach the parent session's snapshot (session-id resolution across the boundary) is untested here; context-guard: research non-interactive observability (headless + subagent context usage) #1478 owns the non-interactive/subagent observability survey.
• The 15%-vs-guess episode is one occurrence on one machine. It demonstrates the failure is reachable, not how often it occurs.

[kyle-sexton]

This was generated by AI during triage.

Triage: briefed → human-gated.

Verification note: the recovery premise checks out. #1571 is closed carrying this as an unchecked
deferred box, #1479 (which scoped it assess-only) is closed too, and the audit's stated blindspot
still holds — a search across the session-flow plugin returns no context-guard reference at all,
so none of its skills consumes the seam today. The motivating episode is recorded as one occurrence on
one machine and is presented that way in the body; it demonstrates the failure mode is reachable, not
its frequency. Nothing here needs reproducing before the decision.

Why a human must act — genuinely open design space, decided once for a whole plugin. This is not a
single-fork item with a vetoable default:

• It spans at least four skills whose flows differ (handoff, orchestrate, keep-going,
  running-retro), and the body's own scope rule is that it must not be solved in one of them alone.
• The substantive half — what a skill does with a zone — is open design, not a lookup. handoff has
  an obvious use; orchestrate's is explicitly less obvious and is constrained by that skill's own
  model- and tool-agnostic export contract, which a machine-specific read would break unless it is
  confined to the priming addendum that export modes omit.
• Ordering against the producer-side counterpart (context-guard: zone-crossing hooks (advisory/enforcing) + window-class token bands #1475, itself human-gated and structural) is called
  out as a genuine open question, since zone-crossing injection could make some pull-side work
  unnecessary.

That is cross-cutting contract design across a plugin's public surface — the human-gated exit. Parked
for a maintainer decision rather than queued as a worker question.

Brief

Type: Task
Summary: Decide once, plugin-wide, whether and how session-flow skills consume the context-guard
zone seam — which skills read it, at what point, with what presence-gating and staleness handling, and
what each does with the result.

Current behavior:
The context-guard capability publishes a per-session context-window snapshot and ships a reducer that
collapses it to a single zone word. It is observability-only by design; its reader contract leaves the
response to consumers. No session-flow skill is a consumer. Skills whose correctness depends on how
degraded the current context is therefore make that call without reading the one seam that answers it,
and a session can state a context figure it never measured.

Desired behavior:
A single recorded decision covering every affected skill, specifying for each: whether it reads the
seam, where in its flow, and what it does with each zone value — including the absent, stale, and
unknown cases, which must degrade to today's behavior and never block or guess. The decision records
its relationship to the producer-side zone-crossing work so the two do not implement overlapping
behavior.

Hard constraint (carried from #1571): orchestrate's export brief is model- and tool-agnostic by
construction, so a machine-specific seam read cannot enter its imperatives or export rails. Its
existing lane for such a read is the priming addendum, which export modes already omit. Any design
must respect that split, and the equivalent question must be answered per skill rather than assumed
from orchestrate's answer.

Acceptance criteria (from the item, preserved):

• A single recorded decision covering all four skills — not a per-skill improvisation.
• Presence-gating, staleness, and unknown handling specified; an absent seam degrades to current
  behavior with no new failure mode.
• orchestrate's agnostic-export contract demonstrably preserved — machine-specific reads confined
  to the priming addendum.
• The relationship to the producer-side zone-crossing work recorded.
• No skill states a context figure it did not read from the seam.
• A decision on whether the sibling rate-limit signal rides along.

Out of scope:

• Implementing the producer side (zone-crossing hooks) — that is the complementary item, and this one
  should not block on it.
• Resolving whether a subagent can reach the parent session's snapshot; the non-interactive/subagent
  observability survey owns that and it is recorded here as unverified.
• Making any skill hard-depend on the seam being present.

[kyle-sexton]

This was generated by AI (decide lane, operator-authorized frontier decision pass — human gates decided, not skips).

Decide brief — plugin-wide decision: consume the seam, presence-gated

Decision: session-flow skills whose behavior depends on window degradation consume the context-guard zone seam, presence-gated, per the reader contract. Implementation: #2514 (carries Fixes #1602).

Why consume rather than stay observability-only on the consumer side: the motivating episode is dispositive — the instrument had a fresh snapshot (15%, smart) four minutes old while the session asserted "around 40%" as fact. Skills that decide whether to checkpoint (handoff), which continuation mechanism (workflow router), whether to keep working here (keep-going), how degraded the session is (running-retro), and how much to fan out (orchestrate) are exactly the seam's designed readers; leaving them guessing contradicts the seam's purpose.

The pattern is the one already ratified on main: handoff and the workflow continuation router (landed since this issue was filed) established it — resolve per the reader contract, consume only the zone word, inline no band values, treat absent/unknown as degraded, honor the evidence-degraded marker. #2514 extends the identical discipline to the three remaining named skills, closing the plugin-wide question this issue was recovered to track. orient and reconcile stay non-consumers deliberately: they are state hygiene reads, not degradation-sensitive decisions.