tegwick
d2802fc55d
COORDINATION-WP-0005: map project-repository workplans onto CoordinationCase, refuse residual as a driver, and document the wait mode without enabling live worker injection. Assistant: grok Assistant-Session: 01a09dc1-b21e-77e1-919e-fcad2f82b267
109 lines
3.6 KiB
Markdown
109 lines
3.6 KiB
Markdown
# Cross-owner wait handling mode v0.1
|
||
|
||
Status: specified (COORDINATION-WP-0005-T02). Not a live wake enablement.
|
||
Owner: coordination-engine.
|
||
Reconciles with: `spec/worker-coordination-service-v0.1.md` (do not fork
|
||
leases, safety, TAMQ, or receipts).
|
||
Ontology: `spec/coordination-model-v0.2.md`.
|
||
|
||
## Problem
|
||
|
||
Repo A sets a task `wait` because repo B’s owner has not returned. Nobody
|
||
observes B. The wait becomes a stranded inbox. That pattern is the top
|
||
theme holding the open-workplan count up.
|
||
|
||
## Mode (replace “set wait and hope”)
|
||
|
||
### Entry
|
||
|
||
Any of:
|
||
|
||
1. A task is `wait` / `needs_human` and names another repo, owner, or
|
||
workplan id.
|
||
2. A workplan is `blocked` on a `depends_on` target whose `repo` is not
|
||
this repo.
|
||
3. A `prj-` driver lists both repos (preferred). If no driver exists,
|
||
still open a **case object** from the waiting plan — do not author a
|
||
new workplan.
|
||
|
||
Do **not** enter this mode for `flavor: residual` unless the flavor has
|
||
been promoted.
|
||
|
||
### Observe
|
||
|
||
Read the foreign owner’s record from State Hub (workplan, tasks,
|
||
`depends_on`, flavor, repo classification). Do not copy their task list
|
||
into this repo. Do not PATCH their tasks.
|
||
|
||
### Attach
|
||
|
||
Open or attach a `CoordinationCase` (`scenario_type: project_driver`
|
||
when a `prj-` workplan exists, otherwise `scenario_type: cross_owner_wait`).
|
||
The waiting plan is the beneficiary. The foreign plan is the obligor
|
||
commitment.
|
||
|
||
### Act (only if the v0.1 service is already running)
|
||
|
||
Lease/wakeup **only** selected gita-registered worker targets for the
|
||
implementer that is actually unblocked. Safety, sensitive-text stops,
|
||
human flags, and “no silent reroute” are exactly the v0.1 worker service.
|
||
This mode does not add a second wakeup path.
|
||
|
||
If the service is not running, the case still exists as a derived object
|
||
and a hub-projectable receipt of `observed` / `waiting`. Agents follow
|
||
the instruction pack instead of injecting workers.
|
||
|
||
### Checkpoint
|
||
|
||
Reuse v0.1 checkpoint shape (summary, files_changed, next_action,
|
||
blocked_reason, 8 KiB, local). `blocked_reason` stops automatic
|
||
continuation. A checkpoint is not completion.
|
||
|
||
### Fail closed
|
||
|
||
Missing authorization, unregistered target, residual-as-driver, or
|
||
attempt to reassign another owner’s task → `stopped` with reason. Never
|
||
silently re-assign.
|
||
|
||
### Exit
|
||
|
||
| Exit | Condition |
|
||
| --- | --- |
|
||
| `satisfied` | Obligor workplan/task reaches `done`/`finished`/`archived` |
|
||
| `stopped` | Safety, human, missing auth, residual driver |
|
||
| `waiting` | Foreign record still open; case remains attached |
|
||
|
||
## Receipt shape (hub-projectable)
|
||
|
||
Extends the v0.1 sanitized receipt (state, reason, lease/trigger ids).
|
||
Additional fields (no payloads, no secrets):
|
||
|
||
```yaml
|
||
scenario_type: project_driver | cross_owner_wait
|
||
case_id: string
|
||
driver_workplan_id: string?
|
||
driver_repo: string?
|
||
obligor_workplan_id: string
|
||
beneficiary_workplan_id: string
|
||
flavor: string?
|
||
```
|
||
|
||
Projection remains `POST /progress/` with
|
||
`event_type: coordination_receipt` as in the v0.1 Hub adapter. Queued
|
||
edge-relay receipts are not proof of central publication.
|
||
|
||
## Common estate pattern
|
||
|
||
Repo A (e.g. `net-kingdom`) blocked on repo B (e.g. `key-cape`,
|
||
`flex-auth`, OpenBao owner). If `HFACT-WP-0001` (or another `prj-`
|
||
driver) already lists both, attach there. Otherwise derive
|
||
`cross_owner_wait` from A’s waiting workplan. Observe B. Do not implement
|
||
B’s tasks from A’s session. Do not message `ops-warden` for a secret.
|
||
|
||
## Anti-patterns
|
||
|
||
- Stranded `wait` with no case and no observer
|
||
- Copying B’s tasks into A’s workplan
|
||
- Treating `flavor: residual` as a driver
|
||
- Inventing `warden secret` / asking ops-warden for API keys
|
||
- Enabling live worker injection as a side effect of documenting this mode
|