codewiki-lint

name	codewiki-lint
description	Audits CodeWiki health for contradictions, broken wikilinks, orphan pages, stale code claims, source drift, frontmatter/tag problems, oversized pages, and log/index issues. Use when wiki drift is suspected, contested knowledge needs review, a periodic health check is due, or large batches of wiki changes need validation.
allowed-tools	["Read","Glob","Grep","Bash"]

CodeWiki Lint

Inspect the wiki for structural and content health problems so the knowledge base keeps compounding instead of silently drifting out of sync with the project. ## Step 1: Resolve and load the wiki catalog - Read `.codewiki/config.yml` if it exists. - If `.codewiki/config.yml` declares `wiki.path`, use it as the wiki root. - If `wiki.path` is not declared, use `wiki/` as the wiki root. - Read `SCHEMA.md` from the resolved wiki root when it exists. - Read `index.md` from the resolved wiki root first. - Read recent entries from `log.md` in the resolved wiki root. - Glob all markdown files under the resolved wiki root to inventory every wiki page currently present. - Read `_backlinks.json` from the resolved wiki root to identify high-importance pages (many backlinks) versus orphaned pages (zero backlinks). - Run the remaining checks in severity order: HIGH findings first, then MEDIUM findings, then LOW findings.

Step 2: Validate links and index coverage

• Programmatically scan all markdown files for [[wikilinks]].
• Flag broken wikilinks that do not resolve to any wiki page.
• Find pages that exist under the resolved wiki root but are not listed in its index.md.
• Check whether index metadata includes current Last updated and Total pages values.

Step 3: Validate frontmatter and tags

• Check every active wiki page for required frontmatter: title, created, updated, type, tags, sources, confidence, contested, and contradictions.
• Check raw markdown sources for source_url, ingested, and sha256 when applicable.
• Extract the tag taxonomy from SCHEMA.md; flag tags used on pages but missing from the taxonomy.

Step 4: Detect contradictions and quality risks

• Look for conflicting claims about the same entity, decision, issue status, or file ownership.
• Report the conflicting pages and the statements that disagree.
• Surface every page with contested: true or non-empty contradictions.
• List pages with confidence: low.
• Flag single-source pages that have no explicit confidence field.

Step 5: Detect orphaned pages

• Cross-reference with _backlinks.json from the resolved wiki root: pages with zero backlinks and missing index coverage are strong orphan candidates.
• Flag each orphan with its path and likely category.

Step 6: Detect source drift

• For each raw markdown file with sha256 frontmatter, recompute the digest over the body after the closing ---.
• Flag digest mismatches as source drift or raw immutability violations.

Step 7: Detect stale content

• Search for references to deleted, renamed, or missing project files.
• Flag claims that appear to describe code paths or behaviors that no longer exist.

Step 8: Detect missing cross-references

• Find pages that should link to each other but do not.
• Prefer high-value gaps: entity-to-decision, issue-to-lesson, source-to-entity.

Step 9: Detect page size and template drift

• Flag pages over 200 lines as split candidates.
• Compare representative pages against .codewiki/templates/ expectations.
• Flag pages whose structure has drifted so far that future maintenance becomes unreliable.

Step 10: Check log health

• Count log.md entries matching ## [YYYY-MM-DD] action | subject.
• Flag malformed log entries and recommend rotation if the log exceeds 500 entries.
• Include the exact lint log entry the user should append if they approve logging the lint run.

Step 11: Report findings

• Output a structured report grouped by severity:
  • HIGH: broken links, contradictions, source drift, or materially stale claims
  • MEDIUM: missing index coverage, orphan pages, invalid frontmatter, unknown tags, low-confidence/contested pages
  • LOW: template drift, oversized pages, thin pages, discoverability gaps, log rotation
• If the wiki looks healthy, say so explicitly and list any small improvement opportunities.

Step 12: Boundaries

• This is a read-only lint pass.
• Do not edit files from this command.