Research: a kind for freeform documents

State: open/active · Genre: research

Status: findings as of 2026-10-02, implemented by #2512: the spec is vendored, okf validate walks all of docs/, the note kind exists and 47 documents were migrated. What stays open is other bundles. Part of the strategy hub. Time-boxed research for milestone 1, Ontology foundation, in the roadmap.

Question. Can a somewhat freeform document, like this hub, fit into our ontology? And is OKF (Open Knowledge Format) applied across all markdown files?

Findings

OKF in this repo is thin. No OKF spec is vendored or linked. Everything the repo knows about OKF is secondhand from the 0.8 plan: okf_version: "0.2", type: Note on bundle files, optional status and generated keys. The 0.8 task that landed OKF (T-IZ3L-bundle-index-md-files-with-okf-version-0-2-type-note-or) says so, and chose scope-exclusion over a type: Note sweep.

sdlc okf validate is an allowlist. It checks docs/index.md (required), glossary.md and references.md (if present), and the top level of the twelve entity directories under docs/planning/, plus decision dossier READMEs. Five checks: bundle index present, type present, type registered, okf_version present and equal to 0.2. No body or schema checks; those belong to entities audit. The directory list is hard-coded, so widening scope is a code change. A type: Note file inside an entity directory would fail as an unrecognized type.

OKF is not used across all markdown, and should not be. Roughly 7,500 of the repo’s markdown files are code docs, skills, conventions and vaults. They are not corpus and have their own formats. The real gap is the untyped files inside docs/planning/ itself:

Where	Count	What
root	7	`vision.md`, two plan docs, two research docs, a launch doc, a release checklist
`analysis/`	19	four audits and reconciliations, fifteen flowline use cases
`design-language/`	5	plan, proposal, survey, candidates
`bug-sweeps/`	3	sweep notes
`strategy/`	8	this hub
`decisions/<D-id>/`	~70	dossier attachments, mostly under D-7VMX; typed READMEs are already checked

Entity kinds have one near miss. Twelve kinds exist. reference is for material we did not write, so internal plans do not fit it. backlog is the only kind with no required body sections (lenientBody([])), which proves the shape: strict frontmatter, freeform body. The roadmap kind already points at a loose plan doc through plan_doc, a wikilink slug whose shape is checked but whose target nothing resolves (RM-E2L0 uses it, as does RM-0RYV in #2474).

Cost of a kind. A kind is a directory under lib/model/entities/<kind>/: schema.ts, definition.md, body-template.eta, ops/create.ts and preview-id.ts, optional site_projection.ts, plus registry entries. It is then covered by entities audit, okf validate, the docs site and the graph for free.

Options

	Shape	For	Against
A	`plan` kind only	Smallest; fixes `plan_doc`	Leaves analyses, research and strategy untyped
B	One `note` kind with a `genre` field (`plan`, `research`, `analysis`, `strategy`, `retro`)	One kind covers every loose doc; `type: Note` matches what OKF already uses on bundle files; `research` skill gets an output kind	A field instead of a type carries less meaning in the graph
C	Scope-exclusion marker, no kind	No schema work	Docs stay outside the graph; nothing links to them typed

Recommendation

Option B. One kind, note, with:

Frontmatter: the shared core (id N-XXXX, title, state, created, related, tags) plus genre and an optional parent for hub and sub-document trees.
Body: freeform, lenientBody([]). Wikilinks count as edges; transclusions allowed.
Dossier attachments stay excluded. They belong to their decision, not the corpus.
Migration: the 42 loose files under root, analysis/, design-language/, bug-sweeps/ and strategy/ move to docs/planning/notes/ as notes. plan_doc becomes a typed link to a note id and roadmap check resolves it. vision.md stays where it is as a note with a fixed id.
Skills: research writes a genre: research note; capability-groom writes its proposals as genre: plan notes until they settle into capability and decision entities.

Open: the id prefix, and whether genre is an enum or free text.

← Back to Notes