docs audit: one owner per fact, real OKF compliance, human-readable pages #64

Closed
opened 2026-10-21 02:07:58 -07:00 by dank · 1 comment
Owner

Machine census of the 97-page bundle (kb-lint and kb-coverage are already green, so the mechanical gates are not the problem):

  • 53 Obsidian [[wikilinks]] in 17 pages — not OKF links. kb-lint resolves them Obsidian-style instead of rejecting them, so they never trip the link gate and an external OKF consumer sees plain text where a link should be.
  • 34 duplicated H2 section titles across pages, several carrying the same fact twice (ghostty custom shaders, gitea boot persistence, niri vs ghostty keybindings, agentic-web-research "The finish rule", node-js vs sdlc monorepos).
  • 22 pages stamped verified: 2026-08-28, several of them fleet-fact pages.
  • tags present on 22 of 76 concept pages while references/okf-spec.md claims tags discipline; nothing in the toolchain consumes either field.
  • 12 pages with external links and no # Citations; 2 stray TODO/FIXME markers; 1 index entry with no description.
  • Readability hot spots: 75 lines over 120 characters in research/secrets-for-agents.md, 58 in research/chezmoi-evaluation.md, walls of 700+ character paragraphs in 8 pages.

Workstreams

  1. Dedupe — one fact, one owner; the loser becomes a pointer. Per-cluster scout ledgers, every verdict re-checked against the file, the tests and log.md before anything moves.
  2. OKF compliance — wikilinks converted to real links (open decision: whether to also forbid them in kb-lint, which would replace the two tests that pin the current tolerance), citations filled, frontmatter claims made true. Linter hardening already landed: 4735702 — a markdown link may no longer resolve into .AGENTTRASH/, incident #57 in markdown clothing.
  3. Readability — long lines and wall paragraphs broken for a human reader; tables where a table is the shape.
  4. Purpose test — measured numbers for hardware or models that are not deployed get destroyed, not archived.

cwd: /home/blank/.omp/wt/wt-20261019-125509-7c8a99d · session: 01a155bb-6474-7366-be9d-629f74af0e05

Machine census of the 97-page bundle (`kb-lint` and `kb-coverage` are already green, so the mechanical gates are not the problem): - 53 Obsidian `[[wikilinks]]` in 17 pages — not OKF links. `kb-lint` resolves them Obsidian-style instead of rejecting them, so they never trip the link gate and an external OKF consumer sees plain text where a link should be. - 34 duplicated H2 section titles across pages, several carrying the same fact twice (ghostty custom shaders, gitea boot persistence, niri vs ghostty keybindings, agentic-web-research "The finish rule", node-js vs sdlc monorepos). - 22 pages stamped `verified: 2026-08-28`, several of them fleet-fact pages. - `tags` present on 22 of 76 concept pages while `references/okf-spec.md` claims tags discipline; nothing in the toolchain consumes either field. - 12 pages with external links and no `# Citations`; 2 stray TODO/FIXME markers; 1 index entry with no description. - Readability hot spots: 75 lines over 120 characters in `research/secrets-for-agents.md`, 58 in `research/chezmoi-evaluation.md`, walls of 700+ character paragraphs in 8 pages. ## Workstreams 1. **Dedupe** — one fact, one owner; the loser becomes a pointer. Per-cluster scout ledgers, every verdict re-checked against the file, the tests and `log.md` before anything moves. 2. **OKF compliance** — wikilinks converted to real links (open decision: whether to also forbid them in `kb-lint`, which would replace the two tests that pin the current tolerance), citations filled, frontmatter claims made true. Linter hardening already landed: `4735702` — a markdown link may no longer resolve into `.AGENTTRASH/`, incident #57 in markdown clothing. 3. **Readability** — long lines and wall paragraphs broken for a human reader; tables where a table is the shape. 4. **Purpose test** — measured numbers for hardware or models that are not deployed get destroyed, not archived. --- cwd: /home/blank/.omp/wt/wt-20261019-125509-7c8a99d · session: 01a155bb-6474-7366-be9d-629f74af0e05
Author
Owner

Campaign ledger — #64 closed by PR #65

Landed in docs(#64): one owner per fact, truth re-read from the boxes, readable pages — merged --no-ff to main on Frank's explicit authorization. 16 commits, 36 files, +612/−612: net zero lines moved, which is the point — the bundle got shorter in one place exactly as much as it got longer in the place that owns the fact.

Ownership moves (loser → owner)

Lost its copy Now owned by What had been duplicated
tools/ghostty/index.md tools/ghostty/configuration.md Custom Shaders options + uniforms list, Default Keybindings table — both strict subsets of the reference
tools/gitea/index.md architecture.md, management.md, data-persistence.md container/unit table, network topology, boot-persistence law, management commands, data layout — while the index's own See Also already named those pages
tools/llama-cpp/index.md tools/llama-cpp/setup.md Docker deployment and the LLAMA_ARG_* env form; setup.md's own intro had always promised them. A CUDA docker run went out with them — the fleet owns no NVIDIA card
agentic-web-research/research-effectiveness.md agentic-search-best-practices.md#the-finish-rule the stop-when-sources-agree rule, stated twice with different stop conditions
log.md the concept pages it now points at laws re-taught inside dated entries

references/okf-maintenance.md now names AGENTS.md as co-owner of the work-log entry law (always-loaded tier), so an editor has to change both instead of learning about the other one later.

Facts re-read from the boxes, not re-derived

Page Was Is Read with
system/dankserver.md 8C/16T 8 cores, 8 threads — SMT off; do not plan for 16 nproc, /proc/cpuinfo siblings
system/dankserver.md frank-medium masked unit absent from the unit list; masking implies a file to unmask systemctl list-unit-files
system/network.md Pi-hole missing from the DNS-server list 192.168.0.143 is a client DNS server; router 192.168.0.1 is not resolvectl status
system/dankclaw.md volatile slot/ctx math copied from engine flags model, endpoint, engine family, GPU + a pointer to the serverAppConfigs vault for exact KV/ctx numbers podman ps, unit descriptions, lspci, free -g
agentic-web-research/searxng-tuning.md "388 engine entries" 385 upstream today; the count moves weekly, so it is now a size class and /config is named the only authority for what an instance loads (fleet: 262) upstream settings.yml, live /config
tools/niri/displays.md wlr-randr listed as installed not installed (pacman -Qs wlr matches nothing; grim/slurp absent too) pacman -Qs, command -v

Flagged, deliberately not recorded as state: on 2026-10-21 :7770 on dankclaw answered /v1/models while frank-dragoon.service sat inactive with Result=exit-code — a container was running outside its unit. The pages now say a successful curl /v1/models is not proof the unit is healthy. No production unit was stopped, masked, or restarted; the drift itself is yours.

Rejected findings, with evidence

Proposal Why it died
Delete/archive pi/** as dead weight pi/index.md carries an honest archive banner dated 2026-10-18 and routes survivors to /core/**; pi/packages/index.md is the required index for its five children — deleting it fails the linter
Drop gitea/management.md incident log as archival the incident is the law (quadlet [Install] + linger); it changes behaviour next reboot
Add # Citations to six skills/ pages the bundle's convention is resource: frontmatter (12 pages; # Citations on 3). skills/skills-cli.md already had it; skills/ecosystem.md gained it — the only real hit
Merge node-js.md's monorepo sentence into sdlc.md both readers are legitimate: the language page answers "what do I use here", the SDLC page is the cross-language comparison. A one-sentence overlap that cannot drift into a contradiction is not worth a hop
core/statusline.md corrections list is dead weight five strikethroughs are the audit trail that stops the next reader re-deriving the same misreads

Fan-out, and why most scout rows never reached a diff

Seven audit subagents on one local endpoint produced nothing for seventeen minutes: task.maxConcurrency is 2, so five were queued while two thrashed, and proc:// labels a queued task running. Cancelling five let the survivors land within minutes.

The checkable-false share of their ledgers was large, which is the campaign's real lesson:

  • three pages "missing an H1" — skills/index.md, pi/skills.md, skills/issue-tracker.md all have one
  • a 215-line omp-docs/AGENTS.md with missing directory entries — the file does not exist
  • core/settings.md "wikilinks + 700-char wall" — zero [[wikilinks]], no line over 300 chars; commit 62a70ca that same morning had already fixed it
  • core/subagent-limits.md "superseded by runtime config" — agent/config.yml:164-166 still carries maxRuntimeMs: 1800000, softRequestBudget: 120, maxRecursionDepth: 1, exactly as the page states
  • delivery failure: one scout yielded against a zero-byte local:// ledger, three more wrote filenames containing their own serialized parameter block, so their ledgers existed only under names no caller could request. Reported to xd://report_issue.

Nothing entered the diff until it was re-read against the file it accused.

Also in this branch, not duplication work

4735702 makes kb-lint fail a markdown link that resolves into the quarantine, with tests/kb-lint.bats coverage — the linter had been blessing links into archived territory. de7dd6f fixes five See Also links with empty text (- ](index.md)), invisible as a defect because a rendered empty bullet looks like a style choice.

Gates on every commit: scripts/kb-lint.sh 0 violations, scripts/kb-coverage.py 0 issues, full bats tests/ at pre-push, secret gate armed (no --no-verify anywhere in the branch).


cwd: /home/blank/.omp/wt/wt-20261019-125509-7c8a99d · session: 01a155bb-6474-7366-be9d-629f74af0e05

## Campaign ledger — #64 closed by PR #65 Landed in [`docs(#64): one owner per fact, truth re-read from the boxes, readable pages`](http://192.168.0.143:3000/dank/command-center/pulls/65) — merged `--no-ff` to `main` on Frank's explicit authorization. 16 commits, 36 files, `+612/−612`: net zero lines moved, which is the point — the bundle got shorter in one place exactly as much as it got longer in the place that owns the fact. ### Ownership moves (loser → owner) | Lost its copy | Now owned by | What had been duplicated | |---|---|---| | `tools/ghostty/index.md` | `tools/ghostty/configuration.md` | Custom Shaders options + uniforms list, Default Keybindings table — both strict subsets of the reference | | `tools/gitea/index.md` | `architecture.md`, `management.md`, `data-persistence.md` | container/unit table, network topology, boot-persistence law, management commands, data layout — while the index's own *See Also* already named those pages | | `tools/llama-cpp/index.md` | `tools/llama-cpp/setup.md` | Docker deployment and the `LLAMA_ARG_*` env form; `setup.md`'s own intro had always promised them. A CUDA `docker run` went out with them — the fleet owns no NVIDIA card | | `agentic-web-research/research-effectiveness.md` | `agentic-search-best-practices.md#the-finish-rule` | the stop-when-sources-agree rule, stated twice with different stop conditions | | `log.md` | the concept pages it now points at | laws re-taught inside dated entries | `references/okf-maintenance.md` now names `AGENTS.md` as co-owner of the work-log entry law (always-loaded tier), so an editor has to change both instead of learning about the other one later. ### Facts re-read from the boxes, not re-derived | Page | Was | Is | Read with | |---|---|---|---| | `system/dankserver.md` | 8C/16T | 8 cores, **8 threads** — SMT off; do not plan for 16 | `nproc`, `/proc/cpuinfo` siblings | | `system/dankserver.md` | `frank-medium` masked | unit **absent** from the unit list; masking implies a file to unmask | `systemctl list-unit-files` | | `system/network.md` | Pi-hole missing from the DNS-server list | `192.168.0.143` is a client DNS server; router `192.168.0.1` is not | `resolvectl status` | | `system/dankclaw.md` | volatile slot/ctx math copied from engine flags | model, endpoint, engine family, GPU + a pointer to the `serverAppConfigs` vault for exact KV/ctx numbers | `podman ps`, unit descriptions, `lspci`, `free -g` | | `agentic-web-research/searxng-tuning.md` | "388 engine entries" | 385 upstream today; **the count moves weekly**, so it is now a size class and `/config` is named the only authority for what an instance loads (fleet: 262) | upstream `settings.yml`, live `/config` | | `tools/niri/displays.md` | `wlr-randr` listed as installed | not installed (`pacman -Qs wlr` matches nothing; `grim`/`slurp` absent too) | `pacman -Qs`, `command -v` | **Flagged, deliberately not recorded as state:** on 2026-10-21 `:7770` on dankclaw answered `/v1/models` while `frank-dragoon.service` sat inactive with `Result=exit-code` — a container was running outside its unit. The pages now say a successful `curl /v1/models` is not proof the unit is healthy. No production unit was stopped, masked, or restarted; the drift itself is yours. ### Rejected findings, with evidence | Proposal | Why it died | |---|---| | Delete/archive `pi/**` as dead weight | `pi/index.md` carries an honest archive banner dated 2026-10-18 and routes survivors to `/core/**`; `pi/packages/index.md` is the required index for its five children — deleting it fails the linter | | Drop `gitea/management.md` incident log as archival | the incident *is* the law (quadlet `[Install]` + linger); it changes behaviour next reboot | | Add `# Citations` to six `skills/` pages | the bundle's convention is `resource:` frontmatter (12 pages; `# Citations` on 3). `skills/skills-cli.md` already had it; `skills/ecosystem.md` gained it — the only real hit | | Merge `node-js.md`'s monorepo sentence into `sdlc.md` | both readers are legitimate: the language page answers "what do I use here", the SDLC page is the cross-language comparison. A one-sentence overlap that cannot drift into a contradiction is not worth a hop | | `core/statusline.md` corrections list is dead weight | five strikethroughs are the audit trail that stops the next reader re-deriving the same misreads | ### Fan-out, and why most scout rows never reached a diff Seven audit subagents on one local endpoint produced nothing for seventeen minutes: `task.maxConcurrency` is 2, so five were queued while two thrashed, and `proc://` labels a queued task `running`. Cancelling five let the survivors land within minutes. The checkable-false share of their ledgers was large, which is the campaign's real lesson: - three pages "missing an H1" — `skills/index.md`, `pi/skills.md`, `skills/issue-tracker.md` all have one - a 215-line `omp-docs/AGENTS.md` with missing directory entries — the file does not exist - `core/settings.md` "wikilinks + 700-char wall" — zero `[[wikilinks]]`, no line over 300 chars; commit `62a70ca` that same morning had already fixed it - `core/subagent-limits.md` "superseded by runtime config" — `agent/config.yml:164-166` still carries `maxRuntimeMs: 1800000`, `softRequestBudget: 120`, `maxRecursionDepth: 1`, exactly as the page states - delivery failure: one scout yielded against a zero-byte `local://` ledger, three more wrote filenames containing their own serialized parameter block, so their ledgers existed only under names no caller could request. Reported to `xd://report_issue`. Nothing entered the diff until it was re-read against the file it accused. ### Also in this branch, not duplication work `4735702` makes `kb-lint` fail a markdown link that resolves into the quarantine, with `tests/kb-lint.bats` coverage — the linter had been blessing links into archived territory. `de7dd6f` fixes five See Also links with **empty text** (`- ](index.md)`), invisible as a defect because a rendered empty bullet looks like a style choice. Gates on every commit: `scripts/kb-lint.sh` 0 violations, `scripts/kb-coverage.py` 0 issues, full `bats tests/` at pre-push, secret gate armed (no `--no-verify` anywhere in the branch). --- cwd: /home/blank/.omp/wt/wt-20261019-125509-7c8a99d · session: 01a155bb-6474-7366-be9d-629f74af0e05
dank closed this issue 2026-10-21 02:45:53 -07:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: dank/command-center#64