[andyhorn]

Follows #17, #1, and #14. This is what lets the samples workflow catch a page whose references went unlinked.

The validator now fails a page when a file:line reference is neither linked nor marked as deliberately bare.

Why

validate-output.sh printed references=N linked=M but never compared the numbers. A page that dropped back to bare references, the defect the sample repair fixed, still exited 0, and so did CI. validation.md asked the writer to compare the counts by hand. The rule allows two deliberate exceptions, but nothing on the page recorded which bare references were deliberate, so the script couldn't enforce it.

Changes

• A data-bare attribute marks a deliberate exception, as in <code data-bare="outside-repo">main.py:8</code>. It doesn't affect rendering. SKILL.md, validation.md, and the template comment document it.
• The script fails when fewer than references − marked are linked. Pages whose provenance line says References are not linked (the unresolved-host case) are exempt.
• The reference pattern is tighter. A reference must start the <code> span or .filename label, and host:port strings with a common TLD, such as example.com:8080, are no longer counted.
• The fastapi PR 16102 sample marks main.py:8, the reader's own file and the only unlinked reference among the samples.

Verification

• All 9 samples pass, and their reference counts under the tighter pattern equal the old ones.
• Test pages fail as expected: 3 references with 1 link fails, and localhost.example.com:8080 is not counted.

For the reviewer

• This adds an authoring rule every generated page must follow. Check whether data-bare is the marker you want, or whether you'd prefer another mechanism.

🤖 Generated with Claude Code

[malav2110]

Merged #17, Thank You @andyhorn ! Could you rebase this one onto main? #17 went in as a squash, so its two commits here no longer match main.

[andyhorn]

Rebased onto main. The branch now carries only its own commit (fbba6d9) on top of the #17 squash, with no conflicts, and all 9 samples pass.

[malav2110]

Thanks Andy! This closes the gap where unlinked references still passed CI. All 9 samples pass with it merged into main.

data-bare works for me as the marker, and the parser draft in #21 checks the same attribute. One small gap: the script only checks the attribute name. Either check for outside-repo, or drop "naming the reason" from validation.md.

@ChristianMurphy found three cases against this check in #21. I reproduced them, and the inline comments have tested fixes. I'd like lines 35, 40, and 45 fixed before merging. Line 36 is just a question.

[malav2110]

@andyhorn, Christian's #29 replaces validate-output.sh and already fixes the spare-link and provenance cases, with a test page for each. So I'm dropping my asks on lines 40 and 45. Only the line 35 pattern is still needed. It keeps a data-bare before class and 127.0.0.1:8000 from failing until #29 lands. Happy to commit it myself if that's easier.

[malav2110]

Thanks @andyhorn ! I re-ran Christian's cases with GNU, BSD, and busybox tools. An unlinked filename wide label now fails, a data-bare before class passes, and 127.0.0.1:8000 is no longer counted. All 9 samples pass merged into main, with the same reference counts as before, and the new validation.md note answers my .org question. Merging now.