ADR-022: Deterministic Context Capsules

• Status: Accepted
• Date: 2026-08-18
• Owners: Project governance
• Scope: Agent preload context and read-only continuation verification

Context

Execution packets already bind objective, scope, dependency and contract state, but required_reads previously named whole files without a machine-enforced preload budget. Loading full roadmap and orchestration documents wastes context; passing chat history makes continuation non-reproducible. Letting an AI summarize the authority sources would make the preload itself nondeterministic.

Decision

scripts/governance/context_capsule.rb builds a capsule from the packet at the current Git HEAD. It always includes the exact packet and packet context.md, then resolves at most eight explicit required_reads entries. A plain locator includes a complete file. A path#heading-slug locator includes that Markdown heading and its complete subtree up to the next heading of equal or higher rank.

Every source must be a regular, non-symlink repository file whose bytes match the same path at HEAD. The capsule records the source commit, whole-source hash, selected-content hash and exact selected text. Missing, ambiguous or unsafe selectors fail closed. AI does not select, rewrite or summarize source text.

The policy is closed in code and configuration:

• default target: 12,000 estimated tokens;
• hard limit: 16,000 estimated tokens;
• working reserve: 1,500 estimated tokens;
• maximum must-read artifacts: 8;
• estimator: UTF-8 bytes divided by three, rounded upward.

The estimator is deterministic and model-independent, not an exact billing-token claim. It measures the complete canonical JSON transport, including escaping, question, hashes and provenance metadata. The explicit reserve absorbs tokenizer and working-context variance. Both the packet target and hard limit are checked before any capsule is emitted.

Continuation proof uses exactly two fresh agents in separate empty, read-only workspaces. Each receives only the same capsule and returns the strict result schema. The verifier requires distinct claimed identities, prior_context: false, exact capsule hash binding and the same continue or blocked decision. These claims are untrusted evidence metadata: verifier output is explicitly scoped to semantic agreement, marks execution as unattested and grants no authority. The verifier does not establish workspace mode, session identity or context freshness. Those operational claims require separately retained invocation evidence; without it they remain explicitly lead-reported metadata.

Historical replay reads source text and the capsule policy from the declared commit. The current trusted implementation replays the declared schema version; future implementations must retain the v1 parser or provide an explicit versioned migration. Historical candidate code is never executed during verification.

Consequences

• A specialist can recover exact authority without inheriting a long chat.
• Capsule drift and stale source bytes are detectable by commit and content hash.
• JSON transport overhead is included in the enforced preload estimate.
• Large source documents require explicit stable heading selection or packet split.
• Historical packet records remain valid; selector syntax is opt-in for new work.
• F1-033 can verify a bounded continuation artifact before enabling write agents.

Rejected Alternatives

Full conversation handoff

It is large, non-canonical and unavailable to a genuinely fresh agent.

AI-generated source summaries

They save space but can omit authority, change between runs and cannot reproduce the exact source wording.

Reviewer command replay

It duplicates deterministic evidence. Independent agents are used here only because continuation comprehension is the behavior under test.

Revisit Conditions

• The repository adopts one pinned tokenizer available offline on every supported platform.
• Markdown heading identity changes to a stable explicit anchor contract.
• Capsules need non-text or externally hosted authoritative artifacts.