kb-lint

name	kb-lint
description	Health check the knowledge base — validates schema, detects broken links, orphans, staleness, and missing provenance. Use when the user wants to lint, validate, or health-check their KB. Also triggers on "kb-lint" or "/kb-lint".

kb-lint

Run health checks on the knowledge base. Validates frontmatter schema, detects broken wikilinks, orphaned pages, stale content, and missing provenance.

Arguments

• --fix — Automatically apply safe fixes (optional).
• (no arguments) — Report-only mode.

Step 1: Resolve KB

python3 ~/.config/kb/scripts/kb_resolve.py --mode mutating

Note: lint itself is read-only, but --fix is mutating. Resolve in mutating mode so fixes can be applied if requested.

Step 2: Run Lint Checks

python3 ~/.config/kb/scripts/kb_lint_checks.py "{{KB_ROOT}}"

If --fix was passed:

python3 ~/.config/kb/scripts/kb_lint_checks.py "{{KB_ROOT}}" --fix

The script returns a JSON report with this structure:

{
  "errors": [...],
  "warnings": [...],
  "info": [...],
  "fixable": [...],
  "summary": {
    "total_pages": 0,
    "errors": 0,
    "warnings": 0,
    "info": 0
  }
}

Step 3: Parse and Categorize Findings

CRITICAL (must fix)

• missing_frontmatter — Page lacks required YAML frontmatter.
• invalid_type — type field is not one of: entity, concept, summary, synthesis.
• missing_source_ids — Page has no source_ids or references non-existent raw files.
• invalid_confidence — confidence is not a number between 0.0 and 1.0.
• invalid_stability — stability is not one of: stable, permanent, evolving, volatile.

WARNING (should fix)

• broken_wikilink — [[wikilink]] target page does not exist.
• orphaned_page — Wiki page not referenced by any other page or index.
• stale_page — last_verified significantly older than source modification date. Present as warning only; NEVER auto-adjust confidence based on staleness.
• missing_tags — Page has an empty tags array.
• missing_dates — created or last_verified fields missing.
• deprecated_links — Active pages still link to pages in wiki/deprecated/.

INFO (optional)

• unprocessed_sources — Raw files with no corresponding summary page.
• low_confidence — Pages with confidence below 0.4.
• large_pages — Pages over 500 lines that could be split.
• deprecated_count — Number of pages in wiki/deprecated/.
• human_reviewed_count — Number of write-protected pages.

Step 4: Present Report

Display findings grouped by severity:

## KB Lint Report: {{KB_NAME}}

### CRITICAL ({{N}})
- [path] — description of issue

### WARNING ({{N}})
- [path] — description of issue

### INFO ({{N}})
- [path] — description of issue

### Summary
- Total pages scanned: {{N}}
- Issues found: {{N}} critical, {{N}} warning, {{N}} info
- Human-reviewed pages: {{N}} (excluded from auto-fix)

Step 5: Offer Auto-fixes

If --fix was passed or the user approves, apply safe fixes:

Safe auto-fixes (apply automatically)

• Add missing optional frontmatter fields with defaults.
• Set created and last_verified to today if missing.
• Add empty tags array if field is absent.
• Fix broken wikilinks where the target page can be unambiguously resolved.
• Replace wikilinks to deprecated pages with plain text + deprecation note.

Unsafe fixes (require confirmation per-item)

• Update source_ids to fix broken references.
• Move orphaned pages to wiki/deprecated/.
• Generate skeleton frontmatter for pages missing it entirely.

Never auto-fix

• Never edit pages where human_reviewed: true. Report issues but skip fixes. Print: "SKIPPED: {{PATH}} — human_reviewed is true. Fix manually."
• Never modify confidence values. Confidence is event-driven only.
• Never delete any files. Only deprecate.
• Never modify raw/ files.

Step 6: Append Log

Add a row to log.md:

| {{DATE}} | lint | {{N}} critical, {{N}} warning, {{N}} info — {{N}} auto-fixed |

Final Output

Print:

• Overall health status (healthy / needs attention / critical).
• Summary counts by severity.
• List of auto-fixes applied (if any).
• List of issues requiring manual attention (especially on human_reviewed pages).
• Suggestion: "Fix critical issues first, then run kb-lint again to verify."