the-custodian/research/2026-07-19-work-orchestration-infrastructure-survey.md

# Work Orchestration Infrastructure Survey — Coulomb Fleet

> Research artefact — 2026-07-19. Phase 1 of the work-orchestration
> reconciliation effort (trigger: AWQ-010 reintegration in binky-control,
> founder direction 2026-07-19). Surveys every mechanism the fleet currently
> uses to plan, organize, implement and document work. Companion:
> `2026-07-19-work-orchestration-best-practices.md` (external), synthesized in
> `WorkOrchestrationArchitectureDraft.md`.

## 1. The canonical backbone (what is settled)

### ADR-001 — files first, hub as read model

Workplans and work items originate as Markdown files in the owning repo;
the State Hub indexes them and must be rebuildable from repo files alone
(`canon/architecture/adr-001-workplans-as-repo-artefacts.md`). Corollaries:
DB is disposable; MCP bootstrap tools are index/sync tools; the sanctioned
registration path is *write file → commit → `statehub fix-consistency`*
(C-06 registers, writes UUIDs back into frontmatter). A closure protocol
(closure review, stale-task cleanup as fallback) governs finishing.

### ADR-005 — cross-repo work gets a project repo

Every workplan has exactly one repo anchor; genuinely cross-repo efforts get
a dedicated `category: project` repo with lifecycle
`draft → active → completed → archived` and a completion record listing
modified repos. Repos are recognized as "the most stable, git-managed
entities in the ecosystem".

### Terminology canon

`canon/standards/workplan-terminology-fleet_v0.1.md`: **workplan** is the
fleet term (legacy: workstream, metered retirement via legacy-meter,
STATE-WP-0069). IDs: `{PREFIX}-WP-NNNN` for workplans, `{WP}-TNN` for tasks;
hub UUID is internal and opaque — exactly the layered id scheme aspect 5
asks for, already practiced.

### State models

- **Workplan lifecycle** (`state-hub/docs/workplan-state-model-proposal.md`):
  `proposed | ready | active | blocked | backlog | finished | archived`, with
  `stale/stalled/oldies` explicitly **derived health labels, not stored
  states** — an important precedent for aspect 6 (policy tagging).
- **Task lifecycle** (`state-hub/docs/task-state-canon-migration.md`): the
  InfoTechCanon model `wait | todo | progress | done | cancel` (symbolic
  codes WAIT/TODO/PROG/DONE/CNCL). Deliberately separate from workplan
  lifecycle. Canon source lives in `info-tech-canon` — the abstract-state
  backbone for aspect 4 already has a home.
- **Task flow engine** (`state-hub/docs/task-flow-engine-spec.md`, plus hub
  `list_flow_definitions`/`get_flow_state`): a generic workstation +
  assertion substrate ("information objects move through named workstations";
  pure predicates over object properties, no domain knowledge). This is the
  existing mechanism for *kind-specific* lifecycles under shared abstractions
  — largely underused so far.

### Hub ecosystem generations

`docs/hub-ecosystem-architecture.md`: **hub-core** (library) / **state-hub**
(dev coordination, file-first, localhost) / **core-hub** (Gen-3 production
framework, `/api/v2`, contract-first FastAPI/Postgres, operator console,
`hub.coulomb.social`). core-hub's `docs/specs/workplan-coordination.md`
explicitly preserves the file-first rule and commits to ingesting ADR-001
workplans before replacing state-hub operations. Gen 2 (inter-hub/IHP) is
being drained. The dashboard/global-visibility layer of aspect 2 is
core-hub's charter.

### Event / automation delegation

`state-hub/docs/activity-core-delegation.md`: the hub is a read model, **not
a task factory**. It publishes lifecycle events on NATS
(`org.statehub.repo.registered`, `…workstream.completed`,
`…decision.resolved`, `…domain.goal.activated`, `…task.stale`);
activity-core reacts via declarative `ActivityDefinition` YAML (cron + event
triggers, rule expressions, instructions; Temporal-backed history). "Rules
auditable, testable, modifiable without redeploying the hub."

### Execution stack

`agent-harness/docs/architecture.md` three-layer model:

| Layer | Repo | Artefact |
| --- | --- | --- |
| Blueprint | kaizen-agentic | agent personas, schedule blueprints, coach/metrics loop |
| Instance | consuming repo | `.kaizen/schedule.yml` manifest — declarative only: blueprint, cadence, `lane` (green/blue), named `tool_profile`, `budget` (tokens/run), pinned harness major |
| Runtime | agent-harness | task intake (issue-core poll/claim), persona bind, credential acquisition (OpenBao/ops-warden lanes), bounded session, commit verification, hub + kaizen reporting |

Notable: **manifest declares, harness enforces**; completion events are the
idempotence currency; budgets and lanes are already machine-enforced at this
layer. issue-core provides claimable task distribution (Gitea/local
backends); ops-warden is the policy front door for credentials; llm-connect
abstracts model providers.

### Supporting hub entities (from the dev-hub surface)

Suggestions (staged lifecycle with `relevance_weight`, vet / decline /
promote-to-task), capability requests (request/accept/reroute/dispute),
contributions, interface changes, technical debt, risks, domain & repo
goals (with `needs_workplan` guidance), decisions (record/resolve,
auto-escalation of financial/legal pending decisions "per constitution §4"),
token events (`record_token_event`, `get_token_summary`), ad-hoc and
interactive task records (`record_adhoc_task`, `record_interactive_task`),
DOI checks, kaizen agent registry, human-flagging (`flag_for_human`,
`needs_human`, intervention notes), messages (agent inbox).

## 2. The binky-control queue layer (the new thing to reconcile)

Built during company-kernel bootstrap (BINKY-WP-0002/0003), governed by
`AutonomyPolicy.md`:

| Document | Role | Item ids | Lane semantics |
| --- | --- | --- | --- |
| `AutopilotWorkQueue.md` | evergreen pull queue for idle agent capacity; "never empty" | `AWQ-NNN` | Green/Blue |
| `DecisionQueue.md` | prepared approval packages for the founder | `DEC-YYYY-NNN` | Yellow/Red |
| `OfficeHourQueue.md` | business-hour interactions batched into command days | `OH-YYYY-NNN` | Orange |
| `OperatingRhythm.md` | cadence: daily brief, queue hygiene, bridge scheduler → harness cutover | — | — |
| `ControlLoopCatalog.md` | company as Sense→Interpret→Decide→Act→Record→Learn loops | Loop N | — |
| `RiskRegister.md` | risks | `RISK-NNN` | — |

The **autonomy lanes** (Green safe-autonomous / Blue reversible-logged /
Yellow deferred-approval / Orange time-window / Red human-only) are the
conceptual spine: "maximize Green+Blue throughput, queue Yellow, batch
Orange, protect Red." Approval packages, founder attention budget
(minutes/day, max decisions/day), and founder availability as first-class
state are defined here — none of it yet fleet canon.

### What the queues got right

1. **Cheap intake.** A YAML block appended to a live document — far lighter
   than authoring a workplan file. Mail triage → `AWQ-010` took one commit.
2. **Lane-aware routing.** Items are born with an execution route (pull
   queue vs. decision package vs. office-hour batch) — the suggestion→task
   flow has no equivalent.
3. **Human attention as a budgeted resource.** DecisionQueue +
   OfficeHourQueue are effectively WIP-limited human workstations.
4. **Pull protocol.** Idle agents self-serve; matches issue-core's
   claim model but in file form.

### Where they break the backbone

1. **Not indexed.** AWQ/OH/DEC/RISK items have ids and states but no hub
   representation → invisible to `get_domain_summary`, dashboards, dependency
   modeling, staleness detection. (DEC items acquired ad-hoc
   `state_hub_decision_id` mirroring only via manual dual bookkeeping —
   done by hand twice on 2026-07-19.)
2. **Parallel ontology.** A queue item *is* a work item (or a decision) with
   a different id scheme, different state vocabulary (`queued|prepared|done`,
   `prepared|resolved|deferred`), and hand-maintained "Completed" logs
   instead of the canonical task lifecycle.
3. **Manual promotion.** AWQ-010 → BINKY-WP-0005 required a human/agent to
   notice, transcribe, and re-register — the exact "sidetrack reintegration"
   signal aspect 7 names.
4. **Repo-local convention.** Nothing stops other repos from inventing
   different queue formats; there is no schema, no fix-consistency check, no
   canon standard.

## 3. Adjacent mechanisms with overlapping ontology

- **Suggestions (hub)** overlap AWQ intake almost 1:1 (idea → vet →
  promote-to-task) but are **hub-first entities with no file artefact** —
  themselves in tension with ADR-001.
- **issue-core issues** overlap task distribution (claim/execute/close) —
  used as harness intake sink, but issues are not file-backed either.
- **ADHOC workplans** (`workplans/ADHOC-YYYY-MM-DD.md`) cover spontaneous
  low-risk work — a third intake form.
- **OH/DEC vs. hub decisions**: decisions exist in three places (queue file,
  hub record, DecisionQueue resolved log).
- **Capability requests, CCRs (credential change requests,
  railiance-platform), interface changes**: further typed work-item species
  with their own id schemes and states.

**Count of intake/work-item species currently live: ≥ 9** (workplan task,
adhoc task, suggestion, issue, AWQ item, OH item, DEC item, capability
request, CCR) — with ~5 distinct state vocabularies and ~8 id schemes.

## 4. Existing budget / risk / policy controls

- Token budget policy (workstation CLAUDE.md): 8k soft / 10k hard per task —
  human-convention enforced only, but `record_token_event` +
  `get_token_summary` exist in the hub, and the harness manifest has a
  machine-enforced `budget` (tokens/run).
- Lanes + tool profiles: enforced at harness runtime, declared in manifests.
- Decision auto-escalation: hub escalates pending financial/legal decisions
  (constitution §4) — observed live on DEC-2026-004.
- `needs_human` flag + intervention notes; `flag_for_human` /
  `clear_human_flag`; `list_blocked_tasks`.
- Derived health labels (stalled/stale) specified but only partially
  implemented in views.
- Consistency: `statehub fix-consistency` (ADR-001 checks C-01…C-24
  including C-06 registration, C-24 repo classification) — the natural
  enforcement point for any new convention.

## 5. Markup / knowledge persistence infrastructure

- All coordination artefacts are Markdown + embedded YAML blocks; hub parses
  ```task blocks and frontmatter.
- markitect family (markitect-main/-tool/-filter/-quarkdown, marki-docx)
  provides the markup toolchain; DOCX/PDF only as external inputs/outputs —
  matches aspect 3's stance and needs only codifying, not building.
- Research artefacts precedent: `core-hub/docs/research/2026-06-27-…` and
  binky-control `integrations/*.md` design docs; briefs in `briefs/`,
  evidence CSVs in `mailmeta/reports/`.

## 6. Observed pain points (data, not speculation)

1. **AWQ-010** — queue item had to be manually re-integrated as a workplan
   (2026-07-19). Root cause: no automatic path from intake item to
   registered work.
2. **Dual decision bookkeeping** — DEC-2026-003/004 each required manual
   file+hub mirroring in both directions (create and resolve).
3. **Suggestion flow unused in practice** — binky-control never used
   suggestions; the queue format won because intake friction was lower.
   The infrastructure lost to a Markdown file — that is the efficiency bar.
4. **BINKY-WP-0002 hub slug drift** (`bnky-wp-0001` slug, title mismatch) —
   registration by early manual path left inconsistent index data; C-06-era
   registrations are clean.
5. **Historic DB-first violations** required ADR-001 remediation; the
   pattern recurs whenever a new entity type (suggestions, issues) is added
   hub-first or file-only without the sync pair.
6. **Terminology migrations are expensive** (workstream→workplan:
   4 workplans, a legacy-meter, a fleet standard) — arguing for getting the
   umbrella ontology right *before* the queue pattern spreads beyond
   binky-control.

## 7. Assets to build on (summary)

| Aspect (founder list) | Existing asset |
| --- | --- |
| 1 agile + planned, dependencies, budgets | queues (agile) + workplans (planned); `create_dependency`/`create_workplan_dependency`; harness budgets + token events |
| 2 global visibility, tenancy | core-hub charter; domains/topics/repos; agent-harness multi-tenant; repo-classification standard |
| 3 repos as base unit, X-as-Code, rebuildable | ADR-001/ADR-005, fix-consistency, ActivityDefinitions-as-YAML, manifests-as-YAML; markitect |
| 4 one framework, many work kinds | InfoTechCanon task model + task-flow-engine workstations |
| 5 layered ids, migration-stable history | UUID internal / canonical name external, already practiced; legacy-meter retirement discipline |
| 6 policy tagging | derived health labels precedent; needs_human; lanes |
| 7 opinionated, anti-sidetrack | fix-consistency as gate; AGENTS.md generation from state-hub templates |