wiki-lint

Run a comprehensive wiki lint pass. Follow each step in order.

A slash command runs in whatever directory the session happens to be in, so do not use bare relative paths — every path below is absolute under the wiki root.

1. Resolve the wiki root and run the mechanical pass. Set WIKI to the path in ~/.claude/wiki-root if that file exists, else ~/knowledge/wiki (expand the ~ to the absolute home path), and use $WIKI/... throughout. Then run bash ~/.claude/hooks/wiki-lint-checks.sh and keep its output: it precomputes the deterministic facts (QUEUE, BROKEN-LINK, FRESHNESS, LOG-GAP, TASK, ROOT-ENTRY lines) that steps 1-8 consume — do not re-derive those by hand. (Script not installed? Derive the same facts manually and continue.) After each step, append one line to $WIKI/.lint-run recording what you did and what you found (e.g. step 3 broken-links: 2 found, 2 fixed). Start by truncating $WIKI/.lint-run.

The mechanical checks (link validity, freshness inputs, log gap, task collection, root listing) live in the script — same answer every run, no tokens spent re-deriving them. The judgment calls (which pages to update, whether a flagged item actually matters, what to fix vs surface) are yours and stay in the steps below.

1. Process update queue. The QUEUE line says whether $WIKI/.update-queue has entries. If so, read each entry, determine which wiki pages need updating, update them, clear the queue.
2. Freshness check. From the FRESHNESS lines: flag pages whose last_updated lags far behind their git activity, and project pages >1 week stale relative to their repo. (Mechanical inputs; the staleness call is yours.)
3. Broken links. Fix each BROKEN-LINK line: auto-fix obvious renames, flag true orphans.
4. Task aggregation. From the TASK lines: age via git blame if useful, write the top 10 to $WIKI/tasks-open.md.
5. Log gap check. Flag if the LOG-GAP line shows the most recent $WIKI/log.md entry is >3 days old.
6. Unprocessed sources. Skip unless your pages actually use a processed: frontmatter key — no shipped page does on a fresh install, so this no-ops until the convention appears. Once it does: flag files in $WIKI/sources/ without processed: true, older than 5 days.
7. Log rotation. If $WIKI/log.md has entries older than 30 days, archive them to $WIKI/sources/log-archive-YYYY-MM.md.
8. Root cleanliness. Check each ROOT-ENTRY line (the knowledge root's contents) against the approved bucket list in CLAUDE.md. Ask triage for anything loose: do it / defer it / kill it.
9. Auto-memory drift check. Skip unless you have enabled Claude Code memory (the template does not scaffold it). If enabled: diff key facts between auto-memory and wiki, auto-fix obvious staleness.
10. Plan reconciliation. Skip unless your plan pages actually carry a last_reconciled frontmatter key — no shipped page does on a fresh install. Once they do: for each $WIKI/plans/*.md, compare last_reconciled to last_updated of any referenced project and flag plans that predate their dependencies.
11. Heartbeat. Write the current timestamp to $WIKI/.lint-heartbeat. Update the Last updated / Last lint heartbeat line in $WIKI/INDEX.md with the lint summary, and make sure its task pointer reads tasks-open.md.
12. Report. Read $WIKI/.lint-run back verbatim, then present findings: auto-fixed (just report) and needs-attention (ask triage per item).
13. Remote sync. cd "$WIKI" && ([ -z "$(git status --porcelain)" ] || (git add -A && git commit -m 'wiki-lint: auto-sync' && GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=10' git push)). git status --porcelain (not git diff) is the dirty check so brand-new untracked pages count as changes too. BatchMode makes an SSH remote fail fast instead of hanging when no ssh-agent is loaded; an HTTPS remote with a credential helper avoids it entirely.

These steps grow as conventions actually appear. Following the repo's own rule, add a new check (or a new gated frontmatter key) only after its need has fired twice — don't pre-wire checks for keys no page uses yet.