Erich Blume
c1f7b2a9a3
## Summary - Introduce C0/C1/C2 change classification based on the Mikado method, where documentation cards serve as persistent context for agents across sessions - Add `docs-mikado` mise task to visualize active Mikado dependency chains from `status: active` and `requires` frontmatter fields - Rename `zk-docs` task to `ai-docs` ## Changes - **New:** `docs/how-to/agent-change-process.md` — methodology card - **New:** `mise-tasks/docs-mikado` — Python uv script for dependency graph visualization - **Renamed:** `mise-tasks/zk-docs` → `mise-tasks/ai-docs` - **Updated:** `CLAUDE.md` — added Change Classification section, updated references - **Updated:** `ai-assistance-guide.md`, `exploring-the-docs.md`, `how-to.md` — updated references and index ## Verification - [x] `mise run ai-docs` works - [x] `mise run docs-mikado` runs (no active chains yet, as expected) - [x] `docs-check-links` — all valid - [x] `docs-check-index` — all indexed - [x] `docs-check-frontmatter` — all valid - [x] All pre-commit hooks pass 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/225
115 lines
3.6 KiB
Text
Executable file
115 lines
3.6 KiB
Text
Executable file
#!/usr/bin/env -S uv run --script
|
|
# /// script
|
|
# requires-python = ">=3.12"
|
|
# dependencies = ["rich>=13.0.0"]
|
|
# ///
|
|
#MISE description="Check that all docs have required frontmatter fields"
|
|
"""Validate that all documentation files have required YAML frontmatter.
|
|
|
|
Required fields: title, tags, modified
|
|
|
|
Scans all markdown files in docs/ (excluding changelog.d/) and checks
|
|
that each file has YAML frontmatter containing the required fields.
|
|
|
|
Usage: mise run docs-check-frontmatter
|
|
"""
|
|
|
|
import re
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
from rich.console import Console
|
|
from rich.table import Table
|
|
|
|
DOCS_DIR = Path(__file__).parent.parent / "docs"
|
|
HOWTO_DIR = DOCS_DIR / "how-to"
|
|
REQUIRED_FIELDS = {"title", "tags", "modified"}
|
|
# These fields are only permitted in docs/how-to/
|
|
HOWTO_ONLY_FIELDS = {"status", "requires"}
|
|
|
|
# Match YAML frontmatter block
|
|
FRONTMATTER_PATTERN = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
|
|
|
|
# Match top-level YAML keys (not indented)
|
|
KEY_PATTERN = re.compile(r"^([a-zA-Z][a-zA-Z0-9_-]*):", re.MULTILINE)
|
|
|
|
|
|
def extract_frontmatter_keys(file_path: Path) -> set[str] | None:
|
|
"""Extract top-level keys from YAML frontmatter. Returns None if no frontmatter."""
|
|
content = file_path.read_text()
|
|
match = FRONTMATTER_PATTERN.match(content)
|
|
if not match:
|
|
return None
|
|
frontmatter = match.group(1)
|
|
return set(KEY_PATTERN.findall(frontmatter))
|
|
|
|
|
|
def main() -> int:
|
|
console = Console()
|
|
console.print("[bold]Frontmatter Validation[/bold]")
|
|
console.print(f"Required fields: {', '.join(sorted(REQUIRED_FIELDS))}")
|
|
console.print()
|
|
|
|
missing_issues: list[tuple[str, set[str]]] = []
|
|
misplaced_issues: list[tuple[str, set[str]]] = []
|
|
|
|
for md_file in sorted(DOCS_DIR.rglob("*.md")):
|
|
if "changelog.d" in md_file.parts:
|
|
continue
|
|
|
|
rel_path = str(md_file.relative_to(DOCS_DIR))
|
|
keys = extract_frontmatter_keys(md_file)
|
|
|
|
if keys is None:
|
|
missing_issues.append((rel_path, REQUIRED_FIELDS))
|
|
continue
|
|
|
|
missing = REQUIRED_FIELDS - keys
|
|
if missing:
|
|
missing_issues.append((rel_path, missing))
|
|
|
|
# Check that status/requires only appear in how-to docs
|
|
is_howto = HOWTO_DIR in md_file.parents or md_file.parent == HOWTO_DIR
|
|
if not is_howto:
|
|
misplaced = keys & HOWTO_ONLY_FIELDS
|
|
if misplaced:
|
|
misplaced_issues.append((rel_path, misplaced))
|
|
|
|
has_issues = bool(missing_issues or misplaced_issues)
|
|
|
|
if missing_issues:
|
|
console.print("[bold red]Missing Required Frontmatter[/bold red]")
|
|
console.print()
|
|
table = Table(show_header=True, header_style="bold")
|
|
table.add_column("File")
|
|
table.add_column("Missing Fields")
|
|
|
|
for rel_path, missing in missing_issues:
|
|
table.add_row(rel_path, ", ".join(sorted(missing)))
|
|
|
|
console.print(table)
|
|
console.print()
|
|
|
|
if misplaced_issues:
|
|
console.print("[bold red]Misplaced Frontmatter Fields[/bold red]")
|
|
console.print(f"[dim]These fields are only allowed in {HOWTO_DIR.relative_to(DOCS_DIR)}/[/dim]")
|
|
console.print()
|
|
table = Table(show_header=True, header_style="bold")
|
|
table.add_column("File")
|
|
table.add_column("Disallowed Fields")
|
|
|
|
for rel_path, misplaced in misplaced_issues:
|
|
table.add_row(rel_path, ", ".join(sorted(misplaced)))
|
|
|
|
console.print(table)
|
|
console.print()
|
|
|
|
if has_issues:
|
|
return 1
|
|
|
|
console.print("[bold green]All docs have required frontmatter![/bold green]")
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|