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

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"]

Field Definitions

Examples

Example 1: Run Tests

Input:

code: "npm test -- --grep 'UserService'"
language: "bash"
timeout: "120s"

Output:

result:
  success: true
  exit_code: 0
  stdout: |
    > project@1.0.0 test
    > jest --grep 'UserService'

    PASS src/services/__tests__/UserService.test.ts
      UserService
        ✓ creates user with valid data (45ms)
        ✓ validates email format (12ms)
        ✓ hashes password on save (23ms)

    Test Suites: 1 passed, 1 total
    Tests:       3 passed, 3 total
  stderr: ""
  duration: "2.3s"
execution:
  command: "npm test -- --grep 'UserService'"
  language: "bash"
  started_at: "2024-01-15T10:30:00Z"
  completed_at: "2024-01-15T10:30:02Z"
analysis:
  summary: "3 tests passed in UserService"
  warnings: []
  errors: []
evidence_anchors:
  - "command:npm test:output"

Example 2: Execute Query

Input:

code: "SELECT COUNT(*) as user_count FROM users WHERE created_at > '2024-01-01'"
language: "sql"
environment:
  DATABASE_URL: "${DATABASE_URL}"

Output:

result:
  success: true
  exit_code: 0
  stdout: |
    user_count
    ----------
    15423
    (1 row)
  stderr: ""
  duration: "0.15s"
execution:
  command: "psql -c \"SELECT COUNT(*)...\""
  language: "sql"
  started_at: "2024-01-15T10:35:00Z"
  completed_at: "2024-01-15T10:35:00Z"
analysis:
  summary: "Query returned 15423 users created in 2024"
  warnings: []
  errors: []
evidence_anchors:
  - "command:psql:query_result"

Example 3: Execution Failure

Input:

code: "python -c 'import nonexistent_module'"
language: "bash"

Output:

result:
  success: false
  exit_code: 1
  stdout: ""
  stderr: |
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
    ModuleNotFoundError: No module named 'nonexistent_module'
  duration: "0.05s"
execution:
  command: "python -c 'import nonexistent_module'"
  language: "bash"
  started_at: "2024-01-15T10:40:00Z"
  completed_at: "2024-01-15T10:40:00Z"
analysis:
  summary: "Import failed: module 'nonexistent_module' not found"
  warnings: []
  errors:
    - "ModuleNotFoundError: No module named 'nonexistent_module'"
evidence_anchors:
  - "command:python:error"

Verification

• • Exit code is captured
• • Stdout and stderr are both recorded
• • Duration is reasonable
• • Analysis summary matches output
• • No mutations occurred

Verification tools: Bash (to verify command execution environment)

Safety Constraints

• •mutation: false
• •requires_checkpoint: false
• •requires_approval: true
• •risk: medium

Capability-specific rules:

• •Verify code does not mutate persistent state
• •Enforce timeout limits
• •Capture all output for audit trail
• •Do not execute code that requires elevated privileges without approval
• •Prefer mutate for state-changing operations

Composition Patterns

Commonly follows:

• •plan - Execute planned actions
• •generate - Execute generated code
• •transform - Execute transformation scripts

Commonly precedes:

• •verify - Verify execution results
• •detect - Detect patterns in output
• •audit - Record execution for audit

Anti-patterns:

• •Never use execute for persistent state changes (use mutate)
• •Avoid execute without timeout limits
• •Never execute untrusted code without sandboxing

Workflow references:

• •See reference/workflow_catalog.yaml#debug_code_change for execute in testing
• •See reference/workflow_catalog.yaml#digital_twin_sync_loop for execute in sync loops