Make Every Repo in the Tree OKF Compliant
61 context-v bundles, 1,083 docs, most now OKF compliant. What's done, what's left, and how to finish the rest.
- Path
- issues/Make-Every-Repo-OKF-Compliant.md
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5.5 (1M context)
- Tags
- Issue · Open-Knowledge-Format · Normalization-Sweep · Status-Discipline · Workflow-Management
Make Every Repo in the Tree OKF Compliant
Why Care?
Every repo in the Lossless tree keeps a context-v/ folder: the specs, plans, blueprints, reminders and issues that humans and agents work from. We’re building a dashboard that manages work across all of them at once: what’s ready to assign, what’s in flight, what’s a standing rule, which issues are open. That only works if every doc says, in a field a machine can read, what kind of doc it is and where it stands.
The Open Knowledge Format (OKF) v0.2 gives us the first half: every doc declares a type, and every folder has an index.md an agent can scan without opening each file. The kit’s frontmatter template gives us the rest: identity (site_uuid, hex_code), honest dates, and a status from one shared vocabulary.
As of 2026-11-01, most of the tree is there. This issue tracks the rest.
Definition of done, per repo
A repo’s context-v/ bundle is compliant when:
- Every doc declares
type, the folder’s name in Train-Case (specs/→Specs,narratives/→Narratives). A folder README with frontmatter counts as a doc. - The bundle root has
index.mdwithokf_version: "0.2", and every folder has anindex.md, one line per doc (description, else lede, else title). - Baseline frontmatter is filled from facts:
title,date_created,date_modified,authors,site_uuid,hex_code. Dates come from git or the doc’s own first-draft date, never today’s date. statusis on the shared vocabulary (seestatus-discipline.mdin the context-vigilance skill), and it’s true: a plan whose work is in git isn’tDraft.- The normalizations are applied: list fields as lists; Title-Case tags and statuses; repo names out of tags where the body already names the repo; package names out of tags;
"[]"dates emptied. - Any splash that loads
context-v/skipsindex.md, so indexes stay navigation for agents and never become pages. - All three tiers carry it:
development,mainandmasteron origin point at the same commit.
Docs sitting loose in a bundle root (not in a folder) aren’t typed; they’re listed in [[Loose-Docs-in-Context-V-Roots]] to be filed.
The method
Fixed by the kit’s plan [[Retrofit-Every-Repo-to-OKF-Then-the-Kit-Frontmatter]] (decisions 1–19). In short:
- Only repos whose three tiers agree are swept. Divergent repos go to [[Repos-Not-at-Branch-Parity]] first.
- Two phases, one commit and one changelog entry each. Phase 1: types and indexes. Phase 2: the frontmatter template and statuses.
- Every edit by hand, frontmatter only. No script writes any
.mdfile; no body line changes; no existing date moves;publishis never flipped. - Statuses are decided from evidence, not queued: read the doc, check git log and the code, and record a
date_first_publishedfrom the commit that shipped the work. - Work happens in a scratch worktree, pushed with
git push --atomic origin HEAD:development HEAD:main HEAD:master. Then the operator’s local tiers are fast-forwarded and the parent’s submodule pointer is bumped.
State on 2026-11-01
A tree-wide scan (scan.py --scope tree, excluding agent skills, roll-ups and corpus/) found 61 bundles holding 1,083 docs, 314 of them without a type. 216 of those 314 are in one repo, augment-it.
Done: swept to the current rules (2026-11-01)
Typed, indexed, frontmatter filled, statuses decided from evidence, pushed to all three tiers:
| Group | Repos |
|---|---|
| Anchor and corpus | lossless-monorepo (root context-v/), context-v-corpus |
| ai-labs | dididecks-ai, id-didi-sh, studies/context-v |
| dididecks client sites | calmstorm-decks, humain-vc-decks, chroma-decks, reach-edu-hub, the-water-foundation, eventcut-ai, lfg-hub, lossless-decks |
| astro-knots | astro-knots itself, dark-matter, twf_site |
| content-farm | content-farm itself, metafetch, lmstud-yo, stenographer |
| Other | self-host-stack (both bundles), event-hog-mcp, dididecks-player |
| ai-labs, rebuild branch | augment-it (217 docs, swept and pushed on rebuild/turbo-rsbuild only, the branch it lives on: 453a52a, f9f8638; compound statuses keep their text in status_note) |
| astro-knots, local-only | mpstaton-site’s 14 gitignored deck narratives: typed and indexed in place (public repo, so the deck stays untracked; only the folder’s index, which names no deck, is committed) |
| Study collections | memory-layers-for-agents, open-specs-and-standards, agent-harnesses, adhd-and-executive-function-skills, conversational-ui-and-native-shells, sync-and-content-version-control, vector-databases (75 docs: 72 Profiles, 3 Inquiry; the two with only main got development and master created first) |
Done before the current rules (2026-10-31)
These are OKF compliant (typed and indexed) but were swept before the status vocabulary, the repo-name-tag rule, the "[]" rule, and the README fix existed. No re-pass is planned (operator decision, 2026-11-01): the newer rules are now in the kit’s compliance-sweep.md and the upgrade skill, and apply whenever these repos are next worked on. The off-list statuses below are what a future pass would meet.
| Group | Repos | Off-list statuses seen |
|---|---|---|
| ai-labs | ai-labs (its own context-v/), corpora-builder, flave-ai, kay-os, hope-ai, memopop-ai, memopop-orchestrator, context-vigilance-kit |
Proposed, Moved, Implemented, Exploration, Built-Awaiting-Deploy, Gated-On-Deploy, In-Discussion, Partially-Resolved, compound strings |
| astro-knots sites | fullstack-vc, mpstaton-site, lossless-toolkit-site, client-portals-site, learnstart-site, arthouse-site, lossless-slides-site, dominocielo-site, gth-site, multiphasic-site, lossless-changelog, astro-knots-mcp |
Planned, draft-v1, Parked |
| content-farm plugins | cite-wide, perplexed, image-gin, file-transporter, filestarter, grab-reference, plunk-it |
Authoritative, Proposed, In-Progress |
| Other | site, lfm |
Retired, In-Progress, Proposed, Issue-Resolution |
The memopop-orchestrator bundle is the largest of these (110 docs, 8 distinct off-list statuses).
Not started, and why
| Repo | Docs (untyped) | Why it’s held |
|---|---|---|
ai-labs/dididecks-ai/client-sites/jobmachine |
1 (1) | No GitHub remote yet; sweep once it has one. |
astro-knots/sites/humain-web |
1 (1) | Skip. Someone else’s repo (aneilbaboo/humain-web). |
Three single untyped docs remain in otherwise-done repos (content-farm, image-gin, twf_site). All three are loose root docs, tracked in [[Loose-Docs-in-Context-V-Roots]].
Tooling follow-ups
- Fix the survey scanner’s README blind spot. A README with frontmatter now counts as a doc and is flagged if untyped, matching
okf.md’s check (kit75437a3; the check itself was fixed inb6fccbd). - Stop the scanner counting
agent-skills/*/SKILL.mdas untyped bundle docs (kit75437a3). - Write the method down for others:
context-vigilance/references/compliance-sweep.mdin the kit, linked from theupgradeskill, whose repo check now covers the gaps this sweep kept finding (kit75437a3). - Re-run the survey, so the dashboard reads the new types and statuses (2026-11-02: 1,069 docs across 65 bundles).
- Refresh the roll-ups: the corpus (
scripts/refresh-corpus.sh --apply) and the ai-labs splash (pnpm rollup:sync), so the copies carry the swept frontmatter.
Known gaps left on purpose
## Remaining worksections. Many docs are nowPartially-Shipped; the vocabulary asks for a## Remaining worksection in the body, and the sweep doesn’t edit bodies. Their existing status notes carry that for now.- Statuses on live slide data. Some deck narratives (e.g. calmstorm-decks) carry slide content in their frontmatter, read directly by the deck components. They’re typed and indexed but get no
status, so no new key lands in data the site renders. - Legacy
date:keys stay where a splash still reads them (decision 8): the reader has to change first.
Resolution (2026-11-02)
Every repo held to this issue’s definition of done is swept, and the survey and roll-ups read the result. The 2026-11-02 survey found 47 untyped docs, none of them a gap this issue owns:
- Not docs:
SKILL.mdfiles in repo-levelagent-skills/folders (the scanner still counts these outside the top level) and the loosecontext-v/README.mdfiles. - Held on purpose: jobmachine (no remote yet) and humain-web (not our repo).
- Loose root docs: the three in [[Loose-Docs-in-Context-V-Roots]].
- Written after the sweep: one spec still being drafted in astro-knots, which gets its
typewhen its author files it.
50 statuses remain off the vocabulary, all in the repos swept before the current rules. They’re corrected whenever those repos are next worked on, per compliance-sweep.md.