Wiki lint

/wiki-lint — Karpathy wiki health-check

Purpose

Validate that a markdown wiki is navigable, source-backed, and safe to use as LLM context.

Input:

knowledge/<topic>/INDEX.md
knowledge/<topic>/_sources.md
knowledge/<topic>/_log.md
inventory/              # optional but expected for fresh builds
text_corpus/            # optional corpus backing

When to use

Triggers:

• "Check the wiki / knowledge base"
• "Run lint on <topic>"
• "Are there any duplicates / broken links / orphans?"
• After /wiki-build
• After a big /corpus-ingest
• Before using the wiki as a sales/client deliverable

Do NOT use:

• on daily memory notes
• on random non-Karpathy folders without INDEX.md
• as a replacement for corpus conversion/OCR

Checks

1. INDEX integrity

• INDEX.md exists
• all listed node links exist
• all actual nodes are listed or intentionally excluded
• "When to read what" routes to real files/anchors
• subfolders with 3+ nodes have a local INDEX.md

2. Markdown links

• all local links resolve
• no stale renamed paths after cleanup
• no broken relative paths to inventory/ or text_corpus/

3. Source map integrity

• _sources.md exists
• source refs used in nodes appear in _sources.md
• source paths/reports exist where local
• coverage caveats mention skipped/failed buckets from inventory reports

3a. Source notes & semantic layer

• source_notes/README.md exists and explains the layer
• topic nodes cite source notes via [[source_notes/<bucket>/<id>#anchor]] evidence-links, NOT raw text_corpus/ paths
• every [[source_notes/...]] link resolves to an existing file with the referenced anchor
• significant useful_text sources from inventory reports either have a source note OR are explicitly listed as deferred in caveats
• routing-only files (_pdf_sources.md, _image_sources.md) are not cited from topic nodes as the route to comprehension — they may exist for audit but should be flagged as audit-only
• contradictions.md exists (even empty); cross-source disagreements are not silently resolved in topic nodes
• topic nodes do not contain phrases like "see these PDFs", "list of routed sources", "full extraction map → PDF" — that is shallow integration

4. Corpus drift

Compare the wiki/source map against the project corpus:

• text_corpus/ files not referenced anywhere
• inventory/*report* newer than the wiki _log.md
• conversion reports mention failures not reflected in caveats
• raw buckets not represented in the sources map

5. Duplicates

• similar node names
• repeated sections across nodes
• duplicate source listings
• same topic split across multiple nodes without a cross-reference

6. Orphans

• node exists but is not in INDEX.md
• source/output exists but is not in _sources.md or _pdf_sources.md
• wiki file has no inbound/outbound references

7. Stale and caveats

• old updated: dates
• recency markers older than 12 months for unstable claims
• caveat says "not parsed" but the corpus now has extracted outputs
• known failed buckets not listed in caveats

8. Contradictions

LLM-assisted pass when needed:

• conflicting numbers/dates/rules
• opposite recommendations
• incompatible source interpretations

Contradictions require a user decision; do not auto-fix them.

9. Structure hygiene

Project-level sanity when running after ingest/build:

• raw files under raw/
• extracted text under text_corpus/
• runtime caches under _runtime/
• accidental/legacy dirs under _archive/
• logs grouped by domain
• README explains the canonical structure

Phase 0 — Scope

Determine the lint target:

• /wiki-lint <topic> → one wiki
• /wiki-lint → active project wiki
• /wiki-lint --all → all project wikis

If multiple candidates exist, ask once.

Phase 1 — Run deterministic checks first

Use file-system checks before LLM reasoning:

• list files
• parse markdown links
• grep source refs
• compare timestamps and report paths
• count orphans/broken links

For large contradiction checks, /batch-analyze can be used internally as an extract/verify utility.

Phase 2 — Report

Report categories:

INDEX integrity: ok / issues (intent-routes? topic-listing-only?)
Broken links: N
Source map: ok / issues
Source notes & semantic layer: ok / shallow / missing
  - source notes coverage: M of K useful_text sources
  - evidence-link integrity: N broken / N raw-path citations
  - audit-only files cited as memory: N
Contradictions log: present / missing / silently-resolved
Corpus drift: N
Duplicates: N
Orphans: N
Stale/caveats: N
Contradictions found by LLM pass: N
Structure hygiene: ok / issues

Separate:

• auto-fixable
• needs a user decision
• informational caveats

Phase 3 — Fix policy

Auto-fixable after confirmation:

• broken local links caused by renames
• missing INDEX entries for obvious nodes
• stale caveat wording that contradicts current reports
• source map path updates after cleanup
• README/log updates

Never auto-fix without a decision:

• merge/delete duplicate content
• resolve contradictions
• delete raw/source files
• remove wiki nodes

Prefer moving questionable files to _archive/ or _orphans/, not deleting.

Phase 4 — Log

Append to the wiki _log.md:

- YYYY-MM-DD: wiki-lint — broken links N, source issues N, orphans N, fixed M, deferred K.

Also append to the daily note for meaningful cleanup.

Anti-patterns

• Do not delete files as a lint fix.
• Do not report "ok" if source reports show skipped/failed buckets.
• Do not use the LLM contradiction pass before deterministic link/source checks.
• Do not silently rewrite node content while "linting".
• Do not let lint become ingest or wiki-build.