docs: one owner for the one-log rule, and an honest scope on the census

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
This commit is contained in:
Frank committed 2026-10-21 01:06:51 -07:00
1 parent a280c29d2c
commit 66e1129e6c
4 files changed
+23 -11

No files matched your search

+1 -1
View File
@@ -72,7 +72,7 @@ Documentation exists for ONE reason: **point of use**. A page earns its bytes on
#### THE WORK LOG IS ONE FILE. #### THE WORK LOG IS ONE FILE.
The work log is a single page in the knowledge base: `omp-docs/log.md` in this repo, or whichever change-log page the repo's docs index names. Write the entry when the change lands — in the same commit as the change — and read that page to recover where things stand before starting. It follows its own entry law: a dated entry is what changed plus the durable lesson, a few lines. The work log is a single page in the knowledge base: `omp-docs/log.md` in this repo, or whichever change-log page the repo's docs index names. Write the entry when the change lands — in the same commit as the change — and read that page to recover where things stand before starting. It follows its own entry law: a dated entry is what changed plus the durable lesson, a few lines.
- NEVER create a second log: not per directory, not per project, feature, branch or run, not `NOTES.md` / `PROGRESS.md` / `STATUS.md` / `worklog/`, not a dated diary. Logging in fifty places is not logging — the entry is never where the next reader looks, and each copy re-dates the same event on its own authority. In `dank/command-center` the KB linter reports any `log.md` that is not the bundle root's. - NEVER create a second log: not per directory, not per project, feature, branch or run, not `NOTES.md` / `PROGRESS.md` / `STATUS.md` / `worklog/`, not a dated diary. In `dank/command-center` the KB linter reports any `log.md` that is not the bundle root's; the rule and its reasoning are owned by `omp-docs/references/okf-spec.md`.
- A log holds laws and incidents, never bookkeeping: no per-file inventories, no run-by-run numbers, no transcripts. A number in a log still has to pass the purpose test above. - A log holds laws and incidents, never bookkeeping: no per-file inventories, no run-by-run numbers, no transcripts. A number in a log still has to pass the purpose test above.
- If a knowledge base has no log page, add one at its root and list it in the index. That is the fix — never a log somewhere else. - If a knowledge base has no log page, add one at its root and list it in the index. That is the fix — never a log somewhere else.
+3 -1
View File
@@ -1,5 +1,7 @@
# Inventory Index # Inventory Index
Census of all userspace program configuration on the workstation. Tracked-vs-box-only census of userspace configuration on blankpad. Read the scope before
trusting coverage: these pages measure `~/.config`, not `~/.local/share`, not system package
state, not the servers.
- [home-config-census.md](home-config-census.md) — Per-file tracked-vs-box-only census of ~/.config on blankpad — the input for the dotfiles pruning/adoption session. - [home-config-census.md](home-config-census.md) — Per-file tracked-vs-box-only census of ~/.config on blankpad — the input for the dotfiles pruning/adoption session.
+14 -3
View File
@@ -16,9 +16,8 @@ lesson, a few lines. Full incident narratives are recoverable from git
(`git log --follow omp-docs/log.md`); knowledge that outlives an entry lives (`git log --follow omp-docs/log.md`); knowledge that outlives an entry lives
on its concept page, linked here. Never re-expand an entry in place. on its concept page, linked here. Never re-expand an entry in place.
This page is the bundle's **only** work log: one file, at the root. Never start a This is the bundle's only work log; [references/okf-spec.md](references/okf-spec.md) owns the
second one in a subdirectory or under another name — `scripts/kb-lint.sh` reports any one-log rule and `scripts/kb-lint.sh` enforces it.
`log.md` that is not this one.
## 2026-10-21 — reviewing a day of work, and finding checks that lie ## 2026-10-21 — reviewing a day of work, and finding checks that lie
@@ -45,6 +44,11 @@ rather than its argument, so the suite asserted the mask was set and per-card ba
unobtainable on the 2×R9700 box. Model the platform rule in the stub and the existing test goes unobtainable on the 2×R9700 box. Model the platform rule in the stub and the existing test goes
red against the old code — that is the red-proof worth having. red against the old code — that is the red-proof worth having.
Same shape in `remote-job.sh status`: it globbed its arguments, so a job named `x*` was reported
as whatever happened to match in the caller's directory. A name is data — split it (`read -a`),
never let the shell expand it — and a multiplexed `tail` with no jobs says "no jobs" instead of
handing `*.out` to tail and reporting a missing file.
Incident, found while verifying the gate: the live-sync heartbeat had failed three hourly ticks, Incident, found while verifying the gate: the live-sync heartbeat had failed three hourly ticks,
because a managed skill that documents how to write a secret gate quotes the vendor's all-zeros because a managed skill that documents how to write a secret gate quotes the vendor's all-zeros
placeholder id and the gate's shape rule fired on the documentation. Prose about credentials is placeholder id and the gate's shape rule fired on the documentation. Prose about credentials is
@@ -53,6 +57,13 @@ the hole. Placeholder judgement reads the matched token — plus what follows it
quantifier truncates `EXAMPLE` to `EXA` — never the whole line. `ALLOW_SECRETS` stays the only quantifier truncates `EXAMPLE` to `EXA` — never the whole line. `ALLOW_SECRETS` stays the only
override, and the heartbeat's own payload was replayed through the fixed hook to prove it lands. override, and the heartbeat's own payload was replayed through the fixed hook to prove it lands.
The rest of #60 was claims about the machine that the machine had stopped honouring:
`.gitignore` and `deploy.sh`'s exclusion list had drifted apart (`Noctalia*` was excluded, never
ignored), `.gitattributes` was the stated reason `git-lfs` was installed — for wallpapers that
same week's diff untracked, and the one-log rule was restated in four owners. A coverage claim
names what was measured; a tool justified by dead config is a tool nobody can defend when the
config goes.
## 2026-10-21 — a documented mode the panel never had ## 2026-10-21 — a documented mode the panel never had
The home ultrawide had been running at 60 Hz for weeks while `desk-1-home.kdl` The home ultrawide had been running at 60 Hz for weeks while `desk-1-home.kdl`
+5 -6
View File
@@ -21,12 +21,11 @@ Knowledge bundles rot. It is the nature of knowledge to attract cobwebs, much li
## Change Tracking with `log.md` ## Change Tracking with `log.md`
Every OKF bundle has a `log.md`, and it is the bundle's **only** work log: one file, Exactly one `log.md` per bundle, at the bundle root — [okf-spec.md](okf-spec.md) owns that rule
at the bundle root. A subdirectory never gets its own — not `core/log.md`, not and `scripts/kb-lint.sh` enforces it, reporting any `log.md` that is not the root's. The
`notes.md`, not a per-project, per-branch or per-run diary. Sprawl is not caution: maintenance action is collapse, never coexistence: when a second log turns up (`core/log.md`,
with fifty logs the entry is never where the next agent looks, and each copy re-dates `notes.md`, a per-run diary), move its entries into the root log under their own dates, delete
the same event on its own authority. `scripts/kb-lint.sh` reports any `log.md` that is the file, and re-run the linter.
not the root's.
**Format:** one dated section per day, newest first; a few lines per change — what **Format:** one dated section per day, newest first; a few lines per change — what
happened, and the durable lesson. It is not a file manifest. happened, and the durable lesson. It is not a file manifest.