Defame1297
59f27dbd94
The adapter check shipped green on files it should have failed, and failed files it should have passed. Each defect is a residual of the fix that closes #115. A fenced, indented or HTML-commented `@AGENTS.md` counted as an import, though Claude Code resolves none of them — the adapter deferred to nothing and the gate said so approvingly. Import matching now runs against a character mask that marks fenced blocks and HTML comments inert, and applies CommonMark's four-space rule. The mask is deliberately not applied to prose pointers, where four-space indentation is ordinary list continuation. The encoding fix reached only BOM-carrying UTF-16/32. BOM-less UTF-16LE/BE and UTF-32LE are valid UTF-8, so they still produced the exact false diagnosis the fix was written to remove: "no reference to AGENTS.md" on a file whose first line is `@AGENTS.md`. A NUL-byte check is the complete signal. BOM stripping is no longer positional, which also drops the mirror-image false FAILs on a doubled or mid-file BOM. `@NOTAGENTS.md`, `@zzzAGENTS.md` and `@docs/does/not/exist/AGENTS.md` all passed: the pattern had no path-segment boundary and the target was never resolved on disk. Both now hold, and a zero-byte or blank target is reported rather than credited. Unresolved candidates print as `Near miss:` lines so the author sees why a line was not counted. `--no-import-syntax` still used substring matching, so `Do NOT read AGENTS.md; it is obsolete.` passed as a pointer. That is #115's own defect surviving in the flag's other mode. A mention must now carry a deference cue and must not be negated. An unreadable file passed `isfile()`, raised, and exited 1 with a traceback and no FAIL line — the one exit code no document covered, while Step 3 says to re-run until it exits 0. It now exits 3 with a diagnostic, and the README states all four codes and what to do about each instead of "exits non-zero on any failure". Tests 18 to 42. Two of the new cases initially survived their own mutation and were strengthened: `@NOTAGENTS.md` was being rejected by the disk check before the token boundary ran, and stripping that boundary leaves the fragment `NOT`, which the negation cue then rejects for an unrelated reason. Refs: #115
scripts/
Deterministic self-check this skill shells out to instead of relying on LLM judgment for a mechanical check.
| File | Purpose |
|---|---|
validate-adapter.sh |
Checks a rewritten provider file (CLAUDE.md, etc.) has a working reference to AGENTS.md, doesn't duplicate its content, and stays under a thin-file line threshold |
Takes exactly <adapter-file> <agents-md-file>, with optional --no-import-syntax and --max-lines N flags (also accepted as --max-lines=N). A third positional argument or an unknown option is an error, not something quietly ignored.
What counts as a reference to AGENTS.md
Both modes require the named path to be a real path segment ending in AGENTS.md — AGENTS.md or …/AGENTS.md, not NOTAGENTS.md — that resolves on disk, relative to the adapter file, to a non-empty file. An adapter deferring to a path that is not there defers to nothing, so the check has to touch the disk rather than pattern-match the line.
A reference only counts where something would actually resolve it. A line inside a fenced code block, an indented code block, or an HTML comment is not credited in either mode: Claude Code resolves an import in none of those, so a fenced @AGENTS.md is the silent-drop failure this gate exists to catch, not a pass.
Default mode wants a real import: @AGENTS.md alone on its own line, indented no more than three spaces. --no-import-syntax wants a prose pointer that reads as one — the sentence naming AGENTS.md must carry a deference cue (see, read, refer to, documented in, conventions, …) and must not be negated. Do NOT read AGENTS.md; it is obsolete. and We deleted AGENTS.md last year. name the file while pointing the reader away from it, and neither is a pointer.
Exit codes
The distinction matters because the skill's closeout tells the agent to fix any non-zero exit by editing the provider file. That is right for exactly one of these.
| Code | Meaning | What to do |
|---|---|---|
0 |
Passes every check | Nothing |
1 |
One or more FAIL findings printed to stdout — empty adapter, no working reference to AGENTS.md, excessive duplication, or not thin |
Edit the provider file |
2 |
Usage or input error: a bad, missing, or extra argument, an unknown option, a path that is not a file, or a file that is not UTF-8. Nothing was graded, so there is no FAIL line |
Fix the invocation or the file's encoding — do not edit the adapter |
3 |
A named input file exists but could not be read (permissions, I/O error). Nothing was graded and the adapter's contents are unknown | Fix the file's readability — do not edit the adapter |