124 lines
4.9 KiB
Markdown
124 lines
4.9 KiB
Markdown
|
# 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)
|
||
|
|
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.
|
||
|
|
|
||
|
|
`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.
|