agents-doc-presence

An agent-contract doc must exist at the repo root, every surface, and every non-opted-out package.

Runs under: @noctcore/harness lint-meta, not ESLint · Factory: createAgentsDocPresenceRule from @noctcore/lint-meta-rules · Category: source-text · Fails CI by default: yes

Why

An agent editing a boundary should read its guardrails first. Requiring an AGENTS.md (or whatever doc you name) at the root and at every meaningful package means the contract is never missing where it matters. A new package ships the doc by default; only trivial leaves opt out, and the opt-out is explicit and reviewable.

What it flags

Reports a missing doc at:

• the repo root (unless requireAtRoot is false),
• every directory derived from surfaceGlobs (all surfaces), and
• every directory derived from packageGlobs, except those in optOut.

What it does not flag

• A package directory listed in optOut.
• The repo root when requireAtRoot is false.
• Directories that no surfaceGlobs or packageGlobs entry matches (the defaults look one level deep under apps/ and packages/).
• The doc’s content: an empty or stale file passes, since only its presence is checked.

Options

createAgentsDocPresenceRule(options?: AgentsDocPresenceOptions): IMetaRule

Option	Type	Default	Meaning
docFile	string	'AGENTS.md'	The agent-contract filename required in each location.
requireAtRoot	boolean	true	Whether the repo root must carry the doc.
surfaceGlobs	string[]	['apps/*/package.json']	Surfaces (all require the doc).
packageGlobs	string[]	['packages/*/package.json']	Library packages (require the doc unless opted out).
optOut	string[]	[]	Package directories exempt from the requirement.
ciCritical	boolean	true	Whether a violation fails CI.

When not to use it

If your repo does not adopt an agent-contract doc convention, skip it.