lint

name	lint
description	Health-check the Obsidian wiki — the "static analysis" pass for a knowledge base. Use when the user runs /lint, /health, /scan, or asks to "check the wiki", "find broken links", "clean up the wiki", or "find gaps/orphans/conflicts". Read-only scan that reports dead links, dead media embeds, orphan pages, pages missing from index.md, unresolved knowledge conflicts, and the count of pending `flagged:` freshness flags (≥5 suggests a deep-lint). Also restores the graph colour palette on request (on-demand only, never on a routine scan). Proposes fixes but only applies them after the user confirms.
user-invocable	true

lint — knowledge-graph health check

Goal

Bring software static-analysis discipline to the wiki. Find the rot that accumulates as a knowledge base grows: dead links, orphans, unindexed pages, unresolved conflicts.

When to run (and when not)

ingest and query already leave the graph integrity-clean (ingest self-checks at its Step 7), so don't lint routinely after a normal ingest — there's nothing to fix. Run lint when integrity may have drifted from outside that path (manual edits/renames/deletes in Obsidian, external or OneDrive/git sync changes, many ingests over time), or periodically for discovery a per-source ingest can't do: emerging gap pages, cross-corpus contradictions, and stale claims.

Scope boundary: confidence coverage, staleness scoring, and online-source freshness are not lint's job — they live in the heavier, ~monthly deep-lint. Routine /lint stays cheap and never reads pages for confidence or fetches anything.

Triggers

/lint · /health · /scan · "check my wiki" · "find broken links / orphans / gaps".

Pipeline (read-only until the user approves fixes)

1 — Index consistency

Read wiki/index.md; glob every .md under wiki/ (exclude index.md, log.md). Report: pages registered in the index but missing on disk, and pages on disk but not registered.

2 — Link health (one shared script — the single source of truth for link rules)

Run python3 .claude/skills/lint/check-links.py (exit 0 = clean, 1 = findings; deep-lint's structural pass uses the same script). It applies the codified rules so scans never re-derive them: code spans / fenced blocks / HTML comments are not links; frontmatter aliases resolve; vault-path and root-doc targets resolve; wiki/log.md is exempt as a source (append-only history); and media embeds ![[name.png|pdf|…]] are checked against assets/ — a missing target is a dead embed, reported separately (they are checked, not skipped). The script prints its scan totals as its own positive control (§11): zero findings with zero links scanned is a broken probe, not a clean vault.

• Page with no inbound links from any other page → orphan — but exempt index, log, and maps/ pages (Maps of Content are navigational entry points, not orphans).

2b — Pending freshness flags (count only — reconciling them is deep-lint's job)

grep -rl "^flagged:" wiki --include='*.md' | wc -l — with the engine control grep -rl "^confidence:" wiki --include='*.md' | wc -l (must be >0, proving the probe ran). Report the count; at ≥5 flagged pages, suggest running /deep-lint (the adaptive-cadence signal from wiki/developments/deeplint-scalable-maintenance-design.md). Never read or resolve the flagged pages here — lint counts, deep-lint reconciles.

3 — Conflict audit

Find pages containing ## Conflicts / Open Questions. List each unresolved conflict (the two sides) as cognitive tech-debt to resolve.

4 — Gap scan (optional, suggestive)

Note entities/concepts mentioned often but lacking their own page, and stale claims newer sources supersede. Suggest sources or web searches to fill gaps.

Graph colour restore (on-demand — NOT part of a routine lint)

The graph's per-type colours live in .obsidian/graph.json → colorGroups. That file is volatile: Obsidian rewrites it from memory whenever a graph setting changes (or a sync clobbers it), and can wipe the palette so the graph turns all-grey. Unlike dead links or orphans, a wiped palette is immediately visible, so there is no need to scan for it on every lint — handle it only on a real signal.

Trigger — do this only when:

1. the user reports a grey/colourless graph or asks to check/fix/restore graph colours, or
2. it is a fresh vault at first-run — ingest's bootstrap calls this once (see that skill).

Otherwise do nothing: a routine /lint never reads graph.json or the palette.

Procedure (one shared script — the single source of truth for the palette):

• Detect: python3 .claude/skills/lint/apply-palette.py --check → exit 0 = palette complete (stop); exit 1 = it prints the missing framework groups.
• Confirm, then restore: on the user's OK, python3 .claude/skills/lint/apply-palette.py --apply — it merges the canonical palette (.claude/skills/lint/palette.json) into colorGroups, adding only the missing framework groups and preserving any custom groups. Idempotent.
• Reload: tell the user to close the graph view and reload Obsidian (Cmd/Ctrl+R), so Obsidian does not overwrite the edit with stale in-memory state.

The palette data (palette.json) and logic (apply-palette.py) ship with this skill, so setup.sh, ingest's first-run, and this restore all use the same definition — read only on this path, never on a routine lint.

Report format

## 🩺 Wiki Health Report — YYYY-MM-DD

### ✅ Healthy
- ...

### ⚠️ Warnings
- **N orphan pages**: [[..]] — suggest linking or categorizing
- **N unindexed pages**: [[..]] — on disk but missing from index.md

### ❌ Errors
- **N dead links**: [[Source]] → [[Missing Target]] · **N dead embeds**: [[Source]] → ![[missing.png]]
- **N unresolved conflicts**: [[Page]]

### ⏳ Flags
- **N pages carry `flagged:`** (engine control OK) — ≥5 → consider `/deep-lint`

### 🛠️ Proposed next steps
1. Auto-register unindexed pages? (y/n)
2. Re-derive / resolve the listed conflicts?

Hard constraints

• Read-only scan. Do not modify, rename, or delete anything before the report.
• No unverified "clean". A check that returns zero findings must be validated with a positive control (the same probe matching something known to exist) before the report may say "clean" (CLAUDE.md §11).
• Wait for confirmation before applying any fix.
• Graph colour restore is on-demand only (see its section) — never scanned or read on a routine lint.
• After approved fixes, append to wiki/log.md: ## [YYYY-MM-DD] lint | fixed N issues (M dead links, K unindexed).
• Report in British/UK English.