Evidence And Assumptions
What you'll learn
- The split Craik enforces between evidence (citable) and assumptions (unresolved claims).
- The shape of an evidence reference, and what the local assembler produces for every case file.
- The current assumption-ledger entries the runtime emits and what they mean.
- The honesty rules for promoting an assumption to a fact.
Two different objects, on purpose
Evidence is source material the runtime can cite. Assumptions are unresolved claims that should not be treated as facts yet. Conflating the two is how an agent runtime starts hallucinating policy.
Evidence references
Every piece of context the local case assembler loads becomes an
evidence_reference in the resulting case file. The local assembler
emits one for:
The task request
The original user request and the runtime's accepted interpretation.
The project profile
The registered project with its docs paths, immutable paths, and validation commands.
Repository status
Branch, head, clean/dirty, default branch, remote identity.
Discovered documentation
Mutable doc roots loaded into the case file as context.
Discovered immutable documentation
ADRs and other declared evidence paths — loaded as evidence, never as edit targets.
Each evidence reference carries:
doc · immutable_doc · repo_state · memory_fact · handoff · github_issue · github_pr · ...immutable: true for ADRs, indexed_at for staleness.The assumption ledger
When expected context is unavailable, the local assembler records an assumption rather than fabricating evidence. Today's runtime emits assumptions in these shapes:
"Memory facts were not loaded"
The project has no memory backend configured (or the backend was unreachable). Connect Stigmem or set CRAIK_MEMORY_BACKEND.
"GitHub state was not loaded"
The GitHub adapter was disabled, unconfigured, unauthenticated, or rate-limited. Issues and PRs are not part of this case file.
"No mutable documentation files were discovered"
The project has no docs paths declared, or every declared path was excluded by discovery. Likely a registration problem.
"Some documentation was omitted by the context budget"
Context budgeting trimmed candidate docs to keep the prompt deterministic. context_budget.docs_excluded names what got cut.
The list grows as the runtime grows. The schema doesn't.
The honesty rule
Agents must not promote assumptions to memory or documentation claims unless later evidence supports them. This is the single most important rule in the whole runtime — break it, and downstream case files start inheriting unverifiable facts.
The promotion path is concrete:
Find evidence. Locate a file, issue, PR, or upstream fact that supports the assumption.
Attach the evidence reference. When proposing memory or writing a handoff, cite the new evidence directly.
Note the promotion in the handoff. Record that the assumption was promoted, with the evidence id.
Refute or carry forward when you can't. If the evidence didn't materialize, the assumption stays open. That's fine — that's what "open assumption" means.
Immutable documentation as evidence
Immutable docs — ADRs especially — are first-class evidence. Case files
label them separately in adrs (or immutable_docs) and mark their
evidence reference with metadata.immutable = true:
{
"source": "docs/adr/0004-policy-envelope-shape.md",
"kind": "immutable_doc",
"locator": "docs/adr/0004-policy-envelope-shape.md",
"summary": "Policy envelope shape ADR — defines runtime contract.",
"metadata": {
"immutable": true,
"indexed_at": "2026-05-19T12:14:08Z"
}
}
The immutable flag prevents downstream code from accidentally treating
the ADR as a mutable doc and proposing an edit.