feat: failed pages whose references are neither linked nor marked data-bare

samples/fastapi/2026-09-01-pr-16102-explanation.html

@@ -767,7 +767,7 @@ <h3>What the developer sees</h3>
           </div>
           <p class="mock-caption">
             The server starts. Note the first token: the warning is attributed to
-            <code>main.py:8</code>, the line in your own file that called
+            <code data-bare="outside-repo">main.py:8</code>, the line in your own file that called
             <code>app.frontend()</code>. Getting that attribution right is what
             most of this page is about.
           </p>

skills/explain-diff-html/SKILL.md

@@ -483,6 +483,12 @@ The second is a path that is not in this repo at this ref, such as a file from a
 dependency. One page may carry a mix, and an unlinked reference reads exactly as
 it does today.
 
+Mark each reference you leave bare in the second case with a `data-bare`
+attribute, as in `<code data-bare="outside-repo">main.py:8</code>`. The
+validation script fails a page whose unlinked references are not marked, so an
+unmarked one reads as a link the run forgot. The first case needs no marker,
+because the provenance line already says `References are not linked`.
+
 This is GitHub only, on purpose. A url from `gh` names a GitHub-family host by
 construction, so link against whatever host it gives you. A parsed remote could
 be any forge, so link it only when the host is exactly `github.com`, which the

skills/explain-diff-html/html-template.html

@@ -705,7 +705,8 @@ <h2>Code walkthrough</h2>
           <!-- The path label above a code block. Link it when the run resolved a
                host: the anchor goes outside the text, and the href ends #L<n> for
                a single line or #L<a>-L<b> for a range. Drop the <a> and keep the
-               bare text when the reference is one the run could not link. -->
+               bare text when the reference is one the run could not link, and
+               mark a path outside the repo with data-bare="outside-repo". -->
           <p class="filename">
             <a
               class="srcref"

skills/explain-diff-html/references/validation.md

@@ -74,10 +74,19 @@ that mistake now fails instead of passing.
   still opens offline.
 
 - The page linked the references it should have, and every link names the
-  provenance commit in full. The script prints both counts as
-  `references=N linked=M`, then fails on any `/blob/` link whose sha is not the
-  full 40 characters starting with the short commit. It also fails on a link to
-  a `.md` or `.markdown` file that has a line anchor and no `?plain=1`.
+  provenance commit in full. The script prints `references=N linked=M
+  marked-bare=B`, then fails when fewer than `N - B` references are linked.
+  It skips that comparison when the provenance line says `References are not
+  linked`, the host case, where every reference is bare by design. It also fails
+  on any `/blob/` link whose sha is not the full 40 characters starting with the
+  short commit, and on a link to a `.md` or `.markdown` file that has a line
+  anchor and no `?plain=1`.
+
+  Mark each reference you deliberately leave bare with a `data-bare` attribute
+  naming the reason, as in `<code data-bare="outside-repo">main.py:8</code>` or
+  `<p class="filename" data-bare="outside-repo">`. The attribute does not change
+  how the page renders. It is how the script tells a deliberate choice from a
+  reference the run forgot to link.
 
   The script's count needs both the `tr` and the `sed`. A `.filename` label
   reads `class="filename">path:line` when bare and
@@ -87,11 +96,13 @@ that mistake now fails instead of passing.
   `tr` the opening tag is never stripped and the same reference goes uncounted.
   Either way `links` ends up exceeding `refs` on a page where everything worked.
 
-  The mismatch scan proves nothing on its own: with no links on
-  the page it finds nothing and reports success, which is exactly when the
-  feature is most broken. So compare the counts first. `links` should equal
-  `refs` minus the references you deliberately left bare, and you should be able
-  to name every one of those and say which of the two reasons applies.
+  The count takes a `<code>` span or `.filename` label that starts with
+  `path.ext:line`. A `host:port` such as `example.com:8080` has the same shape,
+  so the script drops one whose extension is a common top-level domain.
+
+  The sha check alone proves nothing: with no links on the page it finds
+  nothing and reports success, which is exactly when the feature is most
+  broken. The count comparison is what catches that case.
 
 - No `file:line` reference shortens its path with `...`. The script fails on
   `.../` inside a `.filename` label or a `<code>` span, because a link cannot

skills/explain-diff-html/scripts/validate-output.sh

@@ -29,10 +29,27 @@ fi
 status=0
 
 # Flatten, then strip anchors, so a linked reference still counts as a reference.
-refs=$(tr '\n' ' ' < "$page" | sed -E 's#</?a[^>]*>##g; s/  +/ /g' \
-  | grep -oE '(<code[^>]*>|class="filename"[^>]*>) *[^<]*\.[A-Za-z]+:[0-9]+' | wc -l | tr -d ' ')
+# A reference is a <code> span or .filename label that starts with path.ext:line.
+# A host:port such as example.com:8080 looks the same, so drop common TLDs.
+flat=$(tr '\n' ' ' < "$page" | sed -E 's#</?a[^>]*>##g; s/  +/ /g')
+ref='(<code[^>]*>|class="filename"[^>]*>) *[A-Za-z0-9_./-]+\.[A-Za-z0-9]+:[0-9]+(-[0-9]+)?[ ,<]'
+tld='\.(com|org|net|io|dev|app|local|internal|localhost):'
+count() { printf '%s\n' "$flat" | grep -oE "$ref" | grep -vE "$tld" | grep -cE "$1"; }
+refs=$(count '.')
+marked=$(count 'data-bare=')
 links=$(grep -o 'class="srcref"' "$page" | wc -l | tr -d ' ')
-echo "references=$refs linked=$links"
+echo "references=$refs linked=$links marked-bare=$marked"
+
+# Every reference is linked unless the page marks it with data-bare, or the
+# provenance line says the host could not be linked at all.
+if printf '%s\n' "$flat" | grep -q 'References are not linked'; then
+  echo "pass: provenance says references are not linked"
+elif [ "$links" -lt $((refs - marked)) ]; then
+  echo "FAIL: $((refs - marked - links)) references are neither linked nor marked data-bare"
+  status=1
+else
+  echo "pass: every reference is linked or marked data-bare"
+fi
 
 # A link names the full 40-character sha. GitHub resolves an abbreviation only
 # while the commit is on a branch, so a short sha 404s once a squash merge lands.