wiki-context/skill/lint.md

Lint Procedure

The lint operation health-checks the vault and reports findings. It auto-fixes mechanical issues only. Substantive issues go to the user for review.

Pre-flight

1. Read <vault-root>/CLAUDE.md
2. Read <vault-root>/log.md
3. Confirm the vault is in a clean git state. If not, ask the user whether to proceed (lint is read-mostly, but auto-fixes would commit on top of uncommitted work)

Checks

1. Broken wikilinks

For every wikilink [[<target>]] in the vault:

• If the target file exists, OK
• If the target file does not exist:
  • If the link is unambiguous (target name uniquely matches a file with a different slug), auto-fix
  • Otherwise, flag for user review with the source page and line number

2. Orphan pages

Pages with no inbound wikilinks. List but do not act. Some orphans are legitimate (top-level indexes, brand-new pages).

3. Frontmatter validation

For every page:

• type: must be one of: project, session-notes, entity, topic-landing, synthesis
• status: (where present) must be one of: active, paused, completed, archived
• path: must match the actual folder location
• created: must be present and ISO date format
• updated: must be present, ISO date format, and >= created:
• Page-type-specific required fields per CLAUDE.md spec

Auto-fix: missing updated: (set to created: or file mtime), path: mismatched with folder (correct the field).

Flag for user review: missing type:, invalid type:, malformed dates that can't be inferred.

4. Stale updated: dates

If a file's content has been edited (mtime newer than the updated: frontmatter date by more than 1 day), refresh the date. Auto-fix.

5. Synthesis page integrity

For every page with type: synthesis:

• Every page in the sources: list must exist. Flag any missing.
• For each source, check whether its content has substantively changed since the synthesis page's updated: date. If yes, flag the synthesis page as potentially stale — do not auto-rewrite.
• Verify the synthesis page has a Sources section with prose attribution, not just the frontmatter list.

6. Cross-page contradictions

Best-effort check for the same factual claim stated differently across pages. This is heuristic — flag candidates for user review. Do not auto-resolve.

7. Tag hygiene

• Tags used on only one page may be candidates for retirement (or for the page using a wikilink instead). List but do not act.
• New tags introduced since the last lint pass: list, ask user to confirm they should remain in the curated tag set.

8. Index and landing freshness

• For each <domain>/index.md, check that Active projects list matches the actual status: active projects in the domain. If out of sync, flag (do not auto-fix; that's compile's job).
• Same check for Recent sessions and Synthesis pages sections.

Auto-fix commit

If any auto-fixes were made, commit:

git add -A
git commit -m "lint: <one-line summary of fixes>" -m "<list of fixes>"

If no auto-fixes were made, no commit.

Lint report

Report to the user:

• Auto-fixed — what was fixed (with counts)
• For your review — what was flagged
  • Broken wikilinks (with source pages and line numbers)
  • Frontmatter issues (with file paths)
  • Stale synthesis pages (with names and reasons)
  • Suspected contradictions (with pages and details)
  • New tags (with usage counts and example pages)
  • Stale indexes (suggest running compile)
  • Orphan pages (informational only)
• Suggested next step — usually a compile run if lint found stale indexes or substantive changes

Stop conditions

Stop and report if:

• CLAUDE.md is missing or unreadable
• Git operations fail
• The vault appears corrupted (no recognizable structure)

What this procedure does not do

• Rewrite synthesis pages
• Delete orphan pages
• Modify page content beyond auto-fix scope
• Run compile
• Run migration