# Worktree Orchestration

Cadence UI uses worktree-oriented orchestration as an optional layer on top of the harness
validation suites. The goal is to let a leader agent or operator dispatch isolated implementation
attempts without making the repository depend on one specific orchestration service.

## Wrapper Command

Use the repository wrapper instead of calling `orch` directly:

```bash
pnpm harness:orch -- <orch command> [flags]
```

The wrapper also exposes repo-local helper commands:

```bash
pnpm harness:orch -- doctor --plan-file docs/exec-plans/my-plan.md
pnpm harness:orch -- plan inspect --plan-file docs/exec-plans/my-plan.md
pnpm harness:orch -- plan body --run cadence_ui_demo --task T1 --plan-file docs/exec-plans/my-plan.md
```

The wrapper applies these defaults:

- orchestration database: `.artifacts/orch/coord.db`
- worktree root: `.artifacts/orch/worktrees`
- repo path for dispatch: the current Cadence UI repository root
- strict worktree mode for dispatch
- `--base-ref` defaults to the current branch if not provided

Binary resolution order:

1. `CADENCE_UI_ORCH_BIN`
2. `orch` on `PATH`
3. the legacy `~/.codex/skills/orch/assets/orch` location

If no binary is found, `pnpm harness:orch -- doctor` prints the checked locations and exits
non-zero so the failure is explicit instead of looking like a broken wrapper.

## Suggested Workflow

1. Write or update an execution plan in `docs/exec-plans/`.
2. Inspect the plan task sketch with `pnpm harness:orch -- plan inspect --plan-file <plan>`.
3. Create an orchestration run.
4. Add tasks and dependencies that map to the execution plan.
5. Dispatch ready tasks into isolated worktrees, ideally with `--plan-file` so the wrapper can
   generate the task body from the plan automatically.
6. Reconcile worker state and run the relevant harness suites before merge.

## Example

Create a run:

```bash
pnpm harness:orch -- run init \
  --run cadence_ui_harness_001 \
  --goal "Complete the next Cadence UI release slice" \
  --summary "Break the work into isolated component, docs, and validation tasks"
```

Add tasks:

```bash
pnpm harness:orch -- task add \
  --run cadence_ui_harness_001 \
  --task T1 \
  --title "Implement component change" \
  --summary "Update the component source and unit tests"

pnpm harness:orch -- task add \
  --run cadence_ui_harness_001 \
  --task T2 \
  --title "Update docs and smoke coverage" \
  --summary "Refresh stories and keep Storybook smoke stable"

pnpm harness:orch -- dep add \
  --run cadence_ui_harness_001 \
  --task T2 \
  --depends-on T1
```

Dispatch a task into a strict worktree:

```bash
pnpm harness:orch -- dispatch \
  --run cadence_ui_harness_001 \
  --task T1 \
  --to default-worker \
  --plan-file docs/exec-plans/2026-03-24-harness-control-plane-hardening.md
```

When `--plan-file` is provided without `--body-file`, the wrapper parses the plan's
`## Orchestration Task Sketch`, finds the matching task id, and writes a generated task body under
`.artifacts/orch/task-bodies/<run>/<task>.md` before dispatching.

Inspect status:

```bash
pnpm harness:orch -- status --run cadence_ui_harness_001
pnpm harness:orch -- blocked --run cadence_ui_harness_001
pnpm harness:orch -- reconcile --run cadence_ui_harness_001
pnpm harness:orch -- cleanup --run cadence_ui_harness_001 --all-completed
```

## Mapping Plans To Tasks

Execution plans are still the source of intent. Orchestration tasks should be a thin translation of
the plan:

- one task per independently dispatchable slice
- dependencies only where integration would otherwise conflict
- task bodies should point back to the execution plan and the relevant harness suites
- workers should validate the narrowest useful suites first, then report what remains

Suggested task sketch format:

```md
- `T1`: stabilize docs smoke coverage
- `T2 -> T1`: reconcile a11y coverage and docs after the smoke slice lands
```

`T2 -> T1` means task `T2` depends on `T1`.

## Safety Notes

- dispatch from a committed or otherwise reviewable base when possible
- keep shared integration files on the leader side when multiple workers are active
- prefer one task per isolated write scope
- use `status`, `blocked`, `answer`, and `reconcile` instead of ad hoc coordination
- run `pnpm harness:orch -- doctor` before the first dispatch on a new machine so binary discovery,
  defaults, and plan parsing all fail fast