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
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