agents-file-coverage-gate

name

agents-file-coverage-gate

description

在一个仓库跑「AGENTS.md 契约覆盖」gate——扫出根目录和每个源码目录是否都有 AGENTS.md,可一键补 stub 并接 CI 卡关。确定性脚本运行器,不做交付分类。触发:"查/跑 AGENTS 覆盖"、"查/跑/补 agent 覆盖地图"、"agent 契约覆盖"、"扫一下哪些目录缺 AGENTS.md"、"每个目录都有 agent 契约了吗"、"补缺失的 AGENTS.md"、"契约覆盖 gate"、"给这个仓初始化契约覆盖"、"装 AGENTS 的 pre-commit / CI 卡关"、"check AGENTS.md coverage"、"agents coverage"、"scaffold missing AGENTS.md"、"bootstrap agents coverage"、"do all dirs have an agent contract"。Skip:问「何时/是否」该更新契约或分层策略本身 → `product-rd-workflow` 的 spec/repo-contract sync gate;只是写某一个 AGENTS.md 的内容 → 直接编辑该文件;定义 agent 工具调用/函数的输入输出 schema 或调用契约(不是 AGENTS.md 文件覆盖)→ `llm-inference-integration`。

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 <script> --repo <dir> --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 <filename>. See bash <script> --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.