command-center/omp-docs/references/okf-maintenance.md

type, title, description, tags, timestamp

type	title	description	tags	timestamp
guide	OKF Bundle Maintenance	Keep your OKF knowledge bundle from rotting — change tracking, frontmatter discipline, staleness detection, and automation.	okf maintenance documentation best-practices unverified	2026-10-19

OKF Bundle Maintenance

Knowledge bundles rot. It is the nature of knowledge to attract cobwebs, much like an unvisited pantry attracts spiders that are frankly doing you a favor by reminding you it has been a while. An OKF bundle maintained by agents is no exception — files drift out of sync, frontmatter becomes decorative, and index.md turns into a ghost town where links go to die.

The core principle: if you do not track changes, you do not know when they happened. If you do not have a changelog, you are the person who finds the broken thermostat and wonders why it is set to "volcano."

---

Change Tracking with log.md

Every OKF bundle has a log.md file. It is not optional. It is the bundle's memory.

Format: Date-grouped entries, newest first. One line per change with timestamp, file path, and what changed.

# Bundle Change Log

## 2026-01-15
- `/docs/ghostty.md` — Updated keybind table after v1.2 release
- `/docs/pi-permission-system/` — Added `policy.md` and `audit.md`
- `/docs/index.md` — Synced with directory contents

Rules:

• Newest entries first. Putting old entries at the top inverts the timeline and makes it impossible to see what just happened.
• One line per change. A single line is sufficient. The git history is there if someone wants the gory details.
• Group by date. Batch all changes from the same day together.
• Always date-stamp the section. Use ## YYYY-MM-DD.
• Mention index.md whenever you change a bundle. If you added or removed a file, update the index and note it in the log.

Common Mistakes

• ❌ Writing "Updated ghostty.md" — Updated it with what? Be specific.
• ❌ Forgetting to write to log.md — This is the equivalent of doing surgery without keeping a record.
• ❌ Using relative paths — Use absolute paths (/docs/ghostty.md).
• ❌ Leaving stale entries from manual edits — The log is the single source of truth.

---

Frontmatter Discipline

Frontmatter is the metadata layer. It is not decoration.

Required field:

• type — The concept type. The only strictly required frontmatter field.

Strongly recommended:

• description — The preview text. Without it, the file is invisible and confusing.
• tags — Use for cross-cutting concerns. Tags hold things together across categories.
• timestamp — Include for staleness detection. A file with a timestamp from 2023 is more likely stale than one from 2026.
• title — Optional but helpful.

Rules:

• ✅ Every concept file must have a description.
• ✅ Use tags liberally but consistently.
• ✅ Include timestamp on every file.
• ✅ Pick descriptive type values: reference, guide, configuration, tutorial.
• ❌ Don't use type: file or type: document — be specific.
• ❌ Never leave description blank or copy the title.

---

One Thing Per File

OKF is built on the principle that a file is one concept.

Splitting criteria:

• ✅ One topic, one file. If the content can be summarized in one sentence without using "and," it belongs in one file.
• ✅ Give each file its own type.
• ✅ Keep each file between 1 and 500 lines. Under 1 = over-split. Over 500 = under-split.
• ❌ Don't create a file called misc.md — misc is a graveyard, not a category.
• ❌ Don't use # Other or # Additional Notes sections — these are taping things to the wall.

---

Auto-Generation Strategies

Index files as living documents:

find docs/bundle-name/ -name '*.md' ! -name 'log.md' -type f | \
  sort | \
  awk '{print "- " $0}' > docs/bundle-name/index.md

Staleness detection:

# Find files older than 90 days
find docs/ -name '*.md' ! -name 'index.md' ! -name 'log.md' \
  -mtime +90 -type f -print

# Find files missing timestamp
find docs/ -name '*.md' ! -name 'index.md' ! -name 'log.md' \
  -type f -exec grep -L '^timestamp:' {} \;

# Find files missing description
find docs/ -name '*.md' ! -name 'index.md' ! -name 'log.md' \
  -type f -exec grep -L '^description:' {} \;

---

Version Control Best Practices

• ✅ One logical change per commit
• ✅ Write meaningful commit messages ("Updated file" is not a commit message. It is a shrug in text form.)
• ❌ Don't commit entire bundle dumps — a commit touching 50 files is a data dump, not a change

Useful git commands:

git blame -L 1,30 docs/ghostty.md          # Who changed what and when
git log --oneline -n 10 -- docs/pi-permission-system/  # Last commits in a directory
git status --short                            # What is uncommitted

---

Knowing When Something Is Stale

Signal	Threshold	Action
timestamp field older than 6 months	Auto-flag	Review and update or archive
File not modified in 12 months	Auto-flag	Assess whether still relevant
index.md count differs from file count	Always	Fix immediately
log.md has no entries for 30+ days	Context-dependent	Normal if no changes made

---

Automated Gates (this bundle)

Two mechanical checkers live in scripts/; both exit non-zero on violations. Run both before committing any omp-docs/ change; tests/kb-lint.bats pins their behavior.

bash scripts/kb-lint.sh omp-docs         # OKF conformance
python3 scripts/kb-coverage.py omp-docs  # index coverage doctrine

• kb-lint — OKF v0.1 rules: non-empty type frontmatter on every non-index file, no frontmatter on index.md, resolvable wikilinks and relative links, reserved names (index.md/log.md), YYYY-MM-DD log headings.
• kb-coverage — the AGENTS.md anti-rot mechanism: every directory has an index.md, and that index links every sibling file and subdirectory.

---

See Also

• OKF v0.1 Specification — The complete format specification.
• Root Index — This bundle's structure and navigation.