47 lines
3.0 KiB
Markdown
47 lines
3.0 KiB
Markdown
|
# F-012: Six commit references in the docs resolve nowhere, and nothing would have caught it
|
||
|
|
|
||
|
|
category: doc-drift
|
||
|
|
confidence: high
|
||
|
|
|
||
|
|
evidence:
|
||
|
|
- All SHA-shaped tokens in the 40 management documents were resolved against every ref of
|
||
|
|
all six repos and against the rewrite mapping (`analysis/scripts/inv_shas.py` ->
|
||
|
|
`analysis/data/sha_refs.tsv`): 22 resolve, **6 do not**.
|
||
|
|
- The six, with their nature established individually:
|
||
|
|
- `hosts/cfgmon.md:54` `dfe04c4a` and `verfahren/deploy-uebergabe.md:84` `dfe04c4` —
|
||
|
|
a commit pushed directly to Gitea and overwritten by the mirror. Unresolvable **by
|
||
|
|
design**; the surrounding text documents the loss ("vom Mirror überschrieben").
|
||
|
|
- `verfahren/deploy-uebergabe.md:85` and
|
||
|
|
`verfahren/aar/2026-08-01-cve-pipeline-gitops47.md:13` `2b715ca` — same class, the
|
||
|
|
second documented overwrite ("2b715ca→0bd77e2").
|
||
|
|
- `hosts/overmind.md:23` `7645a2b` — a commit in the `vendor/windows` repo, which the
|
||
|
|
human placed out of scope; not resolvable here, not a defect.
|
||
|
|
- `hosts/overmind.md:87` `5bc25447` — not a commit at all but a **container image tag**
|
||
|
|
("Tags `5bc25447` + `stable`"); a false positive of the extractor, recorded as such.
|
||
|
|
- So of six, four are intentional records of lost commits and two are out-of-scope or
|
||
|
|
mis-typed as commits. **No accidental orphan was found** — and that is the finding worth
|
||
|
|
keeping: the mapping list did its job (F-015).
|
||
|
|
- What no mechanism provides: none of this was checkable before this session wrote a
|
||
|
|
script for it. `analysis/data/links.tsv` covers markdown link targets and reports 2
|
||
|
|
broken links in 11,390 (both malformed upstream Element changelog entries), but a SHA in
|
||
|
|
prose is not a link and was never checked.
|
||
|
|
|
||
|
|
impact: Low today, structurally high. The repo cites commits as evidence throughout — it is
|
||
|
|
the house style, and a good one (`README.md:68-70`, "woher stammt die Aussage?"). That style
|
||
|
|
depends on citations staying resolvable across exactly the kind of history operation this
|
||
|
|
project performed on 2026-08-07, and the only thing that kept it working was a document
|
||
|
|
someone remembered to write by hand.
|
||
|
|
|
||
|
|
root-cause pattern: **Evidence-by-citation without a checker.** The convention is sound and
|
||
|
|
followed; its integrity rests on human diligence at rewrite time.
|
||
|
|
|
||
|
|
neckbeard mechanism: **Gap in neckbeard.** `scripts/validate.py` checks link integrity in
|
||
|
|
two places — `check_links` for frontmatter link fields and `check_body_links` for inline
|
||
|
|
markdown links, erroring with "inline link target missing" — and `schema.yaml:19-20`
|
||
|
|
extends body-link checking to root-level prose via `link_only: ["*.md"]`. Commit SHAs cited
|
||
|
|
in prose are outside both. Given `AGENTS.md:101-103` ("Deterministic jobs … are done by
|
||
|
|
scripts … If a deterministic job lacks a script, propose one"), resolving a cited SHA is a
|
||
|
|
textbook deterministic job — `git cat-file -e` — and its absence is a real hole for any
|
||
|
|
project whose docs cite commits. `analysis/scripts/inv_shas.py` is a working reference
|
||
|
|
implementation.
|