Link, Lint, and Consolidate
Keep the wiki coherent by treating links, duplicates, contradictions, and staleness as maintainable state.
By the end
You can build a graph from readable links, produce a quality report, and consolidate without letting an agent erase history.
A graph begins with meaningful links
Treat canonical pages as nodes and explicit relationships as edges. Human-authored wikilinks make the graph inspectable; typed fields can distinguish supports, supersedes, owned-by, and depends-on. Begin by making visible links correct. Preserve unresolved links as repair work instead of dropping them, and do not mistake mere co-occurrence for a meaningful relationship.
Lint knowledge the way engineers lint code
A wiki linter makes decay concrete. Check required metadata, invalid dates, orphan pages, unresolved links, duplicate aliases, stale review dates, source-less claims, and impossible status combinations. Separate deterministic fixes from judgment calls. Each finding should carry a severity, page, evidence, and proposed action rather than a mysterious score.
- Error: breaks schema, identity, access, or citation integrity.
- Warning: likely stale, duplicated, weakly sourced, or unresolved.
- Info: opportunity for a backlink, index entry, or clearer title.
Represent disagreement instead of erasing it
A prior plan can be historically accurate and currently inactive; two sources can legitimately disagree. Store claims, sources, relevant time windows, and relationships instead of overwriting until only the newest sentence remains. Statuses and links such as supersedes, contradicts, and valid-during let the current summary favor active truth while retaining an audit trail.
Consolidate through proposals and rollback
Consolidation merges compatible pages, refreshes summaries, adds missing links, and promotes repeated observations. It can also rewrite beliefs. Bound the topic or time window, generate a patch and explanation, require approval for deletion or claim changes, preserve aliases and prior versions, and verify that inbound links and citations still resolve.
Match maintenance cadence to risk
Run cheap deterministic checks on every change and heavier semantic duplicate or contradiction reviews daily or weekly. Review sensitive and fast-changing areas more frequently than timeless reference material. End each run with a digest: what changed, what is unresolved, which pages are stale, and what awaits approval. Invisible background edits are drift, not self-improvement.
Working reference
Commands and patterns
[Starter repo after this lab] Run a machine-readable lint
npm run wiki:lint -- --format json
Runs the Chapter 6 linter; its JSON receipt can power CI, dashboards, and repair queues.
[Starter repo] Review consolidation
git diff --stat && git diff -- vault/Wiki/
Inspect both the size and substance of an agent-generated maintenance patch.
When the happy path breaks
Failure modes
Symptom
The graph has many edges, but following them rarely improves an answer.
Likely cause
Edges were generated from co-occurrence rather than typed meaning.
Recovery
Limit edge types, require evidence, and evaluate graph expansion against real questions.
Symptom
A maintenance agent rewrites summaries back and forth.
Likely cause
Consolidation lacks stable rules and an idempotency test.
Recovery
Version the policy, require a material-change threshold, and test a second run for no-op behavior.
Symptom
Older evidence disappears after a merge.
Likely cause
Deduplication was treated as deletion.
Recovery
Preserve source IDs, history, aliases, redirects, and inbound links before archiving duplicates.
Hands-on lab
Run a knowledge-quality review
Build a linter and repair a deliberately messy ten-page wiki.
- 01Seed ten pages with an orphan, broken links, a duplicate, a stale claim, and a missing source.
- 02Parse frontmatter and body links into a graph keyed by canonical ID.
- 03Generate findings with severity, evidence, and proposed action.
- 04Auto-fix only one deterministic issue.
- 05Merge the duplicate with history and aliases preserved.
- 06Rerun lint and compare resolved and remaining findings.
Deliverable: A linter, before and after reports, one safe auto-fix, and one reviewed consolidation patch.
Reusable artifact
Wiki maintenance runbook
A reusable sequence for coherent maintenance without silent rewriting.
1. Snapshot or commit the vault. 2. Run schema, source, link, orphan, duplicate, and staleness checks. 3. Separate deterministic fixes from judgment-required proposals. 4. Apply deterministic fixes in a bounded patch. 5. Review merges, contradictions, and summary changes. 6. Verify inbound links and citations. 7. Rerun lint and compare issue counts. 8. Publish a digest and operation receipt.
Before you move on
Receipt checklist
- Before and after node, edge, orphan, and unresolved-link counts.
- Machine-readable lint report.
- Reviewed diff for content-changing consolidation.
- Second-run result showing stable behavior.
Primary sources
