Agents File Coverage Gate

AGENTS.md File Coverage Gate

On-demand runner for the agent-contract coverage gate: it verifies (and can scaffold) that a repo's root and every source-code directory carry an AGENTS.md. This skill RUNS the gate; the policy — when a delivery must update a contract, and the layering rules contracts encode — lives in product-rd-workflow's spec / repo-contract sync gate. Do not re-decide policy here.

In a project health-check system, this is a deterministic check provider for repo-local contract coverage. It reports the coverage states implemented by this gate, and it becomes CI-enforceable only when the project wires the vendored script with --enforce; agent review still owns whether each contract's content correctly captures the directory boundary.

Contracts are nearest-file-wins (the closest AGENTS.md to the edited file applies; there is no root index). Scope is every directory that contains a source file picked up by the scan (tracked, or untracked-but-not-gitignored; outside a git work tree it falls back to a plain file scan), detected by extension — so Go packages like dal/service/handler with no manifest are covered.

The gate checks one repository. Before running, confirm --repo points at a single repo, not a GitLab group / parent-of-repos checkout (sibling repos cloned side by side under a parent folder, where the parent is not itself a git repo). Running it on a group parent would conflate sibling repos and report a spurious "missing root contract" — so the script now detects that case (target is not a git repo root yet contains nested repos) and refuses with exit 2, listing the sub-repos to run per-repo. For a group, loop the gate over each member repo.

Run

The gate ships in this package at product-rd-workflow/scripts/check-agent-contract-coverage.sh. Resolve that script inside the installed ccl-skills plugin (the newest match under the plugin cache) and run it against the target repo (default --repo .). Never copy it into the repo just to run it; copying is only for CI.

1. Scan — bash --repo --check. Lists every source directory missing a non-empty AGENTS.md. Exit 0 (guidance) — never blocks, safe on legacy repos.
2. Scaffold — when the user wants to close gaps: --fix writes a stub AGENTS.md in each missing directory. Additive only: it never edits or overwrites an existing file, and never follows a symlink.
3. Fill — replace each stub with the directory's real contract: role/responsibility; allowed and forbidden dependencies and layering rules (e.g. a logic layer must not access the database directly — go through the data-access layer); invariants; build/test commands; a link to the nearest parent contract. An empty stub still counts as a gap. Edit only AGENTS.md files. Keep every contract SHORT: Codex consumers (per current documented behavior — project_doc_max_bytes, default 32 KiB, version/config-dependent; primary source: the official Codex AGENTS.md guide at developers.openai.com/codex/guides/agents-md — verify against the installed version) build ONE instruction chain at session start from repo root down to cwd and stop appending on overflow (the guide documents the cap and the stop-adding behavior; no overflow warning is documented) — an oversized root/parent contract can therefore evict deeper overrides, and contracts outside the root→cwd path are not auto-loaded there at all (hosts implementing the agents.md convention apply nearest-file-wins per edited file — per the agents.md spec FAQ; the short-contract discipline serves both semantics).
4. Enforce — --enforce exits 1 on any missing / empty / symlinked contract. Wire it into make lint/CI once the repo is clean.

Tune scope per project/language: --source-ext ".tf .razor", --exclude "migrations gen", --name . See bash --help.

A clean result only covers the languages the scan recognizes. Source dirs are detected by file extension; a directory whose source is a language outside the active --source-ext set is silently unscanned and contributes no gap — so a green --enforce on a repo whose source is in an unrecognized extension (e.g. .tf / .razor / .zig, or Dockerfile / Makefile) can be a false-negative for those dirs. (--source-ext appends to the built-in default set rather than replacing it, so common mainstream languages are already covered; the blind spot is the extensions neither in the defaults nor added.) Before trusting a clean result (or wiring --enforce as a blocking gate), confirm the active extension set covers every in-scope source language whose directories should count toward AGENTS coverage; widen it, or record the unscanned languages as a known coverage gap — do not read a green from a partial extension set as full contract coverage.

Bootstrap a repo (one-time adoption)

To make coverage self-sustaining — enforced on every commit with no agent and no prompt — set a repo up once:

1. Vendor the script into the repo. This is the ONLY case where copying is correct: a git hook or CI runner cannot reach the plugin cache. Copy check-agent-contract-coverage.sh to e.g. tools/.
2. Scaffold + fill the current gaps — --fix, then fill each stub (Run step 3).
3. Install the gate as a git hook or CI step that runs --enforce:

• pre-commit / pre-push: bash tools/check-agent-contract-coverage.sh --enforce. To share across the team, commit a hooks/ dir AND have a setup/init script run git config core.hooksPath hooks (that config is local per clone, so it must be installed, not just committed).
• or CI / make lint: the same command.

During rollout run --check (warn-only, exit 0); flip to --enforce once the repo is clean so it blocks.

After bootstrap, every commit/CI run enforces coverage automatically; the on-demand path above is then only for ad-hoc checks. This skill can drive the bootstrap (vendor + scaffold + install hook); the running afterwards needs neither agent nor skill — just the vendored script.

Boundary

• This skill is the on-demand path (a short ask → run the gate) plus one-time bootstrap (vendor + hook/CI). The steady-state automatic enforcement is the vendored script in a hook/CI, not this skill.
• It does not decide when contracts must change or what layering rules to impose — route those to product-rd-workflow's sync gate.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ccoalm
• Source: ccoalm/ccl-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.