Home-Network/home-network-k3s-impl
2
0 Fork 0
Code Issues 2 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs: Massive amounts of historical data #101

Open
pm-agent wants to merge 1 commits from docs/source-comment-audit into main
pull from: docs/source-comment-audit
merge into: Home-Network:main
Conversation 0 Commits 1 Files Changed 1
+441
pm-agent commented 2026-10-31 17:26:37 +00:00
Member
Copy link
Copy source

Closes #97.

Source-comment audit — recommended changes (read-only; no source file touched)

The audit you asked for is in one new file: decisions/2026-10-31-source-comment-audit.md.
git diff --stat against main is exactly one added file and nothing else. Every finding
cites path:line-range and is checkable offline by opening that line.

Your premise holds — with one number worth pricing in

I found ~420 candidate hits across ~190 files, so the "massive amounts" reading is right.
But of the 55 findings I judged in detail, 22 are genuinely historical and 32 are
load-bearing — phrased as history, yet the only record of a current non-obvious
constraint. Those get a rewrite, not a deletion. A mechanical "delete the history" sweep
would strip real constraints, which is the main reason I'd keep the pruning per-directory
and individually rejectable.

Counts

Directory candidates coverage findings sensitive path?
platform/ 107 sampled 9 no (except kyverno/**)
infra/ 75 sampled 8 no (except gitea/**)
conformance/ (excl. runs/) 72 sampled 5 yes
clusters/ 43 sampled 7 yes
ci/ 42 sampled 6 yes
catalog/ 39 sampled 7 no
.gitea/ 10 full 5 yes
bootstrap/ 4 full 3 yes
platform-config/ 3 full 3 yes
apps/vms/ 3 full 2 no
apps/wave-* 15 excluded (generated) 0 no
conformance/runs/ 8 excluded (archived logs) 0 yes
runbooks/ 11 not audited (prose docs) 0 no

This is a sample, not an exhaustive inventory — your brief capped it at ~50 findings and
I'd rather say so than pad. Fully covered: .gitea/, bootstrap/, platform-config/,
apps/vms/. Sampled: platform/, infra/, conformance/, clusters/, ci/, catalog/.
Roughly 365 candidate hits remain unexamined (candidate ≠ finding — precision on what I
read was under half, so the real residual is smaller, but it is still in the low hundreds).
29 of the 55 findings sit on sensitive paths, so about half this work needs your review
no matter how cosmetic the diff is.

Three things I found that change how the pruning must be done

1. apps/wave-0/1/2 are generated — do not hand-edit comments there. They're goldens
from catalog/render.py, and ci/render-golden.sh:136-150 byte-compares every one. Any
hand-edit is a hard gate FAIL. The 15 candidate hits there are copies of comments whose
source is catalog/*.yaml (e.g. apps/wave-0/gitea.yaml:130 is the rendered form of
catalog/gitea.yaml:100). Fix the catalog source and re-render.

2. A dangling pointer, replicated across 18 files. 18 files cite
DECISIONS-LOG: "Headlamp gating stall" as their rationale — and no such entry exists:
grep -ci "gating stall" DECISIONS-LOG.md → 0, and it's nowhere in decisions/ either.
This is the audit's warning about its own remedy: "replace the narrative with a pointer" only
helps if the target exists. decisions/<file>.md is checkable; DECISIONS-LOG: "<title>" is
not. Your call: write one real decisions/ entry for the leaf-gating lesson and repoint
all 18, or drop the citations. Worth doing before the per-directory PRs so they don't each
re-litigate it. (Nothing in my report recommends a pointer target I didn't confirm exists.)

3. conformance/runs/*/run.log (18 files) are archived evidence, not source — the
comments in them are copies of test bodies as they stood at run time. I excluded them;
please confirm you agree.

The clearest examples

  1. platform/crafty/service-l4.yaml:33-91 — 58 lines of "CORRECTED 2026-09-14 after an 8-DAY
    LAN OUTAGE… this file used to say Local". Load-bearing → rewrite: keep "Cilium's L2
    announcer isn't backend-aware", "SNAT loses the client IP so use /ban not /ban-ip" and
    "cluster subsumes remote-node, do NOT 'fix' the CNP". Drop the outage story.
    apps/vms/unifi/50-service-l4.yaml:27-78 is its ~52-line twin.
  2. ci/decisions-log.sh:5-23 — 19 lines reproducing the four-PR conflict table verbatim
    from decisions/README.md:9-30    , which the comment itself already cites. Replace with
    the pointer     it already has.
  3. catalog/qbittorrent.yaml:7-12 — "DELIVERED 2026-09-12 (the deferral below is CLOSED;
    kept for the record)". Self-describes as exactly what you're objecting to. Delete.
  4. clusters/prod/kustomization.yaml:335-351 — three completed, unrepeatable DNS flip
    prerequisites ("dev's 18 A records released", "18 legacy TXT entries deleted by hand").
    Rewrite, keeping only the still-true note about the zone's wildcards.
  5. catalog/qbittorrent.yaml:141-151 — "It USED to be a doubled-dollar expansion… that
    MISDIAGNOSIS is preserved in this service's own marker log at 2026-09-13T05:35Z".
    Rewrite to "PORT is a literal; a literal cannot be mangled by envsubst" — the war
    story is already preserved where the comment says it is.
  6. platform/longhorn/helmrelease.yaml:249-254 — "CORRECTION, re-measured later the same
    day: the line originally recorded here read…". Delete; the correct reading is three
    lines above it.
  7. conformance/.../bulk-tier-distinct-from-replicated/check.sh:447 — the same "It used to
    assert … ci/l0.sh carried a hand-written UNCONDITIONAL stage" paragraph is duplicated
    verbatim in 3 check.sh files    . One small PR, identical edit ×3.
  8. infra/plex/claim-ship.sh:29-32 — "Branch prefix is now cosmetic. It used to matter…".
    Delete; the live trigger set is already in .gitea/workflows/gate.yml and CLAUDE.md §4.
  9. Counter-example, deliberately listed so a keyword sweep doesn't eat it:
    apps/vms/unifi/30-virtualmachine.yaml:119 # legacy Network UI (still served) —
    "legacy" is the vendor's own name for a port that still serves. Keep. Same for
    catalog/jackett.yaml:73, a dated version floor.
  10. The good pattern already in the tree: catalog/pihole.yaml:210 and :218 are already
    reduced to see decisions/2026-10-04-pihole-multi-replica.md / -pihole-declare-state.md.
    That's the shape I'd converge everything on.

Proposed PR order — cheapest and least sensitive first

  1. catalog/ + re-render apps/wave-* (7, not sensitive) — best value: also fixes the
    generated copies.
  2. platform/ excl. kyverno/** (9, not sensitive) — biggest residual; I'd split it by
    component into 2–3 PRs.
  3. infra/ excl. gitea/** (8, not sensitive).
  4. apps/vms/ (2, not sensitive) — do straight after platform/crafty/service-l4.yaml.
  5. The dangling-pointer fix (18 files) — before the sensitive PRs below.
  6. platform-config/kustomization.yaml (3, sensitive) — one file, three edits: the
    smallest possible sensitive-path review.
  7. bootstrap/ (3, sensitive).
  8. .gitea/ (5, sensitive) — keep gate.yml:118-123 in its own commit; it documents a
    live, deliberate tolerance-widening and reads like a behaviour change if buried.
  9. ci/ → clusters/ → conformance/ (6 + 7 + 5, all sensitive) — last, because ci/
    edits touch the thing doing the approving.

Steps 1–4 are 26 findings that can merge on a green gate alone.

Two things I'm not deciding for you

  • ci/tests/*.test.sh headers (5 files) say things like "this suite exists because
    ci/gate.sh used to set BLOCK=1 for a FAILED stage but…". For a regression test, the
    regression it guards is arguably the test's subject, not fluff. Calling these historical
    would strip the only record of what each assertion is for. Your ruling.
  • 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) — documentation, not source
    comments, so arguably already where you want narrative to live. Not audited as findings.

Gate

./ci/gate.sh → rc 3 (UNDETERMINED), with "Stages that did not run:
spec-immutability gitea-settings" — the two expected skips per CLAUDE.md §3
(the sibling spec repo isn't reachable from the cluster, and I deliberately hold no
SETTINGS_API_TOKEN). Nothing failed. Green stages: decisions-log, lint, l0,
render-golden, l1, approval-policy. Not a pass — I'm not rounding rc 3 up.

One note on the gate log: it also prints "TOUCHED-REQUIREMENT SET NOT DETERMINABLE
(on-base) — HEAD is not ahead of origin/main". That's because I run before the commit
exists; it should resolve once the branch is pushed and the PR gate runs with real branch
commits. Worth a glance on the PR run rather than assuming.

What I did not verify, and what I need from you

  • Nothing about the live cluster. I hold no kubeconfig and no ServiceAccount token, so
    kubectl cannot run here. No behaviour changed, so there's nothing to measure — but it
    also means every factual claim quoted inside the comments I audited (lease holders,
    Longhorn series counts, the NFS address, the k3s version) is unverified by me. I
    classified comments by what they talk about, not by whether their measurements still hold.
    Any rewrite that restates one as current fact should re-measure first.
  • R-TEST-06 was not exercised on this run (spec-immutability skipped).
  • The keyword sweep is not a complete detector. It finds phrasings I thought of. A stale
    rationale written confidently in the present tense is invisible to it — and that's the
    most dangerous category. A complete audit needs a reader per directory, not a grep.
  • I wrote no replacement text. Each "rewrite" row names what I believe is the
    load-bearing residue; whoever prunes must confirm it's still true.
  • Asks: (a) confirm the two exclusions (apps/wave-*, conformance/runs/); (b) rule on
    the ci/tests/ and README groups above; (c) decide the dangling-pointer fix (new
    decisions/ entry vs. drop the citations); (d) pick which directories from the order above
    you want briefed first. Your original calibration examples would still sharpen the
    historical/load-bearing line if you have them.

Nothing here traces to an R-* requirement — housekeeping, as you framed it.

Gate run inside the worker (the pinned toolbox, on this exact commit, before the
branch was pushed): exit 3, stages that did not run: spec-immutability gitea-settings.
That is the worker's own run, not this pull request's CI run — read the check on this
pull request for that. A green tick is not proof anything ran; read what executed.

Opened by the PM agent from issue #97. It does not merge its own pull requests.

🤖 Generated with Claude Code

Closes #97. ## Source-comment audit — recommended changes (read-only; no source file touched) The audit you asked for is in one new file: **`decisions/2026-10-31-source-comment-audit.md`**. `git diff --stat` against `main` is exactly one added file and nothing else. Every finding cites `path:line-range` and is checkable offline by opening that line. ### Your premise holds — with one number worth pricing in I found **~420 candidate hits across ~190 files**, so the "massive amounts" reading is right. But of the **55 findings I judged in detail, 22 are genuinely historical and 32 are load-bearing** — phrased as history, yet the only record of a *current* non-obvious constraint. Those get a **rewrite**, not a deletion. A mechanical "delete the history" sweep would strip real constraints, which is the main reason I'd keep the pruning per-directory and individually rejectable. ### Counts | Directory | candidates | coverage | findings | sensitive path? | |---|---|---|---|---| | `platform/` | 107 | sampled | 9 | no (except `kyverno/**`) | | `infra/` | 75 | sampled | 8 | no (except `gitea/**`) | | `conformance/` (excl. `runs/`) | 72 | sampled | 5 | **yes** | | `clusters/` | 43 | sampled | 7 | **yes** | | `ci/` | 42 | sampled | 6 | **yes** | | `catalog/` | 39 | sampled | 7 | no | | `.gitea/` | 10 | **full** | 5 | **yes** | | `bootstrap/` | 4 | **full** | 3 | **yes** | | `platform-config/` | 3 | **full** | 3 | **yes** | | `apps/vms/` | 3 | **full** | 2 | no | | `apps/wave-*` | 15 | excluded (generated) | 0 | no | | `conformance/runs/` | 8 | excluded (archived logs) | 0 | **yes** | | `runbooks/` | 11 | not audited (prose docs) | 0 | no | **This is a sample, not an exhaustive inventory** — your brief capped it at ~50 findings and I'd rather say so than pad. Fully covered: `.gitea/`, `bootstrap/`, `platform-config/`, `apps/vms/`. Sampled: `platform/`, `infra/`, `conformance/`, `clusters/`, `ci/`, `catalog/`. Roughly **365 candidate hits remain unexamined** (candidate ≠ finding — precision on what I read was under half, so the real residual is smaller, but it is still in the low hundreds). **29 of the 55 findings sit on sensitive paths**, so about half this work needs your review no matter how cosmetic the diff is. ### Three things I found that change how the pruning must be done **1. `apps/wave-0/1/2` are generated — do not hand-edit comments there.** They're goldens from `catalog/render.py`, and `ci/render-golden.sh:136-150` byte-compares every one. Any hand-edit is a hard gate FAIL. The 15 candidate hits there are *copies* of comments whose source is `catalog/*.yaml` (e.g. `apps/wave-0/gitea.yaml:130` is the rendered form of `catalog/gitea.yaml:100`). Fix the catalog source and re-render. **2. A dangling pointer, replicated across 18 files.** 18 files cite `DECISIONS-LOG: "Headlamp gating stall"` as their rationale — and **no such entry exists**: `grep -ci "gating stall" DECISIONS-LOG.md` → **0**, and it's nowhere in `decisions/` either. This is the audit's warning about its own remedy: "replace the narrative with a pointer" only helps if the target exists. `decisions/<file>.md` is checkable; `DECISIONS-LOG: "<title>"` is not. **Your call:** write one real `decisions/` entry for the leaf-gating lesson and repoint all 18, or drop the citations. Worth doing before the per-directory PRs so they don't each re-litigate it. (Nothing in my report recommends a pointer target I didn't confirm exists.) **3. `conformance/runs/*/run.log` (18 files) are archived evidence**, not source — the comments in them are copies of test bodies as they stood at run time. I excluded them; please confirm you agree. ### The clearest examples 1. `platform/crafty/service-l4.yaml:33-91` — 58 lines of "CORRECTED 2026-09-14 after an 8-DAY LAN OUTAGE… this file used to say `Local`". **Load-bearing → rewrite:** keep "Cilium's L2 announcer isn't backend-aware", "SNAT loses the client IP so use `/ban` not `/ban-ip`" and "`cluster` subsumes `remote-node`, do NOT 'fix' the CNP". Drop the outage story. `apps/vms/unifi/50-service-l4.yaml:27-78` is its ~52-line twin. 2. `ci/decisions-log.sh:5-23` — 19 lines reproducing the four-PR conflict table **verbatim from `decisions/README.md:9-30`**, which the comment itself already cites. **Replace with the pointer** it already has. 3. `catalog/qbittorrent.yaml:7-12` — "DELIVERED 2026-09-12 (the deferral below is CLOSED; **kept for the record**)". Self-describes as exactly what you're objecting to. **Delete.** 4. `clusters/prod/kustomization.yaml:335-351` — three completed, unrepeatable DNS flip prerequisites ("dev's 18 A records released", "18 legacy TXT entries deleted by hand"). **Rewrite**, keeping only the still-true note about the zone's wildcards. 5. `catalog/qbittorrent.yaml:141-151` — "It USED to be a doubled-dollar expansion… that MISDIAGNOSIS is preserved in this service's own marker log at 2026-09-13T05:35Z". **Rewrite** to "PORT is a literal; a literal cannot be mangled by envsubst" — the war story is already preserved where the comment says it is. 6. `platform/longhorn/helmrelease.yaml:249-254` — "CORRECTION, re-measured later the same day: the line originally recorded here read…". **Delete**; the correct reading is three lines above it. 7. `conformance/.../bulk-tier-distinct-from-replicated/check.sh:447` — the same "It used to assert … `ci/l0.sh` carried a hand-written UNCONDITIONAL stage" paragraph is **duplicated verbatim in 3 check.sh files**. One small PR, identical edit ×3. 8. `infra/plex/claim-ship.sh:29-32` — "Branch prefix is now cosmetic. It used to matter…". **Delete**; the live trigger set is already in `.gitea/workflows/gate.yml` and `CLAUDE.md` §4. 9. **Counter-example, deliberately listed so a keyword sweep doesn't eat it:** `apps/vms/unifi/30-virtualmachine.yaml:119` `# legacy Network UI (still served)` — "legacy" is the vendor's own name for a port that still serves. **Keep.** Same for `catalog/jackett.yaml:73`, a dated version floor. 10. **The good pattern already in the tree:** `catalog/pihole.yaml:210` and `:218` are already reduced to `see decisions/2026-10-04-pihole-multi-replica.md` / `-pihole-declare-state.md`. That's the shape I'd converge everything on. ### Proposed PR order — cheapest and least sensitive first 1. **`catalog/` + re-render `apps/wave-*`** (7, not sensitive) — best value: also fixes the generated copies. 2. **`platform/` excl. `kyverno/**`** (9, not sensitive) — biggest residual; I'd split it by component into 2–3 PRs. 3. **`infra/` excl. `gitea/**`** (8, not sensitive). 4. **`apps/vms/`** (2, not sensitive) — do straight after `platform/crafty/service-l4.yaml`. 5. **The dangling-pointer fix** (18 files) — before the sensitive PRs below. 6. **`platform-config/kustomization.yaml`** (3, sensitive) — one file, three edits: the smallest possible sensitive-path review. 7. **`bootstrap/`** (3, sensitive). 8. **`.gitea/`** (5, sensitive) — keep `gate.yml:118-123` in its own commit; it documents a live, deliberate tolerance-widening and reads like a behaviour change if buried. 9. **`ci/` → `clusters/` → `conformance/`** (6 + 7 + 5, all sensitive) — last, because `ci/` edits touch the thing doing the approving. Steps 1–4 are 26 findings that can merge on a green gate alone. ### Two things I'm not deciding for you - **`ci/tests/*.test.sh` headers** (5 files) say things like "this suite exists because `ci/gate.sh` used to set BLOCK=1 for a FAILED stage but…". For a *regression* test, the regression it guards is arguably the test's subject, not fluff. Calling these historical would strip the only record of what each assertion is for. **Your ruling.** - **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`) — documentation, not source comments, so arguably already where you want narrative to live. Not audited as findings. ### Gate `./ci/gate.sh` → **rc 3 (UNDETERMINED)**, with "Stages that did not run: **spec-immutability gitea-settings**" — the two expected skips per `CLAUDE.md` §3 (the sibling spec repo isn't reachable from the cluster, and I deliberately hold no `SETTINGS_API_TOKEN`). Nothing failed. Green stages: `decisions-log`, `lint`, `l0`, `render-golden`, `l1`, `approval-policy`. **Not a pass** — I'm not rounding rc 3 up. One note on the gate log: it also prints "TOUCHED-REQUIREMENT SET NOT DETERMINABLE (on-base) — HEAD is not ahead of `origin/main`". That's because I run before the commit exists; it should resolve once the branch is pushed and the PR gate runs with real branch commits. Worth a glance on the PR run rather than assuming. ### What I did not verify, and what I need from you - **Nothing about the live cluster.** I hold no kubeconfig and no ServiceAccount token, so `kubectl` cannot run here. No behaviour changed, so there's nothing to measure — but it also means every *factual* claim quoted inside the comments I audited (lease holders, Longhorn series counts, the NFS address, the k3s version) is **unverified by me**. I classified comments by what they talk about, not by whether their measurements still hold. Any rewrite that restates one as current fact should re-measure first. - **R-TEST-06 was not exercised** on this run (`spec-immutability` skipped). - **The keyword sweep is not a complete detector.** It finds phrasings I thought of. A stale rationale written confidently in the *present* tense is invisible to it — and that's the most dangerous category. A complete audit needs a reader per directory, not a grep. - **I wrote no replacement text.** Each "rewrite" row names what I believe is the load-bearing residue; whoever prunes must confirm it's still true. - **Asks:** (a) confirm the two exclusions (`apps/wave-*`, `conformance/runs/`); (b) rule on the `ci/tests/` and README groups above; (c) decide the dangling-pointer fix (new `decisions/` entry vs. drop the citations); (d) pick which directories from the order above you want briefed first. Your original calibration examples would still sharpen the historical/load-bearing line if you have them. Nothing here traces to an `R-*` requirement — housekeeping, as you framed it. --- **Gate run inside the worker** (the pinned toolbox, on this exact commit, before the branch was pushed): exit `3`, stages that did not run: `spec-immutability gitea-settings`. That is the worker's own run, not this pull request's CI run — read the check on this pull request for that. A green tick is not proof anything ran; read what executed. Opened by the PM agent from issue #97. It does not merge its own pull requests. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
pm-agent added 1 commit 2026-10-31 17:26:37 +00:00
docs: Massive amounts of historical data
gate / gate (pull_request) Successful in 2m58s
Details
gate / conformance (pull_request) Has been skipped
Details
f6150b8957 
From Gitea issue #97.

Authored by the PM agent's worker; the merge gate is the approver. Refs #97.

Agent: pm-agent (issue #97, mode implement)
All checks were successful
gate / gate (pull_request) Successful in 2m58s
Required
Details
gate / conformance (pull_request) Has been skipped
Details
Checking for merge conflicts…
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin docs/source-comment-audit:docs/source-comment-audit
git checkout docs/source-comment-audit
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
agent
automated-update
blast-radius
breaking
ci-tooling
dependencies
needs-review
own-image
range-widen
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
gitea-admin jakman85 (Keith Jackson) pm-agent renovate-bot
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Home-Network/home-network-k3s-impl#101