Canonical Document Enforcer Skill Skill

Canonical Document Enforcer Skill

Purpose: Enforce canonical filename and metadata standards for ALL markdown documentation across the repository.

Scope

This skill validates and fixes:

All .md files in the repository (except exempted paths)
Filename format: MM-DD-YYYY-HH-MM_DESCRIPTIVE_TITLE.md
YAML frontmatter with required fields
Content hash placement and validity
Timestamp consistency

Exemptions

The following paths are EXEMPT from canonical enforcement:

LAW/CANON/*.md - Canon files (different governance)
CAPABILITY/SKILLS/*/SKILL.md - Skill manifests
CAPABILITY/TESTBENCH/**/*.md - Test fixtures
LAW/CONTRACTS/fixtures/**/*.md - Test data
README.md, AGENTS.md, CHANGELOG.md - Root documentation
.github/**/*.md - GitHub metadata
BUILD/**/*.md - User workspace

Operations

1. Validate

Scans repository for non-canonical documents and reports violations.

Usage:

python run.py --mode validate

Output:

List of files with violations
Specific violation types per file
Suggested fixes

2. Fix

Automatically renames and updates files to canonical format.

Usage:

python run.py --mode fix [--dry-run]

Actions:

Renames files to MM-DD-YYYY-HH-MM_TITLE.md
Adds/updates YAML frontmatter
Computes and inserts content hash
Preserves file content

3. Report

Generates compliance report for the repository.

Usage:

python run.py --mode report --output INBOX/reports/

Required Fields

All canonical documents MUST have:

---
uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
title: "Human Readable Title"
section: report|research|roadmap|guide|archive
bucket: "category/subcategory"
author: "System|Antigravity|Human Name"
priority: High|Medium|Low
created: "YYYY-MM-DD HH:MM"
modified: "YYYY-MM-DD HH:MM"
status: "Draft|Active|Complete|Archived"
summary: "One-line summary"
tags: [tag1, tag2, tag3]
hashtags: ["#category", "#topic"]
---
<!-- CONTENT_HASH: <sha256> -->

Validation Rules

Filename Pattern: ^\d{2}-\d{2}-\d{4}-\d{2}-\d{2}_.+\.md$
Title Format: ALL_CAPS_WITH_UNDERSCORES
YAML Presence: Lines 1-N start with ---
Hash Placement: Immediately after closing ---
Hash Validity: SHA256 matches content (excluding YAML and hash line)
Timestamp Match: Filename timestamp == YAML created field
UUID Format: RFC 4122 UUID v4

Exit Codes

0 - All documents canonical
1 - Violations found (validate mode)
2 - Fix operation failed
3 - Invalid arguments

Integration

Pre-commit Hook

# In .githooks/pre-commit
python CAPABILITY/SKILLS/governance/canonical-doc-enforcer/run.py --mode validate --staged-only

CI/CD

# In .github/workflows/governance.yml
- name: Validate Canonical Docs
  run: python CAPABILITY/SKILLS/governance/canonical-doc-enforcer/run.py --mode validate

Examples

Validate Repository

python run.py --mode validate
# Output:
# [VIOLATION] MEMORY/ARCHIVE/roadmaps/AGS_ROADMAP_3.3.18.md
#   - Invalid filename (missing timestamp prefix)
#   - Missing YAML frontmatter
#   - Missing content hash

Fix Non-Canonical File

python run.py --mode fix --file "MEMORY/ARCHIVE/roadmaps/AGS_ROADMAP_3.3.18.md"
# Output:
# [RENAMED] AGS_ROADMAP_3.3.18.md -> 01-05-2026-12-45_AGS_ROADMAP_3_3_18.md
# [UPDATED] Added YAML frontmatter
# [UPDATED] Added content hash

Dry Run

python run.py --mode fix --dry-run
# Output:
# [DRY-RUN] Would rename: AGS_ROADMAP_3.3.18.md -> 01-05-2026-12-45_AGS_ROADMAP_3_3_18.md
# [DRY-RUN] Would add YAML frontmatter
# [DRY-RUN] Would add content hash

Receipts

All operations emit receipts to LAW/CONTRACTS/_runs/canonical-doc-enforcer/:

validate_receipt.json - Validation results
fix_receipt.json - Fix operation results
report_receipt.json - Compliance report data

LAW/CANON/DOCUMENT_POLICY.md - Canonical document policy
CAPABILITY/TOOLS/utilities/rename_canon.py - Legacy renaming tool
CAPABILITY/SKILLS/inbox/inbox-report-writer/ - INBOX-specific tooling

Agent Skills: Canonical Document Enforcer Skill

Install this agent skill to your local

Skill Files