38f4431341
Separated skill-wiki.md bundle into compile.md, lint.md, migration.md. Backported compile.md and SKILL.md (skill-wiki.md) from the installed skill at ~/.claude/skills/wiki-maintenance/ so the repo archive reflects the shipped two-layer Sources/+Wiki/ taxonomy rather than the old flat draft. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
135 lines
3.9 KiB
Markdown
135 lines
3.9 KiB
Markdown
# 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 |