85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
|
---
|
||
|
|
name: validate
|
||
|
|
description: >-
|
||
|
|
Check that an Open Knowledge Format (OKF) bundle is conformant with the v0.2
|
||
|
|
spec (§11). Use when asked to validate, lint, or check an OKF bundle, or before
|
||
|
|
committing changes to one. Runs a deterministic Python checker — not an
|
||
|
|
eyeball pass. Also migrates a v0.1 bundle to v0.2 in place with `--migrate`.
|
||
|
|
user-invocable: true
|
||
|
|
argument-hint: "[bundle-dir] [--strict | --max-warnings N] [--migrate]"
|
||
|
|
allowed-tools: Bash
|
||
|
|
---
|
||
|
|
|
||
|
|
# Validate an OKF bundle
|
||
|
|
|
||
|
|
Run the deterministic conformance checker against the target bundle. Default to
|
||
|
|
the project's `.okf/` directory when no path is given.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS
|
||
|
|
```
|
||
|
|
|
||
|
|
If `uv` is unavailable, fall back to:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python3 -m pip install --quiet pyyaml && \
|
||
|
|
python3 "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS
|
||
|
|
```
|
||
|
|
|
||
|
|
`${CLAUDE_SKILL_DIR}` resolves whether this skill runs as part of the `okf`
|
||
|
|
plugin or is installed standalone (e.g. via `npx skills add`), so the checker is
|
||
|
|
always found alongside the skill.
|
||
|
|
|
||
|
|
Interpret the result:
|
||
|
|
|
||
|
|
- **ERROR** → a hard §11 conformance failure (no parseable frontmatter, a
|
||
|
|
missing/empty `type`, or a file the checker cannot read as UTF-8). The bundle
|
||
|
|
is non-conformant. Fix every one.
|
||
|
|
|
||
|
|
Only `index.md` and `log.md` are reserved: §11.1 makes *every* other `.md` in
|
||
|
|
the tree a concept, convention files included. An `AGENTS.md` or `README.md`
|
||
|
|
dropped next to a bundle is therefore an ERROR until it carries frontmatter with
|
||
|
|
a `type` (`Document` reads well), which is the fix; a skip-list would put the
|
||
|
|
checker out of conformance. Move the file above the bundle root if it is not
|
||
|
|
knowledge.
|
||
|
|
- **warn** → soft guidance (missing recommended field, non-ISO log date, broken
|
||
|
|
cross-link, a malformed v0.2 family, a footnote naming no source, an actor
|
||
|
|
that misses the §7 shapes, an Attested Computation missing `runtime`, a
|
||
|
|
computation path that resolves nowhere, frontmatter in a reserved file (§8,
|
||
|
|
§9), a root `index.md` carrying extra keys or declaring a different
|
||
|
|
`okf_version` (§12)). Never blocks; broken links in particular are explicitly
|
||
|
|
tolerated by the spec (§6.1). Fix when cheap.
|
||
|
|
|
||
|
|
One warning is worth more than the others: a §7 near-miss such as `Human:dana`
|
||
|
|
or `human/dana`. §5.3 keys trust tiers off the exact lowercase `human:` prefix,
|
||
|
|
so the concept silently reads as machine-confirmed when a person did review it.
|
||
|
|
Fix that one on sight.
|
||
|
|
|
||
|
|
v0.1 bundles validate too: a legacy `timestamp` or `# Citations` section is
|
||
|
|
reported as a warning naming its v0.2 replacement (`generated.at`, `sources`),
|
||
|
|
never as an error (§13.1). Under `--strict` those warnings do fail the run —
|
||
|
|
that is the migration nudge, and `--migrate` is the door.
|
||
|
|
|
||
|
|
## Migrating a v0.1 bundle
|
||
|
|
|
||
|
|
`--migrate` **rewrites the bundle in place** before validating — the one mode of
|
||
|
|
this skill that is not read-only, so say what it will touch before running it on
|
||
|
|
a bundle the user has not asked to migrate. It is textual (comments, key order
|
||
|
|
and quoting survive) and idempotent.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" .okf --migrate --strict
|
||
|
|
```
|
||
|
|
|
||
|
|
It hoists `timestamp` to `generated: { by: process:okf-migrate, at }`, lifts a
|
||
|
|
`# Citations` list into `sources`, and bumps `okf_version`. Two limits worth
|
||
|
|
repeating to the user: `generated.by` cannot be recovered for pre-v0.2 content
|
||
|
|
(hence the `process:` actor — the concept stays correctly `unverified` under
|
||
|
|
§5.3), and per-claim `[^id]` attribution was never encoded in v0.1, so only the
|
||
|
|
source list moves up.
|
||
|
|
|
||
|
|
## Exit codes
|
||
|
|
|
||
|
|
Non-zero if any error is present, or if warnings exceed the gate:
|
||
|
|
`--strict` allows none, `--max-warnings N` allows N, the default allows any.
|
||
|
|
Add `--json` for machine-readable output (useful in CI).
|