Skip to content

docs(discovery): add the ADR Discovery module specification - #56

Merged
pengyuzhang merged 1 commit into
mainfrom
docs/discovery-readme
Aug 23, 2026
Merged

docs(discovery): add the ADR Discovery module specification#56
pengyuzhang merged 1 commit into
mainfrom
docs/discovery-readme

Conversation

@pengyuzhang

@pengyuzhang pengyuzhang commented Aug 22, 2026

Copy link
Copy Markdown
Collaborator

What this adds

One file: Discovery/adr_discovery/README.md, the specification for the ADR Discovery endpoint collector.

Discovery already has a test plan in the repository (Discovery/tests/README.md) but nothing describing what the collector is, what it has to find, or how it is built. This fills that gap.

What it covers

  • The four targets — AI binaries, AI agents, MCP servers and skills — with where each lives and what counts as proof, plus the two categories excluded on purpose (instruction files, and the scripts and schedulers that start an agent).
  • The six sources the enumerator queries before it searches: package databases, application registries, the kernel, application state, network egress, and the platform execution journal.
  • The M1–M7 module split with its three cross-cutting concerns — catalog, redaction and coverage.
  • The code layout that split implies, and the import rules that keep it: one directory per module, only world/ touching the OS, no stage importing a sibling, all checkable by a single walk of the import graph.
  • The asset and coverage shapes, the redaction rules, the evaluation layers, and the build order.

Notes for review

  • The status section says plainly that the implementation is not in this repository yet, so the file cannot be misread as documenting code you can import today.
  • Two categories are excluded from discovery deliberately, and both are named in coverage.out_of_scope rather than silently omitted — so a clean machine stays distinguishable from an unasked question.
  • Accuracy claims state which measurement layer produced them. A fixture suite built from the catalog measures internal consistency and is labelled as such; it is not reported as precision or recall.

Discovery has a test plan in the repository but no document describing
what the collector is or how it is built. This adds one.

It states the four discovery targets and what is deliberately out of
scope, the six sources the enumerator queries, the M1-M7 module split
with its three cross-cutting concerns, the code layout that split implies
and the import rules that hold it in place, the asset and coverage
shapes, the redaction rules, the evaluation layers, and the build order.

The status section is explicit that the implementation is not in this
repository yet, so the file cannot be misread as documenting code that
can be imported today.
@pengyuzhang
pengyuzhang merged commit d422d67 into main Aug 23, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants