release: 2.1.1 (#23)

* fix(imports): a markdown link is not an import

The capture ran through `[@user](https://…)` link syntax into the URL,
picked up a `/`, and passed the looks-like-a-path gate. Biome's CLAUDE.md
credits twenty-two maintainers that way, and every one was an AGF004 error.
No real import target contains a `]`, so the capture stops there now.

* fix(imports): resolve an import from the file that declares it

Measured on Claude Code 2.1.238: a chain of imports loads sub/leaf.md from
sub/mid.md while an identically named file at the repository root stays
unloaded. Resolution is file-relative, and root-relative is not a fallback.

The old resolver used the directory the file governs, which for
.github/CLAUDE.md is the root — so n8n's `@../AGENTS.md`, a real 18KB file
one directory up, escaped the repository and was reported missing. The same
measurement cuts the other way: an import that only resolves against the
root is genuinely broken and is now reported. One that escapes the
repository is never reported, because a bounded scan cannot prove absence.

* fix(frontmatter): read skills, commands, and rules the way the programs do

The 2.1.0 lenient parser went to one of five call sites. trigger.dev's
drizzle skill — an unquoted description carrying `conventions: ` — loads in
Claude Code and echoes its description back verbatim, while agentfile
reported a parse error and a missing description. Measured per surface: a
command with `description: uses: colons, badly: everywhere` is listed with
exactly that description, and a .claude/rules file with the same shape still
loads its body. An unclosed fence is still an error in either reading.

* fix(skills): a name the loader ignores cannot be an error

Measured on Claude Code 2.1.238: a skill named n8n:create-pr in a create-pr/
directory loads and is invoked as create-pr; a skill in a directory named
My_Weird.Skill loads and is invoked as exactly that; a SKILL.md with no
frontmatter at all is listed with its first heading standing in for the
description and resolves when invoked by name. The directory is the identity.

So AGF101's grammar and directory-mismatch findings drop to warning, a name
that breaks both is one finding rather than two, and AGF102's default drops
to warning: missing metadata degrades discovery, it does not break the
skill. n8n's 22 namespaced skills were 44 errors; they are 22 warnings.

* fix(injection): an emoji's joiner is rendered, not hidden

AGF505 flagged the ZERO WIDTH JOINER inside PostHog's 🧑‍💻 — the codepoint
that makes two pictographs one glyph. A well-formed emoji ZWJ sequence is
exempt now; a joiner that joins nothing is still a finding.

The same finding pointed at lines 306 and 311 when the characters sat on 317
and 322: skill and subagent text starts after the frontmatter, and the
scanner numbered it from 1. Both now carry bodyLine through the IR, the same
anchor instructions already had.

* test: every fix carries the measurement that grounds it

Each regression case names the repository it came from and the behaviour
measured on Claude Code 2.1.238, and each keeps a mutation guard: the
unclosed fence still errors, the bare joiner still fires, the root-relative
import that never loads is now a true positive.

* release: 2.1.1

A patch by docs/stability.md: no new codes, no meaning changes — severity
defaults and heuristic reach are documented as not stable. Ten popular
repositories produced 69 error-severity findings on 2.1.0; all 69 were
wrong, in six ways, and each fix in this release carries its measurement.
Internal ranges move with the version, as they did last time.

* fix(action): plant a defect that is still a defect

The fixture's frontmatter stopped being an error when the readers went
lenient — correctly, since the programs load it. The self-test now plants a
broken import instead: CLAUDE.md promising a file that does not exist stays
an error on every measured path, so the gate has something real to gate on.

* chore(deps): take the six open dependabot bumps into the release

biome 2.5.11, semver ^7.8.5, react-query ^5.102.8, plugin-react ^6.1.1,
lucide-react ^1.35.0, zod ^4.5.2 (core and ui), open ^11.0.2, diff ^9.0.0,
checkout@v7 and setup-node@v7 in the action and its self-test.

The two red checks on the open and diff PRs were not those dependencies:
2.1.0 reached npm at 13:38:02 and their runs started at 13:38:09, the first
runs to resolve latest after the fixture's planted defect stopped being an
error. The corrected fixture in this branch is the fix.

Closes #16. Closes #17. Closes #18. Closes #19. Closes #20. Closes #21.

---------

Co-authored-by: Dennis Havermans <dennis.havermans@ae.be>

Author: dennishavermans

.github/workflows/action.yml

@@ -21,10 +21,13 @@ jobs:
     name: Reports and counts known defects
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
-      # Two defects a human reads straight past: a bare * opens a YAML alias
-      # rather than a glob, so neither rule's frontmatter parses at all.
+      # Two defects a human reads straight past. The import names a file that
+      # does not exist, so the instructions it promises are silently absent —
+      # measured on Claude Code, imports resolve from the declaring file and
+      # nothing else, so there is no path on which this loads. The bare * in
+      # the rule's globs is the shape Cursor cannot match.
       - name: Write a fixture with defects we can count
         run: |
           mkdir -p subject/.cursor/rules
@@ -35,8 +38,9 @@ jobs:
           ---
           Use type hints.
           RULE
-          cat > subject/AGENTS.md <<'DOC'
+          cat > subject/CLAUDE.md <<'DOC'
           # Conventions
+          Read @docs/style.md before writing code.
           Use type hints.
           DOC
 
@@ -80,12 +84,12 @@ jobs:
     name: Gates the build when findings are present
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - run: |
           mkdir -p subject/.cursor/rules
           printf -- '---\ndescription: Python rules\nglobs: *.py\n---\nUse type hints.\n' > subject/.cursor/rules/python.mdc
-          printf '# Conventions\nUse type hints.\n' > subject/AGENTS.md
+          printf '# Conventions\nRead @docs/style.md before writing code.\nUse type hints.\n' > subject/CLAUDE.md
 
       - id: gated
         uses: ./
@@ -109,7 +113,7 @@ jobs:
       contents: read
       security-events: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - uses: ./
         id: agentfile

CHANGELOG.md

@@ -9,6 +9,75 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [2.1.1] — 2026-09-01
+
+2.1.0 shipped with a claim it had only partly earned. The lesson of that
+release was that a parse error belongs to the linter, not the program — and
+the fix went to one of the five call sites that had the bug. This release
+comes from running 2.1.0 over ten popular repositories in full and measuring
+every error it produced against Claude Code 2.1.238. There were 69 findings at
+error severity. All 69 were wrong, in six distinct ways, and every fix below
+carries the measurement that grounds it. The same run's one true finding — an
+invisible U+2060 WORD JOINER inside a code span in trigger.dev's Cursor rules
+— still stands, now at the right line number.
+
+### Fixed
+
+- **A markdown link is not an import.** `AGF004`'s capture ran through
+  `[@user](https://…)` link syntax into the URL, picked up a `/`, and passed
+  the looks-like-a-path gate. Biome's CLAUDE.md credits twenty-two maintainers
+  exactly that way, and every one was an error. No real import target contains
+  a `]`, so the capture now stops there.
+
+- **An import resolves from the file that declares it.** n8n's
+  `.github/CLAUDE.md` opens with `@../AGENTS.md`, and the target is a real
+  18KB file. The resolver used the directory the file *governs* — the root —
+  so the `..` escaped the repository and the import was reported missing.
+  Measured: a chain of imports loads `sub/leaf.md` from `sub/mid.md` while an
+  identically named file at the root stays unloaded, so resolution is
+  file-relative and root-relative is not a fallback. That cuts both ways: an
+  import that only resolves against the root is genuinely broken and is now
+  reported, where before it passed. A target that escapes the repository is
+  never reported — a bounded scan cannot prove absence.
+
+- **Skills, commands, and `.claude/rules` read their frontmatter the way the
+  programs do.** The 2.1.0 lenient parser went to subagents only.
+  trigger.dev's `drizzle` skill — an unquoted description carrying
+  `conventions: ` — loads in Claude Code and echoes its description back
+  verbatim, while agentfile reported a parse error and a missing description.
+  Measured per surface: a command whose frontmatter reads
+  `description: uses: colons, badly: everywhere` is listed with exactly that
+  description, and a rule with the same shape still loads its body. All five
+  call sites now share the strict-then-lenient reading; an unclosed fence is
+  still an error in either reading.
+
+- **An emoji's joiner is rendered, not hidden.** `AGF505` flagged the ZERO
+  WIDTH JOINER inside PostHog's 🧑‍💻 — the codepoint that makes two
+  pictographs one glyph. A well-formed emoji ZWJ sequence is now exempt; a
+  joiner that joins nothing is still a finding.
+
+- **`AGF505` line numbers point at the file, not the body.** Skill and
+  subagent text starts after the frontmatter, and the scanner numbered it from
+  1 — PostHog's finding said lines 306 and 311 when the characters sat on 317
+  and 322. Skills and subagents now carry `bodyLine` through the IR, the same
+  anchor instructions already had.
+
+### Changed
+
+- **A skill name the loader ignores cannot be an error.** Measured: a skill
+  named `n8n:create-pr` in a `create-pr/` directory loads and is invoked as
+  `create-pr`, and a skill in a directory named `My_Weird.Skill` loads and is
+  invoked as exactly that. The directory is the identity, so `AGF101`'s
+  name-grammar and directory-mismatch findings drop to warning severity, and a
+  name that both breaks the grammar and mismatches its directory is one
+  finding, not two — n8n went from 44 errors to 22 warnings. `AGF102` drops
+  its default to warning for the same reason: a `SKILL.md` with no frontmatter
+  at all still loads, is listed with its first heading standing in for the
+  description, and resolves when invoked by name. Missing metadata degrades
+  discovery; it does not break the skill. Severity defaults are documented as
+  not stable in [docs/stability.md](docs/stability.md); pin them in
+  `agentfile.yaml` if CI depends on them.
+
 ## [2.1.0] — 2026-09-01
 
 A minor, not the patch this started as. Most of it is correctness work, but

action.yml

@@ -77,7 +77,7 @@ runs:
         fi
 
     - if: steps.node.outputs.satisfied != 'true'
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v7
       with:
         node-version: 22
 

docs/diagnostics.md

@@ -116,10 +116,19 @@ A skill breaks a specification requirement:
 * two skills sharing a name, where which one loads depends on directory
   precedence the platforms do not document identically
 
-### `AGF102` missing-skill-metadata · error · active
+The two name findings are reported at warning severity rather than the code's
+default: measured on Claude Code, a skill whose name breaks the grammar or
+disagrees with its directory still loads and is invoked under the directory
+name, so the finding describes a portability and cross-reference problem in a
+skill that works. When a name both breaks the grammar and mismatches the
+directory, only the mismatch is reported — one fact, not two.
+
+### `AGF102` missing-skill-metadata · warning · active
 A skill omits `name` or `description`, the two fields the specification requires.
-A missing description is not a weak skill but an unusable one: the description is
-the only thing an agent sees before deciding whether to load it.
+The skill still loads and can be invoked by name — measured on Claude Code, a
+`SKILL.md` with no frontmatter at all is listed with its first heading standing
+in for the description — but the description is what an agent weighs when
+deciding to load a skill unprompted, so without one the skill is rarely chosen.
 
 ### `AGF103` skill-routing-quality · warning · active
 The description is valid but an agent cannot route on it reliably — it is too