From 3330ca55cdb28e3e2518be86fd099de2e7427059 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 4 Apr 2026 11:52:32 -0700 Subject: [PATCH] docs(runtime): define first conforming product plan --- .../ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md | 88 ++++++++++++++++++- .../ECOSYSTEM_IMPLEMENTATION_TRACKER.md | 3 +- ...5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md | 6 +- .../adoption/learning_ai_claw-cowork.md | 15 +++- .../adoption/learning_ai_flowmonk.md | 12 ++- 5 files changed, 116 insertions(+), 8 deletions(-) diff --git a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md index 79a2b2c9..87847120 100644 --- a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md +++ b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md @@ -332,7 +332,89 @@ Current product expectations: --- -## 13. Acceptance Criteria +## 13. First Conforming Implementation Plan + +The first conforming implementations for Phase 5 should be treated as two tracks: + +### Track A: Cowork conformance + +Goal: + +- present Cowork as the reference high-autonomy runtime producer + +Required external contract surface: + +- `AgentSession` +- `AgentTask` +- `AgentTodo` +- `AgentRun` +- `AgentApprovalCheckpoint` +- `AgentActionLog` +- dispatch validation +- checkpoint/resume narrative support + +Current state: + +- sessions, tasks, runs, approvals, actions, and dispatch validation are already exposed through + `cowork-service` +- todos are currently task-backed +- replay anchors now use canonical Rust audit `event_id` + +Next conforming steps: + +1. add a first-class Cowork todo/checklist source or make the task-backed mapping an explicit long-term choice +2. expose checkpoint metadata or equivalent persisted resume summaries through product-facing runtime surfaces +3. preserve canonical event IDs anywhere approval/audit state crosses service boundaries +4. document which Cowork transitions are direct observations versus projections derived by `cowork-service` + +Conformance bar: + +- a reviewer can inspect one Cowork session and understand queued, running, paused, waiting-approval, + resumed, and completed states without reading Rust internals + +### Track B: FlowMonk conformance + +Goal: + +- present FlowMonk as the reference scheduled/queued runtime producer + +Required external contract surface: + +- `AgentSession` +- `AgentTask` +- `AgentTodo` +- `AgentRun` +- `AgentApprovalCheckpoint` +- `AgentActionLog` +- dispatch validation where scheduling hands off into downstream execution +- checkpoint/resume narrative for planning state + +Current state: + +- sessions, tasks, todos, runs, approvals, actions, and dispatch validation are exposed through the backend +- approvals are derived from agent-suggested schedule entries +- todos are derived from the planning backlog + +Next conforming steps: + +1. decide whether approvals remain derived or become a first-class product primitive +2. decide whether backlog tasks are the permanent todo model or whether a distinct checklist model will exist +3. expose checkpoint summaries for planning sessions so resume state is not inferred only from final records +4. document the exact rule for when a scheduled entry becomes a new run under an existing session + +Conformance bar: + +- a reviewer can inspect one FlowMonk planning session and understand which work was queued, + confirmed, executed, deferred, or resumed without guessing from schedule records alone + +Shared closeout requirement: + +- both products should publish a short product-local adoption note that maps their native entities to + the shared runtime contract and explicitly names any remaining derived projections + +--- + +## 14. Acceptance Criteria 1. A dispatched Cowork task can be resumed after interruption without losing audit continuity. 2. A FlowMonk execution can emit task/todo state using the same contract. @@ -342,7 +424,7 @@ Current product expectations: --- -## 14. Implementation Checklist +## 15. Implementation Checklist - [x] finalize entity list and minimum required fields - [x] define run vs session vs task boundaries @@ -350,7 +432,7 @@ Current product expectations: - [x] define dispatch payload contract - [x] define action-log hook points - [x] define ActionTrail replay requirements -- [ ] define first conforming implementation plan for Cowork and FlowMonk +- [x] define first conforming implementation plan for Cowork and FlowMonk Commits: diff --git a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md index 4f4cb637..9aa124f2 100644 --- a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md +++ b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md @@ -272,7 +272,8 @@ These should be resolved before claiming the ecosystem docs are fully implementa - Cowork: add `AgentTodo` direct projection once the product exposes first-class todo entities. - FlowMonk: replace the current derived approval/todo projections once the product exposes first-class approval/todo primitives. -- Shared runtime: define the first conforming implementation plan for Cowork and FlowMonk beyond the current baseline projections. +- Cowork: expose product-facing checkpoint summaries for resume review. +- FlowMonk: expose product-facing checkpoint summaries and document the run/session rollover rule. ### 6.2 Explicit Blockers And Questions diff --git a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md index 73ef1978..970998d0 100644 --- a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md +++ b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md @@ -112,7 +112,11 @@ Observed baseline: - Cowork now emits shared runtime projections from cowork-service, preserves Rust-side canonical event IDs on approval/audit records, and still lacks a first-class native `AgentTodo` product source behind the current task-backed projection. - FlowMonk now emits direct runtime projections for planning sessions, tasks, todos, runs, approvals, and action logs, but it still lacks distinct native checklist and approval entities behind those projections. -- the first conforming implementation plan still needs to be made explicit for Cowork and FlowMonk beyond the current baseline projections. +- the conforming implementation plan is now explicit in the runtime contract, but the product-level follow-through still remains: + - Cowork needs a first-class todo source or an explicit decision to keep the task-backed mapping + - Cowork needs product-facing checkpoint summaries + - FlowMonk needs an explicit decision on whether approvals/todos stay derived or become first-class primitives + - FlowMonk needs product-facing checkpoint summaries and a documented run/session rollover rule ## 8. Explicit Blockers And Questions diff --git a/docs/ecosystem/adoption/learning_ai_claw-cowork.md b/docs/ecosystem/adoption/learning_ai_claw-cowork.md index 87e8bfc4..95da6d36 100644 --- a/docs/ecosystem/adoption/learning_ai_claw-cowork.md +++ b/docs/ecosystem/adoption/learning_ai_claw-cowork.md @@ -34,9 +34,22 @@ ActionTrail now treats the exported JSON audit shape as the canonical import inp --- -## 3. Remaining Follow-Up +## 3. Runtime Conformance Follow-Up + +For Phase 5, Cowork is also a first conforming runtime implementation. + +Current runtime adoption state: + +- shared runtime projections now exist through `cowork-service` +- audit/action surfaces preserve canonical Rust `event_id` +- approvals and action logs can participate in ActionTrail replay +- todos are still derived from orchestrator tasks + +Remaining follow-up: - add an explicit product-local helper for exporting ecosystem-ready audit payloads +- decide whether task-backed todo projection is temporary or permanent +- expose product-facing checkpoint summaries for resume review - optionally emit canonical runtime events alongside the current local audit logs - add signed dispatch or upload flow from Cowork desktop into ActionTrail when runtime integration is prioritized diff --git a/docs/ecosystem/adoption/learning_ai_flowmonk.md b/docs/ecosystem/adoption/learning_ai_flowmonk.md index 700a8ce0..22e793be 100644 --- a/docs/ecosystem/adoption/learning_ai_flowmonk.md +++ b/docs/ecosystem/adoption/learning_ai_flowmonk.md @@ -1,8 +1,8 @@ # Adoption: learning_ai_flowmonk -> **Status:** Phase 2 baseline implemented +> **Status:** Phase 2 baseline implemented, Phase 5 runtime baseline implemented > **Owner:** `learning_ai_flowmonk` -> **Ecosystem focus:** plan -> routine -> habit golden flow +> **Ecosystem focus:** plan -> routine -> habit golden flow and scheduled runtime projection --- @@ -11,6 +11,7 @@ - emit canonical `plan` artifacts from planning-export data - emit canonical `artifact.created` events for plans - provide enough lineage for ChronoMind and EffoRise consumers +- expose FlowMonk planning/runtime state through the shared runtime contract ## Checklist @@ -18,7 +19,14 @@ - [x] emit `artifact.created` for the plan artifact - [x] include correlation/session IDs for downstream linking - [x] persist latest plan indexes for downstream consumers +- [x] expose direct runtime sessions, tasks, todos, runs, approvals, and actions +- [ ] decide whether approvals remain derived or become first-class primitives +- [ ] decide whether todos remain backlog-task projections or become a first-class checklist primitive +- [ ] expose product-facing checkpoint summaries for planning-session resume +- [ ] document the rule for when a scheduled entry becomes a new run under an existing session Commits: - `59ab8b1` implemented the Phase 2 producer path +- `1ccafa7` implemented direct runtime sessions, tasks, runs, actions, and dispatch validation +- `faf93ec` implemented direct runtime approvals and todos