| name | format-checker |
| description | The record's format rules as a runnable check — frontmatter, filenames, links, structure. Use before handing off any change to knowledge/, when a check fails and you need to fix it, or when unsure whether a document is well-formed. Run with `pnpm check` (or node .agents/skills/format-checker/check.mjs). |
| metadata | {"version":"2.1.0"} |
Format checker
pnpm check runs check.mjs — a self-contained Node program that needs no
install. It is generated by ksor from the same rule set ksor build and
ksor ingest run, so the three can never disagree about what a well-formed
record is. Do not edit it: ksor init writes it and ksor migrate rewrites
both copies of it when you upgrade the tool, so an edit is overwritten rather
than kept. It is read-only in the other direction too — it reports, and never
rewrites a file.
If its refusals contradict this document, the checker is older than the record:
upgrade @panaversity/ksor and re-run ksor migrate, and never "fix" the
record by undoing what the migration wrote.
What it holds the record to (the full contract is ksor's record spec):
- Every document in
knowledge/ is a concept in the KSoR Profile of OKF:
frontmatter is real YAML carrying type, title, description, status
(draft | stable | deprecated) and ksor.audience (a list; public or
audiences registered in .ksor/governance.yaml). A stable concept carries
generated and an approval by an authorised actor; a deprecated one says
who deprecated it and usually names its successor; a reserved type (Policy,
Procedure, …) names sources and ksor.owner. Every timestamp is an
instant with an offset; every footnote label matches a sources[].id.
.ksor/governance.yaml exists and names approval and takedown authorities;
.ksor/takedowns.yaml is append-only, every entry by a takedown authority,
and never names a concept that no longer exists.index.md files are generated by ksor build, never authored — a stale or
missing one is refused (ksor-index-stale; run ksor build). log.md and
README.md are reserved names.- Filenames are portable identities: lowercase ascii, no spaces, no
case-collisions, no
x.md beside x/, no parentheses or leading
underscore. knowledge/ holds .md, companions (<doc>.summary.md,
<doc>.{flashcards,quiz,slides}.yaml) and images only.
- Links resolve inside
knowledge/ — inline, <angle-bracketed> and
reference-style alike; code is never a link — and never reach a document
that not every reader of the source may read (the widening rule).
instance.md is format: 2 with the closed key set the profile defines.CLAUDE.md stays a one-line pointer; .agents/skills/ and
.claude/skills/ hold the same files byte for byte in both directions; the
site contains no content files.
Every failure prints where, the rule's slug (problem: ksor-…), why the rule
exists, and the fix — obey the printed fix literally; if it doesn't resolve
the problem, that is a bug worth reporting to ksor.
When you edit any skill under .agents/skills/, re-copy it to
.claude/skills/ — the checker holds the two trees identical.
