A generated See Also pass left `- ](index.md)` style links on the gitea pages, tools/cachyos.md,
and tools/applications.md. Rendered, an empty-text link is a bullet with nothing clickable in it,
so it reads as a formatting quirk and never as the broken reference it is. All five now name the
page they point at and use the absolute bundle path the spec recommends; the grep that finds them
is recorded in the log so the sweep is repeatable.
Refs #64
The day had three `## 2026-10-21` headings — three logs wearing one date, which is the sprawl the
spec's one-dated-section rule exists to prevent. One date now, one `###` per campaign. `okf-maintenance.md`
states the multi-campaign shape explicitly so nobody has to infer it, and names `AGENTS.md` as the
co-owner of the entry law so an editor changes both.
The new entry records what the dedupe sweep actually taught: an index that restates its own
reference pages becomes the stale authority, and a subagent ledger is a claim until it is re-read
against the file it accuses — most rows returned by the audit fan-out were checkably false, and
half the ledgers never arrived at all. `skills/ecosystem.md` gains the `resource:` frontmatter the
bundle's other externally-sourced pages carry.
Refs #64
The intro carried "388 engine entries" from a 2026-10-19 probe; upstream is at 385 today. The
number moves every week, which makes a precise one a liability in a runbook. The page now states
the size class, names `/config` as the only authority for what an instance loads, and keeps the
fleet's live 262 with today's date.
Refs #64
The chezmoi overview was one 488-character sentence-block; the git-crypt mechanism and verdict
lines were the same shape. Reflowed to ~100 columns with no wording lost, so the pages read the
same in an editor as they do rendered.
Refs #64
The overview page carried `docker run` invocations (including a CUDA variant, on a fleet with no
NVIDIA card left in it) and the `LLAMA_ARG_` environment rule, while `setup.md` — the page whose
own intro promises "build instructions, Docker, and systemd deployment" — carried the Compose
example and the same env form in use. Two places to look, one place to be wrong.
`setup.md` now states the env-prefix rule where the flags live (and why units prefer it: one
flag per line is auditable, a forty-flag command line is not), and the overview keeps only the
API surface and the GGUF format, pointing at the sections that absorbed the rest.
Refs #64
Two independent copies of the same law, and each page cited its own numbers. The finish rule —
stop when independent sources agree, when the retrieval budget is spent, or when every claim is
met; report gaps, never invent a source — stood in full in `agentic-search-best-practices.md`
(with the loop caps: 20 steps, re-plan every 4) and again in `research-effectiveness.md` without
them. The operational page owns it; the measurement page keeps the pointer and the one thing
that is its business, which is that unbounded loops are why "infinite re-search" is a named
failure mode.
`tools/gitea/index.md` was a second copy of its own directory: an architecture table, a
management command table, a data-persistence path table and a boot-persistence paragraph, every
one of them a subset of `architecture.md`, `management.md` and `data-persistence.md` — verified
line by line before cutting, including the two facts that looked unique to the index (the
`dns_enabled: false` default network, the `/opt/gitea` leftover) and turn out to be owned
upstream with more detail. The index now answers "which page owns my question" and gives three
one-line orientation facts. Gitea's live version was re-read while I was in there: still 1.27.3.
Refs #64
`tools/ghostty/index.md` had its own Custom Shaders section and its own eight-row default
keybinding table. `configuration.md` owns both, in more detail, and the copies had already
drifted: the index claimed `ctrl+` raises the font size where the reference's appendix lists
`ctrl+=` / `ctrl++`. An index exists to route a reader to the page that owns the fact; a second
summary of the same facts just guarantees two versions that age differently.
What the index keeps is the routing plus the one fact worth having at hand (`ctrl+shift+,`
reloads the config), and the config-syntax "Key Points" — repeatable options, `option = ""`
resets, `?` optional includes — which the reference never states as a set, only per option.
Refs #64
Three pages described the fleet; two of them still described the pre-September arrangement.
Re-read live on 2026-10-21 (`/v1/models`, `systemctl`, `lspci`, `nproc`, `resolvectl`):
- `system/network.md` called Dankclaw the "large inference model" box and Dankserver the
"small" one — that is the topology from before the RTX 3090 moved in September. The served
ids today are `frank-archon` on Dankserver:7770 (the main model) and `frank-dragoon`
(:7770) + `frank-zealot` (:7771) on Dankclaw. The gateway and the DNS pin were re-read too.
- `system/dankserver.md` claimed `frank-medium` is *masked*: the unit file does not exist
(`is-enabled` answers `not-found`), which is a different fact with a different remedy. And it
claimed 8C/16T: this 7700X exposes **8 threads** (`nproc` = 8), so anything sized for 16 is
sized for a machine that is not this one.
- `system/dankclaw.md` transcribed the engine's slot/KV/context math — `2×262,144 slots over
one 524,288 pool, unquantized f16 K+V, MTP off` — while the live unit says `3x200704 slots
over one 602112 pool, f16 K + q8_0 V, MTP armed`, and dragoon's ctx had moved too. That math
belongs to the serverAppConfigs runbook the page already names: the unit's `ExecStart` is a
wrapper script, so any copy here rots on the next engine change. The page now keeps the
contract — id, unit, port, engine family, which GPU, and how to prove it — and disowns the
numbers, with the reason stated so the next agent does not re-transcribe them.
Also recorded, because it is how this audit nearly missed a stopped service: `curl :7770/v1/models`
answered normally while `frank-dragoon.service` sat `inactive` with `Result=exit-code` — the
container is running outside systemd. A serving port is not a healthy unit. (Flagged for Frank
separately; no production unit was touched.)
Refs #64
Two pages described Dankclaw's search stack from memory, and one of them invented a port.
`searxng-tuning.md` claimed "`:8081` (UI) / `:8082` (JSON API)". Re-probed 2026-10-21: JSON is
served on **8081** (`/search?q=…&format=json` returns results) and **8082 is not SearXNG at
all** — it publishes container port 8085, which is Marreta's nginx, moved off 8080 because
SearXNG owns that port inside the shared namespace. Four containers print the same port list in
`podman ps` because they share gluetun's namespace, which is exactly the detail that gets
mistaken for "the JSON API is on another port". The policy-drift flag now carries today's
reading: `/config` still reports 262 engines and zero disabled, unchanged since 2026-10-19, so
the tuned engine policy is still not live — still an operator decision, still not silently
re-applied.
`vpn-routing.md` gave a mullvad-shaped gluetun example and no fleet shape at all, while the
bundle's own work log says the manual-WireGuard law lives "on concept pages". It lives here now,
read from the running container: `VPN_SERVICE_PROVIDER=custom` + `VPN_TYPE=wireguard` + the
single-peer `WIREGUARD_*` names (`protonvpn` and the plural `WIREGUARD_PEERS_*` family are both
wrong for this image), `FIREWALL_ENABLED_DISABLING_IT_SHOOTS_YOU_IN_YOUR_FOOT=on` — whose name
is the warning that disabling it leaks egress while every check keeps passing — and
`tun0` present. The mullvad block stays as the generic illustration, now labelled as one.
Refs #64
An index is the skim layer: its entries decide whether a reader opens the page, so an entry
that runs 250 characters is a paragraph wearing a bullet. Four entries in `tools/index.md`
(`dotfiles-deploy`, `packages`, `pcie-probe`, `remote-job`) now say what the page is for in one
line and let the page carry the detail — which is the whole argument for progressive disclosure
having an index at all.
`engineering/infra/index.md` pointed at `../sdlc.md` with no description at all; it now carries
the one from that page's frontmatter, like its four siblings.
Refs #64
504 lines, 4,496 words — the log had become the largest page in the bundle, and the reason was
not history: twelve entries dated 2026-10-18 → 2026-10-21 each re-narrated the incident AND
re-stated the law AND pointed at the page that owns the law. Three copies of one fact, dated
three ways. 384 lines / 3,251 words now.
What was cut: the restatements. The refuse-by-default guard belongs to
`tools/pcie-probe.md`, the completion-sentinel law to `tools/remote-job.md`, the verbatim
mode-string law to `tools/niri/displays.md`, the enable-snapshots-a-path trap to
`tools/dotfiles-deploy.md`, the sorted-directive rule to `caddy/caddyfile.md`, the effort-map
contract to `pi/models.md`, the tier law and the footer/`xdg-open` fleet laws to `AGENTS.md`,
and the gate's mechanics to `.githooks/pre-commit` plus its tests — each now named once, from a
short entry.
What was kept deliberately: laws with no other owner anywhere in the bundle. Fail-closed on a
blind `git diff`; a stub that echoes its environment instead of its argument cannot see the bug;
a name is data, never let the shell expand it; extensions must never await work that can exceed
30 s; `systemctl --user enable` snapshots an absolute path; agents never run
sudo/yay/pacman/pkexec (faillock incident, with the reset command); a claim about what the
harness sends is worth exactly its last capture; a number in a page is a claim, not a
measurement. Deleting those would have been the actual loss.
The 2025-08-05 entry is annotated rather than deleted: this repo's history dates that file's
arrival at 2026-08-28 (the OKF rebuild copied it), so 2025-08-05 is a legacy-tree date and the
entry now says so instead of silently contradicting `git log`.
Refs #64
The note in `references/okf-spec.md` claimed the bundle keeps a "`tags` discipline". It does
not: 22 of 76 concept pages carry `tags`, and neither `kb-lint.sh` nor `kb-coverage.py`
reads that field or `verified` — so the note was a claim about intent that an agent would
believe and pay the wrong cost for (adding tags to a page helps no tool, while `verified`
silently does the real work: it is the date someone last re-checked the page against the
fleet, and its absence means nobody ever has).
The note now states the measured usage instead of the aspiration, records the house link
style (bundle-absolute, 99 links already written that way), and says plainly that Obsidian
`[[wikilinks]]` are not OKF links — with the count this bundle had and the date they were
converted. The spec's own repository is now cited under `# Citations`, which the page was
missing while it lectured others about skipping citations.
Refs #64
`key-bindings-syntax.md` told you to run `wev` and read `sym: XXXX` — a placeholder nobody
fills in, for a tool that is not on the machine: `command -v wev` is empty, `pacman -Ss
--sync wev` is empty on CachyOS, and the AUR carries it as `wev-git`. The bind token is an
XKB keysym, and the complete list is already on every box that links libxkbcommon, so the
page now leads with the grep against `/usr/include/xkbcommon/xkbcommon-keysyms.h` (run here:
`a A Escape Left Return Tab`), and keeps `wev` as the "press the key and see" option with its
real package name and where to get it.
`screenshots.md` line 35 read `(FIXME upstream).`, which scans as unfinished work in a page
that is finished: the defect is upstream's, tracked in the two issue links six lines below.
Reworded to say that.
Refs #64
The page explained matcher ordering beautifully and never said where the file lives — so the
next agent hunts for a Caddyfile on the host and finds nothing. Measured on Dankclaw
2026-10-21: Caddy is a rootless Quadlet container (`caddy.container`, a *user* unit, so a
root `systemctl is-active caddy` answers `inactive` and means nothing), its config is
`/etc/caddy/Caddyfile` **inside the container**, `/etc/caddy` does not exist on the host, and
`pgrep -a caddy` prints a config path that no host path satisfies. Version is v2.11.7, which
closes the one version-dependent rule on the page: the leading-`/` `rewrite` form needs
2.8.0+, so the `*` disambiguator is legacy in this fleet's config.
Also: the seven caddyserver.com links sat in a mid-page "Sources:" paragraph. OKF wants
external claims under `# Citations`, so they move there and each entry says which claim it
supports. The validate section now points at the container instead of telling you to run the
validator on a file that is not there.
Refs #64
`[[page|Label]]` is Obsidian syntax, not OKF. `kb-lint` resolves it Obsidian-style — by
filename, anywhere in the bundle — so it has never tripped the link gate, while every other
consumer of the bundle (an OKF renderer, a Gitea wiki export, `grep` for reachability) sees
bracketed text where a link should be. That is how two generated pages ended up with no
inbound link at all and nobody noticed: the my-first link census of the bundle reported them
as orphans because their only inbound edges were wikilinks.
Mechanical conversion, 52 links across 17 pages, each resolved against the same page set
`kb-lint` uses: an explicit `|Label` is kept verbatim, an unlabelled link takes the target's
frontmatter `title`. Targets are emitted bundle-absolute (`/tools/niri/tips.md`), the form
the spec recommends and the form 99 existing links in this bundle already use.
Two links were `[[index]]`, which resolves by filename to 21 pages — the ambiguity that
filename-resolution invites. Both meant their own directory's index, so both are now written
out in full: `/tools/gitea/index.md`, `/tools/niri/index.md`.
The linter still tolerates wikilinks; whether it should reject them outright is an open
question on #64, because that would replace the two tests pinning today's tolerance.
Refs #64
The link-integrity pass ended in `is_file()`, and `.AGENTTRASH/` is a real directory on
this machine: a page pointing at `[x](.AGENTTRASH/gone.md)` passed the gate here and was a
dead link everywhere else, because the quarantine is gitignored. This is incident #57 — the
wikilink resolver resolving `[[log]]` onto a quarantined copy — reproduced in markdown
clothing, which is to say: fixing one resolver while leaving the identical assumption in the
other one is not a fix.
A link that lands inside the bundle must land on a page that belongs to the bundle. A link
that leaves the bundle is still honoured (`tools/live-sync.md` -> `../../AGENTS.md` points at
the operating contract, which is not bundle content and is real on disk). Red test added
first, both link spellings covered; nothing previously green changed.
Refs #64
Two conflicts, both resolved to trunk, both proven content-free for the running
machine before the merge was committed:
- `agent/APPEND_SYSTEM.md` — the checkout's dirty copy and trunk differ in one line
only: #61's trim of the duplicated one-log reasoning, replaced by the owner pointer.
The doctrine text itself is byte-identical on both sides.
- `desk-1-home.kdl` — non-comment lines are byte-identical (`diff` on the stripped
file: no output), so the deployed modes are unchanged: `3440x1440@180.000` ×3 and
`1920x1080@60.001`. What changes is the comment: trunk's carries the measured mode
list (`3440x1440@239.998` exists), the reason 180 is deliberate, and the verbatim
mode-string law — the live copy still asserted "no 240 Hz mode exists", which the
panel contradicts. `niri validate` on the assembled config: valid.
Deployment state after this: the checkout is main, and `agent/memories/**` +
`agent/managed-skills/**` were committed by the heartbeat commit underneath. Refs #60#62
Landing blocker for #61 and #63: the deployment checkout is 12 commits behind and
`merge --ff-only` refuses while tracked paths are dirty. Discard is not available here
(workspace policy: no `checkout`/`stash` on shared state), so the dirt is committed.
- `agent/APPEND_SYSTEM.md`: the point-of-use / one-work-log / PR-link doctrine, already
byte-identical to `origin/main` (`cmp` against the trunk blob: no difference). No new
prose — the commit exists so the trunk merge can proceed.
- `agent/config.yml` and `agent/managed-skills/**`: the machine-live tier the heartbeat
owns (AGENTS.md § Live-sync tiers).
`ALLOW_SECRETS=1` was used, deliberately and after auditing the staged diff by hand: the
only credential-shaped strings in it are two copies of `AKIA0000000000000EXAMPLE` — the
inert all-zero AWS example id — and they appear inside the two skill pages that teach
that exact placeholder shape. This checkout is still running the pre-#61 hook; the merged
gate (value-scoped placeholder filter, `71601f7`) exempts this value, so the refusal
dies with this landing. No `--no-verify` was used: the gate ran and its verdict is
recorded here.
Refs #61
The entry rewrote every effort before the wire: `minimal -> low`, `high -> xhigh`,
`max -> xhigh`, under a comment claiming flash-server rejects anything outside
{xhigh, medium, low}. The engine says otherwise, in its own 400:
reasoning_effort 'maximum' unsupported; use minimal|low|medium|high|xhigh|max|none
and the harness passes an unmapped level through verbatim
(`compat.reasoningEffortMap?.[effort] ?? effort`, read in the pinned `dist/cli.js`). So the
fold protected nothing and silently changed what the caller asked for. The levels are not
cosmetic either — thinking length on one prompt at `max_tokens 2048`: `low` 766 reasoning
tokens, `xhigh` 614, `max` 1049 with the block closed at 1024.
The map is identity. Two things came out of capturing the wire (scratch HOME + a logging
proxy forwarding :7799 to :7770) that reading the config could not have told me:
- `:off` does not switch thinking off. The default disable mode sends the lowest effort,
so `off` left as `reasoning_effort: "minimal"` — and `minimal` still thinks, a canned
26-token block on every request. `reasoningDisableMode: none-effort` makes the harness
send `"none"`, which the engine honours as a real switch: `reasoning_tokens: 0`, answer
only, no thinking block rendered. Verified after the change, not before it.
- `:max` still arrives as `xhigh`: the harness clamps the requested effort to its own
ladder for this model before the map applies. Recorded in the comment as the engine-side
half of the contract rather than papered over — nothing in models.yml forces it.
Also pinned `top_k: 20` (accepted; the comment claimed the wire matched the server sampler
while `top_k` was never sent, leaving the recipe one env edit away from drifting), and
restored the pre-callsign model ids `frank-medium` / `frank-large` / `frank-small` — the
2026-10-08 rename had replaced the old id inside its own explanation, leaving "renamed
from frank-dragoon" three times and destroying the record needed to resolve an old id.
Verified: full suite green (0 failures), `kb-lint` 0 violations, YAML parses, and the four
efforts `off/high/medium/max` captured on the wire as `none/high/medium/xhigh` with
`top_k: 20` on every request. Refs #62
The one-work-log rule was written near-verbatim in four places — okf-spec,
okf-maintenance, log.md's preamble, and APPEND_SYSTEM.md. Four copies is four
authorities: each can be edited alone, and the next reader cannot tell which one the
linter implements. okf-spec.md owns it; maintenance now carries the action (collapse
a second log into the root, then re-run the linter) instead of re-arguing it; the log
page points at the rule rather than restating it. APPEND_SYSTEM keeps its imperative —
a system prompt cannot fetch a link at the moment of writing — but no longer carries
the duplicated reasoning.
`inventory/index.md` advertised "all userspace program configuration on the
workstation". The one page in that directory measures `~/.config` on blankpad: not
`~/.local/share`, not system package state, not the servers. A coverage claim that
names what was measured is the difference between a census and an alibi.
Refs #60
`deploy_file` excludes `*/Noctalia*` (noctalia's capital-N palette naming) but
`.gitignore` had only the lowercase classes, so a generated palette file could become
tracked-but-never-deployed — the fiction class #41 removed, reintroduced by the
ignore list falling out of step with the deployer. The patterns are one contract in
two files; both halves are now stated and the comment says so.
`natives/` (2.4 MB of tree-sitter grammars the harness unpacks into the repo root on
first use, measured on blankpad) sat unnamed in the root, one `git add -A` away from
being committed as configuration. It is runtime state by every clause of AGENTS.md's
doctrine, so it is ignored. The wallpaper re-fetch note pointed at
`https://wallhaven.cc/w/<id>`, which answers text/html — it now names the API
resolution the deploy page carries.
`git-lfs` was installed because `.gitattributes` routes image types through the LFS
filter — for wallpapers this week's diff untracked: `git lfs ls-files` is zero, so
those four rules match nothing. The manifest now states what the tool is actually for
(cloning LFS-backed upstreams such as Hugging Face model/dataset repos) and the file
records its own inert state. Deleting `.gitattributes` is a pruning call for a session
with Frank, not a cleanup an agent runs alone.
Verified with `git check-ignore -v` for both new rules.
Refs #60
`status` built its job list with `for n in $names`, which word-splits AND globs. The
second half is the bug: a job named `x*` was expanded against the caller's working
directory, so the report described unrelated files there as jobs and never mentioned
the one that ran — on a harness whose whole purpose is a report you can trust after
the session that started the job is gone. Splitting stays (several names in one
argument is the documented call shape); expansion goes.
`tail` was honest-by-accident in the wrong direction: with no jobs it handed a
literal `$JOBS/*.out` to tail, which reports a missing *file* — indistinguishable
from a broken tool — and a missing name produced tail's errno rather than "no job
called that". Both now say what is missing and exit 1.
Red first: the name test reads the report from a directory containing an unrelated
file, so the old glob is visible as a phantom job; both new tests fail against the
previous code and pass against this one.
Refs #60
Three rows claimed `wlr-randr`, `qt6-multimedia` and `brightnessctl` were
dependencies. `pacman -Q` on blankpad says none is installed, and the two features
they were cited for do not come from them at all: display information comes from
`niri msg outputs` (the niri page already said so), and brightness is driven through
the kernel — `/sys/class/backlight/amdgpu_bl1` exists with no helper installed — so
no package is doing that work.
A dependency table is a claim about a machine, and every row of it is now measured
against `pacman -Q` on blankpad (2026-10-21). Verified against the package database:
check `pacman -Q <name>` before adding a row.
Refs #60
The page asserted the Sceptre M34's EDID tops out at 180 Hz. Measured on blankpad
after the merge, `niri msg outputs` lists 3440x1440@239.998 — the claim was false
in main, and it was load-bearing: it is the reason nobody questioned the profile
while the panel ran at 60 Hz for weeks. The real defect was one character: the
profile asked for 239.999, the panel offers 239.998, and niri matches mode strings
verbatim, falling back to *preferred* without failing.
Corrected to the measured mode list, and the deployed 180 is now documented as a
deliberate choice (the link is trained at x8 32.0 GT/s against a max of x16 and the
display engine throws EINVAL), so the next reader neither "restores 240" blind nor
re-pins 180 as a hardware ceiling. The kdl profile comment carries the same facts at
the point of edit, because that is where the next change to this mode gets typed.
Refs #60
The resolver copied Obsidian's filename-anywhere semantics with a raw rglob, which
walked .AGENTTRASH/ as well. [[log]] therefore stayed "valid" by landing on the
quarantined core/log.md — a page that is out of circulation until a pruning session
and, being gitignored, does not exist on any other machine. The gate reported a
green bundle while pointing readers at a file git does not carry: exactly the #57
failure, hidden by the check that exists to catch it.
Resolution now uses the same filtered set linting uses (pages()), so the two can
never disagree about what exists. A companion test pins that filename-anywhere
resolution for live pages still works, so the narrowing costs nothing; mutating
the resolver back to rglob turns the new test red.
Refs #60
The live-sync heartbeat failed three hourly ticks (22:25, 23:27, 00:28) because a
managed skill that documents how to write a secret gate quotes the vendor's
all-zeros placeholder access-key id, and the shape rule fired on the
documentation. The machine tier is prose ABOUT credentials — the gate's own header
says a gate that fires there gets overridden until it means nothing — and a
heartbeat that cannot commit is a fleet that silently stops syncing config.
- shape hits are judged on the matched token, not the line: a documented fake is
inert, one live token sharing the file still blocks. The match is judged with
its following context, because a fixed quantifier truncates `EXAMPLE` to `EXA`
and the placeholder would vanish from what is examined.
- assignment values keep the stricter rule from the previous commit: a comment on
the same line cannot vouch for the token beside it.
- `ALLOW_SECRETS` remains the only override; nothing here widens what is scanned,
it only stops flagging text that was never a credential.
Verified against the payload that is stuck right now: the skill page that the
heartbeat cannot commit passes the fixed hook and was refused by the live one.
Refs #60
Two lies in the unit loop, both reported as success:
- `systemctl --user enable live-sync.service` fails on every deploy — the file has
no [Install] section, because live-sync.timer is what arms it. The result was
swallowed by `|| true` and the tool printed ENABLE anyway, so the line an
operator reads after a rebuild was false on every box, on the repo's own
heartbeat. The [Install] section is readable from the file being deployed, so
the tool now checks it and prints INERT with the reason instead of making a
call that cannot succeed; a real enable failure prints INERT too.
- The loop walked *.service only. live-sync.timer was never enabled by anything,
so a rebuilt box got the heartbeat and no schedule for it. Timers are walked
now; a timer has no ExecStart, so the "does this unit belong on this box" test
runs against the service it activates.
The systemctl stub models systemd's refusal (no [Install] section -> non-zero),
which is what makes the new tests red against the old loop; both new tests were
run red first, and the five existing unit tests still pin #44's semantics.
Refs #60
Three ways the fail-closed gate failed open, all reproduced by new tests first:
- `git diff --name-only` quotes any path it cannot print as UTF-8
(core.quotePath, on by default). The quoted string was handed back to
`git diff -- <path>`, which matches nothing, and an empty diff is `continue`d —
so a credential under `café/` committed cleanly. The list is now NUL-delimited
and read from a temp file, because command substitution deletes NUL bytes and
the names must survive to the loop that reads them.
- The placeholder filter matched the whole added line, so `API_TOKEN=<live> #
example, placeholder, changeme` was exempt on the strength of its own comment.
The filter now reads the assigned value only — the token up to whitespace or
`#`. Truncation errs toward blocking; ALLOW_SECRETS remains the way out.
- `report+=` ended on a command substitution, so the next file's name was glued
onto the previous file's last hit line and the report blamed the wrong file.
Three tests, all red before the change: a quoted path, a placeholder comment
beside a live value, and two leaking files each named on their own line.
Refs #60
install.sh and pkg-inventory.sh carried byte-identical copies of read_manifest.
That is the duplicated-code half of the problem; the worse half is untested —
neither script had any test for the grammar that decides what gets installed.
- scripts/lib/manifest.sh is the parser; both scripts source it
- tests/manifest-parser.bats writes the contract first (comments, CRLF, first
field only, unreadable file fails loudly instead of yielding "nothing desired")
- an unreadable manifest now fails inside the helper rather than depending on
whichever `set` options the caller happens to run under
- install.sh check mode verified end to end against a stubbed pacman: a CRLF
manifest with trailing comments resolves to bare names, installed names drop
Refs #60
Three things from the review (#60), one of them a finding of my own that did not
survive measurement:
- The reported defect — additions never subtract `pacman -Qtdq`, so an orphan can
be emitted as a manifest line — is wrong. A package carries one install reason:
`-Qtdq` selects installed-as-dependency, additions come from `-Qqe`, so the sets
are disjoint (blankpad: 206 explicit, 3 orphans, none in common). A subtraction
would be dead code that looks like a guard, so the header now says why not to
add one. The packages page law was rewritten to the same effect.
- What the old test should have pinned: an implicit dependency installed AFTER
the baseline. Only `-Qqe` keeps it out of drift — mutate that query to `-Qq` and
the new test goes red (verified), where the old assertion passed no matter what.
- `--help` printed `set -euo pipefail` and the LC_ALL line as documentation: the
hardcoded sed range ran past the comment block. It now stops at the first line
of code, so the header can keep growing.
Refs #60
Measured fixes, one line each, from the review of everything that landed on
2026-10-20 (issue #60). Each page keeps its own facts; nothing was moved.
- inventory/index, index: the census blurb says what the page actually covers
(tracked-vs-box-only per file), not "all userspace configuration"
- dotfiles-deploy: the wallpaper re-fetch recipe resolves the CDN URL through
the wallhaven API — /w/<id> answers text/html, so curl -L never yields a
JPEG; description widened to the whole page, tools/index blurb matched
- okf-maintenance: the link example and the mistake bullet now agree with
okf-spec, which RECOMMENDS absolute bundle paths (they said the opposite)
- decisions/index: the unlisted-page gate is kb-coverage.py, not kb-lint
- AGENTS.md: the three skill-config subsections are pointers again; the pages
own issue tracker, labels and domain docs
- swayidle-lock.service: Description names what the unit does (arms the idle
lock over noctalia-shell IPC); suspend belongs to noctalia's inhibitor
- common.pkgs: git-lfs re-justified by the tracked .gitattributes filter
contract; the swayidle comment drops its lid-policy claim
Per-card measurement was unreachable for every card but ordinal 0: the driver
set HIP_VISIBLE_DEVICES=N and still passed N as the device argument, so the
probe called hipSetDevice(N) on a runtime where the mask left only ordinal 0.
The bats stub reported the env var rather than the argument it received, so
the suite asserted the mask was set and never noticed the collision.
- one selector: the ordinal is passed as argv, the mask is never set
- a probe that fails is now exit 5 and names probe + device; the sweep still
measures the remaining cards instead of swallowing the failure
- the guard fails closed when `fuser` is missing (gpu_busy_percent reads 0 for
a resident-but-idle service), with PCIE_PROBE_FUSER as the test seam
- stub probes now model the HIP mask rule; the pre-existing per-device test
goes red against the old driver, which is the regression proof
Refs #60
desk-1-home.kdl asked the Sceptre M34 for 3440x1440@239.999, a mode the panel
has never offered. niri does not reject an unavailable mode: it logs "configured
mode ... could not be found, falling back to preferred" and drives the EDID
preferred mode - 60 Hz - on every connector event, which is why the monitor
looked like it was dying rather than misconfigured. Read live with
`niri msg outputs`, the mode list tops out at 180.
Also destroys the copies of the phantom number: displays.md carried 239.999 in
its diagram, its panel table and its copy-paste pattern block, and its rule 4
claimed an impossible mode leaves the output dark. Rule 4 now states the real
failure mode, a new section separates config / DP-link / amdgpu-driver faults by
log signature, and wlr-randr is corrected to not-installed (three pages claimed
it; `pacman -Qs wlr` matches nothing).
Applied live with `niri msg output <panel> mode <mode>` - the temporary
per-output path, so no config reload and no logged-out session - verified at
3440x1440 @ 180.000 Hz with the compositor PID unchanged.
Refs #58
Rule 1 lost its work-log sentence in the point-of-use rewrite. Restoring it plainly would
re-create the old failure, where one agent kept logs in fifty-odd files and none of them
was the place to look. So the restored rule names the file: a single page in the
knowledge base — omp-docs/log.md here, whichever change-log page a repo's index names
elsewhere — read before starting, written in the same commit as the change it describes,
under that page's own entry law. Explicitly banned: per-directory logs, per-project or
per-run logs, NOTES.md/PROGRESS.md/STATUS.md/worklog/, dated diaries. If a KB has no log
page, the fix is one at its root plus an index entry, never a log somewhere else.
The bundle's own log records the change and the two-log incident it came out of.
The spec listed `log.md` as a reserved name and the maintenance page said every bundle
"has a `log.md`" — neither said there is only one, so a subdirectory could invent its own
and look compliant. Which is how the sprawl Frank banned started: with fifty logs the
entry is never where the next reader looks, and every copy re-dates the same event.
The maintenance page also taught the wrong format: "one line per change with file path",
exampled as `/docs/ghostty.md — Updated keybind table`, i.e. a manifest duplicating git,
with absolute paths that kb-lint cannot resolve because OKF links are relative. Replaced
with the law this bundle already runs: what changed plus the durable lesson, a few lines,
relative links, laws and incidents rather than bookkeeping.
The bundle had two work logs. `core/log.md` was created "for tracking core directory
modifications" and holds two entries of pure migration bookkeeping (file moved,
directory created, log created) — every one recoverable from `git log` — plus a date
for the OKF conversion (2026-07-15) that matches neither the bundle log (2026-01-15)
nor git history, where the OKF rebuild lands 2026-08-28. `core/index.md` was still
linking it, which is exactly how a stale page stays in circulation. kb-lint now reports
any `log.md` that is not the bundle root's; the page moved to omp-docs/core/.AGENTTRASH/
per the trash convention, and the core index points one level up.
Both gates also walked `.AGENTTRASH/`, so trashing a page turned them red: kb-lint
demanded frontmatter from a quarantined page and kb-coverage demanded an index for the
trash directory. A gate that only goes green once the quarantined copy is deleted is a
gate that deletes history, so both skip any path containing `.AGENTTRASH` — pinned by a
test in each suite, and kb-coverage finally gets its own test file.
The section rule was `/^[[:space:]]*\/\/[[:space:]]*─+ (.+) ─+…$/`, a quantifier on a
multibyte character. Under LC_ALL=C — which is what cron, systemd user units and agent
shells get, regardless of LANG — gawk matches byte-wise, so `─+` means "the last byte of
U+2500, repeated" and never matches. Measured on the live keybinds.kdl: the old script
emitted 0 section headers instead of 12, all 120 binding rows intact, exit status 0. A
silent one-third-of-the-page loss, invisible to any caller that only checks the status.
The dash is now matched and stripped as a literal (`gsub(/─/, "")`), which is byte-safe
in every locale, and a comment must be dash-decorated on both sides to open a section, so
plain comments are still ignored. A test pins the C-locale case explicitly, because the
box's own terminal has always been UTF-8 and could never have caught this.
The committed artifact omp-docs/tools/niri/keybindings.md is unaffected (12 headers,
120 rows — it was generated from a UTF-8 shell); output is now identical either way.
"#54" made Frank go hunting: numbers are per-repository across the forges this
fleet uses, and a number carries no hint of which work is being reported. Every
mention of a PR now pairs its web URL with its title — gitea.franksdank.cloud for
the Dankclaw Gitea, the equivalent for any other forge.
Refs the AGENTS.md convention that an open PR gets opened in Frank's browser: the
rule covers prose, where the browser tab does not help.
The live deployment has been running this rewrite of rule 1 since 2026-10-19, but
the file was never committed: agent/APPEND_SYSTEM.md is prose tier, outside the
live-sync allowlist, so the heartbeat surfaces the dirt instead of committing it —
which is correct behaviour, and it left the fleet's system prompt with no history
and no way for another machine to pull it. Committed verbatim as it runs, no
editorial changes: the purpose test, the dead-weight-number law, and the
deletion-is-an-update clause.
A config that only exists on one disk is not a deployment; it is a pending loss.
The RDNA4 offload campaign left three HIP probes and a driver sitting loose in
$HOME, where the next agent cannot find them and a stray `rm -rf` ends them. They
answer a recurring question on the R9700 box — is decode limited by the link or by
the engine's read path — so they move into scripts/probes/ with a driver, tests,
and a page.
Two things changed in the code, not just the address:
- The driver measures only after a guard that runs BEFORE anything is built:
gpu_busy_percent over PCIE_PROBE_MAX_BUSY, or any process holding /dev/kfd, is a
refusal (exit 3) rather than a measurement. A benchmark taken beside a live
endpoint is both disruptive and worthless, and silently unloading a production
service is not a tool's decision — --force is the human saying otherwise. The
refusal-before-build ordering is pinned by a test, because the sysfs and kfd
paths are overridable and a refusal is otherwise untestable off the card box.
- hip_smoke.hip and pcie_probe.hip called hipGetDeviceProperties, which SEGFAULTS
on this ROCm build even though hipGetDeviceCount works; only pcie_bw.hip avoided
it, and that is the one that produced the campaign's numbers. Device identity now
comes from the sysfs topology block the driver prints, so all three probes are
runnable on the build we ship. Verified here: refusal on a real busy APU (exit 3),
missing toolchain (exit 4), missing sources (exit 2). Compile-and-run still needs
the box with hipcc.
Refs #53
`ssh host 'cmd | tail -f log | sed -n /ready/q'` reported success on jobs that
never finished, three structural ways: the broker aborts the long connection, a
readiness pattern can match a log header printed before the work starts, and
`sed -n /x/q` exits the instant it matches — tearing down the very command it
was watching. The replacement runs the job detached on the host and writes
NAME.out, NAME.rc, then NAME.done LAST, so status is a cheap read of files over
a short-lived connection. That survives the connection, the restart, and the job
that restarts the endpoint the agent itself is running on.
Black-box tests pin the sentinel ordering (rc before done), that a finished-but-
failed job is DONE rc=N with the report still exiting 0, and that a name with no
state is never reported DONE.
Refs #53
Frank
dank