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.shand 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.