# Execution Runtime Contract

This document contains the operational contract for resumable, parallel, and evidence-backed task execution. The method and lifecycle remain canonical in `FRAMEWORK.md`; this file owns runtime mechanics.

## Scope

The runtime coordinates workspaces, task ownership, command plans, execution waves, isolated worktrees, local integration, and recovery. It does not grant product approval, replace task write scopes, or spawn agents.

## Workspace and ownership

- Use `.product/workspaces/WORK-NNN/` for concurrent focus; never invent a global active feature.
- A workspace records identity, state, handoffs, checkpoints, command plans, and evidence.
- Task ownership is a renewable lease with heartbeat and expiry. A lease does not grant approval or permission beyond the task's `writeScope`.
- Isolated tasks use `.worktrees/WORK-NNN/TK-NNN` when the graph/runtime contract requires isolation.
- Resume from `state.json`, the latest checkpoint, and the latest handoff. Legacy `WORK-NNN.json` is read-only until explicit migration.

## Graph and scheduling

The Execution Graph is a DAG. The scheduler calculates deterministic conflict-free waves from dependencies, `writeScope`, `sharedResources`, capabilities, leases, priority, and capacity. It does not execute tasks or spawn agents.

Parallel tasks require no dependency path between them and must not overlap in `writeScope` or contend for an undeclared shared resource. Path overlap is prefix-based. A conflict becomes a dependency or requires task merging.

Graph lifecycle is `draft -> proposed -> materialized -> approved`. `materialized` is a Graph-specific state: it means canonical task files and the generated index exist; it is not a general artifact lifecycle state.

## Command execution

Command plans store direct argv rather than shell strings. The command executor initially permits only R0 read-only and R1 local-temporary operations. It refuses stale inputs, scope escapes, conflicting resources, unsupported risk levels, and attempts beyond the configured limit. Human approval is required for remote, destructive, security-sensitive, or otherwise consequential operations.

## Evidence and integration

Implemented tasks record the required immutable working-tree evidence and current diff hash. Code Review and task QA review the same diff hash before Commit Crafter creates local commits. Validated task commits are integrated locally in DAG order; conflicts stop for human resolution, followed by Integrated QA where applicable.

Runtime commands include `runtime`, `resume`, `handoff`, `checkpoint`, `lease`, `commands`, `schedule`, and `integrate`. Use the installed CLI help as the authority for exact flags and syntax.

## Owning skills

- `execution-graph`: defines and validates the DAG and graph lifecycle.
- `execution-scheduler`: calculates waves and conflicts without executing tasks.
- `command-planner`: creates an approved command plan.
- `command-executor`: executes only an approved, current, scoped command plan.
- `delivery-orchestrator`: routes work through persisted state and handoffs.
- `integration-orchestrator`: integrates verified local commits and requires integrated validation.