/lint

description: "Run health checks on the wiki. Find broken links, missing indexes, stale content, archive registry drift, inconsistencies, and suggest improvements."
argument-hint: "[--fix] [--deep] [--include-archived] [--archived-only] [--wiki <name>] [--local]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(ls:*), Bash(wc:*), Bash(date:*), Bash(mv:*), Bash(mkdir:*), WebSearch

Your task

**Resolve the wiki.** Do NOT search the filesystem or read reference files — follow these steps: 1. Read `$HOME/.config/llm-wiki/config.json`. If it has `hub_path`, expand leading `~` only (not tildes in `com~apple~CloudDocs`) and prefer that path; use `resolved_path` only as a fallback cache when the expanded `hub_path` is unavailable and `resolved_path` is initialized. If config has only `resolved_path`, use it. If the configured path can be statted but reading `wikis.json` or listing `topics/` fails with `Operation not permitted`, stop and ask the user to grant Full Disk Access/iCloud Drive access to the launcher; do not fall back to `~/wiki` or `resolved_path`. Do not write machine-specific `resolved_path` into shared configs. 2. If no config → read `$HOME/wiki/_index.md`. If it exists → HUB = `$HOME/wiki`. If nothing found, ask the user where to create the wiki. 3. **Wiki location** (first match): `--local` → `.wiki/` in CWD; `--wiki <name>` → `HUB/wikis.json` lookup with portable path resolution (`<HUB>`, `~`, absolute, or HUB-relative); if the registry path is stale, fall back to `HUB/topics/<name>`; CWD has `.wiki/` → use it; else → HUB. 4. Read `<wiki>/_index.md` to verify. If missing → stop with "No wiki found. Run `/wiki init` first."

Read the linting rules at `skills/wiki-manager/references/linting.md`. Then run health checks on the wiki.

Parse $ARGUMENTS

• **--fix**: Automatically fix issues found (default: report only)
• **--deep**: Also use WebSearch to fact-check claims and find missing information
• **--include-archived**: Include archived topic wikis in structural

maintenance. Do not create freshness chores unless the user explicitly asks for a full archived maintenance pass.

• **--archived-only**: Check only archived topic wikis under

`HUB/topics/.archive/`.

Run Checks

Execute checks from `references/linting.md`. Order matters: C13 (alias rewrite) must run before C2 and C11 so downstream checks see canonical field names, and C11 (placement) must run before C3 so the index pass sees final file locations.

1. C1: Structure (Critical)

Verify all required directories and `_index.md` files exist. Treat completely absent `inventory/` and `datasets/` layers as unused optional layers, not critical structure failures.

At the hub level, allow `topics/.archive/` as the archived-topic container. Do not recursively lint archived topic content in a normal lint pass; report the count as skipped unless `--include-archived` or `--archived-only` is set.

2. C13: Frontmatter Aliases (Warning, runs early)

For every `.md` file's frontmatter, rewrite legacy keys and enum values to canonical form using the alias tables in `references/linting.md`. This is how frontmatter schema evolution is handled — there is no migration command. Fix first so subsequent checks see canonical fields.

3. C2: Frontmatter (Critical/Warning)

Read each `.md` file's frontmatter. Check required fields exist and have valid values.

4. C11: Canonical Placement (Critical)

For every `.md` file under `raw/` and `wiki/`, derive the expected directory from its frontmatter using the placement map in `references/linting.md` (raw `type` → `raw/<type>/`; wiki `category` → `wiki/concepts|topics|references/`; `type: thesis` → `wiki/theses/`). Flag files whose actual path doesn't match; auto-fix by `mv`. Flag content directories at the hub level. This heals both user mistakes and stale layouts from older wiki versions with the same code path. Does not touch `output/projects/` — that's C8's territory.

5. C12: Unknown File Quarantine (Warning)

Walk `raw/`, `wiki/`, `inventory/`, `datasets/`, and the wiki root. Flag files and directories that are not in the allowlist for their location (per `references/linting.md` C12 table). Skip `output/` — C8 and C9 own that subtree.

6. C3: Index Consistency (Warning)

Compare actual directory contents against `_index.md` entries. Verify statistics match. Runs after C11 because placement fixes may have changed which files live where — stale indexes will rebuild on next read per the Derived Index Protocol.

7. C4: Link Integrity (Warning)

For each wiki article and inventory record, extract all markdown links. Verify each local markdown link resolves to an existing file. Check bidirectional "See Also" links for wiki articles.

7b. C4b: Source Provenance (Warning)

For wiki articles, verify `sources:` frontmatter resolves to existing raw sources using the Source Reference Resolution protocol. For inventory records, verify local `sources:` entries resolve to existing `raw/`, `wiki/`, `output/`, `datasets/`, or `inventory/` paths; external URLs are allowed. Inventory sources are provenance for tracking state, not factual evidence.

8. C5: Tag Hygiene (Warning)

Collect all tags across all files. Find near-duplicates. Check consistency between files and indexes.

9. C6: Coverage (Suggestion)

Check that every raw source is referenced by at least one wiki article. Find orphan articles with no incoming links.

10. C7: Deep Checks (only if --deep)

Use WebSearch to spot-check key claims. Identify stale content. Suggest new connections and articles.

11. C8: Project Hygiene (Critical/Warning/Suggestion)

For each `output/projects/<slug>/` directory. Sub-check execution order matters — run C8c first so migrated projects pass C8a in the same lint pass:

1. **C8c** (run first): if a legacy `_project.md` is present, migrate it to `WHY.md` per the rule in `references/linting.md` § C8 (critical, auto-fixable — this is the first real appli