# 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 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

## Suggested Workflow

1. Write or update an execution plan in `docs/exec-plans/`.
2. Create an orchestration run.
3. Add tasks and dependencies that map to the execution plan.
4. Dispatch ready tasks into isolated worktrees.
5. 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 \
  --body-file docs/exec-plans/task-t1.md
```

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

## 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