execute

Intent

Execute code or commands in a controlled manner, capturing output for verification. Unlike mutate, this capability is for operations that don't permanently change state (tests, queries, builds, analysis tools).

Success criteria:

• Code/command executed successfully
• Output captured completely
• Exit code recorded
• Errors properly surfaced

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Parameter	Required	Type	Description
code	Yes	string	Code or command to execute
language	No	string	Programming language or shell (bash, python, ruby, etc.)
timeout	No	string	Maximum execution time (default: "60s")
environment	No	object	Environment variables to set

Procedure

1. Validate execution request: Ensure code is safe to run

   • Check for mutation operations (if found, suggest mutate instead)
   • Verify timeout is reasonable
   • Confirm execution environment

2. Prepare environment: Set up execution context

   • Set required environment variables
   • Ensure dependencies are available
   • Create isolated context if needed

3. Execute code: Run the code/command

   • Capture stdout and stderr
   • Record start time
   • Monitor for timeout

4. Capture results: Collect execution output

   • Record exit code
   • Capture complete stdout
   • Capture complete stderr
   • Note execution duration

5. Analyze output: Interpret results

   • Identify success/failure from exit code
   • Extract key information from output
   • Note warnings or anomalies

6. Return results: Structure output for consumption

   • Include all captured data
   • Provide execution summary
   • Reference evidence for assertions

Output Contract

Return a structured object:

result:
  success: boolean  # Exit code == 0
  exit_code: integer  # Process exit code
  stdout: string  # Standard output
  stderr: string  # Standard error
  duration: string  # Execution time
execution:
  command: string  # What was executed
  language: string  # Execution environment
  started_at: string  # ISO timestamp
  completed_at: string  # ISO timestamp
analysis:
  summary: string  # One-line result summary
  warnings: array[string]  # Notable warnings
  errors: array[string]  # Extracted error messages
evidence_anchors: ["command:output"]