home-network-k3s-impl/decisions/2026-10-31-source-comment-audit.md

date, branch, title

date	branch	title
2026-10-31	docs/source-comment-audit	Audit — historical narrative in source comments (read-only inventory, sample not exhaustive)

What changed

Nothing but this file. This is the read-only audit asked for in issue #97. No source file was edited; the pruning is to be briefed afterwards, per directory, from this list.

What was asked, and the calibration applied

From the reporter (issue #97, 2026-10-31T16:42:30Z): "'historical' talks about previous issues or intent that have changed and why/how it is used today within comments of source files rather than keeping them in the decisions and documentation. Source file comments should only talk about the current files and sections of code/yaml purposes, uses, expectations."

Each row below is classified:

• historical — narrative about a superseded state, a past incident, a corrected earlier belief, or a closed issue. Says nothing about what the line does today.
• load-bearing — phrased as history, but the sentence is the only record of a current non-obvious constraint. Per the brief these get rewrite, never delete.
• ambiguous — I could not rule without the operator. Left for a human, deliberately not resolved here.

THIS IS A SAMPLE, NOT AN EXHAUSTIVE INVENTORY

The brief caps the audit at roughly 40–50 findings and asks for honesty over padding. Measured candidate volume, tree-wide, with the keyword sweep below:

git ls-files -z | xargs -0 grep -nEi '#.*(used to|previously|formerly|no longer|we had|
  before we|historically|in the past|originally|superseded|turned out|was wrong|predates|
  legacy|issue #[0-9]+|PR #[0-9]+|measured 20|as of 20[0-9][0-9]-|see decisions/|DECISIONS-LOG)'

Directory	candidate hits	files	coverage here	findings listed
platform/	107	56	sampled	9
infra/	75	44	sampled	8
conformance/ (excl. runs/)	72	~31	sampled	5
clusters/	43	19	sampled	7
ci/	42	15	sampled	6
catalog/	39	9	sampled	7
.gitea/	10	5	full	5
bootstrap/	4	3	full	3
platform-config/	3	1	full	3
apps/vms/ (hand-authored)	3	2	full	2
apps/wave-* (generated)	15	—	excluded — see below	0
conformance/runs/ (archived logs)	8	18 files	excluded — see below	0
runbooks/	11	—	not audited (prose docs, not source comments)	0
total	~420	~190	—	55

Covered fully: .gitea/, bootstrap/, platform-config/, apps/vms/. Covered by sample only: platform/, infra/, conformance/, clusters/, ci/, catalog/. Roughly 365 candidate hits remain unexamined, and candidate ≠ finding — the keyword sweep's precision on the parts I did read was well under half, so the true residual is smaller than 365 but is certainly in the low hundreds.

The issue's premise holds, with one qualification the operator should price in: of the 55 rows below, 22 are load-bearing and get a rewrite rather than a deletion. The narrative is genuinely excessive, but a mechanical "delete the history" sweep would destroy real constraints. That ratio is the single most important number in this report.

Two structural warnings that change how the follow-up PRs must be written

1. apps/wave-0/, apps/wave-1/, apps/wave-2/ are GENERATED. Do not edit comments there. They are goldens produced by one canonical invocation of catalog/render.py (ci/render-golden.sh:21), and ci/render-golden.sh:136-150 byte-compares every rendered file against its committed golden — any diff is a hard exit 1 that blocks the merge. So the 15 candidate hits under apps/wave-* are copies of comments whose source is catalog/*.yaml or catalog/render.py; e.g. apps/wave-0/gitea.yaml:130 is the rendered form of catalog/gitea.yaml:100. Edit the catalog source, then re-render with the canonical command and commit both. A pruning PR that hand-edits apps/wave-* will sit red.

2. conformance/runs/*/run.log are archived evidence artifacts, not source. 8 candidate hits sit in 18 committed run logs. They are the recorded output of past conformance runs — the comments inside them are copies of the test bodies as they stood at run time. Rewriting them would falsify evidence. Excluded from scope entirely; recommend the operator confirm.

A dangling pointer, replicated across 18 files — fix this before any "replace with a pointer" work

18 files cite DECISIONS-LOG: "Headlamp gating stall" as their rationale pointer, and no such entry exists. grep -ci "gating stall" DECISIONS-LOG.md → 0; the phrase appears nowhere in decisions/ either. Citers:

clusters/base/crafty.yaml           clusters/base/headlamp.yaml
clusters/base/homepage.yaml         clusters/base/kustomization.yaml
clusters/base/runbooks.yaml         clusters/base/vpn-ingress.yaml
platform-config/kustomization.yaml  platform/crafty/deployment.yaml
platform/crafty/kustomization.yaml  platform/headlamp/kustomization.yaml
platform/homepage/kustomization.yaml platform/homepage/README.md
runbooks/kustomization.yaml         runbooks/flux-reconcile.md
conformance/tests/l0-static/alert-runbooks-resolvable/check.sh   (+3 more)

This is the audit's clearest warning about its own remedy: "replace the narrative with a pointer" is only an improvement if the target exists and keeps existing. The archive is frozen and has no index, so a title-based citation into it cannot be checked by anything. Recommendation: when the operator takes the pruning PRs, either write a real decisions/ entry for the leaf-gating lesson and repoint all 18 citations at its filename, or drop the citation. Pointer targets of the form decisions/<file>.md are checkable; DECISIONS-LOG: "<title>" is not. Nothing below recommends a pointer target I did not confirm exists.

---

platform/ — 107 candidates, 9 listed (sampled). NOT sensitive, except platform/kyverno/**

#	path:lines	comment (gist)	class	action	sensitive
1	platform/crafty/service-l4.yaml:33-91	"CORRECTED 2026-09-14 after an 8-DAY LAN OUTAGE … This file used to say Local" — 58 lines of outage narrative	load-bearing	rewrite. Keep the current constraints (Cilium's L2 announcer is not backend-aware; SNAT mode loses client IP; /ban-ip degrades so use /ban; remote-node is subsumed by cluster so do NOT add it; no loadBalancerSourceRanges deliberately). Drop the outage story, the lease-age detail and the per-protocol tell	no
2	platform/longhorn/helmrelease.yaml:191-200	"orphanAutoDeletion: true USED TO BE HERE AND WAS INERT. Removed 2026-09-13"	load-bearing	rewrite to the forward-looking rule: Longhorn ≥1.9 replaced it with orphanResourceAutoDeletion and the chart silently drops unknown defaultSettings keys — so do not set it	no
3	platform/longhorn/helmrelease.yaml:249-254	"CORRECTION, re-measured 2026-09-13 later the same day: the line originally recorded here read …" — corrects a superseded measurement	historical	delete. The correct reading is already stated at :246-248	no
4	platform/monitoring/alerts.yaml:625-636	"Both rules below used to read == 2 / == 3, with the comment 0=unknown 1=healthy…"	load-bearing	rewrite. Keep "longhorn_volume_robustness is a one-hot state-labelled gauge, value 0 or 1" — that is why the expressions look as they do. Drop the old-enum story	no
5	platform/monitoring/alerts.yaml:869-875	"This alert originally used severity: info. That was WRONG, and wrong in the silent direction"	load-bearing	rewrite to the current rule: carries no severity deliberately, because general.rules' InfoInhibitor would swallow an info-severity deploy notification	no
6	platform/monitoring/pvc-capacity-alerts.yaml:12-27	"LonghornVolumeCapacityHigh … never did, for two different reasons in sequence, and it is now GONE" — dated 2026-09-06/2026-09-13 timeline	load-bearing	rewrite. Keep only "these rules key on kubelet_volume_stats_* because longhorn_volume_actual_size_bytes measures allocation, not filesystem use". Delete the sequence	no
7	platform/headlamp/helmrelease.yaml:77-85	"These two used to be keys INSIDE headlamp-oidc-credentials.sops.yaml. That was the bug…" + the dev-Keycloak i/o timeout story	load-bearing	rewrite to the current rule: issuer and callback URLs are public and MUST be cleartext, because Flux's ${BASE_DOMAIN} postBuild substitution cannot reach inside an encrypted Secret. Keep the [parity] note at :87-92 as-is	no
8	platform/vpn-egress/egress-steering.yaml:79	"CORRECTION 2026-09-12 — this comment used to say the host nftables kill-switch 'is the…'"	load-bearing	rewrite to state the actual mechanism (Cilium's eBPF egress-gateway drop) without the correction framing	no
9	platform/keycloak/passkey-reconciler.yaml:18	"It used to be duplicated here almost verbatim"	historical	delete, or replace with pointer decisions/2026-10-18-keycloak-passkey-reconciler.md (confirmed present)	no

Also seen in platform/ and left unlisted for the cap, same shapes: platform/cilium/helmrelease.yaml:57-65 (load-bearing — the k3s_api_host/k3s_apiserver_endpoint split is the current parity contract), platform/kubevirt/kubevirt-cr.yaml:7 (useEmulation was previously true), platform/external-snapshotter/kustomization.yaml:35 (Previously these were REMOTE), platform/kustomization.yaml:7 (the same pattern by which kyverno was previously deferred), platform/pm-agent/configmap.yaml:22, platform/monitoring/tests/run.sh:61 and :129, platform/cnpg/alerts.promtool-test.yaml:20, platform/oauth2-proxy/auth-visibility-alerts.yaml:36-42 and :98-101, platform/vpn-ingress/daemonset.yaml:165.

infra/ — 75 candidates, 8 listed (sampled). NOT sensitive, except infra/gitea/**

#	path:lines	comment (gist)	class	action	sensitive
10	infra/plex/claim-ship.sh:29-32	"Branch prefix is now cosmetic. It used to matter: gate.yml's push trigger covered feature/** … Those per-branch push triggers were deleted"	historical	delete. The live trigger set is already documented at .gitea/workflows/gate.yml:48-56 and CLAUDE.md §4	no
11	infra/ansible/inventory/hosts.ini:105	"GROUP-NAME GAP: CLOSED 2026-08-31. The roles and playbooks used to hardcode the…"	historical	delete — the gap is closed and the current variable is named at playbooks/node-health.yml:12	no
12	infra/ansible/inventory/hosts.ini:147-153	"NOTE (CORRECTED 2026-09-12): this used to read 'node 3 also has wlp1s0 up on 192.168.2.195 (wifi)'. It does not"	load-bearing	rewrite as a positive present-tense assertion: node 3 has no wl* netdev and a single IPv4 uplink on eno1. That fact is load-bearing for the kill-switch datapath; only the correction framing should go	no
13	infra/ansible/roles/node_health/defaults/main.yml:110-121	"The first real run of this role FAILED k3s-prod-1's Crucial/Micron C400 on reallocated=61440 … That verdict was WRONG"	load-bearing	rewrite. Keep the current rule (SMART raw values are vendor-defined; Micron TN-FD-20 scales ID 5 by Block_Sector_Count, so ID 170/196 are the trustworthy corroborators). Drop "the first real run failed"	no
14	infra/ansible/roles/unattended_upgrades/tasks/main.yml:304-309	"This was originally a find over /etc/kernel/postinst.d … That theory was wrong"	load-bearing	rewrite to the current justification: the sentinel writer is ours at two known paths, and two exact stats are strictly stronger than a glob that would match Debian's own conffile	no
15	infra/ansible/roles/node_health/tasks/assess.yml:398	"measurement was right; the inference from the log line was wrong — the memattr block below…"	historical	delete	no
16	infra/devcontainer/dev.sh:103-108	"SUPERSEDED but still honoured: DEV_KUBECONFIG used to be the only way to reach a cluster other…"	load-bearing	rewrite. "Still honoured" is current behaviour and CLAUDE.md §3 tells every agent to set DEV_KUBECONFIG=/dev/null, so this must keep documenting the variable — just not as history	no
17	infra/vpn-ingress/new-peer.sh:136	"COMMENT LINES ARE NOT ALLOCATIONS. This used to grep the whole file and so matched the…"	load-bearing	rewrite, replacing the history with pointer decisions/2026-10-06-new-peer-ignores-template-comments.md (confirmed present)	no

Unlisted, same shapes: infra/ansible/inventory/group_vars/all.yml:31, infra/ansible/inventory/group_vars/k3s_prod/vars.yml:86 ("CORRECTION 2026-09-06: an earlier version of this comment claimed…"), infra/ansible/roles/node_baseline/tasks/disks.yml:559, infra/ansible/roles/node_baseline/tasks/main.yml:801, infra/ansible/roles/kube_vip/tasks/main.yml:68, infra/ansible/roles/cilium/defaults/main.yml:30, infra/ansible/playbooks/node-health.yml:12, infra/ansible/roles/vpn_egress_gateway/templates/vpn-egress-up.sh.j2:39 and vpn-egress-down.sh.j2:15, infra/devcontainer/kubeconfig.sh:26, infra/agent/Containerfile:216, infra/agent/build-image.sh:30, infra/agent/pm-worker:97, infra/agent/probe-validation.sh:98.

catalog/ — 39 candidates, 7 listed (sampled). NOT sensitive — but every edit here re-renders apps/wave-*

#	path:lines	comment (gist)	class	action	sensitive
18	catalog/qbittorrent.yaml:7-12	"BULK DOWNLOADS TIER — DELIVERED 2026-09-12 (the deferral below is CLOSED; kept for the record). This entry used to ship config-only, with a comment promising … 'once OQ-2 is resolved'"	historical	delete. Self-describes as "kept for the record", which is precisely the issue's complaint	no
19	catalog/qbittorrent.yaml:141-151	"It USED to be a doubled-dollar default-operator expansion of a WEBUI_PORT env var … That MISDIAGNOSIS is preserved in this service's own marker log at 2026-09-13T05:35Z"	load-bearing	rewrite. Keep "PORT is a literal matching ingressRoutes[0].port; a literal cannot be mangled by envsubst". Drop the misdiagnosis story (it is already preserved in the marker log the comment itself cites)	no
20	catalog/plex.yaml:43-46	"(This comment previously asserted '~4 minutes' as established fact. It was … Measured 2026-09-29: the full loop is ~2m45s and fits.)"	historical	rewrite to the measured figure alone; delete the self-correction parenthesis	no
21	catalog/plex.yaml:65	"So the earlier 'a placeholder claim Secret would crashloop the pod' note was WRONG about the…"	historical	delete	no
22	catalog/plex.yaml:318	"actually granted access (device-cgroup EPERM, measured 2026-10-01), so there was nothing to keep"	historical	rewrite with pointer decisions/2026-10-01-quicksync-via-device-plugin.md and/or decisions/2026-10-03-cilium-cgroup-hostroot.md (both confirmed present)	no
23	catalog/gitea.yaml:14	"Headless-install bootstrap (formerly apps/gitea-bootstrap-patch.yaml; now first-class via the…)"	historical	delete the "formerly" clause; keep the description of what the block does	no
24	catalog/render.py:159-166	"THE SCRAPE WORKS AS OF 2026-10-05 — but it took THREE independent pieces … (PR #28) … (PR #49)"	load-bearing	rewrite. The three-part requirement and "do not read this flag alone as 'metrics are working'" are current and genuinely non-obvious; drop the PR numbers and the "63.7h" incident, pointing at decisions/2026-10-05-oauth2-sidecar-scrape-verified.md (confirmed present)	no

catalog/pihole.yaml:210 and :218 are the exemplar to copy: narrative already reduced to see decisions/2026-10-04-pihole-multi-replica.md / -pihole-declare-state.md, both of which exist. Unlisted: catalog/gitea.yaml:100-130, catalog/nextcloud.yaml:211 and :226-240, catalog/semaphore.yaml:84, catalog/pihole.yaml:179, catalog/qbittorrent.yaml:389-417, catalog/sonarr.yaml:120, catalog/render.py:672, :1371, :2161. catalog/jackett.yaml:73 ("floor only, no ceiling; 0.24.x runs as of 2026-10-30") is load-bearing, leave alone — a dated version constraint, exactly the carve-out the brief names.

.gitea/ — 10 candidates, 5 listed (FULL coverage). SENSITIVE (.gitea/**)

#	path:lines	comment (gist)	class	action	sensitive
25	.gitea/workflows/gate.yml:14-16	"(it used to print '— not green' and then 'MERGE GATE: PASS', exit 0 — fail-open in the gate itself)"	historical	delete the parenthesis; the surrounding GATE_STRICT_SKIPS rationale is current and stays	yes
26	.gitea/workflows/gate.yml:48-56	"There is NO per-branch push trigger. There used to be a prefix list (feature/** fix/** …) and it was a net negative here" + the 2026-09-29 plex-claim cost	load-bearing	rewrite. "Do not re-add a push trigger; act_runner is capacity 1 and the duplicate run serialises ahead of the PR run" is a live constraint a future editor needs. Drop the plex-claim anecdote	yes
27	.gitea/workflows/gate.yml:118-123	"WIDENED TOLERANCE, DECLARED: || [ "$?" -eq 3 ] used to cover exactly one skip (spec-immutability)"	load-bearing	rewrite. This documents a deliberate current weakening plus its exit condition (REQUIRE_GITEA_SETTINGS=true once the secret is seen green). Keep the instruction, drop "used to"	yes
28	.gitea/workflows/renovate.yaml:72-76	"CORRECTED 2026-10-30. This list used to name only write:repository + read:user … Run 350 then failed at GET /api/v1/orgs/… 403"	load-bearing	rewrite to the required scope list as a plain present-tense requirement; point at decisions/2026-10-30-renovate-auth.md (confirmed present) for the run-350 story	yes
29	.gitea/workflows/merge-gate.yaml:15	"The text that used to sit here…"	historical	delete	yes

Remaining .gitea/ candidates examined and judged not findings (current-state measurements, correctly phrased): renovate.yaml:6, :34, :259, images.yaml:44, scripts/images.sh:11.

ci/ — 42 candidates, 6 listed (sampled). SENSITIVE (ci/**)

#	path:lines	comment (gist)	class	action	sensitive
30	ci/decisions-log.sh:5-23	19-line "WHY THIS STAGE EXISTS" block reproducing the four-PR conflict table verbatim	historical	replace with a pointer. It is a near-verbatim duplicate of decisions/README.md:9-30, which the comment itself already cites at :23. Cut to the assertion list + that pointer (and decisions/2026-09-29-decisions-log-conflict-free.md, confirmed present)	yes
31	ci/gitea-settings.sh:7-23	"On 2026-09-29 that blind spot was measured … PR #1 … sat pending for 30.6 minutes … PRs #5-#9 merged with zero approvals"	load-bearing	rewrite. "No other check can see Gitea's own database; assert-scripts do not detect drift from their own target" is the current reason the stage exists. Drop the PR-by-PR history	yes
32	ci/l0.sh:15-23	"That union replaces what used to be a hand-written 'UNCONDITIONAL' stage per whole-repo check (3c subst-safety / 3d keycloak-client-secrets / 3e bulk-tier)"	historical	rewrite to describe the present selection rule only (touched-requirement subset ∪ every test declaring scope: whole-repo)	yes
33	ci/lib.sh:138-142	"WHY THIS EXISTS: ci/l0.sh used to carry a hand-written stage per whole-repo check, each with its own summary … line"	historical	rewrite to "names every offline check that ran and its verdict"	yes
34	ci/approval-policy.sh:107-112	"Blocking on that turned 'CI cannot read your override' into a message that said 'you did not post one', and cost a real debugging session on PR #38"	load-bearing	rewrite. The token-scope fact and the fail-direction guarantee ("an unreadable source can only cause a false BLOCK, never a false pass") are current; the debugging-session cost is not	yes
35	ci/touched-requirements.sh:288-293	"R-TEST-06 added 2026-09-12. The comment in changed_diff()'s rule 3 above records why it was ABSENT: R-TEST-06 used to be enforced by the spec-immutability STAGE"	load-bearing	rewrite. Keep why a ci/ change must attribute R-TEST-06 today; drop the absence history	yes

Unlisted: ci/approval-policy.sh:30-38 and :182, ci/conformance.sh:73, ci/gate.sh:133, :233-234, ci/l0.sh:86, ci/l1.sh:33, ci/lib.sh:65, ci/render-golden.sh:5-6 and :24, ci/touched-requirements.sh:39, :316, plus ci/tests/*.test.sh (5 files — note these are test rationale headers, where a "this used to fail on main" line arguably earns its keep; I would send the whole ci/tests/ group to ambiguous).

clusters/ — 43 candidates, 7 listed (sampled). SENSITIVE (clusters/**)

#	path:lines	comment (gist)	class	action	sensitive
36	clusters/base/cluster-vars.yaml:244-251	"IT IS NO LONGER A CROSS-NETWORK KNOB (2026-10-07). This used to read 'the two clusters are on OPPOSITE SIDES of pfSense'…"	load-bearing	rewrite. Keep "exactly one storage host, 192.168.2.30; still a knob only because the renderer reads it per-environment" and the immutability warning at :253+. Replace the pfSense/DNAT history with pointer decisions/2026-10-07-bulk-nfs-truenas.md (confirmed present)	yes
37	clusters/prod/kustomization.yaml:335-351	"APEX AS OF 2026-09-13 … Prerequisites completed and VERIFIED before this flip, in this order: 1. dev's 18 A records released … 2. dev's 18 LEGACY UNPREFIXED TXT registry entries deleted by hand … 3. dev's Certificate deleted"	historical	rewrite. The three completed prerequisites are done and unrepeatable. Keep only the still-true NOTE at :348-351 (the zone's two wildcards point at the legacy stack's public IP and prod's specific records shadow them)	yes
38	clusters/prod/kustomization.yaml:472-479	"*** DECIDED 2026-09-06 by the operator: the VIP, as intended. *** (This block previously read 'Not yet decided' while shipping .10 …)"	load-bearing	rewrite. Keep "this is the control-plane VIP, NOT .20 the ingress VIP and NOT .10 the single node address" and why a node-pinned CNI endpoint fails silently. Drop the previous-wording parenthesis	yes
39	clusters/base/apps-vms.yaml:51-55	"postBuild.substituteFrom ENABLED 2026-08-31 (R-ENV-02). It was previously omitted because Flux's envsubst runs over the ENTIRE manifest…"	load-bearing	rewrite. The envsubst hazard over VM cloud-init and the $${...} escape obligation are live constraints for anyone adding a VM manifest; the enablement date and prior omission are not	yes
40	clusters/dev/kustomization.yaml:282-287	"THIS VALUE IS INERT — dev is decommissioned, its nodes no longer exist, and the Proxmox host this used to name (192.168.1.9) went with the pools it held"	load-bearing	keep, trim. "Inert, restated per this overlay's supply-every-knob convention, unproven because there is no dev node" is honest current state and the kind of comment the issue wants	yes
41	clusters/base/apps-wave-0.yaml:4, apps-wave-1.yaml:4, apps-wave-2.yaml:4	"wait:true health-gates ONLY this wave's resources, so a later wave can no longer stall an earlier one" (×3, and the same sentence is emitted by catalog/render.py:2385)	load-bearing	rewrite the "no longer" to plain present tense. Note the renderer emits this string, so fix render.py:2385 and re-render rather than editing the three files by hand	yes
42	clusters/base/headlamp.yaml:9-12, homepage.yaml:10, crafty.yaml:11, kustomization.yaml:53, runbooks.yaml:15, vpn-ingress.yaml:9	six files citing DECISIONS-LOG: "Headlamp gating stall" — target does not exist (see above)	historical	rewrite to the present-tense rule (a leaf UI belongs in its own post-platform-config Kustomization so its crashloop cannot stall the chain) and drop or repoint the dead citation	yes

Unlisted: clusters/base/cilium.yaml:52, cluster-vars.yaml:29, :51, :264, platform.yaml:17, :56, platform-config.yaml:6, platform-config-cdi.yaml:13, oauth2-proxy.yaml:10, clusters/dev/kustomization.yaml:67, :81, :222, clusters/dev/sync.yaml:8, clusters/prod/kustomization.yaml:277-283, :317, :363, :546, :554.

conformance/ — 72 candidates (excl. runs/), 5 listed (sampled). SENSITIVE (conformance/**)

#	path:lines	comment (gist)	class	action	sensitive
43	conformance/tests/l3-fault-injection/vpn-killswitch/chainsaw-test.yaml:16-24	"MECHANISM CORRECTED 2026-09-12: this comment used to credit 'the host nftables kill-switch' … The ASSERTION below is unchanged and still the right one — only the explanation was wrong"	load-bearing	rewrite to state the real mechanism (Cilium's eBPF egress-gateway drop, netfilter never invoked) in the present tense. Pairs with finding #8 — same correction duplicated in platform/vpn-egress/	yes
44	conformance/tests/l3-fault-injection/vm-data-survival/chainsaw-test.yaml:18-27	"(Feature-gate note, revalidated 2026-08: an earlier revision of this comment also claimed the containerDisk BOOT path was broken … That premise is now STALE: the cluster is k3s v1.36.4, where ImageVolume is ENABLED)"	historical	rewrite to the one current sentence that matters — DataVolume is used because only it survives a rebuild — and drop the whole stale-premise parenthesis	yes
45	conformance/tests/l0-static/ha-control-plane-as-code/chainsaw-test.yaml:51-60	"TWO GAPS CLOSED 2026-09-06 (they used to be listed above; recorded so the change is legible)"	historical	rewrite. Both gaps are closed and now asserted; state the assertions, drop the gap history. Same in check.sh:98 and :500 ("This section used to be an ESCALATION in the header's gap list")	yes
46	conformance/lib/status.py:303-310	"It used to be, and that mis-reported a SAFETY-CRITICAL requirement … A previous engineer worked around it by rewording prose"	load-bearing	rewrite. "Scaffold detection must name the idioms it hunts for, because a placeholder-detection test legitimately contains the words" is the current design constraint; the R-STATE-03 misreport and the previous engineer are not	yes
47	conformance/tests/l0-static/bulk-tier-distinct-from-replicated/check.sh:447-455	"It used to assert … in L0: ci/l0.sh carried a hand-written 'UNCONDITIONAL' stage per whole-repo check" — the same paragraph is duplicated verbatim in 3 files (also flux-postbuild-substitution/check.sh:604, keycloak-client-secret-reconciler/check.sh:678)	historical	rewrite all three to the present mechanism (the test declares scope: whole-repo; ci/l0.sh unions declaring tests via --include-scope; both halves checked). Good candidate for one small PR — identical edit ×3	yes

Unlisted: conformance/incluster/chainsaw-job.yaml:44, conformance/incluster/rbac.yaml:105 (also sensitive as **/rbac.yaml — "superseded design" for the gluetun Deployment; load-bearing, since it explains why the fault Job needs no RBAC), conformance/lib/common.sh:33, conformance/lib/status.py:114, and ~10 further tests/l0-static/*/check.sh headers of the same shape (alert-metrics-have-scrape-targets, alert-rules-unit-tested, alert-runbooks-resolvable, auditability-proofs-producible, keycloak-passkey-reconciler).

bootstrap/ — 4 candidates, 3 listed (FULL coverage). SENSITIVE (bootstrap/**)

#	path:lines	comment (gist)	class	action	sensitive
48	bootstrap/flux/components/kustomization.yaml:36-38	"On 2026-09-01 that shipped k8sServiceHost: "" into the Cilium HelmRelease and put 2 of 3 agents into Init:Error (DECISIONS-LOG, INCIDENT entry)"	load-bearing	rewrite. The fail-open default and what the feature gate changes are the current justification; the incident is one clause. Pointer is vague ("INCIDENT entry") — grep finds 2026-09-01 material in the archive, so if a citation is kept it should name a locatable heading, not "INCIDENT entry"	yes
49	bootstrap/flux/bootstrap.sh:84-86	"see ./components/kustomization.yaml and the 2026-09-01 INCIDENT entry in DECISIONS-LOG.md"	historical	rewrite to keep only the cross-reference to ./components/kustomization.yaml, which is checkable; drop the archive citation (duplicate of #48)	yes
50	bootstrap/sops/secret-templates/pia-custom-ovpn.yaml.example:6	See DECISIONS-LOG "Phase 3 VPN — custom .ovpn"	ambiguous	operator call. The target does exist (10 hits for "Phase 3 VPN" in the archive), so this is a working pointer of the discouraged form. Keep, or repoint if a decisions/ entry is written. Cited by path+line only; no content quoted (secret-adjacent .example template)	no (*.sops.yaml.example is not matched by **/*.sops.yaml)

Remaining candidate bootstrap/flux/bootstrap.sh:122 ("a patch target that no longer exists after a Flux…") examined — not a finding, it describes current failure behaviour.

platform-config/ — 3 candidates, 3 listed (FULL coverage). SENSITIVE (platform-config/kustomization.yaml)

#	path:lines	comment (gist)	class	action	sensitive
51	platform-config/kustomization.yaml:8	"See clusters/base/platform-config.yaml + DECISIONS-LOG."	historical	rewrite to keep the checkable half (clusters/base/platform-config.yaml) and drop the bare, untargeted DECISIONS-LOG reference — it names no entry and cannot be resolved	yes
52	platform-config/kustomization.yaml:93	"Invisible on dev, whose CDI CRDs have existed for months. See DECISIONS-LOG 2026-09-05."	load-bearing	rewrite. "THE RULE" at :95-96 is the keeper; the dev-invisibility observation is stale (dev is decommissioned — see finding #40) and should go	yes
53	platform-config/kustomization.yaml:167	"headlamp: httproute MOVED OUT … Keeping it here … meant a headlamp crashloop stalled platform-config. See DECISIONS-LOG 'Headlamp gating stall'."	historical	rewrite to the present-tense statement of where the HTTPRoute lives now; dead pointer, see the dangling-pointer section	yes

apps/vms/ — 3 candidates, 2 listed (FULL coverage). Hand-authored, NOT generated

#	path:lines	comment (gist)	class	action	sensitive
54	apps/vms/unifi/50-service-l4.yaml:27-78	"CORRECTED 2026-09-14 after an 8-DAY LAN OUTAGE … This file used to say Local … BOTH HALVES OF THAT WERE FALSE" — ~52 lines	load-bearing	rewrite, same treatment as #1 (its near-twin). Keep: L2 announcer is not backend-aware; KubeVirt masquerade already destroyed the client IP so Cluster costs nothing here; cluster subsumes remote-node so do NOT "fix" the CNP; no loadBalancerSourceRanges deliberately. Drop the outage story	no
55	apps/vms/unifi/30-virtualmachine.yaml:119, 40-networkpolicy.yaml:36	# legacy Network UI (still served), # legacy UI on port 8443	load-bearing	keep. "legacy" here is the upstream product's own name for a port that is still served — it describes current behaviour, not history. Listed so a keyword-driven sweep does not delete it	no

---

Per-directory counts (findings listed above)

Directory	historical	load-bearing	ambiguous	total	sensitive-path?
platform/	2	7	0	9	no (except kyverno/**)
infra/	3	5	0	8	no (except gitea/**)
catalog/	4	3	0	7	no
clusters/	2	5	0	7	yes
ci/	3	3	0	6	yes
conformance/	3	2	0	5	yes
.gitea/	2	3	0	5	yes
bootstrap/	1	1	1	3	yes (×2)
platform-config/	2	1	0	3	yes
apps/vms/	0	2	0	2	no
total	22	32	1	55	29 of 55 sensitive

The ambiguous bucket is thin because I could rule on most rows against the reporter's calibration. Two groups I am deliberately not ruling on and want the operator's call:

1. ci/tests/*.test.sh headers (5 files). These say things like "this suite exists because ci/gate.sh used to set BLOCK=1 for a FAILED stage but…" and "a stage was added to gate.sh by PR #17, never added here, so 15 of 50 assertions failed on main". For a regression test, the regression it guards is arguably the test's subject rather than fluff. Ruling these historical would strip the only record of what each assertion is for. Operator to decide.
2. In-repo README.md prose (platform/vpn-egress/README.md:91, platform/crafty/README.md:52, infra/devcontainer/README.md:126, infra/gitea/README.md:253). These are documentation, not source comments, so arguably already in the place the issue wants narrative to live. I did not audit them as findings.

Suggested order for the follow-up PRs — cheapest and least sensitive first

1. catalog/ + re-render apps/wave-* (7 findings, not sensitive). Highest value per unit of review: it also fixes the generated copies under apps/wave-*. Must re-run python3 catalog/render.py --all catalog -o apps --wave-layout --no-image-automation, drop the not-onboarded outputs, and commit the goldens, or render-golden fails.
2. platform/ excluding kyverno/** (9 findings, not sensitive). Biggest residual too (107 candidates) — worth splitting by component (monitoring/, longhorn/, crafty/, headlamp/, vpn-egress/) into 2–3 PRs rather than one sweep.
3. infra/ excluding gitea/** (8 findings, not sensitive). ansible/roles/* is most of it; infra/plex/claim-ship.sh:29-32 (#10) is a clean one-paragraph deletion and a good first commit.
4. apps/vms/ (2 findings, not sensitive). Self-contained; #54 is the twin of #1, so do it right after platform/crafty/service-l4.yaml while the reasoning is fresh.
5. The dangling-pointer fix (18 files, crosses sensitive and non-sensitive). Either write one decisions/ entry for the leaf-gating lesson and repoint all 18, or drop the citations. Doing this before steps 6–9 means those PRs do not have to re-litigate it.
6. platform-config/kustomization.yaml (3 findings, sensitive). One file, three edits — the smallest possible sensitive-path PR, so it is the cheapest review.
7. bootstrap/ (3 findings, sensitive). Two files.
8. .gitea/ (5 findings, sensitive). Keep #27 (gate.yml:118-123) in its own commit — it documents a live, deliberate tolerance-widening and is the one most likely to be misread as a behaviour change.
9. ci/ then clusters/ then conformance/ (6 + 7 + 5, all sensitive, largest residuals). Last, because each needs a non-author approving review or an operator /approve-override, and because ci/ edits touch the thing doing the approving.

A note on review cost: 29 of the 55 findings are on sensitive paths, so roughly half this work cannot merge on a green gate alone. Steps 1–4 (26 findings) are the portion that can. That is the argument for the ordering above.

What I verified

Everything below was run in this container, offline, against the tree at 466f63e on branch docs/source-comment-audit.

• The tree layout, against the brief's believed list. git ls-files → 855 tracked files. The brief's list was broadly right but differs in three ways worth recording: (a) there is no scripts/ and no tools/ directory; (b) docs/ does exist in this repo (9 files: docs/BULK-NFS-STORAGE.md + docs/plans/*.md) and is not the sibling spec repo's docs/ — I audited neither, since both are prose, not source comments; (c) platform-config-cdi/ exists as a separate top-level directory (1 file, 0 candidate hits).
• Candidate volume, per directory, with the keyword sweep quoted verbatim above: platform/ 107 hits / 56 files, infra/ 75 / 44, conformance/ 80 / 40 (72 excluding the 8 in conformance/runs/), clusters/ 43 / 19, ci/ 42 / 15, catalog/ 39 / 9, apps/ 18 (15 under the generated apps/wave-*, 3 under hand-authored apps/vms/), runbooks/ 11, .gitea/ 10 / 5, bootstrap/ 4 / 3, platform-config/ 3 / 1, platform-config-cdi/ 0. Total ≈ 420 candidate hits in ≈190 files.
• apps/wave-* is generated and byte-enforced. Read ci/render-golden.sh: the canonical command is at :21/:120, and the comparison loop at :136-150 iterates the rendered output, requiring each golden to exist and to be byte-identical, exit 1 on any diff. Confirmed the duplication concretely: the "HARDENED (was a silent first-boot RACE)" paragraph appears at both catalog/gitea.yaml:100 and apps/wave-0/gitea.yaml:130. Confirmed apps/vms/ is not produced by that loop (the renderer emits wave-N/ paths only), so it is hand-authored and directly editable.
• The dangling pointer. grep -ci "gating stall" DECISIONS-LOG.md → 0; grep -ci "Headlamp gating stall" DECISIONS-LOG.md → 0; grep -ril "gating stall" decisions/ → no output; git grep -il "gating stall" → 18 files. So 18 files cite a rationale entry that exists in neither the frozen archive nor decisions/.
• Every decisions/...md pointer I recommend exists. Checked against ls decisions/ (71 entries + README.md + ARCHIVE.sha256): 2026-10-18-keycloak-passkey-reconciler.md, 2026-10-06-new-peer-ignores-template-comments.md, 2026-10-01-quicksync-via-device-plugin.md, 2026-10-03-cilium-cgroup-hostroot.md, 2026-10-05-oauth2-sidecar-scrape-verified.md, 2026-10-07-bulk-nfs-truenas.md, 2026-10-30-renovate-auth.md, 2026-09-29-decisions-log-conflict-free.md, 2026-10-04-pihole-multi-replica.md, 2026-10-04-pihole-declare-state.md — all present. I recommend no pointer target I did not list in ls output.
• Archive-citation targets, for the rows where I say a DECISIONS-LOG pointer does or does not resolve: "Remote Path" 5 hits, "Phase 3 VPN" 10, "Phase 4 image-automation" 1, F-DNS1 3, F-OPS1 1, 2026-09-01 6 — all present in the 5,733-line archive. "Headlamp gating stall" 0, as above.
• The sensitive-path column is from the policy data, not the brief. Read infra/gitea/approval-policy.json: sensitive_paths = ci/**, .gitea/**, conformance/**, clusters/**, bootstrap/**, infra/gitea/**, platform/kyverno/**, platform-config/kustomization.yaml, .sops.yaml, **/*.sops.yaml, **/rbac.yaml, CLAUDE.md. This matches the brief, and adds the root .sops.yaml and the explicit **/ glob forms. Note **/*.sops.yaml does not match *.sops.yaml.example, which is why findings #50 and the platform/headlamp/...sops.yaml.example row are marked not sensitive.
• Every cited path:line-range was opened and read, not matched and trusted. All 55 rows quote text I read with sed -n at the line numbers given, at 466f63e. Line numbers are from that commit and this PR changes no source file, so they remain valid on merge.
• Secret-adjacent files: no *.sops.yaml content is quoted anywhere in this report, and no .data/.stringData value or key name appears. The two .sops.yaml.example rows (#50, and platform/headlamp/headlamp-oidc-credentials.sops.yaml.example:15 in the unlisted set) are cited by path and line only. I ran no sops -d.
• The gate. Result recorded in the PR; see "What I did NOT verify" for the stages that cannot run in this container.
• git diff --stat against main: one added file, decisions/2026-10-31-source-comment-audit.md, and nothing else — which is the brief's "done means" condition.

What I did NOT verify

• Anything about the live cluster. I hold no cluster credentials — no kubeconfig and no ServiceAccount token is mounted in this container, so kubectl cannot work here. This audit is a pure text analysis of the tree and makes no claim about the running platform. That is appropriate (no behaviour changes), but it also means every factual assertion quoted inside the comments I audited — the measured Cilium lease holders, the longhorn_volume_robustness series counts, the 192.168.2.30 NFS reachability, the k3s version, the oauth2-proxy scrape targets — is unverified by me. I classified comments by what they talk about, not by whether their measurements are still true. A rewrite PR that restates one of those measurements as current fact should re-measure it first.
• The two gate stages that cannot run in this container, per the environment notes and CLAUDE.md §3: spec-immutability (the sibling spec repo has no git remote and is not reachable from the cluster) and gitea-settings (needs SETTINGS_API_TOKEN, which I deliberately do not hold). So R-TEST-06 is not actually exercised on this run.
• ~365 of the ~420 candidate hits were not examined. The per-directory table marks which directories are full and which are sampled. For platform/, infra/, conformance/, clusters/, ci/ and catalog/ the listed findings are representative, not complete, and the historical : load-bearing ratio I report (22:32) is measured over the 55 rows I judged, not over the whole corpus — do not project it onto the residual.
• The keyword sweep is not a complete detector. It finds English phrasings I thought of. Historical narrative that avoids all of them — a dated war story with no "used to", a stale rationale phrased entirely in the present tense, a comment that is simply wrong about today — is invisible to it. The most dangerous category (a confidently present-tense comment describing a superseded state) is precisely the one this method cannot find. A complete audit needs a reader per directory, not a grep.
• runbooks/ (11 candidate hits), the repo-root markdown (README.md, DESIGN-waves.md), and the in-repo docs/ tree were not audited. They are prose documentation rather than source comments, so they fall outside the reporter's wording — but CLAUDE.md §1 already records that runbooks/ contains stale git push origin main instructions, so there is known stale narrative there that this audit does not cover.
• The sibling spec repo (R-* requirements, ADRs) was not read or assessed at all — it is not present in this container and is human-owned and immutable to agents (R-TEST-06). Nothing here proposes a change to it. Where a comment cites a spec document (e.g. docs/06/R-STATE-01 in finding #44), I did not verify that the citation resolves.
• I did not verify that any recommended rewrite is correct, only that the current comment is historical. Each "rewrite" row names what I believe is the load-bearing residue; the engineer doing the pruning must confirm that residue is still true before writing it as present-tense fact. I wrote no replacement text.
• Whether the operator agrees with my historical / load-bearing line. I applied the calibration from issue #97 literally plus the brief's one carve-out. The 22:32 split is a judgement call, and the two groups in the ambiguous discussion above are explicitly unresolved and need a human ruling before the ci/tests/ and README rows are touched.
• conformance/runs/*/run.log and apps/wave-* were excluded by my own judgement, on the structural grounds given (archived evidence; gate-enforced goldens). The operator has not confirmed either exclusion.
• Nothing here traces to an R-* requirement, deliberately — this is housekeeping, per the brief. I did not attempt to attribute one, and I did not check whether ci/touched-requirements.sh expects an attribution for a decisions/-only change.