110 lines
3.6 KiB
Markdown
110 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
|