grimoire-execute

[Required Reading]

1. Read ${CLAUDE_PLUGIN_ROOT}/GRIMOIRE-CONVENTIONS.md. Its rules (§ TDD, § Code comments, § Sub-agent spawning, § Skill composition, § Parallel execution, § Commits, § .grimoire/ layout, § Project context, § Historic, § User-facing language, § Pause-point pattern) are load-bearing for this skill. Note: this skill only updates the page's HISTORIC.md entry status from [planned] to [finished] — it never appends new entries and never rotates. Bootstrap, append, and rotation are owned by grimoire-spec. This skill requires the page to already be planned ([planned] status in HISTORIC.md, step files present); if not, hard-stop per § Pause-point pattern (grimoire-execute: precondition check).
2. If .grimoire/PROJECT.md exists in the project root, read it for project context. If it does not exist, proceed without it and suggest the user run grimoire-init once this task is complete.
3. If .grimoire/HISTORIC.md exists, read it for recent-page context. If older context seems relevant, browse .grimoire/bag/historic/ (newest suffix first). Missing → the page-status check below requires it; treat as a hard-stop unless the page is verifiable through step files alone (see Phase 1).

[Objective] Execute the page identified by:

$ARGUMENTS

[Phase 1: Page Resolution & Precondition Check (HARD STOP)] Per § Pause-point pattern (grimoire-execute: precondition check). Run these checks before spawning any sub-agent; STOP on the first failure with the literal message shown.

1. Parse the page number. Accept $ARGUMENTS as a bare integer with or without zero-padding (42 or 042); normalize to NNN. Reject anything not parseable as an integer.
2. Locate the page folder. Glob .grimoire/pages/NNN-*/. Exactly one match expected.
   • No match → ❌ Page NNN does not exist. and STOP.
3. Confirm step files. Verify at least 1-*.md exists inside the folder.
   • No step files → ❌ Page NNN has no plan yet. Run /grimoire-plan NNN first. and STOP.
4. Check HISTORIC status. Find the entry whose <page-name> matches the folder.
   • Status [spec] → ❌ Page NNN is still in spec. Run /grimoire-plan NNN first. and STOP.
   • Status [finished] → ❌ Page NNN has already been finished. and STOP.
   • Entry missing entirely (rotated mid-execution) → proceed; this is the non-blocking "skip silently if rotated" rule from § Historic. Note this in the run summary.
   • Status [planned] → proceed.
5. Read all step files in the page folder to understand the full scope of execution. If any step or requirement seems contradictory, ask the user for clarification before starting.
6. Detect execution mode. Parse each step file's YAML frontmatter:
   • If no step file carries depends-on frontmatter (or the field is missing/empty on every step), select the legacy strict-serial path — proceed to Phase 2A unchanged from prior behavior.
   • If at least one step file carries depends-on frontmatter, select the parallel-wave path per § Parallel execution:
     • Build the DAG (nodes = step files, edges = depends-on references).
     • Run cycle detection. If a cycle is found → ❌ Page NNN has cyclic dependencies between steps. Run /grimoire-plan NNN to fix. and STOP.
     • Verify every depends-on reference points to an existing step file. Dangling reference → ❌ Page NNN references a non-existent step in depends-on. Run /grimoire-plan NNN to fix. and STOP.
     • Compute waves (Kahn-style topological levels per § Parallel execution).
     • Proceed to Phase 2B's wave loop.

[Phase 2A: Legacy strict-serial execution] Selected at Phase 1 step 6 when no step file carries depends-on frontmatter. Behavior is byte-identical to the pre-0.8.0 implementation.

• Spawn sub-agents per § Sub-agent spawning: one sub-agent per step file, strictly sequential. Never start step N+1 until the sub-agent for step N has fully completed its assignment.
• Each sub-agent must execute its step file step-by-step per § TDD.
• Each sub-agent makes its own atomic Conventional Commits directly in the main workspace per § Commits.