3.7 KiB
3.7 KiB
| type | tldr | status | decided_on | decided_by | affects | confidence | quality | last_updated | freshness_window_days | retention |
|---|---|---|---|---|---|---|---|---|---|---|
| decision | A root ABOUT.md, written by the KB's owner, states what the KB holds — purpose, audience, scope, owners, sensitivity — and the README links to it; agents read it and never edit it, ingest checks material against its scope, the MCP server serves it, and wiki/overview.md stays the agent's summary of what the KB actually holds. | accepted | 2026-10-31 | Michał Kopeć | ABOUT.md, AGENTS.md, README.md, wiki/overview.md, .agents/skills/ckb-ingest/, .agents/skills/ckb-init/, .agents/skills/ckb-upgrade/, .agents/skills/ckb-reset/, .agents/modules/mcp/server/, docs/MANUAL.md | 0.85 | 0.8 | 2026-10-31 | 365 | high |
D-0010 — ABOUT.md states what a KB holds, and the README links to it
Status: Accepted · Decided: 2026-10-31 · Deciders: Michał Kopeć
Context
Every KB's README.md is the template's own technical README, and
ckb-upgrade overwrites it. It describes the Cascade KB tooling, which is
the same everywhere. Nothing a reader opens first said what this KB is
about, who it is for, or who to ask.
wiki/overview.md comes close, but ckb-ingest writes it from what was
ingested. It describes what the KB holds, not what it is meant to hold, and
a person who corrects it competes with the next ingest. Intent, scope and
handling rules are the owner's to state, and the agent should read them.
Decision
- A root
ABOUT.mdis the owner's statement of what the KB is for. Sections: Purpose, Audience, Scope (in and out), Owners and contacts, Expected sources, Sensitivity, Language and terms. Each ships as an HTML comment saying what to write.type: aboutfrontmatter carries atldrandlast_updated. - It is the user's file. Agents read it and edit it only when asked.
It is not a cascade layer and not part of the template layer:
ckb-upgradecreates it only when missing and never diffs it, andckb-resetnever touches it.ckb-initcopies the scaffold and asks one optional question to fill Purpose andtldr. - The README links to it at a fixed path. Because the README is overwritten on upgrade, the link has to be generic; it sits right under the source-repo pointer in both languages.
- Agents use it.
ckb-ingestnames material outside its Scope or ruled out by its Sensitivity section and ingests it only on the user's say-so. Questions about the KB itself are answered from it beforewiki/overview.md. The MCP server puts it first inkb_overviewand takes itstldras the KB's description, ignoring the scaffold's placeholder. wiki/overview.mdkeeps its role as the agent's summary of what the KB actually holds, and links toABOUT.md.
Alternatives considered
- Link the README to
wiki/overview.mdonly was rejected: an agent-maintained page cannot carry the owner's intent, scope limits or handling rules, and regeneration would compete with hand edits. - Replace
wiki/overview.mdwithABOUT.mdwas rejected: the summary of what has been ingested is still useful and is read by the exporters,ckb-quizand the MCP server; moving it touches every one of them for no gain. - Put the owner's statement in
ckb.yamlwas rejected: it is prose for people, and YAML is configuration.
Consequences
- No
kb_schema_versionchange:ABOUT.mdis outsidewiki/, liketemplates/(D-0008). - An unfilled
ABOUT.mdis harmless: ingest skips the scope check and the MCP server falls back to the overview'stldr. - Scope enforcement is only as good as what the owner writes. Ingest reports conflicts; it does not decide them.