git:20260926.d35166c to git:20260926.1cf899c

---

name: compose

description: >-

Internal compose engine; load only via stage holder HARD-GATE — do not invoke directly.

---

# compose

Shared compose engine for stage holders. It takes one input document, runs one

execution, and delivers one document. Step execution lives in

`references/execution.md`.

## Inputs

| Variable | Required | Source | Use |

|---|---|---|---|

| `$CYCLE_ID` | yes | Holder runtime foundation | Active cycle |

| `$PROFILE_PATH` | yes | Holder preflight | Runtime `compose-profile.json` |

| `$SCOPE_PACKAGE` | yes | Holder preflight | Normalized `scope-package.json` |

## Script Macros

Macro expansion: `{SKILL_ROOT}/_runtime.md` § Script Macros → Macro expansion. Non-zero exit → Blocking: stop, report (stderr / exit code), wait for user direction.

| Macro | Command |

|-------|---------|

| `$START_COMPOSE` | `python3 "$SKILL_ROOT/compose/scripts/session/start.py" --project-root "$(pwd)" --cycle-id "$CYCLE_ID" --profile-path "$PROFILE_PATH" --scope-package "$SCOPE_PACKAGE"` |

| `$SESSION_INFO` | `python3 "$SKILL_ROOT/compose/scripts/session/session_info.py" --cycle-id "$CYCLE_ID" --project-root "$(pwd)" --view <view>` |

| `$SESSION_CONTROL` | `python3 "$SKILL_ROOT/compose/scripts/session/session_control.py" --cycle-id "$CYCLE_ID" --project-root "$(pwd)" <subcommand>` |

Subcommands and stdout: script module docstrings or `--help`.

Execution macros are defined in `{SKILL_ROOT}/compose/references/execution.md`. Load that file before using them.

## Lifecycle

```mermaid

stateDiagram-v2

[*] --> Working: Start

Working --> ReadyForDelivery: execution Completed

ReadyForDelivery --> Working: Modify

ReadyForDelivery --> Delivered: Deliver

```

Route only from `$SESSION_INFO` stdout. Do not invent the next step.

## Entry

### Start

Run `$START_COMPOSE`. On failure → Blocking.

Load `{SKILL_ROOT}/compose/references/compose-ontology.md` once.

**Done:** `$CURRENT_STATE=Working`.

### Bind context

Run `$SESSION_INFO --view session`, then bind:

| Cite | JSON field | Use |

|------|------------|-----|

| `$REVISION_DIR` | `revision_dir` | revision-scoped tools |

| `$DEMAND_MANIFEST` | `demand_manifest` | Delivery demand atomization; skip when null |

| `$CURRENT_STATE` | `workflow_state.current_state` | Outer routing |

| `$STEP_STATE` | `execution.state` | Step routing |

## Working

**Session state:** `Working`.

Load `{SKILL_ROOT}/compose/references/execution.md` and follow it.

**Done:** `$STEP_STATE=Completed` → ## ReadyForDelivery.

## ReadyForDelivery

Ask: Deliver or Modify.

- Deliver → ## Delivery.

- Modify → `$SESSION_CONTROL return-to-working --confirm`. Then ## Working. Preview is not required.

## Delivery

1. Run `$SESSION_INFO --view delivery-preview`. On failure → Blocking. Show the preview; full compose document only if asked.

2. Wait for explicit delivery confirmation.

3. **Demand manifest (only when `$DEMAND_MANIFEST` is present):** enumerate delivered demands per `$DEMAND_MANIFEST.unit_rule`, then `$SESSION_CONTROL write-demand-manifest --units-json '<JSON array>'`. Skip when `$DEMAND_MANIFEST` is null. On failure → Blocking.

5. Run `$SESSION_INFO --view stage-transitions`. On non-zero exit → Blocking. Prompt next stages when present.

## Reference

| Document | When |

|----------|------|

| `{SKILL_ROOT}/compose/references/compose-ontology.md` | Start, once per session |

| `{SKILL_ROOT}/compose/references/execution.md` | Working |

| `{SKILL_ROOT}/eval/SKILL.md` | Loaded from execution Evaluating |