Concepts

Concepts

The problem

Several coding agents working on one repository with git hit two walls. Each new session spends tokens re-orienting: reading the tree and rediscovering what was tried, decided and rejected. And a handoff or pull request shows what changed, never why. Git keeps snapshots and throws away intent, decisions and dead ends, so every agent re-derives them.

Scholion stores the why next to the code and hands any agent a deterministic, token-budgeted context pack built from it.

Building blocks

• Task: one unit of agent work, replacing branch + pull request. Each task gets its own jj workspace on disk (~/ws/<repo>/<task>/), branched from trunk. The agent edits files there with its usual tools; av checkpoint snapshots them.
• Record: a short, typed note attached to a task: intent (the goal), decision, attempt (a dead end and why), note, handoff, review. Summaries are at most 200 characters. Records are append-only: a newer record supersedes an older one instead of editing it.
• Anchor: a record's link to code, as a path or path:Symbol. Records resurface whenever a later task touches that code. The anchored code's hash is stored with the record, so a pack marks a claim (changed since recorded) once that code has moved on.
• Convention: a repo rule scoped by path glob (src/api/**), shown only to tasks touching matching files. A required convention is always included, whatever the budget.
• Context pack: Markdown with the sections Task, Map, Decisions & dead ends, Code, Conventions, Live work, built for one task within a token budget (800 tokens by default).
• Session ledger: remembers what each agent session was already sent, so later packs refer back instead of resending. A session with no id gets no deduplication.
• Receipt: every pack is stored as a manifest (rcp:<8 hex>): what was sent, at what tier and why. A record can cite the receipt its author worked from.

How a context pack is built

No LLM is involved, and the same state always gives the same pack.

1. Seeds: the goal, changed files and symbols, an optional focus.
2. Candidates: reference-graph neighbours, records anchored up to two hops away, semantic hits, other tasks touching the same files.
3. Scoring: lexical (BM25) and semantic hits are combined by reciprocal rank fusion.
4. Budget: per-section shares (map 10 % · task 10 % · history 20 % · code 50 % · conventions + live work 10 %); unused share spills over.
5. Tiers: each item is shown at the richest tier that fits (handle → summary → full). av expand <id> pulls the rest.

Code items carry path, lines and signature, not bodies: agents such as Claude Code re-read a file before editing it, so a body in the pack would be paid for twice.

Task lifecycle

From	Event	To
open	submit	in_review
open	handoff	handed_off
handed_off	claim	open
in_review	request changes	open
in_review	approve	in_review (verdict recorded; merge needs it)
in_review	merge	merged, or conflicted on a conflict
conflicted	resolve	open
merged	undo	in_review
open, handed_off, in_review, conflicted	abandon	abandoned (final)

Any other transition is refused with HTTP 422. submit is refused unless the task has changes, and both submit and handoff need at least one decision, attempt, note or handoff record. The refusal lists changed symbols that no record covers.

Handoffs and claims

A handoff stores what is done, remaining, broken and still open, and returns a handoff bundle (goal, state, records with decisions and dead ends first, changes, open questions) within a token budget. claim makes another agent the owner. It also works on an open task whose owner stopped writing for AV_LEASE_SECS (default 30 minutes).

Every claim increments the task's generation. A write sent under an older generation is refused with "claim lost", so a previous owner can never overwrite the new one. Writes under the current generation renew the lease.

Approvals that survive a rebase

An approval carries over a rebase when the task's own patch is unchanged, or when the only overlap is in files matching carry_globs (Markdown by default). When in doubt it fails closed and asks for a fresh review.

Invariants

• Postgres is the source of truth. Qdrant is derived and can always be rebuilt (av reindex).
• main advances only through merge (or revert, which adds a commit); agents never write trunk directly.
• Packs are deterministic, independent of the database's locale.
• If semantic search is down, packs still return and carry degraded: semantic.
• The daemon never runs repository commands. Validations and checks are attestations reported by clients.