Just-in-Time Context Injection
An agent does not need every repository document in every prompt. It does need to notice the requirements that matter when it opens a particular file. Just-in-time context is the advisory bridge between those two needs: the supported read path supplies a short pointer to relevant knowledge at the moment of a read.
The pointer tells the reader what to consult. It is not the full policy, proof that the reader
followed it, or permission to modify the file. The shared pre-read.py entry allows the read
and is fail-open. Its advice and the product’s blocking mutation gates are separate mechanisms.
This source-level behavior does not establish that every host exposes every file access through
the same event; confirm the installed adapter and read route when diagnosing an absent pointer.
How a governing document is chosen
Section titled “How a governing document is chosen”The four tiers are an ordered collection, not a first-match-only switch. More than one tier can contribute to the final additional context. The budget determines how much survives.
Security controls come first. The current classifier recognizes whole path tokens such as
auth, middleware and jwt, including its documented separator and camel-case handling. It
points to security-controls.md; it does not parse that document into a complete security map.
A token match is a reminder to consult the controls, not evidence of a vulnerability or complete
coverage of every security-relevant path.
Accepted ADRs come next. The index selects accepted decisions with nonempty governs:
patterns and matches the relative path. Pointers use the full filename stem, avoiding ambiguity
between decisions that happen to share a number. A matching Accepted status is not a claim of
Implemented or Verified lifecycle state.
Specifications follow. Legacy Markdown specs opt in with the recognized approved-status and
**Governs:** fields. Typed HTML specifications use the installed artifact client’s validated
index. Applicable draft, ready and approved specs supply advisory pointers labelled with their
state; rejected and withdrawn specs do not. Matching a file creates no approval or execution authority.
Fresh provenance claims come last. A recorded source path contributes its claim pointer only when a non-null stored hash matches the current hash. Stale or unverifiable claims are suppressed. The helper hashes a provenance path lazily when that path is actually present in the index; an ordinary unmatched legacy read does not make that hash call.
Follow the evidence into a read
A pointer is a selection, not a verdict
Actual Python helper output over fixed local fixtures, not an installed-host run, approval, or validation of your repository.
The fixture uses real Git content hashes and the repository's read/provenance helpers. Choose an already-recorded case; these controls do not run a tool.
Several governing sources match
Fixture read: src/auth/session.py
1. Gather matching pointers
- security-controlsSecurity policy governs this file: use CTX-SECURITY-CONTROLS records in HTML context, or security-controls.md in Markdown context.
- decisionsADR-0042-session-boundary (Session boundary) governs this file — do not contradict it; route changes via /ca:reconcile or /ca:adr.
- specsspec session governs this file — implement to its acceptance criteria.
- Provenance · standardsstandards.md notes (lines 1-2): Session checks are explicit.
2. Assemble the bounded result
99 estimated tokens · 1 provenance hash call
Security policy governs this file: use CTX-SECURITY-CONTROLS records in HTML context, or security-controls.md in Markdown context.
ADR-0042-session-boundary (Session boundary) governs this file — do not contradict it; route changes via /ca:reconcile or /ca:adr.
spec session governs this file — implement to its acceptance criteria.
standards.md notes (lines 1-2): Session checks are explicit.Repeat in the same session: no additional context. The repeated call performs 0 provenance hash calls.
What this establishes: All four tiers contribute. Priority controls assembly order, not a first-match-only decision.
What you do next: Read the named documents. The pointer is not their complete contents or an approval.
The recorded source still matches
Fixture read: package.json
1. Gather matching pointers
- Provenance · standardstech-stack.md notes (lines 1): The package declares module syntax.
2. Assemble the bounded result
17 estimated tokens · 1 provenance hash call
tech-stack.md notes (lines 1): The package declares module syntax.Repeat in the same session: no additional context. The repeated call performs 0 provenance hash calls.
What this establishes: The recorded package bytes match their current hash, so the provenance claim can contribute a pointer.
What you do next: Inspect the actual claim as well as the hash. Matching bytes do not establish that an earlier interpretation was correct.
The source changed
Fixture read: package.json
1. Gather matching pointers
No matching pointer survives the selection and freshness checks in this fixture.
2. Assemble the bounded result
0 estimated tokens · 1 provenance hash call
Observed output: empty string. The helper did not supply additional context.
Repeat in the same session: no additional context. The repeated call performs 1 provenance hash call.
What this establishes: The package changed from module to commonjs. The old claim is suppressed, and drift detection identifies the dependent document.
What you do next: Review the changed behavior and re-scout or defer. Replacing a hash alone would conceal the now-false claim.
Separate drift output: tech-stack → package.json → changed. The mutation was confined to a disposable fixture.
No mapping exists
Fixture read: src/ui/view.py
1. Gather matching pointers
No matching pointer survives the selection and freshness checks in this fixture.
2. Assemble the bounded result
0 estimated tokens · 0 provenance hash calls
Observed output: empty string. The helper did not supply additional context.
Repeat in the same session: no additional context. The repeated call performs 0 provenance hash calls.
What this establishes: No candidate covers this file. The helper emits nothing and makes no provenance hash call.
What you do next: Do not treat silence as a safety verdict. Confirm activation, mapping, and relevant requirements before changing sensitive code.
This recorded example deliberately matches all four tiers. It contradicts the old first-match explanation: the security pointer does not erase the decision, specification and fresh claim when there is room for them. It does not establish that every real read will fit all of its candidates.
Inspect the static relationship map
The budget is a pointer budget
Section titled “The budget is a pointer budget”The assembler’s default budget is 150 estimated tokens, using
ceil(character_count / 4) as a proxy. It is not a count from the active model’s tokenizer and
not a cap on the entire conversation, retrieved file or total operation cost.
Pointers are considered in tier order. Whole pointers fit where possible; an oversized result is bounded and marked with an ellipsis. If the first pointer alone is too large, a shortened part of that pointer survives rather than a bare ellipsis. Lower-priority omissions are not evidence that those requirements ceased to apply. Open the linked governing records before a relevant change.
Loading an artifact include, a role charter or the full specification is separate on-demand work. Do not confuse the small advisory pointer with a promise that the complete workflow uses only 150 tokens. Role separation explains why the caller must still supply the relevant inputs to an author or reviewer.
What you should expect
Section titled “What you should expect”A supported read inside an enabled repository can receive additional context naming one or more
governing records. Reading .codearbiter/ itself is excluded from this self-injection path, and
an outside-repository path exits before the mapping. A read with no applicable pointer is silent.
The hook never blocks a read merely because it could not assemble advice.
For legacy work, deduplication is per session and relative file. A second read may therefore emit nothing even though the first supplied useful context. It is not a continuous refresh of every legacy decision and claim during a session. A fresh session is the useful control when repeating a mapping observation after edits.
Where HTML specifications exist, the helper builds a validated snapshot before deduplication and includes its artifact identity in the deduplication epoch. Changed revision, model or normative identity can make advice eligible again in the same session. The same snapshot drives both the pointer and its deduplication key, avoiding mismatched reads. This is advisory identity, not a new approval ledger or a promise of zero work on every repeat.
The index and dedup markers are local support state. Their presence proves neither that an agent understood the text nor that a particular task was verified. Do not delete them as a routine workaround for an unexplained result.
When HTML advice reports a problem
Section titled “When HTML advice reports a problem”The source distinguishes an unavailable installed capability from an invalid or unreadable HTML artifact. It can append a bounded diagnostic that names the condition and its repair direction. A diagnostic is not a spec pointer. Source inspection and independent authorized work may continue. Resolve the reported condition before relying on the affected artifact or performing a mutation that requires the unavailable capability.
Use artifact review to identify the installed capability and Resume and recover for stale bindings or uncertain transactions. Do not replace an HTML pair with Markdown, edit receipts, or select an arbitrary repository binary because a read hook permits inspection. The mutation workflow’s stricter checks remain in force.
Practice: predict one injection
Section titled “Practice: predict one injection”Choose a file and enumerate its applicable mappings before reading it: the security path tokens, accepted ADR patterns, applicable specification mapping, and any fresh provenance entries. Predict an ordered candidate set, not one winner. Inspect which claims are actually recorded and whether their hashes can be checked.
Start a fresh supported host session in the intended checkout and ask it to read that exact file. Compare the observed advice with the mapping. Then open the governing documents and identify the behavior that would constrain a change. A second read helps distinguish deduplication from a missing mapping; preserve the first result rather than treating the second silence as a failure.
If the pointer is absent or unexpected, check repository activation, host event support, the path spelling, ADR status, specification format/authority, provenance freshness and prior reads. Treat unreadable records and missing capability as explicit uncertainty. A manual source inspection and doctor can establish different parts of the diagnosis; neither should be presented as proof of an event it did not observe.
Where it fits
Section titled “Where it fits”Repository context is created during initialization, maintained through provenance and reviewed changes, and loaded where a workflow or read needs it. Read advice sits alongside that process, not above its authority. The hooks reference, Provenance and context drift, and Enforcement & Security connect the advisory selection to maintenance and blocking controls. A small pointer can make a rule visible; only the applicable evidence can establish that the work satisfied it.