docs(okf): the work log is one file at the bundle root, and an entry is a lesson not a manifest

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.
This commit is contained in:
Frank committed 2026-10-20 21:49:16 -07:00
1 parent 4849f46eb2
commit bfd6a6340e
2 files changed
+45 -17

No files matched your search

+8 -2
View File
@@ -42,7 +42,7 @@ An OKF knowledge bundle is a directory tree. Every concept is one file. The file
```
my-bundle/
├── index.md # Optional directory listing
├── log.md # Optional update history
├── log.md # The bundle's ONE update history — root only
├── concept-one.md # A concept at the root level
└── subdirectory/
├── index.md # Optional subdirectory listing
@@ -55,7 +55,13 @@ my-bundle/
| Filename | Purpose |
|----------|---------|
| `index.md` | Directory listing for progressive disclosure |
| `log.md` | Chronological update history |
| `log.md` | Chronological update history — **exactly one, at the bundle root** |
**One work log per bundle.** `log.md` is reserved, and it is reserved for a single
file: the bundle root's. A subdirectory never keeps its own change log — a bundle
that logs in fifty places has no log, because the entry is never where the next
reader looks and every copy re-dates the same event. `scripts/kb-lint.sh` reports
any `log.md` that is not the root's.
---