coordination-engine/spec/coordination-model-v0.2.md

# coordination-model-v0.2.md

## 1. Document Status

**Document:** coordination-model-v0.2.md
**Project:** coordination-engine
**Version:** 0.2
**Status:** Addendum to v0.1 (COORDINATION-WP-0005)
**Scope:** Project-repository workplans as coordination drivers
**Extends:** `spec/coordination-model-v0.1.md`
**Related:** `spec/cross-owner-wait-mode-v0.1.md`,
`spec/worker-coordination-service-v0.1.md`,
`the-custodian/canon/architecture/adr-005-cross-repo-workplans-project-repos.md`,
`the-custodian/canon/standards/project-repository-flavor_v0.1.md`

v0.1 remains the ontology. This addendum maps **estate work records** onto
that ontology. It does not replace actors, goals, commitments, or observation
loops.

## 2. Purpose

Cross-repository work in this estate is supposed to live in a **project
repository** (`prj-<slug>`, `repo_flavor: project`, ADR-005). Agents were
instead minting stranded `wait` notes on product workplans. The engine must
treat a `prj-` workplan as the **driver** of a `CoordinationCase`, and
product-repo workplans as **implementers**.

## 3. Out of scope

- The engine **does not author workplans**. Files remain source of truth
  (ADR-001). State Hub remains the work-record read model.
- The engine **does not replace State Hub**, Fabric, or product
  implementation in participating repos.
- The engine **does not vend credentials**. `ops-warden` issues SSH
  certificates only.
- This addendum **does not enable live worker injection**. Wake/lease
  remains the v0.1 worker-coordination service, off until an operator
  starts it.

## 4. Driver and implementer

| Role | Binding | Authority |
| --- | --- | --- |
| **Driver** | Workplan whose repo is `prj-*` / `category: project` / `repo_flavor: project` | Sequences the effort, names participating repos, holds `depends_on` and related child ids. Does not implement production code. |
| **Implementer** | Workplan in a participating product/tooling repo | Owns code, tests, deployables, and local tasks. |

Participant roles on the case (v0.1 `Participant.roles[]`):

- `driver` — the project-repository actor (system: State Hub record +
  project repo)
- `implementer` — each participating product repo (system)
- `observer` — State Hub / Fabric (read-only)
- `agent` — a worker only when the v0.1 service has selected that gita
  repo as a wake target

A workplan with `flavor: residual` is **not** a driver and is **not**
actionable demand unless promoted (STATE-WP-0092). Unspecified flavor is
relevant.

## 5. Mapping onto v0.1

```text
prj- workplan  →  CoordinationCase
  goal         ←  GOAL.md outcome + workplan title
  driver       ←  the prj- workplan (commitment: sequence the effort)
  implementers ←  child workplans in other repos (related / depends_on)
  commitments  ←  depends_on edges (kind: response | completion)
                  needs_human: true tasks (kind: decision)
  observations ←  State Hub task/workplan status, receipts
```

`depends_on` is a **commitment**, not prose. The obligor is the
implementer (or upstream driver) named by the target id. The beneficiary
is the waiting plan. Satisfaction is the target reaching a terminal
satisfactory status (`done` / `finished` / `archived`), matching the
v0.1 worker-coordination dependency rule. Task-block `depends_on`
(fleet standard `task-wait-qualifiers_v0.1.md`, CUST-WP-0074) is the
same commitment with a task rather than a workplan as beneficiary; task
targets are satisfied at `done` / `cancel`.

**`kind: decision`** — a task with `needs_human: true` is a commitment
whose obligor is a person (or the decision named by `decision_id`), not
a workplan. Satisfaction is the person's recorded action or the
decision resolving. The engine observes it and never wakes a worker for
it. A task carrying both `depends_on` and `needs_human: true` is two
commitments; the case is satisfied only when both are.

`related:` without `depends_on` is context, not a commitment.

## 6. Case identity

```yaml
CoordinationCase:
  id: "case:prj:{repo_slug}:{workplan_id}"   # derived, not authored
  scenario_type: project_driver
  driver_workplan_id: string                 # hub UUID or canonical id
  driver_repo: prj-*
  implementers:
    - repo: string
      workplan_id: string?
      role: implementer
  commitments:                               # from depends_on
    - kind: completion
      obligor_workplan_id: string
      beneficiary_workplan_id: string
  flavor: planning | implementation | ...    # driver's flavor
```

The engine derives this object from hub JSON. It does not POST a
workplan.

## 7. Worked example — `prj-helixforge-factory` / `HFACT-WP-0001`

Repo `prj-helixforge-factory` is `repo_flavor: project`. Workplan
`HFACT-WP-0001` (“Establish the internal HelixForge software factory on
Railiance”) is the driver. It states that it owns integration acceptance
and handoff and **neither replaces nor copies child implementation
plans**.

Implementers named in `related:` include `GLAS-WP-0012`, `SAND-WP-0015`,
`REINAH-WP-0003`, `ACTIVITY-WP-0032`, `KEY-WP-0013`, `INFD-WP-0001`,
`APPROVAL-WP-0002`, `SECRETS-WP-0009`, `AUDIT-WP-0009`, `RPF-WP-0038`.
Those remain implementer workplans in their owning repos.

A wait on `KEY-WP-0013` from the factory driver is a **commitment** on
the key-cape implementer, not a stranded `wait` on the driver with no
observer. Cross-owner handling is `spec/cross-owner-wait-mode-v0.1.md`.

## 8. Compatibility

v0.1 cases that are not `scenario_type: project_driver` are unchanged.
The worker-coordination service continues to poll ready/active
implementer tasks. This addendum tells it (and agents) which workplan is
the driver when one exists.