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

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

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.