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:
1 parent
4849f46eb2
commit
bfd6a6340e
2 files changed
+45
-17
No files matched your search
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user