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:

  1. Every doc declares type, the folder’s name in Train-Case (specs/ → Specs, narratives/ → Narratives). A folder README with frontmatter counts as a doc.
  2. The bundle root has index.md with okf_version: "0.2", and every folder has an index.md, one line per doc (description, else lede, else title).
  3. 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.
  4. status is on the shared vocabulary (see status-discipline.md in the context-vigilance skill), and it’s true: a plan whose work is in git isn’t Draft.
  5. 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.
  6. Any splash that loads context-v/ skips index.md, so indexes stay navigation for agents and never become pages.
  7. All three tiers carry it: development, main and master on 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 .md file; no body line changes; no existing date moves; publish is never flipped.
  • Statuses are decided from evidence, not queued: read the doc, check git log and the code, and record a date_first_published from 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 (kit 75437a3; the check itself was fixed in b6fccbd).
  • Stop the scanner counting agent-skills/*/SKILL.md as untyped bundle docs (kit 75437a3).
  • Write the method down for others: context-vigilance/references/compliance-sweep.md in the kit, linked from the upgrade skill, whose repo check now covers the gaps this sweep kept finding (kit 75437a3).
  • 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 work sections. Many docs are now Partially-Shipped; the vocabulary asks for a ## Remaining work section 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.md files in repo-level agent-skills/ folders (the scanner still counts these outside the top level) and the loose context-v/README.md files.
  • 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 type when 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.