Wiki Lint Agent Skill

Wiki Lint

<skill_contract>

<input>Vault root, path configuration, audit scope, exclusions, prior baseline, and explicit repair authorization if any.</input>

<output>A reproducible, severity-ranked wiki health report with file-level evidence, debt queues, and bounded repair proposals.</output>

<done>All twelve checks record scope and receipts, findings are reproducible, and report-only mode leaves content unchanged.</done>

<non_goals>Silent deletion, immutable-source mutation, unapproved repair, semantic rewrite, or health claims without scan evidence.</non_goals>

Audit the wiki as a governed knowledge graph. Report prioritized, reproducible findings; make no content mutation unless separately authorized.

Usage Template

Provide: vault root, optional path config, audit scope, prior report, and whether repairs are authorized. Default to report-only.

Workflow

<intake>

Resolve configured source, concept, entity, clipping, daily, system, and log paths. Record scan timestamp, file count, exclusions, and prior baseline. Fail closed if the supplied path is not the intended vault.

</intake>

<unknowns_gate>

If the vault root or path semantics are ambiguous, return NEEDS_INPUT before scanning or writing. Missing optional directories are findings; inaccessible required directories are BLOCKED_PERMISSION.

</unknowns_gate>

<execute>

Run twelve checks and preserve file-level evidence:

• required frontmatter and stable identifiers;
• broken wikilinks and unresolved embeds;
• source references and block locators;
• orphan concepts and isolated entities;
• duplicate titles or semantic duplicates;
• stale notes and unresolved contradictions;
• single-source or weak-provenance claims;
• concept structure and understanding-gate integrity;
• clipping archive and source lifecycle;

10. permission, immutable-source, and human-approval boundaries;

11. daily-loop receipts and flywheel write-back;

12. V7 promotion-gate readiness for proposed rules.

Classify P0 integrity loss, P1 broken provenance/navigation, P2 debt, and P3 improvement. Prefer deterministic checks; label semantic judgments separately.

</execute>

<evaluate>

Re-scan a sample of findings, deduplicate root causes, and compare counts with the prior baseline. A report is invalid if paths, scan scope, or reproduction details are absent. If repair was authorized, run the relevant check again after each bounded repair.

</evaluate>

<state_contract>

Persist {run_id, status, attempt, budget, evidence, unknowns, last_error, next_action} plus vault fingerprint, scan scope, finding ledger, severity counts, baseline delta, authorized repairs, and receipts. Never overwrite the prior report.

</state_contract>

Failure Protocol

• NEEDS_INPUT: vault identity or configured path semantics are unclear.
• BLOCKED_PERMISSION: required files cannot be read or an authorized report cannot be written.
• VERIFY_FAILED: a finding cannot be reproduced; downgrade or remove it.
• BUDGET_STOP: scan budget ends; return coverage and the unscanned queue rather than a whole-vault claim.

Output Contract

Return status, result (severity-ranked findings and health summary), evidence (paths, checks, counts, samples), unknowns (coverage gaps), and next_action with owner and cheap verification.

Edge Cases

• A concept is intentionally unlinked during drafting: classify it as debt with age/context, not a P0 defect.
• A source note has malformed metadata but is immutable: report the issue and propose an overlay/index repair; do not edit the source.

Success Metrics

• Every P0/P1 finding is reproducible from a path and check.
• Coverage, exclusions, and baseline delta are explicit.
• Repair recommendations preserve provenance and include a cheap check.

Quality Gates

• [ ] Vault identity and scan scope are verified.
• [ ] Deterministic and semantic findings are separated.
• [ ] No immutable source was changed without authorization.
• [ ] Report-only versus repair mode is explicit.

</skill_contract>