Phase Dag Execution

---
name: phase-dag-execution
description: Compile and schedule engineering work as a phase DAG. Use when units have phases, artifact dependencies, owned paths, resource locks, capacity limits, stale evidence, Git worktrees, integration waves, or a need to improve throughput without confusing shards with execution order.
---

# Phase DAG Execution

Use this skill after work units exist and before parallel or long-running
execution. A checklist is inventory; the DAG is the execution model.

## Model

- Node: `(unit, phase)`.
- Hard edge: an artifact, decision, or evidence prerequisite.
- Lock: path, build tool, model cache, database, network, review claim, Git
  integration, or other contention.
- Snapshot: input commit, manifest revision, artifact digests, external versions.
- Admission: dependencies complete, locks free, capacity available, approvals
  settled.
- Stale propagation: changed inputs invalidate downstream evidence.
- Integration wave: several accepted candidates merge and verify together.

Do not encode contention as a hard edge. Use locks so unrelated ready nodes stay
parallel.

## Project Phase Templates

This skill does not define universal phase names. The composition skill or
project manifest declares them, for example:

```yaml
phase_template:
  feature_addition: [slice, design, write, regression, selected_reviews, release]
  py2rs: [recon, align, bootstrap, write, behavior_parity, selected_reviews, promote]
  review_only: [collect_evidence, review, report]
```

## Minimal Manifest Shape

```yaml
dag_execution:
  schema_version: 1
  mode: dry_run # dry_run | enabled
  input_commit: null
  graph_revision: null
  mutating_phases: [write]
  review_phases: [regression]
  capacity:
    agent_slots: 1
    build_slots: 1
  integration_waves: []

units:
  - id: example
    dag:
      phases: [design, write, regression]
      owned_paths: []
      requires:
        - artifact: contract-v1
          before: write
      produces:
        - id: implementation-v1
          phase: write
      locks:
        - id: build
          phases: [regression]
```

Adapt field names to the existing control plane instead of maintaining a second
manifest.

## Dry Run

Prefer the bundled compiler when the manifest shape matches it:

```bash
python skills/foundations/phase-dag-execution/scripts/compile_dag.py manifest.yaml
```

The compiler expands phases, resolves artifacts, rejects cycles and duplicate
producers, derives path locks, emits a graph revision, and prints ready nodes.
It does not launch agents, mutate manifests, create worktrees, merge commits, or
advance state.

## Scheduling Rules

- Start in `dry_run` with one agent slot.
- Enable parallel mutation only with a clean or user-approved baseline,
  isolated worktrees, owned paths, exclusive shared-file policy, stale
  propagation, and a coordinator for integration.
- Admit critical-path work first, then token/context reuse, then raw ready count.
- Record active locks and exact input snapshots.
- Cancel or restart stale downstream nodes after input changes.
- One coordinator owns graph edits, shared dependency state, integration waves,
  conflict resolution, and release/promotion state.

## Non-Negotiables

- Shards organize context; they do not schedule work.
- Hard edges must be causal prerequisites.
- Resource conflicts must be locks.
- Evidence without input commit and graph revision is not reusable.
- A changed candidate commit invalidates review evidence for that candidate.
- `/tmp` and agent-private copies are not durable artifacts.

## Handoff

Return graph revision, ready nodes, critical path, active locks, blocked nodes,
stale evidence, required approvals, and integration-wave plan.