Documentation
¶
Overview ¶
Package orientation builds a compact repo digest that a leaf's first prompt carries so orientation costs zero turns: a bounded directory tree, code-file declaration/signature outlines (NOT bodies), test-file names, and — when the run already knows it — the failing-test summary.
The digest is assembled ONCE per run by the linear worker (internal/exec), which calls BuildDigest with the leaf workspace (known before dispatch) and an optional failing-test list. The result is a stable Markdown string cached per workspace path so repeated calls return byte-identical output — this keeps the provider prefix cache intact when the system prompt is rebuilt every turn.
Index ¶
Constants ¶
const MaxBytes = 8000
MaxBytes bounds the rendered digest. A repo that exceeds this degrades gracefully: the directory tree is truncated first, then code outlines are dropped, leaving the top-level tree and the README head. The bound is in bytes (not UTF-16 code units) because the digest is Markdown read by the model, and a model's token count tracks bytes more closely than JS string length. 8000 bytes ≈ 2000 tokens, which is the budget a pi-harness leaf spends on orientation total.
const MaxOutlineFiles = 40
MaxOutlineFiles bounds how many code files get declaration outlines. Files are prioritised by path depth (shallower first) then alphabetically, so a huge repo keeps the outlines for its entry points and drops the leaf files.
const MaxOutlineLinesPerFile = 25
MaxOutlineLinesPerFile bounds the declarations shown for one file. A file with more declarations than this is truncated with a count of the elided ones. 25 lines covers the public surface of most files.
const MaxReadmeBytes = 1500
MaxReadmeBytes bounds the README excerpt shown when the digest degrades.
const MaxTreeEntries = 300
MaxTreeEntries bounds the directory tree listing. Past this the tree stops and a truncation note names how many entries were elided. 300 entries is enough for a mid-size monorepo's top packages without flooding the digest with node_modules-scale noise.
Variables ¶
This section is empty.
Functions ¶
func BuildDigest ¶
BuildDigest returns a bounded Markdown orientation digest for the workspace at root. failingTests, when non-empty, is rendered as a pre-run baseline so the leaf knows which tests were already red. The result is cached per root path + failing-test signature.
func ClearCache ¶
func ClearCache()
ClearCache invalidates cached digests. Tests call this between scenarios.
Types ¶
This section is empty.
Source Files