Story: Hotfix: the site build aborts on a POSIX class that reads as a link

Table of Contents

This page documents a story in Sprint 26. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

1. Goal

The site build and the CDash site job abort on main while publishing doc/agile/versions/v0/sprint_26/clean-dq/task_clean_dq.org:

Build failed: Unable to resolve link: ":space:"

The page records the command that counted the dq NATS subjects. The command contains a POSIX character class, nats_subject[[:space:]]*=, written between equals-delimited verbatim markers. The = after the class closes the verbatim span early, so the rest of the command is ordinary prose, and org parses the opening bracket pair of the character class as the start of a link whose target is :space:. Nothing can resolve it, so the export aborts, and the site build is red on main for every push.

The fix is two delimiters. The command is written with tilde delimiters instead, which the inner = cannot close, so the exact command text stays in the page and the class stays inside the span. The check that would have caught this at pull-request time did not exist, so this story also adds it: no link type begins with a colon, so a parsed link whose target does is always a mistake, and the check is exact rather than heuristic.

2. Status

Field Value
State DONE
Parent sprint Sprint 26
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-09-28

3. Acceptance

  • The page publishes, and the command in it still renders as the exact command that produced the number.
  • The full site build completes and publishes every page.
  • A doc-lint check fails a link whose target begins with a colon, and fails on the text this story fixes.
  • Every other documentation gate stays green: compass lint, validate_docs.sh and the skill checks.

4. Tasks

Task State Start End Description
Implement Hotfix: the site build aborts on a POSIX class that reads as a link DONE 2026-09-28 2026-09-28 Re-delimit the two spans, add the link check to the doc-lint job, prove the check fails on the original text and passes on the tree, and verify the page and the full site build publish.

5. Decisions

  • The spans take tilde delimiters rather than a rewritten pattern or an inline source block. Rewriting the pattern to avoid the bracket pair would change the evidence command, and the recorded command is the point of the page. An inline source block survives in a paragraph but not in a table cell, which is where both spans live, so it would not have fixed this. Tilde and equals are both org verbatim markers, so the rendering is unchanged and the command is untouched.
  • The check parses only the files that contain a candidate, rather than the whole corpus. Every org file is scanned as text, and the parser sees the handful whose text carries a bracket pair before a colon. On this tree that is two files out of 6020, which keeps a pull-request check cheap enough to run on every documentation change.

6. Out of scope

  • The file: link with a line-number search into a Python file that broke the same build on 2026-09-27 (PR #2262). It was fixed before this story started; the check this story adds catches the shape that remains, and a general "every link resolves" check would need the id map and a full parse of the corpus, which the site build already does on every push to main.

Emacs 29.3 (Org mode 9.6.15)