spae-inspect

Inspect (SPAE)

When to use

• STATE.json has phase: inspect.
• PLAN.md needs validation against SPEC.md, codebase patterns, or technical constraints before execution.

Goal

• Tighten the atomic task graph before execution while keeping the repository source read-only.
• Find gaps between SPEC.md, PLAN.md, and relevant codebase context.
• Fix each classified gap fully; match correction depth to finding severity, not diff size.
• Advance the workstream to execution readiness.

Input

Read only what the inspection requires:

• .spae/current/SPEC.md
• .spae/current/PLAN.md
• .spae/current/STATE.json (consult references/STATE.md for field reference, directives, and phase snapshots)
• Relevant source files for context only.

Never read .spae/current/VERIFY.md—not an input to this phase. Reading qualifies as content-blocking.

Workflow

1. GATE—Read .spae/current/STATE.json, .spae/current/SPEC.md, and .spae/current/PLAN.md. Halt when phase ≠ inspect.
2. ORIENT—Goal: tighten the task graph for execution readiness. Source stays read-only; SPEC.md unchanged.
3. PLAN—Classify each gap before editing PLAN.md. Declare the minimal refinements the findings demand.
4. ACT—Apply classified findings only. Compare requirements, plan tasks, acceptance criteria, verification steps, dependencies, and codebase patterns.
   • Flag any SPEC.md requirement absent from every task as Must fix.
   • Flag any task missing an Intent as Must fix; flag a vague or non-actionable Intent as Should fix; backfill or sharpen it from SPEC.md (or, for enabling tasks, from Context and the plan ## Goal) during refinement.
   • Flag any Satisfies-bearing task's Acceptance section omitting test requirements specified in SPEC.md or required by task logic as Should fix.
   • Flag any Verification section lacking test execution commands as Should fix.
   • Flag any Dependencies entry with a T-NNN ID ≥ the declaring task's own ID as Must fix (topological violation).
   • Flag any cycle—a task transitively depending on itself—as Must fix.
   • Flag any Dependencies entry referencing a T-NNN absent from PLAN.md as Must fix (dangling reference).
   • Flag any mismatch between Task graph mermaid edges and per-task Dependencies fields as Should fix.
   • Flag any task with Satisfies: none lacking a credible enabling-task rationale in its Context as Should fix (orphan task—likely scope creep).
   • Flag any ≥2 adjacent tasks sharing no independent acceptance value and no dependency-ordering reason for separation as Should fix (merge candidate).
   • Classify findings:
     • Must fix: gaps breaking requirements, contracts, safety, or verification.
     • Should fix: refinements reducing risk or simplifying execution.
     • Observations: useful notes that shouldn't expand scope.
   • Refine PLAN.md: Rewrite what each Must fix or Should fix demands—re-split, reorder, add, or remove tasks. Make no change absent a classified finding. Preserve atomic, independently verifiable tasks and contiguous sequential T-NNN IDs. Consult references/prose-protocol.md before rewriting task prose.
     • Renumber atomically: when adding, removing, or reordering, update every T-NNN reference in lockstep—task headers, Task graph mermaid edges, the dependency overview list, and each Dependencies field. Leave no dangling or stale ID.
     • Topological correction: when fixing a topological violation, reorder tasks so every dependency precedes its dependent by ID, then renumber atomically.
5. VERIFY—Loop over every item in ## Verification:
   • For each failing item: return to ACT, address it, then re-enter VERIFY.
   • Exit only when all items pass.
   • Fail only for out-of-scope conditions.
6. PERSIST—Write .spae/current/STATE.json once, atomically: set phase: build; set cursor active_task_id to T-001; rebuild the tasks registry to mirror the refined PLAN.md IDs, each mapped to todo. Re-read STATE.json after writing; on a field mismatch, rewrite and re-read before REPORT.
7. REPORT—Emit the result following the result directives and using the result template.