research: work orchestration reconciliation — fleet survey, best practices, architecture draft

Trigger: binky-control automation queues (AWQ/DEC/OH) emerged as an
unindexed parallel work-item ontology (AWQ-010 reintegration case).
Three artefacts:
- research/2026-07-19-work-orchestration-infrastructure-survey.md —
  inventory of the ADR-001/005 backbone, state models, task-flow engine,
  hub generations, execution stack, and the >=9 live work-item species
- research/2026-07-19-work-orchestration-best-practices.md — external
  2025/26 practice: GitOps reconciliation, risk-tiered HITL, flow
  metrics/WIP, lean budget guardrails; anti-patterns to skip
- research/WorkOrchestrationArchitectureDraft.md — v0.1 proposal:
  unified work-record ontology, type registry + UUIDv7/canonical-name
  layering, lanes to fleet canon, policy/derived tags, queues as
  generated views, staged migration; open questions for discussion

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

research/2026-07-19-work-orchestration-best-practices.md

@@ -0,0 +1,180 @@
+# Work Orchestration Best Practices — External Research
+
+> Research artefact — 2026-07-19. Phase 2 of the work-orchestration
+> reconciliation effort. Surveys current (2025/2026) practice for organizing
+> human, agent, and classic-automation workflows, filtered for relevance to
+> a file-first, repo-anchored, solo-founder-plus-agent-fleet factory.
+> Companion: `2026-07-19-work-orchestration-infrastructure-survey.md`.
+
+## 1. GitOps / everything-as-code
+
+The industry consensus for declarative operations maps directly onto ADR-001
+and generalizes it:
+
+- **Four GitOps principles**: declarative desired state; versioned &
+  immutable storage; state pulled automatically by agents; continuous
+  reconciliation between desired and actual state
+  ([GitLab](https://about.gitlab.com/topics/gitops/),
+  [Spacelift](https://spacelift.io/blog/gitops-best-practices)).
+  Our `fix-consistency` is exactly a reconciliation loop; the gap is that it
+  runs on demand rather than continuously, and only covers workplans/tasks —
+  not queues, suggestions, or decisions.
+- **Validate before apply**: schema validation, policy compliance, dry-run
+  in CI before a change reaches the runtime system
+  ([Pulumi](https://www.pulumi.com/blog/gitops-best-practices-i-wish-i-had-known-before/)).
+  Applied to work items: queue/workplan YAML should be schema-validated in
+  Forgejo CI, not only at hub-ingest time.
+- **Separate code and state repos** where lifecycles differ
+  ([GitHub blog](https://github.blog/enterprise-software/devops/applying-gitops-principles-to-your-operations/))
+  — consistent with ADR-005 project repos and control-plane repos like
+  binky-control.
+- **Ops-as-issues / IssueOps**: operations triggered and audited through
+  issue lifecycles. Validation of our issue-core direction; the key lesson
+  is that the issue is the *interface*, not the source of truth.
+
+## 2. Human-in-the-loop tiering for agentic work
+
+2026 agentic-governance literature converges on patterns our AutonomyPolicy
+already anticipates — with refinements worth adopting:
+
+- **Risk-tiered approval, not blanket oversight**: pre-approval
+  (human-in-the-loop) for irreversible actions (payments, contracts,
+  deletion, production changes); async monitoring (human-on-the-loop) for
+  high-volume recoverable work
+  ([Strata](https://www.strata.io/blog/agentic-identity/practicing-the-human-in-the-loop/),
+  [StackAI](https://www.stackai.com/insights/human-in-the-loop-ai-agents-how-to-design-approval-workflows-for-safe-and-scalable-automation)).
+  Maps to Green/Blue (on-the-loop) vs. Yellow/Orange/Red (in-the-loop).
+- **Approval gates before side effects — propose-then-commit**: block the
+  side-effecting call until approval is recorded
+  ([Velt](https://velt.dev/blog/why-ai-agents-need-approval-layer)). Our
+  approval-package pattern satisfies this at the process level; the harness
+  tool-profile mechanism is where it becomes technically enforced.
+- **Identity-aware orchestration**: pause execution, route to authorized
+  humans, time-boxed decision windows, log every intervention
+  ([Strata](https://www.strata.io/blog/agentic-identity/practicing-the-human-in-the-loop/)).
+  `needed_by` / `fallback_if_no_response` in DecisionQueue are exactly
+  time-boxed windows; the hub should own the clock, not the file reader.
+- **Every agent has an owner, risk profile, and documented decision
+  boundary**; outputs traceable to model versions and configs
+  ([CMR "Governing the Agentic Enterprise"](https://cmr.berkeley.edu/2026/03/governing-the-agentic-enterprise-a-new-operating-model-for-autonomous-ai-at-scale/),
+  [McKinsey](https://www.mckinsey.com/capabilities/risk-and-resilience/our-insights/trust-in-the-age-of-agents)).
+  Matches `agt-…` hub identities + manifests; argues for making `lane` and
+  `owner` mandatory fields on every work item, not just on agents.
+- **Durable pause/resume**: graph-based orchestrators persist state so a
+  workflow can wait days for human input and resume losslessly
+  ([Virtido](https://virtido.com/blog/agentic-workflows-patterns-best-practices-enterprise)).
+  Our equivalent is the file+hub pair: a Yellow item *is* a paused workflow;
+  no in-memory orchestrator state should be required to resume it.
+- **Reviewer quality matters**: "a poorly trained reviewer approving flawed
+  agent outputs is worse than no checkpoint"
+  ([nhimg.org](https://nhimg.org/faq/how-should-security-teams-implement-human-in-the-loop-controls-for-ai-agents/))
+  — supports the approval-*package* discipline (evidence, recommendation,
+  fallback) over bare questions, and the attention-budget cap.
+
+## 3. Flow management: WIP limits, metrics, prioritization
+
+Kanban/lean portfolio practice supplies the quantitative layer the fleet
+lacks:
+
+- **Four flow metrics**: WIP, cycle time, work-item age, throughput
+  ([ProKanban](https://www.prokanban.org/blog/https-prokanban-org-blog-the-kanban-pocket-guide-chapter-6-the-basic-metrics-of-flow)).
+  All four are computable from hub data (timestamped UUIDs + status
+  transitions) — none is surfaced today. Work-item age is the direct,
+  data-driven form of the "stalled" tag (aspect 6).
+- **WIP limits at every state**, including portfolio level; WSJF
+  (cost-of-delay / job size) chooses the next item, WIP limits decide
+  whether the system may accept it
+  ([Agility at Scale — WIP](https://agility-at-scale.com/safe/lpm/work-in-progress/),
+  [WSJF](https://agility-at-scale.com/safe/lpm/wsjf-weighted-shortest-job-first/)).
+  The founder attention budget (max 7 decisions/day) is a WIP limit on the
+  human workstation; the same construct should apply to agent lanes
+  (e.g. max active workplans per repo). A WSJF calibration experiment
+  already exists (`docs/daily-statehub-wsjf-calibration-2026-06-04.md`).
+- **Epics as economic bets** with testable benefit hypotheses, decomposed
+  only for the near horizon; close the measurement loop on predicted
+  outcomes ([Agility at Scale — Epics](https://agility-at-scale.com/safe/lpm/epics/)).
+  Maps to domain/repo goals → workplans; argues for a lightweight
+  `hypothesis`/`expected_outcome` field on goals, checked at closure review.
+- **Lean budget guardrails**: fund value streams within policy boundaries
+  instead of approving each piece of work; segment budgets per area of risk
+  ([Atomic Object](https://spin.atomicobject.com/budget-guardrails-software-project/),
+  [Agility at Scale — Guardrails](https://agility-at-scale.com/safe/lpm/portfolio-guardrails/)).
+  Direct template for token/cost budgets: per-lane and per-workplan budget
+  envelopes with escalation on breach, instead of per-request permission.
+
+## 4. Dependency and risk practice
+
+- **Dependency mapping to see cascade risk**; identify risks early, attach
+  mitigation to the item
+  ([Asana](https://asana.com/resources/project-risks),
+  [Atlassian](https://www.atlassian.com/work-management/project-management/project-risk-management)).
+  The hub has dependency edges (task- and workplan-level); the gap is
+  surfacing them (blocked-cascade views) and the absence of edges for
+  queue-item species.
+- **Risk classification determines autonomy level, data access, and
+  approval requirements per agent**
+  ([TM Forum](https://inform.tmforum.org/features-and-opinion/ai-autonomy-governance-a-governance-framework-for-agentic-ai-enabling-safe-accountable-and-scalable-autonomous-intelligence),
+  [Trend Micro](https://www.trendmicro.com/vinfo/us/security/news/cybercrime-and-digital-threats/from-anarchy-to-authority-closing-the-governance-gap-in-agentic-ai)).
+  Confirms lanes-as-risk-classes; suggests lane should also gate credential
+  catalog access (ops-warden already keyed per-lane).
+
+## 5. Patterns worth *not* importing
+
+- **Heavy portfolio ceremony** (SAFe boards, quarterly PI planning): the
+  attention budget is 90 min/day; anything requiring synchronous ceremonies
+  fails the constraint. Take the *metrics and limits*, skip the meetings.
+- **Ticket-system-as-source-of-truth** (Jira-style): contradicts ADR-001;
+  issues/tickets remain interface projections.
+- **Generic workflow engines as the primary model** (BPMN, Airflow-style
+  DAGs for knowledge work): our work is document-anchored and
+  interruption-driven; the task-flow-engine's assertion model (state =
+  provable properties, not engine position) is the better fit and is already
+  specced.
+- **Per-item human approval as default**: the literature is unanimous that
+  blanket approval queues collapse under volume; risk-tiering is the
+  scalable form — the AutonomyPolicy default ("ask Bernd is never the
+  default") is the correct opinion.
+
+## 6. Condensed implications for the draft
+
+1. Treat *work intake* and *work execution* as separate concerns with
+   different friction budgets — intake must cost one YAML block or less
+   (the queues proved this), execution structure can cost a workplan file.
+2. Every work-item species must live in the same reconciliation loop
+   (file → CI validation → hub index → derived views) or it becomes a
+   sidetrack by construction.
+3. Human attention is a WIP-limited workstation; model it exactly like an
+   agent lane with a budget, a queue, and flow metrics.
+4. States should be few and abstract (canon lifecycle); everything
+   situational (stalled, unclear, automatable, needs-human) should be a
+   **derived or policy-assigned tag**, not a state — states migrate badly,
+   tags migrate trivially.
+5. Timestamped UUIDs internally + stable canonical names externally is the
+   correct layering and is industry-consistent (UUIDv7 for time-sortable
+   internal keys).
+6. Budgets become guardrail envelopes (per lane / workplan / run) enforced
+   at the runtime layer (harness), metered to the hub, escalated on breach.
+
+## Sources
+
+- https://about.gitlab.com/topics/gitops/
+- https://www.pulumi.com/blog/gitops-best-practices-i-wish-i-had-known-before/
+- https://spacelift.io/blog/gitops-best-practices
+- https://github.blog/enterprise-software/devops/applying-gitops-principles-to-your-operations/
+- https://virtido.com/blog/agentic-workflows-patterns-best-practices-enterprise
+- https://www.strata.io/blog/agentic-identity/practicing-the-human-in-the-loop/
+- https://velt.dev/blog/why-ai-agents-need-approval-layer
+- https://www.stackai.com/insights/human-in-the-loop-ai-agents-how-to-design-approval-workflows-for-safe-and-scalable-automation
+- https://nhimg.org/faq/how-should-security-teams-implement-human-in-the-loop-controls-for-ai-agents/
+- https://cmr.berkeley.edu/2026/03/governing-the-agentic-enterprise-a-new-operating-model-for-autonomous-ai-at-scale/
+- https://www.mckinsey.com/capabilities/risk-and-resilience/our-insights/trust-in-the-age-of-agents
+- https://inform.tmforum.org/features-and-opinion/ai-autonomy-governance-a-governance-framework-for-agentic-ai-enabling-safe-accountable-and-scalable-autonomous-intelligence
+- https://www.trendmicro.com/vinfo/us/security/news/cybercrime-and-digital-threats/from-anarchy-to-authority-closing-the-governance-gap-in-agentic-ai
+- https://agility-at-scale.com/safe/lpm/work-in-progress/
+- https://agility-at-scale.com/safe/lpm/wsjf-weighted-shortest-job-first/
+- https://agility-at-scale.com/safe/lpm/epics/
+- https://agility-at-scale.com/safe/lpm/portfolio-guardrails/
+- https://spin.atomicobject.com/budget-guardrails-software-project/
+- https://www.prokanban.org/blog/https-prokanban-org-blog-the-kanban-pocket-guide-chapter-6-the-basic-metrics-of-flow
+- https://asana.com/resources/project-risks
+- https://www.atlassian.com/work-management/project-management/project-risk-management

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

@@ -0,0 +1,234 @@
+# 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 |

research/WorkOrchestrationArchitectureDraft.md

@@ -0,0 +1,274 @@
+# Work Orchestration Architecture — Draft for Discussion
+
+> Draft v0.1 — 2026-07-19. Synthesis of
+> `2026-07-19-work-orchestration-infrastructure-survey.md` (internal) and
+> `2026-07-19-work-orchestration-best-practices.md` (external).
+> Trigger: reconciling the binky-control automation queues with the
+> suggestion/task/workplan backbone (AWQ-010 case). Status: **proposal** —
+> nothing here is canon until ratified; terminology extensions are marked
+> ⟨new⟩ and would land as a canon standard v0.1 after discussion.
+
+## 0. Thesis
+
+The queues were not a mistake — they were a **market signal**. Intake
+through a one-YAML-block append beat the hub suggestion flow because its
+friction was an order of magnitude lower, and it carried routing information
+(lanes) the backbone lacks. The error was ontological, not practical: the
+queue items became a second, unindexed species of work item.
+
+The reconciliation is therefore not "move queues into the hub" but:
+**make the backbone cheap enough at intake that the queue pattern becomes a
+schema-valid, hub-indexed instance of it** — and make every future species
+impossible to create outside the reconciliation loop without tripping an
+alarm.
+
+One sentence: *everything with an ID is a work record, every work record is
+a repo file, every repo file is indexed, and every list anyone works from is
+a derived view.*
+
+## 1. The unified ontology
+
+### 1.1 Work record ⟨new umbrella term⟩
+
+A **work record** is any identified, lifecycle-bearing coordination artefact.
+All existing species become *kinds* of work record:
+
+```
+work record
+├── intake item ⟨new⟩      — spark: idea, mail finding, observation, request
+│     (absorbs: AWQ items, hub suggestions, "actionable" mail-triage rows)
+├── task                   — smallest executable unit (canon lifecycle)
+│     (absorbs: workplan tasks, adhoc tasks, issue-core issues-as-interface)
+├── workplan               — structured, dependency-bearing body of work
+├── decision               — approval package + resolution
+│     (absorbs: DEC items; hub decision records become the index)
+├── engagement ⟨new⟩       — scheduled external interaction
+│     (absorbs: OH items — office-hour/command-day bookings)
+└── register entry         — risk, technical debt, capability request, CCR,
+                             interface change (existing species, unchanged
+                             semantics, brought under the same conventions)
+```
+
+Every work record, regardless of kind, carries the same **conventional
+spine** (aspect 4 — one framework, many demands):
+
+| Field | Convention |
+| --- | --- |
+| `id` | canonical name per type registry (§1.3) |
+| `uuid` | UUIDv7, hub-assigned at first index, written back to the file (like `state_hub_*_id` today) |
+| `kind` | from the closed kind list above |
+| `lane` | green/blue/yellow/orange/red (§2) |
+| `status` | abstract canon lifecycle for its kind (§1.4) |
+| `owner` | repo-anchored owner (agent identity or human) |
+| `repo` | owning repo (ADR-001/ADR-005 anchor) |
+| `tags` | policy + derived tags (§3) |
+| `created`/`updated` | dates; UUIDv7 provides fine-grained internal time |
+
+Kind-specific fields (budget, evidence, deadline_pressure,
+attention_cost, …) extend the spine; they never replace it.
+
+### 1.2 File-first, one reconciliation loop (aspect 3)
+
+- Every work record originates in a repo file: workplans as today; intake
+  items, decisions, engagements as YAML blocks inside per-repo registry
+  documents (`queues/…` or the existing live documents — location is
+  convention, the schema is what matters).
+- **Forgejo CI validates schemas** on push (yaml-block schema per kind —
+  the GitOps "validate before apply" rule).
+- `fix-consistency` grows checks per kind (as C-06 does for workplans):
+  registers new records, writes UUIDs back, syncs status *from file to hub*.
+  The hub stays a read model; runtime operations data (logs, metrics, run
+  histories, token events) is the sanctioned exception and lives only in
+  hub/activity-core/monitoring stores.
+- Derived views (§4) are generated *from the hub*, never hand-maintained:
+  the "Completed" tail of AutopilotWorkQueue.md, daily-brief queue summaries
+  etc. become materialized view output (ADR-003 pattern), clearly marked
+  `[auto]`.
+
+### 1.3 Type registry and layered identity (aspect 5)
+
+A single canon file (`canon/standards/work-record-types_v0.1.md` + machine
+copy `work-record-types.yaml`) registers every id scheme:
+
+```yaml
+- code: WP        # {PREFIX}-WP-NNNN          workplan
+- code: T         # {WP-ID}-TNN               task
+- code: IN        # {PREFIX}-IN-NNNN          intake item   ⟨new; AWQ-* grandfathered⟩
+- code: DEC       # {PREFIX}-DEC-YYYY-NNN     decision
+- code: ENG       # {PREFIX}-ENG-YYYY-NNN     engagement    ⟨OH-* grandfathered⟩
+- code: RISK, TD, CAP, CCR, ADR …             register entries (existing)
+```
+
+- **UUIDv7 is primary** for bookkeeping, relations, dependencies, history —
+  stable across renames, migrations, and terminology transitions
+  (the workstream→workplan migration cost is the proof this matters).
+- **Canonical names are primary for humans and agents** in UI/CLI/API
+  output, prose, and commits; UUIDs inspectable on demand. This is already
+  practiced for WP/T — the registry universalizes it.
+- Grandfathering rule (from the terminology standard): existing ids
+  (AWQ-, OH-) are never renamed; the registry maps legacy prefixes to kinds
+  and the legacy-meter discipline governs retirement of the *schemes*, not
+  the records.
+
+### 1.4 Abstract states + flow profiles (aspect 4)
+
+- The **abstract lifecycles stay minimal and canon-fixed**: task
+  `wait/todo/progress/done/cancel` (InfoTechCanon); workplan
+  `proposed/ready/active/blocked/backlog/finished/archived`; intake item
+  `open → vetted → routed → closed(promoted|declined|absorbed)` ⟨new,
+  replaces both suggestion stages and queue-item ad-hoc states⟩; decision
+  `prepared → resolved(approved|rejected|revised|deferred)`; engagement
+  `queued → prepared → done`.
+- **Different work kinds** (development, ops, compliance, billing, sales…)
+  get their demands met by **flow profiles** on the existing task-flow
+  engine: named workstation definitions whose entry/exit assertions encode
+  the kind-specific gates (e.g. a compliance task cannot exit `progress`
+  without an evidence link; a sales engagement cannot enter `prepared`
+  without prepared_material). Profiles are YAML in repos → same
+  reconciliation loop. States stay abstract; rigor lives in assertions.
+
+## 2. Lanes become fleet canon (aspects 1, 6, 7)
+
+Promote binky-control's AutonomyPolicy lane model to
+`canon/standards/autonomy-lanes_v0.1.md`, unchanged in substance:
+
+- Green (safe autonomous) · Blue (reversible, logged) · Yellow (deferred
+  approval) · Orange (time-window approval) · Red (human-only).
+- `lane` is a **mandatory field on every work record** and on every agent
+  manifest; the harness already enforces lane-scoped tool profiles — this
+  closes the loop from item to execution permission.
+- Human attention is modeled as a **WIP-limited workstation**: the founder
+  attention budget (minutes/day, max decisions/day) is a lane capacity;
+  Yellow routes to the decision queue view, Orange to the engagement view,
+  both subject to that capacity. External research is unanimous that
+  risk-tiered gating is the only scalable human-oversight pattern.
+- Time-boxing (`needed_by`, `fallback_if_no_response`) is hub-owned: the
+  hub (not a human reading a file) raises the escalation when a window
+  lapses — via the existing NATS → activity-core delegation.
+
+## 3. Policy tags, not states (aspect 6)
+
+Two tag classes, both in the `tags` field, never in `status`:
+
+- **Derived tags** — computed by hub/activity-core from data, read-only in
+  files: `stalled` (work-item age over threshold — the flow-metrics form),
+  `stale` (reviewed against older repo state), `overdue-decision`,
+  `budget-breached`, `orphaned` (no goal/workplan link).
+- **Policy tags** — assigned by agents/humans under tagging policies:
+  `automatable`, `needs-human`, `unclear-implementation`, `red-adjacent`
+  (touches a Red boundary), `compliance-relevant`. Tagging policies are
+  YAML rules (activity-core `ActivityDefinition`s may auto-apply them on
+  events) — auditable and evolvable without schema migrations.
+
+Tags drive the optimization loop: `automatable` feeds the autopilot view;
+`needs-human` + lane feeds attention routing; `stalled`+`unclear` feeds the
+kaizen coach. This is how "what should be automated next" becomes a query
+instead of a discovery.
+
+## 4. Queues are views (the reconciliation itself)
+
+The three binky queues are retained **as products, redefined as views**:
+
+| Today | Becomes |
+| --- | --- |
+| AutopilotWorkQueue.md (hand-edited) | *Autopilot view*: `kind=intake∨task, lane∈{green,blue}, status∈{open,todo}, tag=automatable`, WSJF-ordered; "never empty" becomes a monitored invariant with an alert, not a plea |
+| DecisionQueue.md open section | *Decision view*: `kind=decision, status=prepared`, ordered by needed_by; resolved log is generated |
+| OfficeHourQueue.md | *Engagement view*: `kind=engagement`, batched per command day; runbook generation stays (officehour/) |
+
+Mechanics: records are authored in files (cheap intake preserved — one YAML
+block, schema-checked); `fix-consistency` indexes them; view documents are
+regenerated `[auto]` sections. Pull protocol becomes a status transition
+(`todo → progress` with owner) instead of a prose note — which makes claims
+visible fleet-wide and collision-free (issue-core remains the claim
+*interface* for harness runtime; the record is the truth).
+
+Promotion (the AWQ-010 lesson) becomes a **first-class transition**:
+`intake.routed → workplan|task|decision|engagement` with back-links
+(`promoted_to`/`origin`), performable by one CLI/MCP call that writes both
+files and re-syncs — never a manual transcription again.
+
+## 5. Visibility, tenancy, scale (aspect 2)
+
+- **state-hub** remains the dev-coordination read model (localhost,
+  file-first, fix-consistency).
+- **core-hub** is the production visibility layer: dashboards, flow metrics
+  (WIP, cycle time, item age, throughput — all computable from UUIDv7 +
+  status transitions), cross-domain rollups, operator console. The work
+  record spine becomes part of the core-hub contract/IR so Gen-3 ingests
+  ADR-001 artefacts natively (its workplan-coordination spec already
+  commits to this).
+- **Tenancy**: repo → domain → tenant, derived from repo classification
+  (never a parallel spine). agent-harness is already multi-tenant with
+  per-tenant credential lanes (ops-warden/OpenBao); dashboards get
+  tenant/domain scoping from the same derivation. Separation is by
+  classification + credential lanes; centralization is by shared runtime
+  (harness, activity-core, hubs) — efficient utilization with clean blast
+  radii.
+- **Budgets as guardrail envelopes** (aspect 1): per-run token budgets
+  (harness manifests, enforced today) roll up to per-workplan and per-lane
+  envelopes recorded on the work record; `record_token_event` meters,
+  `budget-breached` tag + escalation on breach. Complex-project risk
+  control = dependency edges (existing) + lane gates + budget envelopes +
+  flow metrics, all on one spine.
+
+## 6. Opinionated by construction (aspect 7)
+
+- **The registry is closed.** An id pattern not in the type registry fails
+  CI and fix-consistency (the "sidetrack detector" — a warning that names
+  the reintegration cost explicitly). New kinds are added by canon PR, which
+  is deliberately cheap (one YAML entry + one schema) so the legitimate
+  path is easier than the workaround — the core lesson of the queues.
+- **AGENTS.md generation** (state-hub templates) teaches the conventions in
+  every repo; the guidance and the enforcement come from the same source.
+- **Intake friction budget**: creating an intake item must never cost more
+  than the AWQ pattern did (append one block). If a future workaround
+  appears anyway, the postmortem question is fixed: *which friction did we
+  fail to remove?*
+
+## 7. Migration path (staged, history-preserving)
+
+1. **Canonize** (docs only): work-record umbrella + type registry +
+   autonomy-lanes standard + intake lifecycle → canon standards v0.1;
+   extend `workplan-terminology-fleet` rather than fork it.
+2. **Schema + CI**: YAML schemas per kind; Forgejo CI check; binky-control
+   is the pilot (its queues become schema-valid without renaming ids).
+3. **Index**: fix-consistency checks for intake/decision/engagement kinds
+   (C-2x series); hub tables reuse existing entities where they fit
+   (suggestions table ⇢ intake items — suggestions gain file artefacts,
+   resolving their own ADR-001 tension; decisions already dual-exist,
+   the check just automates the mirroring both ways).
+4. **Views**: generated `[auto]` sections replace hand-maintained queue
+   tails; hub owns needed_by clocks via NATS → activity-core.
+5. **Tags + metrics**: derived-tag computation and the four flow metrics in
+   state-hub first, surfaced in core-hub dashboards as the contract lands.
+6. **Retire** legacy singularities per legacy-meter discipline (e.g. the
+   hub-first suggestion create path) only after zero measured use.
+
+Each stage is independently valuable; stopping after any stage leaves the
+system consistent (no big-bang).
+
+## 8. Open questions for discussion
+
+1. **Naming**: "work record" vs. "work item" as umbrella; "intake item" vs.
+   keeping "suggestion" fleet-wide; German-friendly alternatives?
+2. **Where intake blocks live**: per-repo `queues/intake.md` vs. today's
+   thematic live documents (AutopilotWorkQueue as a *view* argues for
+   separating authored records from generated views into distinct files).
+3. **Engagements** as their own kind vs. decisions-with-a-time-window —
+   the Orange lane is behaviorally distinct (batching), which argues for
+   the separate kind, but the spine could carry it as a decision subtype.
+4. **WSJF adoption**: reuse the 2026-06-04 calibration or start simpler
+   (lane + priority + age) and let kaizen metrics justify WSJF later?
+5. **issue-core's long-term role**: claim interface only (proposed here),
+   or should issues become file-backed work records too?
+6. **Suggestion table reuse vs. new intake entity** in state-hub — schema
+   archaeology needed before stage 3.
+7. **Budget envelope placement**: frontmatter on workplans vs. a separate
+   `budgets.yaml` per repo (compliance kinds may want the latter).
+
+---
+
+*Prepared from live fleet data (AWQ-010 reintegration, DEC-2026-003/004
+dual bookkeeping, BINKY-WP-0002 slug drift) and the two research artefacts
+alongside this file. Next step after discussion: canon standard drafts +
+a CUST workplan for stage 1–2.*