nguyenthienthanh AI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.
Plan Validator
STATUS — v3.7.0-alpha.2. Thin wrapper over aura-frog/scripts/plans/validate-plan-tree.sh.
Behavior
- Detect: if
.claude/plans/does NOT exist → exit silently - Run
bash aura-frog/scripts/plans/validate-plan-tree.sh - If exit_code === 0 → silent (or one-line success when
verbose: true) - If exit_code !== 0 → surface the failing invariant(s) and refuse the calling operation
The 8 invariants (spec §6.7)
| # | Invariant | Failure mode |
|---|---|---|
| 1 | parent existence | Every node's parent field points to an existing node (or MISSION for T1) |
| 2 | children integrity | Every children: [...] entry exists as a node file |
| 3 | no orphans | Every non-MISSION node is referenced by exactly one parent |
| 4 | valid status | status ∈ {planned, active, done, blocked, frozen, discarded, archived} |
| 5 | monotonic revision | revision only increases; never decreases or skips |
| 6 | test_ref existence | When test_ref: set, the referenced test file exists |
| 7 | DAG no-cycles | depends_on: does not introduce cycles when traversed |
| 8 | freeze_reason | status: frozen requires freeze_reason: and frozen_at: fields |
When to invoke
- Before
/aura-frog:plan-expand,/aura-frog:plan-promote,/aura-frog:plan-archive - Before
git commitwhen.claude/plans/has uncommitted changes - After any direct file edit on
.claude/plans/*.md(manual override)
When NOT to invoke
- Read-only commands (
/aura-frog:plan-status,/aura-frog:trace) — running validation on a healthy tree is wasted overhead - During
/aura-frog:plan-undo— the post-restore state may transiently violate invariants while restoring - Inside hooks fired on every PreToolUse — too expensive
Output discipline
- Exit 0: silent (or
✓ Plan tree valid (8/8 invariants pass)if verbose) - Exit 1: enumerate every failing invariant, one per line, with the offending node ID
Tie-Ins
- Spec: §6.7, §9.2
- Script:
aura-frog/scripts/plans/validate-plan-tree.sh— actual implementation - Skill:
plan-loader— companion (loader is read-only; this is the validator) - Agent:
master-planner— invokes before mutations - Command:
/aura-frog:plan-expand,/aura-frog:plan-promote,/aura-frog:plan-archive— invoke before applying - Rule:
rules/workflow/plan-lifecycle.md— invariant 4 enforces valid status transitions