ADR 0058: Use Context Spines And Revision-Bound Task Handoffs

Status

Accepted.

Context

STAGE already separates canonical project sources, active work, evidence, and human authority. It did not explicitly define how work should cross Codex task boundaries or how a fresh agent proves that it recovered the right project state.

The triggering case was the original The Circussy One task. By 2026-07-28 its local rollout had reached approximately 34 GB, 327,100 recorded events, and 1,674 user messages across nearly two months. It contained gameplay design, Unity implementation, debugging, documentation, STAGE creation, research, and unrelated follow-on projects. Automatic compaction kept the task operable, but the transcript became slow, unavailable on some clients, difficult to distinguish from current project truth, and unsuitable as shared multi-agent context. Its configured working folder also no longer matched either primary repository being discussed.

OpenAI guidance recommends a project for continuing work, separate chats for distinct outcomes, and short AGENTS.md files that point into versioned repository documentation. Research on long-context use reports degradation as irrelevant input grows and weaker use of information buried within long sequences. A transcript can therefore preserve history while still being a poor operating memory.

Decision

1. Treat conversation history and model memory as disposable working context, not canonical project state.
2. Define a Project Context Spine as the smallest versioned source chain a fresh agent follows: AGENTS.md, an optional project map, a documentation index, canonical detail, and the active work item.
3. Use one Codex local project per repository, rooted at that repository's Git root. Attach secondary repositories only for explicit cross-repository outcomes.
4. Start a new task for a distinct outcome, repository, independent parallel lane, or materially polluted context. Continue the same task only while one coherent outcome remains active.
5. Use a Task Handoff only for unfinished coherent work crossing a task boundary. It records repository coordinates, protected state, human decisions, evidence, failures, and the exact next action without duplicating durable project knowledge.
6. Treat every handoff as revision-bound. Source state and the newest explicit human direction outrank a stale handoff.
7. Require an Orientation Check before trusting a migrated task: verify repository coordinates, authority, protected state, current outcome, next action, and gates before mutation.
8. Repair failed orientation in the canonical source that should have supplied the fact, then retry from fresh context.

The detailed procedure lives in Task Continuity And Context Recovery. This is practitioner guidance and does not add a mandatory artifact to SPEC.md.

Consequences

• A new task can recover project direction without replaying the project transcript.
• Unfinished work can move safely while keeping handoffs small and disposable.
• Correct Git roots make AGENTS.md discovery and source-control inspection reliable.
• Multi-agent prompts can carry bounded context instead of inherited chat history.
• Durable decisions require intentional maintenance in project sources.
• A handoff can still become stale; the receiver must reconcile it.
• Some repetition moves from automatic chat recall to an explicit orientation check.
• Projects do not gain another database, daemon, or mandatory STAGE artifact.

Rejected Alternatives

• Keep one chat for the whole game: preserves chronology but mixes superseded intent, unrelated outcomes, and transient logs until context and clients fail.
• Paste a full transcript into every new task: maximizes input while preserving the retrieval and contradiction problem.
• Use /handoff as the project archive: a task bridge cannot replace versioned architecture, vocabulary, ownership, or source state.
• Rely on model memory: useful recall has a separate lifecycle and cannot safely own mandatory project rules.
• Create one mega-project for every repository: weakens root-specific configuration and makes unrelated state available by default.
• Build a retrieval database immediately: adds synchronization and ownership cost before repository-native navigation has been tested.
• Use a fixed token or message threshold: clients, models, task shapes, and evidence density vary; observable context pressure is the safer trigger.

Evidence Boundary

Repository-native documentation, task isolation, versioned source, concise agent instructions, structured handoffs, and context compaction are established components. Long-context research supports the risk of context degradation. The exact Context Spine, boundary rules, and Orientation Check are a STAGE workflow proposal derived from the owner's projects. The protocol must be judged by fresh-task recovery in real work; it is not an empirical guarantee that every agent will recover every implicit decision.