{
  "id": "shell_execution",
  "label": "Shell Execution Canonical",
  "phase": "phase-09",
  "category": "operational_flows",
  "status": "ACTIVE_DH_MIRROR",
  "purpose": "Govern terminal command execution as auditable runtime action.",
  "function": "Control command scope, cwd, timeout, expected output, exit code interpretation and evidence capture.",
  "technology_requirements": [
    {
      "technology": "Shell Command Runner",
      "required_for": "Govern terminal command execution as auditable runtime action.",
      "required_by_phase": "phase-09",
      "required_by_category": "shell_execution",
      "required_by_buckets": [
        "Prerequisites",
        "Installation",
        "Configuration",
        "Validation",
        "Observable Evidence",
        "Failure Modes & Recovery",
        "Completion & Promotion"
      ],
      "expected_version": "MISSING until Shell Command Runner is implemented and validated in the future Execution & Monitoring Panel",
      "validation_command": "MISSING until shell_execution can prove scope, evidence, execution state and promotion decision",
      "evidence_path": "/home/yeff/public_html/devon/canon/execution/state/dh_sources/shell_execution.json",
      "status_source": "Documentation Hub + future Execution & Monitoring Panel",
      "blocking_if_missing": true,
      "failure_impact": "The execution risk here is command authority without command accountability. A single unscoped shell line can create evidence, mutate state and mislead the operator at the same time. This category keeps terminal power inside a declared operational envelope."
    }
  ],
  "depends_on": [
    "tool_execution",
    "planning_reasoning",
    "terminal_output_panel"
  ],
  "used_by": [
    "filesystem_operations",
    "test_validation_runner",
    "migration_runner"
  ],
  "overview": {
    "summary": "Shell Execution Canonical owns the moment a planned operation becomes a command in the server. It exists because a terminal line is not just a diagnostic; it can mutate files, start jobs, leak state, hide failure and produce evidence that looks authoritative even when the command was scoped wrong.",
    "function": "FUNCTION: Require each command to declare working directory, target surface, allowed effect, expected output, timeout, failure handling and evidence capture before DEVON-DEV can use the result operationally.",
    "system_position": "This category is downstream of Planning Reasoning and upstream of Terminal Output Panel. Planning explains why a command should exist; Shell Execution defines whether it is allowed to run; Terminal Output Panel preserves what happened. Without this separation, the future panel cannot distinguish a controlled command from terminal improvisation.",
    "failure_impact": "The execution risk here is command authority without command accountability. A single unscoped shell line can create evidence, mutate state and mislead the operator at the same time. This category keeps terminal power inside a declared operational envelope."
  },
  "failure_impact": "The execution risk here is command authority without command accountability. A single unscoped shell line can create evidence, mutate state and mislead the operator at the same time. This category keeps terminal power inside a declared operational envelope."
}