Skip to main content
A spec split across files works when the source is a local file or a git:<ref>:<path> reference. The policy is the same wherever pikopod reads a spec: import, spec-diff and the spec_source watcher.

​
The policy

​
Bounds

Resolution is bounded: at most 64 files and 32 MiB across them. Cycles across files are refused.

​
Refusals

A refused $ref is a typed error naming the pointer, with the code SPEC_REF_UNRESOLVABLE, and exit 2. It is a tool outcome, never reported as drift.

​
Git refs in CI containers

Where the checkout is owned by another user, git refuses to read it and pikopod says so:
Add that line before the gate step. See CI integration.

​
Positions across files

A finding that lands in a referenced file carries that file’s path and line in --format githubactions, so the annotation appears on the file that actually changed. Where a change has no exact position, the nearest enclosing node is used, never the document root.