Skip to main content

Linting and Health

lore lint [--json]

Runs health checks on the wiki:

  • Orphans -- articles with no incoming links
  • Gaps -- concepts mentioned in multiple articles but without their own article
  • Ambiguous -- articles with confidence: ambiguous in frontmatter
  • Suggested questions -- follow-up prompts generated from gaps/orphans/ambiguity
  • Diagnostics -- line-aware diagnostics for actionable fixes

Why Lint Matters​

Lint transforms wiki quality issues into a prioritized, machine-readable queue for maintenance.

  • catches broken conceptual links early
  • reveals weak coverage and disconnected pages
  • helps drive follow-up compile and content work

Diagnostics (JSON)​

lore lint --json includes a diagnostics array while preserving legacy summary arrays.

Diagnostic shape:

{
	"rule": "broken-wikilink",
	"severity": "error",
	"file": ".lore/wiki/articles/example.md",
	"line": 12,
	"message": "Wiki link target missing-topic has no corresponding article."
}

Current rules:

  • broken-wikilink (error)
  • orphaned-article (warning)
  • ambiguous-confidence (warning)
  • missing-summary (warning)
  • short-page (warning)

Rule Priority Matrix​

RuleSeverityTypical action
broken-wikilinkerrorCreate missing target article or fix link target
orphaned-articlewarningAdd incoming links from related articles
ambiguous-confidencewarningClarify claims and adjust confidence when warranted
missing-summarywarningAdd frontmatter summary
short-pagewarningExpand article body with meaningful context

Human Mode Output​

Human mode prints classic summary counts and diagnostics counts:

  • Orphans: X, Gaps: Y, Ambiguous: Z
  • Diagnostics: N (E errors, W warnings)
# 1) gather machine-readable health findings
lore lint --json > lint.json

# 2) prioritize hard failures first
# (broken wikilinks are emitted as diagnostics with severity=error)

# 3) recompile/reindex after edits
lore compile
lore index --repair

# 4) re-check health
lore lint --json

Suggested Remediation Workflow​

  1. fix all broken-wikilink diagnostics first
  2. resolve high-impact orphans (core architecture concepts)
  3. address ambiguous pages and add summaries
  4. re-run compile/index if content changed substantially
  5. re-run lint until diagnostic trend is decreasing

Example Fix Patterns​

  • before: [[compile-locking-system]]
  • after: [[Compile Locking]] or create the missing article

Orphaned article​

  • add backlinks from parent/adjacent concepts
  • ensure article appears in at least one navigation-relevant page

Missing summary​

summary: "Prevents overlapping compile runs and stale output writes."

Using Lint in Automation​

lore lint --json > lint.json

# treat errors as blockers in CI scripts
cat lint.json

For MCP-based maintenance loops, use lint_summary, list_orphans, list_gaps, and list_ambiguous.