From 66e1129e6c182312a7e89c826176bf95447e0d6c Mon Sep 17 00:00:00 2001 From: Frank Date: Wed, 21 Oct 2026 01:06:51 -0700 Subject: [PATCH] docs: one owner for the one-log rule, and an honest scope on the census MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- agent/APPEND_SYSTEM.md | 2 +- omp-docs/inventory/index.md | 4 +++- omp-docs/log.md | 17 ++++++++++++++--- omp-docs/references/okf-maintenance.md | 11 +++++------ 4 files changed, 23 insertions(+), 11 deletions(-) diff --git a/agent/APPEND_SYSTEM.md b/agent/APPEND_SYSTEM.md index 66782a1..d73a27e 100644 --- a/agent/APPEND_SYSTEM.md +++ b/agent/APPEND_SYSTEM.md @@ -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 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. - 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. diff --git a/omp-docs/inventory/index.md b/omp-docs/inventory/index.md index aa03f78..bd992ae 100644 --- a/omp-docs/inventory/index.md +++ b/omp-docs/inventory/index.md @@ -1,5 +1,7 @@ # 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. diff --git a/omp-docs/log.md b/omp-docs/log.md index 62dc325..99fdc02 100644 --- a/omp-docs/log.md +++ b/omp-docs/log.md @@ -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 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 -second one in a subdirectory or under another name — `scripts/kb-lint.sh` reports any -`log.md` that is not this one. +This is the bundle's only work log; [references/okf-spec.md](references/okf-spec.md) owns the +one-log rule and `scripts/kb-lint.sh` enforces it. ## 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 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, 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 @@ -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 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 The home ultrawide had been running at 60 Hz for weeks while `desk-1-home.kdl` diff --git a/omp-docs/references/okf-maintenance.md b/omp-docs/references/okf-maintenance.md index 9100be3..2846550 100644 --- a/omp-docs/references/okf-maintenance.md +++ b/omp-docs/references/okf-maintenance.md @@ -21,12 +21,11 @@ Knowledge bundles rot. It is the nature of knowledge to attract cobwebs, much li ## Change Tracking with `log.md` -Every OKF bundle has a `log.md`, and it is the bundle's **only** work log: one file, -at the bundle root. A subdirectory never gets its own — not `core/log.md`, not -`notes.md`, not a per-project, per-branch or per-run diary. Sprawl is not caution: -with fifty logs the entry is never where the next agent looks, and each copy re-dates -the same event on its own authority. `scripts/kb-lint.sh` reports any `log.md` that is -not the root's. +Exactly one `log.md` per bundle, at the bundle root — [okf-spec.md](okf-spec.md) owns that rule +and `scripts/kb-lint.sh` enforces it, reporting any `log.md` that is not the root's. The +maintenance action is collapse, never coexistence: when a second log turns up (`core/log.md`, +`notes.md`, a per-run diary), move its entries into the root log under their own dates, delete +the file, and re-run the linter. **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.