grace-execute

Execute the development plan step by step, generating code for each pending module with validation and commits.

## Prerequisites
- `docs/development-plan.xml` must exist with an ImplementationOrder section
- `docs/knowledge-graph.xml` must exist
- `docs/verification-plan.xml` should exist and define module-level checks for the modules you plan to execute
- if `docs/operational-packets.xml` exists, use it as the canonical packet and delta reference
- If the plan or graph is missing, stop immediately and tell the user to run `$grace-plan` themselves before large execution runs
- If the verification plan is missing or still skeletal, stop immediately and tell the user to run `$grace-verification` themselves before large execution runs
- Prefer this skill when dependency risk is higher than the gain from parallel waves, or when only a few modules remain

## Core Principle

Keep execution **sequential**, but keep context handling and verification disciplined.

- The controller parses shared artifacts once and carries the current plan state forward step by step
- Each step gets a compact execution packet so generation and review stay focused
- Reviews should default to the smallest safe scope
- Verification should be split across step, phase, and final-run levels instead of repeating whole-repo work after every clean step
- Packets must be strong enough that the worker does not need mid-run task reinterpretation
- Every step should leave behind a visible checkpoint report so failures can be reviewed without hidden reasoning
- Use a small retry budget per step; when the packet or contract is wrong, stop and replan instead of drifting

## Process

### Step 1: Load and Parse the Plan Once
Read `docs/development-plan.xml`, `docs/knowledge-graph.xml`, and `docs/verification-plan.xml`, then build the execution queue.

When the optional `grace` CLI is available, `grace module show M-XXX --path <project-root> --with verification` is a fast way to seed the shared/public portion of a step packet, and `grace file show <path> --path <project-root> --contracts --blocks` is a fast way to inspect local/private details for the current write scope.

1. Collect all `Phase-N` elements where `status="pending"`
2. Within each phase, collect `step-N` elements in order
3. Build a controller-owned execution packet for each step containing:
   - module ID and purpose
   - target file paths and exact write scope
   - preferred stack or tooling excerpt from `docs/technology.xml` when the project defines one
   - module contract excerpt from `docs/development-plan.xml`
   - module graph entry excerpt from `docs/knowledge-graph.xml`
   - dependency contract summaries for every module in `DEPENDS`
   - verification excerpt from `docs/verification-plan.xml`, including module-local commands, critical scenarios, required log markers, and test-file targets
   - assumptions or unresolved edges that are still acceptable inside the step scope
   - stop conditions or replan triggers that should halt the step immediately
   - retry budget for fix or review loops
   - expected graph delta fields: imports, public exports, public annotations, and CrossLinks
   - expected verification delta fields: test files, commands, required markers, and gate follow-up notes
    Use the canonical `ExecutionPacket`, `GraphDelta`, and `VerificationDelta` shapes from `docs/operational-packets.xml` when that file exists.
4. Present the execution queue to the user as a numbered list:
   ```text
   Execution Queue:
   Phase N: phase name
     Step order: module ID - step description
     Step order: module ID - step description
   Phase N+1: ...
   ```
5. Wait for user approval before proceeding. The user may exclude specific steps or reorder.

### Step 2: Execute Each Step Sequentially
For each approved step, process exactly one module at a time.

#### 2a. Implement the Module from the Step Packet
Follow this protocol for the assigned module:
- use the step packet as the primary source of truth
- generate or update code with MODULE_CONTRACT, MODULE_MAP, CHANGE_SUMMARY, function contracts, and semantic blocks
- place START_CONTRACT/END_CONTRACT above both: function signature and docstrings/comments
- generate or update module-local tests inside the approved write scope
- preserve or add stable log markers for the required critical branches
- keep changes inside the approved write scope
- run module-local verification commands from the packet only
- produce graph sync output or a graph delta proposal for the controller to apply, limited to public module interface changes
- produce a verification delta proposal for test files, commands, markers, and phase follow-up notes
- produce a short checkpoint note: assumptions kept, commands run, evidence captured, and whether the step consumed any retry budget
- **commit the implementation immediately after verification passes** with format:
   ```
   grace(MODULE_ID): short description of what was generated
  
  Phase N, Step order
  Module: module name (module path)
  Contract: one-line purpose from development-plan.xml
  ```

#### 2b. Run Scoped Review
After generating, review the step using the smallest safe scope:
- does the generated code match the module contract from the step packet?
- are all GRACE markup conventions followed?
- do imports match `DEPENDS`?
- does the graph delta proposal match actual imports and public module interface changes?
- do the changed tests and verification evidence satisfy the packet's required scenarios and markers?
- does the verification delta proposal match the real test files and commands?
- are there any obvious security issues or correctness defects?

If critical issues are found:
1. fix them before proceeding
2. rerun only the affected scoped checks
3. escalate to a fuller `$grace-reviewer` audit only if local evidence suggests wider drift

#### 2c. Reflect, Replan, or Stop
If implementation or review fails, do not loop indefinitely.

- use the step packet retry budget