Grace-marketplace 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:

   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
• 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; default to at most 2 fix loops when no budget is specified
• after each failed loop, update the checkpoint note with the first divergent test, marker, function, or block
• if the failure points to a wrong contract, missing dependency, unclear third-party surface, or weak verification plan, stop and ask the user to replan instead of improvising architecture mid-run
• if the user gives new requirements during a running step, apply them at the next checkpoint rather than mutating the in-flight goal silently

If only minor issues are found, note them and proceed.

2d. Apply Shared-Artifact Updates Centrally

After the implementation commit from Step 2a:

1. update

   docs/knowledge-graph.xml

   from the accepted graph sync output or graph delta proposal
2. update

   docs/verification-plan.xml

   from the accepted verification delta proposal
3. update step status in

   docs/development-plan.xml

   if the step format supports explicit completion state
4. commit shared artifacts if they changed:

   grace(meta): sync after MODULE_ID
   

2e. Progress Report

After each step, print:

--- Step order/total complete ---
Module: MODULE_ID (path)
Status: DONE
Review: scoped pass / scoped pass with N minor notes / escalated audit pass
Verification: step-level passed / follow-up required at phase level
Checkpoint: assumptions confirmed / retry budget used N / stop trigger none
Implementation commit: hash
Meta commit: hash (if any)
Remaining: count steps

Step 3: Complete Each Phase with Broader Checks

After all steps in a phase are done:

1. update

   docs/development-plan.xml

   : set the

   Phase-N

   element's

   status

   attribute to

   done

2. run the phase-level verification commands or gates referenced in

   docs/verification-plan.xml

3. run

   $grace-refresh

   to verify graph and verification-reference integrity; prefer targeted refresh if the touched scope is well bounded, escalate to full refresh if drift is suspected
4. run a broader

   $grace-reviewer

   audit if the phase introduced non-trivial shared-artifact changes or drift risk
5. run

   grace lint --profile autonomous --path <project-root>

   when the phase materially changed verification, packets, or execution policy
6. commit the phase update if it was not already included in the final step commit:

   grace(plan): mark Phase N "phase name" as done
   

7. print a phase summary

Step 4: Final Summary

After all phases are executed:

=== EXECUTION COMPLETE ===
Phases executed: count
Modules generated: count
Total commits: count
Knowledge graph: synced
Verification: phase checks passed / follow-up required

Error Handling

• If a step fails, stop execution, report the error, and ask the user how to proceed
• If step-level verification fails, attempt to fix it; if unfixable, stop and report
• If targeted refresh or scoped review reveals broader drift, escalate before continuing
• Never skip a failing step; the dependency chain matters
• If the verification plan proves too weak for the module, stop and tell the user to run

  $grace-verification

  themselves before continuing

Important

• Steps within a phase are executed sequentially
• Always verify the previous step's outputs exist before starting the next step
• Parse shared XML artifacts once, then update the controller view as each step completes

• docs/development-plan.xml

  and

  docs/verification-plan.xml

  are shared sources of truth; never deviate from the contract or from required evidence silently
• Prefer step-level checks during generation and broader integrity checks at phase boundaries
• Commit implementation immediately after verification passes - do not batch commits until phase end