Seven links in the published book point at pages mdBook never wrote

[vladimirrott]

Rechecked 2026-09-23 at 0ad26871. docs/cli.md:568 is now :572 and
docs/the-audit-chain.md:492 is now :501, corrected below everywhere they appear. All seven links still resolve at source and
still point at pages mdBook never writes.

mdbook build rewrites every relative .md link to .html. A link that points
out of docs/, and a link to a page missing from docs/SUMMARY.md, both come
out pointing at a file the build never wrote. Seven links across four pages land
on nothing. The repo runs markdown-link-check in CI, and it cannot see any of
this: it resolves the Markdown source, where all seven targets exist on disk. It
would not read these four pages either, which is #372.

Reproduced at 7d19864 with mdBook 0.4.40, the version .github/workflows/docs.yml
pins and installs:

$ mdbook --version
mdbook v0.4.40
$ mdbook build -d /tmp/sk-book
2026-09-05 10:49:20 [INFO] (mdbook::book): Book building has started
2026-09-05 10:49:20 [INFO] (mdbook::book): Running the html backend
$ grep -o 'href="[^"]*user-stories[^"]*"' /tmp/sk-book/cli.html | sort -u
href="user-stories.html"
$ ls /tmp/sk-book/user-stories.*
ls: cannot access '/tmp/sk-book/user-stories.*': No such file or directory

Walking every href in the built tree, with print.html skipped because it
duplicates the rest:

$ cd /tmp/sk-book
$ python3 - <<'PY'
import re, pathlib, urllib.parse
root = pathlib.Path('.')
for html in sorted(root.rglob('*.html')):
    if html.name == 'print.html':
        continue
    for href in re.findall(r'href="([^"]+)"', html.read_text(errors='replace')):
        if href.startswith(('http://', 'https://', '#', 'mailto:', '//')):
            continue
        target = href.split('#')[0].split('?')[0]
        if not target.endswith('.html'):
            continue
        if not (html.parent / urllib.parse.unquote(target)).resolve().exists():
            print(f"{html}\t{href}")
PY
cli.html	../README.html
cli.html	user-stories.html
contributing/CONTRIBUTING.html	../../SECURITY.html
contributing/testing.html	ubuntu-vm-testing.html
contributing/testing.html	../testing/user-stories.html
contributing/testing.html	../../HACKING.html
the-audit-chain.html	../SECURITY.html#audit-anchoring-in-the-default-deployment

I did not check these against the published site. Verifying them there needs an
outbound request this account is not allowed to make, so the evidence above is a
local build of the same tree with the same mdBook version the workflow installs.

Why it matters

docs/cli.md:572 offers the reader the user stories, which is the document that
explains what SysKnife does end to end. docs/contributing/testing.md:333 sends
a contributor to the VM recording procedure. Both are the moment somebody
decided to go deeper, and both give them a 404 on a site whose whole job is to
answer that.

All seven targets are present in the tree, which is why a source-level link
checker passes over them:

$ ls -l README.md SECURITY.md HACKING.md docs/user-stories.md docs/testing/user-stories.md docs/contributing/ubuntu-vm-testing.md 2>&1
-rw-rw-r-- 1 entropia entropia 18618 sep  4 07:01 docs/contributing/ubuntu-vm-testing.md
-rw-rw-r-- 1 entropia entropia 19617 sep  4 07:01 docs/testing/user-stories.md
-rw-rw-r-- 1 entropia entropia 15508 sep  4 07:01 docs/user-stories.md
-rw-rw-r-- 1 entropia entropia 34220 sep  4 07:01 HACKING.md
-rw-rw-r-- 1 entropia entropia 22548 sep  4 07:01 README.md
-rw-rw-r-- 1 entropia entropia 20463 sep  4 07:01 SECURITY.md

Fix the two classes differently.

Four links point outside docs/. README.md, SECURITY.md and HACKING.md
live at the repo root, so mdBook cannot include them at any depth of ../, and
the .md to .html rewrite happens anyway. One file already
does it both ways: docs/the-audit-chain.md:267 links SECURITY.md with a
relative path and breaks, and docs/the-audit-chain.md:501 links the same file
as https://github.com/lacs-project/sysknife/blob/main/SECURITY.md and works.

Three links point at documents that exist and are unlisted.
docs/user-stories.md, docs/testing/user-stories.md and
docs/contributing/ubuntu-vm-testing.md are all in the tree. mdBook renders only
what SUMMARY.md names, so it copied them across as raw Markdown and wrote no
HTML for any of them.

Scope

• Repoint the four outward links at https://github.com/lacs-project/sysknife/blob/main/...,
  copying the form already used at docs/the-audit-chain.md:501.
• Decide, per document, whether the three unlisted files belong in the book. Two
  of them are named by CLAIM_FILES in scripts/check_evidence_claims.py, so the
  project already treats them as load-bearing. Adding them to SUMMARY.md is the
  smaller change; linking them by URL is defensible for anything meant to stay
  out of the published book.
• The trap: docs/user-stories.md and docs/testing/user-stories.md are two
  different documents that share a basename.

$ md5sum docs/user-stories.md docs/testing/user-stories.md
17cb3f780131c1c62baa75bc0b62ca30  docs/user-stories.md
7ff722164b0ec573ab89e09dc9a92609  docs/testing/user-stories.md
$ wc -l docs/user-stories.md docs/testing/user-stories.md
  438 docs/user-stories.md
  593 docs/testing/user-stories.md

docs/cli.md:572 wants one and docs/contributing/testing.md:388 wants the
other. Read both before you pick a target for either link.

Tests first

A guard that builds the book and fails on any internal .html link with no file
behind it. The walk above is the whole implementation. Two things decide whether
it is worth having:

Assert the walk found links at all. A selector that matches nothing reports
zero broken links and passes, which is the failure this tracker keeps meeting;
#362 is the current example, and it cites #315 as the same defect one job over.
Count the hrefs examined and fail when that count is zero.

Prove it bites. Delete one line from docs/SUMMARY.md, rebuild, and watch the
guard name the page that lost its target. Then put it back and watch it go green.

Where it runs is a real choice. .github/workflows/docs.yml already installs
mdBook and builds the book, so a step there costs nothing and catches the break
on the commit that ships it. A tests/release/*.test.sh reaches ci-local.sh
and every contributor, and has to handle a machine with no mdBook: skip loudly,
naming the check that did not run, rather than passing quietly. #346 covers why
a silent local skip is its own defect.

Difficulty

easy. The seven fixes are one line each. The guard is a twenty-line walk over
files the docs job already produces, and deciding which of the three documents
join SUMMARY.md is the only judgement in it.

Getting started

CONTRIBUTING.md
has the build and test commands. This one needs no VM, no daemon and no LLM key:
cargo install mdbook --version 0.4.40 (or the release tarball the workflow
downloads) and mdbook build is the whole environment. No CLA and no copyright
waiver. The project is MIT.

[sonalisrisivani]

I'll take this. Plan:

1. Repoint the four repo-root links (README.md, SECURITY.md, HACKING.md) at https://github.com/lacs-project/sysknife/blob/main/..., matching the form already used in docs/the-audit-chain.md.
2. Add the three unlisted pages to docs/SUMMARY.md so mdBook emits HTML for them: user-stories.md, testing/user-stories.md, and contributing/ubuntu-vm-testing.md.
3. Add a guard that walks the built book for internal .html hrefs with no file behind them, fails when it examined zero hrefs, and proves it bites against a fixture tree before it walks the real book.

PR will follow from this account.

[vladimirrott]

Audited at d881d49. All seven links still land on nothing. Rebuilt the book from
today's tree with the version docs.yml pins:

$ mdbook --version
mdbook v0.4.40
$ mdbook build -d /tmp/sk-book-0906
2026-09-06 12:26:16 [INFO] (mdbook::book): Book building has started
2026-09-06 12:26:16 [INFO] (mdbook::book): Running the html backend

The walk returns the same seven, on the same four pages:

cli.html	../README.html
cli.html	user-stories.html
contributing/CONTRIBUTING.html	../../SECURITY.html
contributing/testing.html	ubuntu-vm-testing.html
contributing/testing.html	../testing/user-stories.html
contributing/testing.html	../../HACKING.html
the-audit-chain.html	../SECURITY.html#audit-anchoring-in-the-default-deployment

Both line references in the body are exact:

$ sed -n '559p' docs/cli.md
- [User stories](user-stories.md) — end-to-end scenario descriptions
$ sed -n '333p' docs/contributing/testing.md
See [docs/contributing/ubuntu-vm-testing.md](ubuntu-vm-testing.md) for the

One sentence in the body is now historical

It says the link check "would not read these four pages either, which is #372".
#376 closed #372 this morning, and all four pages are in the derived list now:

$ scripts/markdown-link-files.sh | tr '\0' '\n' | wc -l
54
$ scripts/markdown-link-files.sh | tr '\0' '\n' | grep -E 'docs/cli\.md|docs/contributing/testing\.md|docs/the-audit-chain\.md|docs/contributing/CONTRIBUTING\.md'
docs/cli.md
docs/contributing/CONTRIBUTING.md
docs/contributing/testing.md
docs/the-audit-chain.md

The check reads them and passes, which is the other half of the sentence and the
half that still matters. .markdown-link-check-internal.json ignores \.html and
resolves the Markdown source, where every one of the seven targets exists:

$ for f in README.md SECURITY.md HACKING.md docs/user-stories.md docs/testing/user-stories.md docs/contributing/ubuntu-vm-testing.md; do printf '%-42s ' "$f"; if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then echo TRACKED; else echo MISSING; fi; done
README.md                                  TRACKED
SECURITY.md                                TRACKED
HACKING.md                                 TRACKED
docs/user-stories.md                       TRACKED
docs/testing/user-stories.md               TRACKED
docs/contributing/ubuntu-vm-testing.md     TRACKED

So #376 widened the coverage and cannot catch this, which is what the issue
predicted. The mechanism is confirmed from the other end too: neither page is in
SUMMARY.md, so mdBook never writes them.

$ grep -n 'user-stories\|ubuntu-vm-testing' docs/SUMMARY.md

No output.

I still have not checked these against the published site. curl is on this
account's deny list and I did not route around it. The evidence above is a local
build of the same tree with the same mdBook version the workflow installs.

[sonalisrisivani]

I implemented the issue in PR #379: #379

It fixes all seven broken published-book links, publishes the three omitted documents through docs/SUMMARY.md, and adds a guard that walks generated HTML and fails on missing targets or zero scanned links. The pinned mdBook build passed locally with 1,173 internal links checked.

[vladimirrott]

@sonalisrisivani rechecked at b2c823e6 while auditing the tracker. All seven links still point outside the book, and one line number in the body has moved.

$ for spec in "docs/cli.md 8" "docs/cli.md 568" "docs/contributing/CONTRIBUTING.md 44" "docs/contributing/testing.md 333" "docs/contributing/testing.md 388" "docs/contributing/testing.md 456" "docs/the-audit-chain.md 267"; do set -- $spec; printf '%-38s %s: ' "$1" "$2"; sed -n "${2}p" "$1"; done
docs/cli.md                            8: the [main README](../README.md) and run `npx sysknife-setup`. Both paths
docs/cli.md                            568: - [User stories](user-stories.md) — end-to-end scenario descriptions
docs/contributing/CONTRIBUTING.md      44:   See [SECURITY.md](../../SECURITY.md) for the disclosure process.
docs/contributing/testing.md           333: See [docs/contributing/ubuntu-vm-testing.md](ubuntu-vm-testing.md) for the
docs/contributing/testing.md           388:    [docs/testing/user-stories.md](../testing/user-stories.md) as the
docs/contributing/testing.md           456: [HACKING.md](../../HACKING.md) §8.
docs/the-audit-chain.md                267: > [SECURITY.md](../SECURITY.md#audit-anchoring-in-the-default-deployment).

The User stories link is docs/cli.md:568, not :559. Neither target is in SUMMARY.md:

$ grep -n 'user-stories\|ubuntu-vm-testing' docs/SUMMARY.md ; echo "rc=$?"
rc=1

And the derived link-check list has grown from 54 files to 56, all four affected pages still in it:

$ scripts/markdown-link-files.sh | tr '\0' '\n' | wc -l
56

I did not check the published site. curl is on my deny list here, so the seven are verified at the Markdown source rather than against what is served, which is enough to show they still resolve outside the book.

No rush on #379 from my side.

[vladimirrott]

Rechecked at ba1a7b8f. All seven links still read as the issue quotes them, and the body's one stale anchor is now corrected.

$ for spec in "docs/cli.md 8" "docs/cli.md 568" "docs/contributing/CONTRIBUTING.md 44" "docs/contributing/testing.md 333" "docs/contributing/testing.md 388" "docs/contributing/testing.md 456" "docs/the-audit-chain.md 267"; do set -- $spec; printf '%-38s %s: ' "$1" "$2"; sed -n "${2}p" "$1"; done
docs/cli.md                            8: the [main README](../README.md) and run `npx sysknife-setup`. Both paths
docs/cli.md                            568: - [User stories](user-stories.md) — end-to-end scenario descriptions
docs/contributing/CONTRIBUTING.md      44:   See [SECURITY.md](../../SECURITY.md) for the disclosure process.
docs/contributing/testing.md           333: See [docs/contributing/ubuntu-vm-testing.md](ubuntu-vm-testing.md) for the
docs/contributing/testing.md           388:    [docs/testing/user-stories.md](../testing/user-stories.md) as the
docs/contributing/testing.md           456: [HACKING.md](../../HACKING.md) §8.
docs/the-audit-chain.md                267: > [SECURITY.md](../SECURITY.md#audit-anchoring-in-the-default-deployment).

Seven for seven. The user-stories line is at :568, not :559; I corrected it in a comment on 16 September and left the body saying 559, which is the half-fix that makes a number harder to trust than leaving it alone. Both occurrences in the body now read :568.

Neither target is in docs/SUMMARY.md, so mdBook still writes neither page:

$ grep -n 'user-stories\|ubuntu-vm-testing' docs/SUMMARY.md; echo "rc=$?"
rc=1

I verified at the Markdown source rather than against the published site, because curl is on this machine's deny list. That is the same limitation I named last time, and it means I can tell you the link targets are absent from the book's table of contents but not that the published pages 404.

@sonalisrisivani #379 is still open against this. Nothing here changes what it needs.

[vladimirrott]

#461 added lines to both files, so two anchors moved: docs/cli.md:568 is now :572 and docs/the-audit-chain.md:492 is now :501. I've updated the body everywhere they appear. The links themselves are unchanged at 0ad26871.