CLI · judge

okf lint

The advisory report: is this bundle well curated?

When to use it

After okf validate passes. validate answers "is it legal?"; lint answers the complementary question: is it well curated, navigable, trustworthy? The curation model explains the split.
On a maintenance pass, to find the highest-value fix: an orphan to link, a stub to expand, a missing concept the bundle keeps pointing at.
In CI, only if you opt in with --fail-on warn. Without that flag, lint exits 0 even with findings.

How it works

lint inspects exactly the things section 9 forbids the validator from rejecting. It has its own report, never emits conformance errors, and stays advisory unless you gate it. Findings fall into six categories, each backed by individual checks:

reachability: orphans, concepts in no index, disconnected islands, degree-0 files (orphan, not_in_index, disconnected_component, unlinked);
backlog: demand-ranked missing concepts and broken index entries (missing_concept, broken_index_entry);
completeness: stubs and missing title / description / timestamp (stub, missing_title, missing_description, missing_timestamp);
freshness: concepts older than a cutoff (stale), computed only when you pass --stale-after;
provenance: uncited external claims and broken citations, per section 8 (uncited_external, broken_citation);
hygiene: duplicate titles, unused or undefined reference links, self-links (duplicate_title, unused_reference_def, undefined_reference, self_link).

Two knobs tune specific checks: --min-body N sets the stub body threshold in characters (default 50), and --stale-after DUR sets the stale cutoff as a duration (90d, 12w) or an ISO date (2026-01-01). --only and --except select checks by name.

Try it

okf lint docs/

OKF lint - docs
  concepts: 37   edges: 87   index.md: 10   log.md: 1
  hubs: features/chat/sources/source-ingestion-pipeline (×12), …

  Backlog
    · info  graph-view.md: referenced by 3 link(s) across 2 concept(s) but does not exist
    ! warn  features/index.md: index links to missing concept `../../CHANGELOG.md`
  Completeness
    · info  features/bundles/entry-editor.md: missing recommended field: description
  Hygiene
    ! warn  link-suggestions.md: reference-style link `[:approved_ids]` has no matching definition (an invisible broken link)

  ⚠ 3 warn, 31 info

For a machine, okf lint docs/ --json emits { bundle, healthy, stats, findings } as compact single-line JSON. That report is the substrate an agent consumes to reason about the two things lint deliberately does not compute, contradictions and semantic staleness, because both need an understanding of meaning.

Pitfalls

--only and --except take check names, not category names. okf lint docs/ --only orphan,stub works; --only reachability is a usage error (exit 2). The valid names are the parenthesized ones above.
A plain okf lint never reports staleness. The stale check runs only when you pass --stale-after; and the value must be a duration or an ISO date, a bare number like 90 is rejected.
Findings do not fail the run. Lint exits 0 with a screen full of warnings unless you pass --fail-on warn. If you want a hard gate, say so explicitly, in CI and in scripts.
Do not send conformance questions here. Lint never emits section 9 errors; a bundle can lint clean and still be non-conformant. Run okf validate for legality.