The Linux Foundation Agentic AI Foundation pinned AGENTS.md as the
agentic-context discovery convention in December 2025; 60k+ repos
now ship it; Codex / Cursor / Copilot / Gemini-CLI / Aider /
Windsurf / Zed read it natively. This crate is JouleClaw's
ingest of the convention.
Plus energy-as-the-orthogonal-trust-anchor (the directive driving
this whole round): discovery is IO, IO costs energy, and the
field has been silent about that cost. Every `AgentsManifest`
carries `bytes_read` and `joules_uj`; the aggregate
`DiscoveryReport` carries the rollup and tags it with the
appropriate `Provenance::Estimator` honesty tier so the receipt
layer downstream sees the floor.
The estimator: `JOULES_PER_BYTE_PJ = 1_000` (= 1 nJ/byte
empirical SSD floor) + `PER_FILE_SETUP_UJ = 10` per file
(syscall + dentry). 4 KB file = ~14 µJ. A 10k-repo crawl
produces a measurable budget.
Surface:
- `AgentsDiscoveryOptions { names, stop_at_repo_root, max_files }`
with `Default` = `["AGENTS.md", "CLAUDE.md"]`, stop at `.git/`,
cap 32.
- `discover(start, opts) -> DiscoveryReport` walks `start` → root
collecting matches; `truncated` flagged when `max_files` hit.
- `find_repo_root(start)` for the boundary search alone.
- `merge(manifests)` concatenates least-specific-first with HTML-
comment scope hints, the Codex / Cursor override convention.
Honest scope (v1): discovery convention only; no schema, no
required sections, no symlink follow (kept the walk's cost
bounded), no persistence, no semantic dedup.
Kani harnesses (`#[cfg(kani)]`): joule arithmetic never overflows
under any `bytes_read` (saturating); empty file costs
`PER_FILE_SETUP_UJ`; joule cost monotone in bytes.
12 tests cover: estimator boundary + monotonicity; discover in
start dir + walks to git marker; collects both file names in
priority order; max_files truncation; missing files silently
skipped; merge reverses walk order; merge includes scope hints;
total joules sums per file; find_repo_root locates git; DiscoveryReport
JSON round trip.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
2ed5c1eea5