Maintain

Team-Wiki Maintain

Daily maintenance routine for the Team-Wiki knowledge base. Detects and reports quality issues: orphaned pages, broken wikilinks, missing index entries, tag inconsistencies, and log rotation.

Prerequisites

• Team-Wiki initialized (team-wiki/setup already run)
• WIKI_PATH environment variable set
• GBrain database available (for cross-referencing entity graph)

Checks Performed

1. Orphan Detection (gbrain find-orphans)

Finds pages with zero inbound links — content nobody can discover via backlinks. Ideally every entity page is linked from at least 2 other pages.

Action: Report orphans; consider adding [[links]] from related pages or marking as meta-only (e.g., schema pages may be intentionally orphaned).

2. Broken Link Audit (gbrain find-broken or grep-based)

Scans all markdown files for [[wikilinks]] pointing to non-existent pages (missing target file or missing page entry). Case-sensitive; hyphenated filenames must match exactly.

Action: Create missing pages, fix typos in links, or remove dead references.

3. Index Completeness (index.md audit)

Verifies every entity page in entities/ is listed in index.md under the correct alphabetical section. The index is the human-readable directory; it must stay current.

Action: Append new entities to index sections, alphabetize within section.

4. Tag Taxonomy Audit

Ensures all pages use tags from the approved domain:item set in SCHEMA.md. Flags:

• Unknown domain prefixes
• Misspelled tags
• Missing required tags (all pages must have at least one domain tag)

Action: Correct tags per SCHEMA; add new domain items to SCHEMA if legitimate.

5. Log Rotation

log.md is append-only. When it exceeds 500 entries, archive it:

• Rename current log.md → log-YYYY-MM-DD-XXX.md (incrementing counter)
• Start a fresh log.md with a header linking to the archive
• Keep last 30 days of archived logs; cull older ones to 4-Archive/ if desired

6. Frontmatter Validation

Checks every markdown file for required YAML frontmatter fields per page type:

• title, created, updated, type, tags[], sources[]
• Ensures dates are valid ISO format (YYYY-MM-DD)
• Ensures type matches directory location

Action: Fix malformed frontmatter; add missing fields.

Invocation

# Run all checks and generate a report
skill:team-wiki/maintain

# With explicit wiki path
skill:team-wiki/maintain --wiki-path ~/Hermes\ Vault/Hermes/Team-Wiki

Output

Produces a plain-text report to stdout:

[maintain] Team-Wiki Health Check — 2026-04-25
=============================================
Orphans: 3
  - [[agent:architect]] (no inbound links)
  - [[company:37signals]] (no inbound links)
  - [[concept:rag]] (no inbound links)

Broken links: 2
  - [[peron:andrej-karpathy]] (typo in entities/people/)
  - [[skill:system-design]] (missing file)

Index gaps: 4 entities not in index
  - agent:debugger
  - company:openai
  - concept:pglite
  - project:hermes-workspace

Tag issues: 1
  - agent:<user> uses unknown domain 'agent-<user>' (should be agent:<user>)

Log rotation: not needed (473 entries)

Automation

Schedule via Hermes cron (daily at 02:00):

/cron add "0 2 * * *" "skill:team-wiki/maintain" --name "team-wiki-daily-lint"

Or run manually after bulk ingest operations.

Remediation

Some checks offer auto-fix flags (future):

• --fix-orphans — Suggest link targets based on content similarity
• --fix-index — Update index.md automatically
• --fix-tags — Normalize tags per SCHEMA (with --dry-run preview)

Currently, the skill reports only; human or an agent (Secretary) applies corrections.

See Also

• gbrain find-orphans / gbrain find-broken
• team-wiki/setup (for SCHEMA reference)
• team-wiki/sync (to re-index after structural changes)