Wiki Frontmatter Maintenance

Source Excerpt

Overview

Wiki frontmatter maintenance encompasses the ongoing processes of validating, repairing, and enriching YAML frontmatter across the retired internal project wiki. With 2,364+ markdown files and frontmatter validity sitting at approximately 35-36%, this is one of the most persistent wiki health challenges.

Required Frontmatter Schema

Every content page must include YAML frontmatter with the following fields:

---
title: "Page Title"
type: "concept"          # concept | entity | guide | reference | synthesis | summary
status: "active"         # draft | active | deprecated
created: "YYYY-MM-DD"
author: "Agent Name"
last_updated: "YYYY-MM-DD"
tags: [tag1, tag2, tag3]
related:
  - [[Related Page Title]]
sources:
  - [[Source Page]]
---

Exempt from frontmatter requirements: index.md files, log.md, raw source files (raw/), schema templates, changelogs, and archived content.

Enrichment Baseline (2026-05-10)

As of the May 10, 2026 remediation effort, the following enrichment stats were recorded across valid frontmatter pages:

Goal: Push all fields above 80% coverage through the Phase 2 Quad-wide enrichment sprint.

Known Bug Patterns

Bug Pattern 1: Malformed Wiki Links in YAML Fields (CRITICAL)

Symptom: yaml.scanner.ScannerError: while scanning a block scalar ... expected chomping or indentation indicators, but found 'c'

Root Cause: Malformed wiki link syntax in YAML related: or sources: fields. The pattern `path (missing the opening bracket on the pipe segment) breaks YAML parsers because the ] and |` characters have special meaning in YAML block scalars.

Incorrect:

related:
  - [[Some Title|path/to/file]]

Correct:

related:
  - [[Some Title|path/to/file]]

Discovery: Identified during the May 10, 2026 remediation effort. 111 files had invalid frontmatter; 85 of those were caused by this specific pattern.

Fix: Regex replacement targeting the malformed pattern:

import re
# Fix: [[Title|path]] -> [[Title|path]]
content = re.sub(r'\[\[([^\]]+)\]\]\|([^\]]+)\]', r'[[\1|\2]]', content)

Bug Pattern 2: Missing type Field

Symptom: Lint runner reports "partial frontmatter — missing required field: type"

Root Cause: Pages created before the schema was enforced, or batch-created by agents without the type field.

Fix: Inject type: "technical-reference" (or appropriate type) into existing frontmatter blocks.

Bug Pattern 3: Empty Frontmatter Blocks

Symptom: Pages with ---\n--- or ---\n\n--- delimiters but no content between them.

Root Cause: Template generation errors or pages created with frontmatter scaffolding that was never populated.

Fix: Run batch script to populate missing fields from file content and metadata.

Remediation Workflow

Phase 1: Local Mechanical Fix (Julius)

1. Run python3 ~/.hermes/scripts/wiki-lint-runner.py to assess current state
2. Categorize issues: missing vs. invalid vs. incomplete frontmatter
3. Run scripts/add_frontmatter_batch.py to add basic frontmatter to missing pages
4. Run targeted repair script for invalid YAML patterns
5. Verify with second lint pass

May 10 results: 79 missing → fixed, 111 invalid → 85 fixed, 26 remaining (complex patterns requiring manual review).

Phase 2: Quad-Wide Enrichment Sprint

1. Dispatch test packets to Cypher, Reacher, and Octavius
2. Validate packet delivery, execution stability, and output quality
3. Assign directory-level enrichment tasks to each agent
4. Agents add missing tags, related, sources, and updated fields
5. Julius reviews and merges all remote output

Status: Pending (as of May 10 evening).

Phase 3: Governance Lock (Skipped)

Phase 3 (pre-commit hooks and CI validation) was explicitly skipped by the user because the existing nightly lint cron job (Large Language Model-wiki-nightly-lint at 2:00 AM ET) already provides ongoing enforcement.

Lint Metrics Trend

Note: The shift from FAIL to NEEDS ATTENTION on May 10 PM reflects the combined effect of the maintenance sprint (index rebuilt, broken links reduced, stale pages cleared) and updated lint thresholds.

Tools

• wiki_lint_runner.py — Main lint script; runs 5 health checks (index, links, frontmatter, stale, contradictions)
• add_frontmatter_batch.py — Batch script for adding basic frontmatter to pages missing it entirely
• wiki_link_check.py — Standalone link checker with Obsidian-style wikilink parsing
• wiki_index_check.py — Index accuracy validator with sub-index awareness

Related Pages

• concepts/agent-wiki-integration — How agents contribute to and maintain the wiki
• concepts/karpathy-llm-wiki-pattern — The underlying wiki architecture philosophy