Wikilink Auto-Repair + Slack Reporting — Plan

Created 2026-07-07

Tags planvaultwikilinksautomationslackmonitoring

Wikilink Auto-Repair + Slack Reporting

Follow-up to vault-audit-report-2026-07-05, triggered by Patrick’s question: why do the daily vault-health Slack alerts keep reporting “a bunch of broken wikilinks,” and can a mechanism auto-fix them and report to Slack with structure recommendations?

Diagnosis (verified 2026-07-07)

Most of the alerted breakage is phantom. The daily Slack alert reads broken_links from the VPS copy of vault-index.db. That count was 71 this morning; a fresh --full rebuild of the same git tree shows only 16 genuinely broken links (all cosmetic, itemized in the audit report).

The ~55 phantom rows exist because of a design gap in scripts/build-vault-index.py: link resolution happens per-file at index time, and the incremental rebuild (the only mode the VPS ever runs, via post-sync-hook.sh) never re-checks old rows. Two stale classes accumulate:

Target-created-later links. File A links to file B before B exists; the row is stored resolved = 0 and stays that way forever unless A itself changes or a --full rebuild runs. Verified example: the whole photography-videography-2026 cluster links to montreal-film-schools-master-list, which exists at contacts/montreal-film-schools-master-list.md — flagged broken on the VPS, resolved on any full rebuild.
Pre-parser-improvement rows. The indexer gained code-block/inline-code exclusion (last parser change 2026-05-24). Files indexed before that still carry rows for syntax examples like [wikilink](/wikilink/), [Star Form](/star-form/), [_index](/index/) in guideline docs and old logs. Those files haven’t changed since, so their stale rows persist on the VPS.

This also explains the step pattern in scripts/audit-log.json (110 → 71 → 16-on-Mac → 71-on-VPS): counts drop wherever a full rebuild happens and plateau elsewhere. A --full rebuild takes 0.62 s on the whole vault, so there is no performance reason to avoid it.

Proposed mechanism (three tiers)

Tier 1 — Kill the phantoms (root cause, ~2-line change)

Make post-sync-hook.sh run build-vault-index.py --full instead of incremental (0.62 s, negligible), or keep incremental on the 5-minute cycle and add a daily --full before the 4:15 ET vault-audit-slack.sh run on the VPS. Either way the Slack alert starts reporting the true number. This alone removes ~78% of the reported breakage.

Tier 2 — Auto-repair the genuine breakage

New script scripts/repair-wikilinks.py, run daily on the VPS after the full rebuild (and available manually anywhere):

For each resolved = 0 row, attempt in order:

Unique basename match — target filename exists exactly once elsewhere in the vault (the moved-file case) → rewrite the link in the source file. Safe, automatic.
Git rename detection — git log --follow --diff-filter=R on the raw target path → rewrite to the renamed path. Safe, automatic.
Near-miss match — case difference, or fuzzy match (difflib ratio ≥ threshold) with exactly one candidate (catches typos like BNNet → BRNet) → auto-fix only at high confidence; otherwise queue as a suggestion.
Unfixable (target genuinely absent, links to .txt/.yml/directories) → queue for the report with a suggested manual resolution (e.g. “convert to backtick path” for non-md targets, per the vault’s own standards).

Guardrails: never touch files under 04-archive or auto-synced community content without a flag; every rewrite goes through the normal vault-sync commit (attributed, revertable); dry-run mode; a .repair-log.json so the same suggestion isn’t re-reported daily.

Tier 3 — Slack report with structure recommendations

Extend the daily VPS flow (vault-audit-slack.sh already posts to #agent-alerts; slack-notify.sh exists):

Fixed: “Auto-repaired N wikilinks” with the list (source → old → new).
Needs a decision: the unfixable queue, each with its suggested resolution.
Structure recommendations: heuristics already computable from vault-index.db + vault-audit.py metrics — directories missing index.md ranked by file count, orphan clusters sharing a parent (one missing index link away from connected), files without frontmatter, single-use tags that fuzzy-match an existing tag. Cap at 3–5 recommendations per message so it stays readable.
Optional later: a weekly Claude CLI pass on the VPS (token infrastructure already exists per 00-inbox/claude-code-shared-context.md) that turns the raw heuristics into a short prose digest.

Sequencing

Tier 1 is a quick win and should ride along with the audit’s remediation batch (it also touches post-sync-hook.sh, same file as audit quick-win #4). Tiers 2–3 are one build session together, ideally after the audit’s quick wins land so the repair script starts from the clean 16-link baseline. This plan folds into the audit report’s remediation plan as an addition to the “quick wins” (Tier 1) and a new structural item (Tiers 2–3).

Status

IMPLEMENTED 2026-07-07 — all three tiers, approved by Patrick and applied same day:

Tier 1 done. scripts/post-sync-hook.sh now runs build-vault-index.py --full on every sync (measured 1.3–1.6 s on the full vault). The VPS picks this up automatically via vault-sync.sh git pull, so the phantom rows die on its next cycle. Bonus root-cause fix: build-vault-index.py now resolves wikilinks to non-md assets ([file.txt](/filetxt/), [config.yml](/configyml/)) when the file exists, so correct asset links stop counting as broken.
Tier 2 done. New scripts/repair-wikilinks.py (stdlib only, dry-run by default, --apply to write). Strategies: asset-extension fix, git rename detection, unambiguous fuzzy match. Protected paths (04-archive, auto-synced community content) are skipped unless --include-protected. Suggestions dedup against gitignored scripts/.repair-log.json. First real run auto-fixed 8 links (5 BRNet transcript links → .txt targets, 3 people-index links → .yml targets); vault went from 16 broken rows to 8 (6 distinct links), all directory links whose real fix is the index.md work in vault-audit-report-2026-07-05 remediation item S5.
Tier 3 done. New scripts/wikilink-repair-slack.sh: daily VPS cron at 04:00 ET (before the 04:15 vault-audit alert): full rebuild → auto-repair → commit/push fixes via vault-sync.sh → Slack message to #agent-alerts with fixes, new needs-a-decision items, and up to 5 structure recommendations (dirs missing index.md ranked by size, orphan clusters, frontmatter-less notes, probable tag typos). Posts only when the message differs from the last one sent, so no repeat noise.

Remaining 6 broken links (all directory links wanting an index.md) are intentionally left for the audit remediation discussion; they’ll appear once in the first Slack report as the needs-a-decision queue.