# 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