Add agent change process (C0/C1/C2) and docs-mikado tool (#225)
## 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
This commit is contained in:
parent
c3748a0638
commit
c1f7b2a9a3
9 changed files with 439 additions and 14 deletions
|
|
@ -1,5 +1,5 @@
|
|||
#!/usr/bin/env bash
|
||||
#MISE description="Prime AI context with key BlumeOps documentation"
|
||||
#MISE description="Prime AI context with key BlumeOps documentation (formerly zk-docs)"
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
|
|
@ -8,6 +8,7 @@ DOCS_DIR="$(cd "$(dirname "$0")/.." && pwd)/docs"
|
|||
# Key files for AI context priming, in order of importance
|
||||
FILES=(
|
||||
"$DOCS_DIR/tutorials/ai-assistance-guide.md"
|
||||
"$DOCS_DIR/how-to/agent-change-process.md"
|
||||
"$DOCS_DIR/index.md"
|
||||
"$DOCS_DIR/reference/reference.md"
|
||||
"$DOCS_DIR/how-to/how-to.md"
|
||||
|
|
@ -22,7 +22,10 @@ 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)
|
||||
|
|
@ -47,7 +50,8 @@ def main() -> int:
|
|||
console.print(f"Required fields: {', '.join(sorted(REQUIRED_FIELDS))}")
|
||||
console.print()
|
||||
|
||||
issues: list[tuple[str, set[str]]] = []
|
||||
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:
|
||||
|
|
@ -57,25 +61,50 @@ def main() -> int:
|
|||
keys = extract_frontmatter_keys(md_file)
|
||||
|
||||
if keys is None:
|
||||
issues.append((rel_path, REQUIRED_FIELDS))
|
||||
missing_issues.append((rel_path, REQUIRED_FIELDS))
|
||||
continue
|
||||
|
||||
missing = REQUIRED_FIELDS - keys
|
||||
if missing:
|
||||
issues.append((rel_path, missing))
|
||||
missing_issues.append((rel_path, missing))
|
||||
|
||||
if issues:
|
||||
# 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 issues:
|
||||
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]")
|
||||
|
|
|
|||
273
mise-tasks/docs-mikado
Executable file
273
mise-tasks/docs-mikado
Executable file
|
|
@ -0,0 +1,273 @@
|
|||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# requires-python = ">=3.12"
|
||||
# dependencies = ["pyyaml>=6.0", "rich>=13.0.0", "typer>=0.15.0"]
|
||||
# ///
|
||||
#MISE description="View active Mikado dependency chains for C1/C2 changes"
|
||||
#USAGE arg "[card]" help="Card stem to show chain for"
|
||||
#USAGE flag "--all" help="Show all cards in full, including complete ones"
|
||||
"""View active Mikado dependency chains for C1/C2 changes.
|
||||
|
||||
Scans all markdown files in docs/ for YAML frontmatter with ``status: active``
|
||||
and ``requires`` fields, then builds and displays the Mikado dependency graph.
|
||||
|
||||
Usage:
|
||||
mise run docs-mikado # list all active chains
|
||||
mise run docs-mikado deploy-authentik # show chain for a card
|
||||
mise run docs-mikado deploy-authentik --all # include complete cards in full
|
||||
"""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Annotated
|
||||
|
||||
import typer
|
||||
import yaml
|
||||
from rich.console import Console
|
||||
from rich.markdown import Markdown
|
||||
from rich.table import Table
|
||||
|
||||
DOCS_DIR = Path(__file__).parent.parent / "docs"
|
||||
|
||||
|
||||
def extract_frontmatter(file_path: Path) -> dict | None:
|
||||
"""Extract YAML frontmatter from a markdown file."""
|
||||
content = file_path.read_text()
|
||||
if not content.startswith("---"):
|
||||
return None
|
||||
|
||||
end_idx = content.find("---", 3)
|
||||
if end_idx == -1:
|
||||
return None
|
||||
|
||||
frontmatter_text = content[3:end_idx].strip()
|
||||
try:
|
||||
return yaml.safe_load(frontmatter_text) or {}
|
||||
except yaml.YAMLError:
|
||||
return None
|
||||
|
||||
|
||||
def build_graph() -> dict[str, dict]:
|
||||
"""Build the dependency graph from all docs."""
|
||||
cards: dict[str, dict] = {}
|
||||
|
||||
for md_file in sorted(DOCS_DIR.rglob("*.md")):
|
||||
if "changelog.d" in md_file.parts:
|
||||
continue
|
||||
|
||||
frontmatter = extract_frontmatter(md_file)
|
||||
if frontmatter is None:
|
||||
continue
|
||||
|
||||
stem = md_file.stem
|
||||
cards[stem] = {
|
||||
"path": md_file,
|
||||
"title": frontmatter.get("title", stem),
|
||||
"status": frontmatter.get("status"),
|
||||
"requires": frontmatter.get("requires", []) or [],
|
||||
"required_by": [],
|
||||
}
|
||||
|
||||
# Compute inverse relationships
|
||||
for stem, card in cards.items():
|
||||
for req in card["requires"]:
|
||||
if req in cards:
|
||||
cards[req]["required_by"].append(stem)
|
||||
|
||||
return cards
|
||||
|
||||
|
||||
def detect_cycles(cards: dict[str, dict]) -> list[list[str]]:
|
||||
"""Detect circular dependencies in the graph. Returns list of cycles."""
|
||||
cycles: list[list[str]] = []
|
||||
visited: set[str] = set()
|
||||
on_stack: set[str] = set()
|
||||
|
||||
def dfs(stem: str, path: list[str]) -> None:
|
||||
if stem in on_stack:
|
||||
cycle_start = path.index(stem)
|
||||
cycles.append(path[cycle_start:] + [stem])
|
||||
return
|
||||
if stem in visited or stem not in cards:
|
||||
return
|
||||
visited.add(stem)
|
||||
on_stack.add(stem)
|
||||
path.append(stem)
|
||||
for req in cards[stem]["requires"]:
|
||||
dfs(req, path)
|
||||
path.pop()
|
||||
on_stack.discard(stem)
|
||||
|
||||
for stem in cards:
|
||||
dfs(stem, [])
|
||||
|
||||
return cycles
|
||||
|
||||
|
||||
def is_active(card: dict) -> bool:
|
||||
"""Check if a card has status: active."""
|
||||
return card.get("status") == "active"
|
||||
|
||||
|
||||
def find_root_goals(cards: dict[str, dict]) -> list[str]:
|
||||
"""Find active cards that aren't required by another active card."""
|
||||
roots = []
|
||||
for stem, card in cards.items():
|
||||
if not is_active(card):
|
||||
continue
|
||||
# A root goal is not required by any other active card
|
||||
has_active_parent = any(
|
||||
is_active(cards[rb]) for rb in card["required_by"] if rb in cards
|
||||
)
|
||||
if not has_active_parent:
|
||||
roots.append(stem)
|
||||
return sorted(roots)
|
||||
|
||||
|
||||
def walk_chain(
|
||||
cards: dict[str, dict],
|
||||
stem: str,
|
||||
console: Console,
|
||||
show_all: bool,
|
||||
visited: set[str] | None = None,
|
||||
depth: int = 0,
|
||||
) -> None:
|
||||
"""Walk the dependency tree depth-first from a card."""
|
||||
if visited is None:
|
||||
visited = set()
|
||||
|
||||
if stem in visited:
|
||||
console.print(f"{' ' * depth}[dim](circular: {stem})[/dim]")
|
||||
return
|
||||
visited.add(stem)
|
||||
|
||||
card = cards.get(stem)
|
||||
if card is None:
|
||||
console.print(f"{' ' * depth}[red](missing: {stem})[/red]")
|
||||
return
|
||||
|
||||
active = is_active(card)
|
||||
|
||||
if active or show_all:
|
||||
# Print full card content
|
||||
console.print()
|
||||
separator = "=" * 72
|
||||
console.print(f"[bold cyan]{separator}[/bold cyan]")
|
||||
status_tag = "[active]" if active else "[complete]"
|
||||
console.print(
|
||||
f"[bold]{status_tag} {stem}[/bold] — {card['title']}"
|
||||
)
|
||||
console.print(f"[dim]{card['path'].relative_to(DOCS_DIR)}[/dim]")
|
||||
if card["requires"]:
|
||||
console.print(f"[dim]requires: {', '.join(card['requires'])}[/dim]")
|
||||
if card["required_by"]:
|
||||
console.print(
|
||||
f"[dim]required-by: {', '.join(card['required_by'])}[/dim]"
|
||||
)
|
||||
console.print(f"[bold cyan]{separator}[/bold cyan]")
|
||||
console.print()
|
||||
content = card["path"].read_text()
|
||||
console.print(content)
|
||||
else:
|
||||
# One-line summary for complete cards
|
||||
console.print(
|
||||
f"{' ' * depth}[green][complete][/green] {stem} — {card['title']}"
|
||||
)
|
||||
|
||||
# Recurse into dependencies
|
||||
for req in card["requires"]:
|
||||
walk_chain(cards, req, console, show_all, visited, depth + 1)
|
||||
|
||||
|
||||
def main(
|
||||
card: Annotated[
|
||||
str | None, typer.Argument(help="Card stem to show chain for")
|
||||
] = None,
|
||||
all: Annotated[
|
||||
bool,
|
||||
typer.Option("--all", help="Show all cards in full, including complete ones"),
|
||||
] = False,
|
||||
) -> None:
|
||||
console = Console()
|
||||
cards = build_graph()
|
||||
|
||||
# Check for circular dependencies
|
||||
cycles = detect_cycles(cards)
|
||||
if cycles:
|
||||
console.print("[bold red]Circular dependencies detected![/bold red]")
|
||||
for cycle in cycles:
|
||||
console.print(f" [red]{' → '.join(cycle)}[/red]")
|
||||
console.print()
|
||||
|
||||
if card is None:
|
||||
# List all active Mikado chains
|
||||
roots = find_root_goals(cards)
|
||||
|
||||
if not roots:
|
||||
console.print("[dim]No active Mikado chains found.[/dim]")
|
||||
console.print(
|
||||
"[dim]Cards need status: active in frontmatter to appear here.[/dim]"
|
||||
)
|
||||
raise typer.Exit()
|
||||
|
||||
table = Table(
|
||||
title="Active Mikado Chains", show_header=True, header_style="bold"
|
||||
)
|
||||
table.add_column("Goal Card")
|
||||
table.add_column("Title")
|
||||
table.add_column("Active Deps", justify="right")
|
||||
table.add_column("Total Deps", justify="right")
|
||||
|
||||
for stem in roots:
|
||||
card_data = cards[stem]
|
||||
|
||||
# Count dependencies
|
||||
def count_deps(s: str, seen: set[str] | None = None) -> tuple[int, int]:
|
||||
if seen is None:
|
||||
seen = set()
|
||||
if s in seen:
|
||||
return 0, 0
|
||||
seen.add(s)
|
||||
active_count = 0
|
||||
total_count = 0
|
||||
c = cards.get(s)
|
||||
if c is None:
|
||||
return 0, 0
|
||||
for req in c["requires"]:
|
||||
total_count += 1
|
||||
req_card = cards.get(req)
|
||||
if req_card and is_active(req_card):
|
||||
active_count += 1
|
||||
sub_active, sub_total = count_deps(req, seen)
|
||||
active_count += sub_active
|
||||
total_count += sub_total
|
||||
return active_count, total_count
|
||||
|
||||
active_deps, total_deps = count_deps(stem)
|
||||
table.add_row(
|
||||
f"[bold]{stem}[/bold]",
|
||||
card_data["title"],
|
||||
str(active_deps),
|
||||
str(total_deps),
|
||||
)
|
||||
|
||||
console.print()
|
||||
console.print(table)
|
||||
console.print()
|
||||
console.print(
|
||||
"[dim]Run: mise run docs-mikado <card> to see full chain[/dim]"
|
||||
)
|
||||
else:
|
||||
if card not in cards:
|
||||
console.print(f"[red]Card not found: {card}[/red]")
|
||||
console.print("[dim]Available cards with status: active:[/dim]")
|
||||
for stem, data in sorted(cards.items()):
|
||||
if is_active(data):
|
||||
console.print(f" {stem} — {data['title']}")
|
||||
raise typer.Exit(code=1)
|
||||
|
||||
walk_chain(cards, card, console, show_all=all)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
typer.run(main)
|
||||
Loading…
Add table
Add a link
Reference in a new issue