wiki-lint

name	wiki-lint
description	Use when checking wiki health, detecting broken links, validating frontmatter, finding orphan pages, or auditing ref/ discoverability. Triggers: 'lint wiki', 'check wiki', 'wiki health', 'broken links', 'index drift', 'frontmatter check'. Soft report only — never blocks deploy.
version	1.0

Wiki Lint Skill

Goal

Detect structural decay in docs/wiki/ — broken links, index drift, frontmatter violations, orphan pages, missing See Also, ref discoverability gaps. Soft report: appends findings to docs/logs/knowledge-changelog.md. Never fails a build, never deletes content.

Workflow

1. Scope

Lint every .md file under docs/wiki/, including:

• docs/wiki/core/
• docs/wiki/components/, docs/wiki/features/, docs/wiki/database/, docs/wiki/logic/
• docs/wiki/hooks/, docs/wiki/integrations/
• docs/wiki/ref/ (special handling)
• docs/wiki/templates/, docs/wiki/examples/ (linter target only, not orphans)

2. Deterministic Operations

2.1 Index consistency — every file in docs/wiki/**/*.md (excluding index.md, ref-index.md, *-template.md, *-example.md, and anything in templates/ or examples/) must appear in docs/wiki/core/00-system-index.md. For every entry in 00-system-index.md, verify the file exists. Missing files marked [MISSING].

2.2 Internal links — every [label](relative-path) in any wiki file must resolve. Auto-fix on --fix if exactly one match elsewhere in the wiki; otherwise report with file:line. Self-referential links ([foo](foo.md) resolving to the same file) are ignored, not bugs.

2.3 Frontmatter — every wiki doc must have YAML frontmatter with type, name, status. status must be one of stable|in-progress|deprecated. dependencies paths must exist.

2.4 Orphan pages — wiki files with zero inbound links from any other wiki file. Exclude 00-system-index.md, knowledge-changelog.md, ref/, templates/, examples/. Report only — never auto-delete.

2.5 See Also health — warn on wiki files >100 lines without ## See Also. Validate any See Also link resolves.

2.6 ref/ coverage — every file in docs/wiki/ref/ must appear in docs/wiki/ref/ref-index.md.

3. Error Handling

Every operation must handle these gracefully:

• Empty wiki — no docs/wiki/**/*.md files exist → report 0 issues, exit cleanly.
• Missing index — 00-system-index.md doesn't exist → create with empty TOC, log to changelog as informational.
• Locked file — file exists but is read-only → skip, log to changelog with file path.
• Permission denied — read fails → skip, log warning, continue with other files.
• Self-referential link — [foo](foo.md) resolves to the same file → ignore (not a bug).
• Always exit cleanly — never throw, never leave the changelog in a partial state. Use single append per lint run.

4. Output

Append exactly one entry to docs/logs/knowledge-changelog.md per invocation:

## [YYYY-MM-DD HH:MM] — lint | <N> issues found
* **Skill:** wiki-lint
* **Findings:** N1 (broken links, index drift) | N2 (orphan pages, missing See Also) | N3 (passes)
* **Files affected:** [list with file:line]
* **Notes:** <optional summary>

5. Optional Flags

• --fix — auto-fix deterministic issues (index entries, broken links with exactly one match). Still soft-report; never delete content.
• --quiet — no changelog entry on clean run (0 issues). Default is to log a baseline entry on every invocation.
• --scope <path> — limit lint to a subdirectory (e.g. --scope docs/wiki/ref/).

Usage Guidelines

• Proactive: Run at end of any work that touched wiki docs (per agent-wrap-up protocol).
• First-thing: Run @wiki-lint on a fresh wiki to establish a baseline.
• Drift detection: Run weekly to catch gradual decay (e.g. renamed files leaving dead links).