Module expert 

L2 of the expertise ladder: a version-keyed expert index of another repo (PLAN.md, “Expertise and the queen”).

borg debug expert <repo> --at <commit> [--version <v>] --q "<text>" answers with at most 3 cited claims from the expert repo as it was at <commit>: every file is read through git ls-tree and git show <commit>:<path>, never the working tree, so nothing written later can leak in. Git runs with the caller’s GIT_DIR / GIT_WORK_TREE / index / object overrides removed and with replace refs disabled, at the repo’s top level. A ceiling (BORG_EXPERT_CEILING, set by the eval to the expert commit) makes --at a hex hash that must be an ancestor of the ceiling.

Sources, parsed deterministically (0 tokens):

• spec requirements: headings #### CORE-073: Title in spec/**.md / specs/**.md, with their text;
• release notes: CHANGELOG.md (or CHANGES / HISTORY / RELEASES) at the root, one claim per change;
• proof coverage: any *proof-coverage.json (theorems[].{name, module, specIds[].{id, fragment}});
• docs: every heading of every tracked README.md and docs/**.md, with its first paragraph.

Retrieval is BM25 over the claim text (the conscience’s tokeniser). With --version:

• a claim that states “since vX” / “until vY” is kept only if the pinned version lies in that range;
• a requirement, or a theorem proving one, whose id the changelog first cites in a release newer than the pin (or only in an unreleased section) is dropped: it did not exist for the consumer;
• releases newer than the pinned one are surfaced as “newer release vY: ”: one slot of the three is kept for the best-matching newer change, or, if none matches, for a line saying that newer releases exist.

A version is 9.0.0, v9, or labelled, java 9.0.0 / rust@11. An unlabelled pin takes the changelog’s only line; when the changelog names several lines (flowlib: Java, TypeScript, Rust, Python) the label is required. Sections headed “unreleased”, or undated above dated releases, are printed as “unreleased (in progress at )”, never as a newer release.

Structs

Answer

The answer: the repo’s name, the commit’s short hash, and the chosen claims, best first.

Api

Identifiers a repo declares: types (class PetriNet, struct Marking, interface TokenSink) and members (fn fire_transition, def deadlock_free, public boolean deadlockFree().

Claim

One citable statement of the expert repo.

Indexed

The expert repo indexed once at a commit, for a consumer pinned at a version: ask it any number of questions, or read its API vocabulary first (see plan_query).

Pin

The version the consumer pins, optionally labelled with the artifact line (java, rust).

Ver

A version as numbers, compared with missing parts as 0 (10 == 10.0.0).

Enums

Kind

Constants

CEILING_ENV

Environment variable naming the newest commit --at may resolve to.

MAX_CLAIMS

At most this many claims are printed. Baseline: the expert section’s fixed size (no eval chose it), about 200 tokens with CLAIM_CHARS.

Functions

ask

Ask the expert repo at at (any commit-ish), for a consumer pinned at version. With a ceiling, at must be a hex hash naming the ceiling or one of its ancestors.

index

All claims of the repo at commit. The pin is resolved once against the changelog (its line made explicit) and then used everywhere: release claims carry newer relative to it; spec, doc and proof claims whose stated range excludes it, or whose requirement arrived later, are dropped.

main

borg debug expert <repo> --at <commit> [--version <v>] [--q <text>] (the question on stdin without --q).

plan_query

What to ask the expert about a plan: the plan’s sentences that mention the dependency, by one of names (case-insensitive, whole words; org.flowlib also matches org.flowlib:flowlib) or by its api (case-sensitive; see Api::used_in). The query is those sentences plus the names, never the whole plan: a long plan otherwise drowns the dependency in unrelated words (E1). None when no sentence mentions it: the plan does not touch the dependency, so nothing is asked.