diff --git a/research/WorkOrchestrationArchitectureDraft.md b/research/WorkOrchestrationArchitectureDraft.md index f3e18d4..12c2ccc 100644 --- a/research/WorkOrchestrationArchitectureDraft.md +++ b/research/WorkOrchestrationArchitectureDraft.md @@ -1,12 +1,13 @@ # Work Orchestration Architecture — Draft for Discussion -> Draft v0.1 — 2026-07-19. Synthesis of +> Draft v0.2 — 2026-07-20 (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. +> suggestion/task/workplan backbone (AWQ-010 case). Status: **proposal, +> founder-reviewed** — the seven open questions were resolved with the +> founder on 2026-07-20 (§8); terminology extensions are marked ⟨new⟩ and +> land as canon standard drafts next. ## 0. Thesis @@ -69,10 +70,20 @@ 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). +- Every work record originates in a repo file — and **any file in a repo is + a potential source of work records**. Workplans stay dedicated files; + intake items, decisions, engagements are YAML blocks authored *in + context*: thematic live documents, meeting notes, design docs, triage + logs. The schema is the contract, not the location. (Motivating example: + meeting notes with todos are kept where the work happens, yet the todos + must surface in one global orientation view — see the index below.) +- A fully **generated per-repo work-record index** captures every + registered record with a reference to its source location — a + transclusion-style view: the record lives once in its source file, the + index (and other views) reference it. Registration binds each record to + hub state wherever it was authored, which stabilizes concurrent + human/agent edits and enables cross-checks instead of causing conflicts. + Efficient transclusion and index management is markitect-family scope. - **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): @@ -171,16 +182,39 @@ 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 | +| AutopilotWorkQueue.md (hand-edited) | *Autopilot view*: `kind=intake∨task, lane∈{green,blue}, status∈{open,todo}, tag=automatable`, ordered by lane+priority+age (§4.1); "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/) | +| — (new) | *Per-repo work-record index* (§1.2): every registered record, any kind, any source file — the "all my todos across everything" orientation view | -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 +Mechanics: records are authored in their source files (cheap intake +preserved — one YAML block, schema-checked, authored where the context is); +`fix-consistency` indexes them; view documents and the index are +regenerated `[auto]`. 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). +visible fleet-wide and collision-free. + +### 4.1 Ordering (resolved 2026-07-20) + +Default ordering is deliberately simple: **lane + priority + work-item +age** — zero extra fields at intake. Dependency capture is *optional* per +record (edges when they matter, never mandatory). **WSJF is an optional, +situational triage instrument** for capacity-overload situations, applied +to a view when selection pressure justifies estimation cost — never a +required field. Rationale: small tasks implement faster than they can +feasibly be planned and evaluated beforehand; mandatory estimation is waste +at the bottom of the size distribution. + +### 4.2 issue-core: third-party connector, not core loop (resolved 2026-07-20) + +issue-core's role is a **connector framework to external issue-tracking +systems** (Forgejo issues, Jira, GitHub, …): it maintains the mapping +between internal work-record UUIDs and external issue ids and provides +two-way, transclusion-like sync *at the boundary* when we collaborate +through a third-party tracker. It is not part of the internal execution +loop — claiming and execution run on work records directly (harness intake +via NATS/activity-core per its stated target). Until an external +integration is actually switched on, the connector layer adds zero load. Promotion (the AWQ-010 lesson) becomes a **first-class transition**: `intake.routed → workplan|task|decision|engagement` with back-links @@ -204,12 +238,20 @@ files and re-syncs — never a manual transcription again. 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. +- **Budgets as guardrail envelopes** (aspect 1, resolved 2026-07-20): + three-level resolution, strictly programmatic — + 1. workplan frontmatter override (narrowest, lives with the work), + 2. per-repo `budgets.yaml` lane/default envelopes (the auditable + guardrails), + 3. **global best-guess default** when neither exists — nothing ever runs + unbounded. + The harness resolves override → repo policy → global default at run + start; `record_token_event` meters; `budget-breached` tag + escalation on + breach. Budget resolution and enforcement is **automation infrastructure + code, never agentic effort** — AI tokens and personal review only refine + the estimates over time. Complex-project risk control = dependency edges + (existing) + lane gates + budget envelopes + flow metrics, all on one + spine. ## 6. Opinionated by construction (aspect 7) @@ -247,28 +289,43 @@ files and re-syncs — never a manual transcription again. Each stage is independently valuable; stopping after any stage leaves the system consistent (no big-bang). -## 8. Open questions for discussion +## 8. Resolved questions (founder review, 2026-07-20) -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). +1. **Naming**: umbrella term is **work record**; the intake kind is + **intake item** ("suggestion" remains only as the legacy bridge name). + Mental model: a task is a specific *kind* of work record — the smallest + executable unit; the work-record supertype guarantees the shared spine + across all kinds. +2. **Where records live**: **any repo file is a potential source of work + records** (meeting notes, thematic docs, design docs); a fully + **generated per-repo index** references all registered records in their + source locations (transclusion-style; markitect-family tooling). See + §1.2. Registration binds records to hub state wherever authored — + stabilization and cross-checking for concurrent human/agent work, not a + conflict source. +3. **Engagements** are their **own kind** — a command day batches many + engagements; an engagement may spawn or resolve several decisions but is + not itself one. +4. **Ordering**: simple default (lane + priority + age); dependency capture + optional; **WSJF optional and situational** — a triage instrument for + limited capacity under overload, not a universal method. Small tasks + implement faster than they can feasibly be planned and evaluated. §4.1. +5. **issue-core** is a **connector framework to third-party issue + trackers** (internal UUID ↔ external issue-id mapping, two-way + transclusion-like sync at the boundary); not part of the internal loop; + must add no load until an integration is actually used. §4.2. +6. **Hub entity**: **fresh intake entity** with the clean UUIDv7 spine; the + suggestions table becomes read-only legacy with a one-time close-out of + its few records. +7. **Budgets**: **hybrid** — per-repo `budgets.yaml` guardrails + + workplan-frontmatter overrides + a **global best-guess default** as + final fallback so nothing runs unbounded; resolution/enforcement is + programmatic infrastructure, never agentic effort. §5. --- *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.* +alongside this file. All open questions resolved with the founder +2026-07-20. Next step: canon standard drafts (work-record types, autonomy +lanes, intake lifecycle) + a CUST workplan for migration stages 1–2.*