From e4087a7dc133fe8c8523ca585b1841ff2b0be2d9 Mon Sep 17 00:00:00 2001 From: Claude Sonnet 5 Date: Sat, 4 Jul 2026 04:08:41 +0000 Subject: feat(story): add StoryOrchestrator -- Builder->Evaluators->Arbitration->accept (Phase 7b) A deterministic, poll-based watcher (internal/scheduler.StoryOrchestrator, sibling to the Phase 5 Scheduler) that drives a story.Story through its execution pipeline, rather than relying on an LLM agent to correctly orchestrate its own fan-out via tool calls. Mechanism: polling, not a handleRunResult hook. Every task the orchestrator watches (a story's root/Builder task, 4 Evaluators, Arbitration) is top-level (no ParentTaskID), and executor.Pool.handleRunResult only ever lands a top-level task at READY or BLOCKED -- never COMPLETED directly, since that transition normally requires a human/chatbot POST /api/tasks/{id}/accept in a different package. A handleRunResult hook would never observe it; polling doesn't care how/whether a task reached a given state. Stages: Builder COMPLETED -> spawn 4 role-typed Evaluator tasks (evaluator_quality/security/correctness/performance, DependsOn: [builder], no ParentTaskID -- true DAG siblings, not delegated subtasks) + story -> VALIDATING. Each Evaluator COMPLETED -> emit KindEvalVerdict (attached to the story's ID, so one GET /api/stories/{id}/events call surfaces every verdict). All 4 Evaluators COMPLETED -> spawn 1 Arbitration task (role: planner, DependsOn: all 4 evaluator IDs). Arbitration COMPLETED -> emit KindArbitrationDecided, story -> REVIEW_READY. POST /api/stories/{id}/accept (mirrors handleAcceptTask) -> DONE, emits KindHumanAccepted. Fixes a gap caught before merging: since none of Builder/Evaluators/ Arbitration have a ParentTaskID, none of them auto-complete -- each would otherwise need a separate manual /api/tasks/{id}/accept, meaning 6 human clicks per story before ever reaching the intended single story-level gate. StoryOrchestrator.autoAccept now transitions each of these specific tasks READY->COMPLETED itself (via the same validated Store.UpdateTaskState path acceptTask uses), scoped only to tasks already established as part of a story's pipeline (root task, or role-matched dependents from ensureEvaluators/ensureArbitration) -- never a blanket sweep of unrelated READY tasks. This makes POST /api/stories/{id}/accept the system's only required human touchpoint for the whole chain, matching the design goal that story (not task/subtask) is the human-interaction atom. Idempotency: structural for task-creation stages (ensureEvaluators/ ensureArbitration check ListDependents for already-existing role-matched tasks before creating -- crash/restart-safe); story.Status=="VALIDATING" gates the Arbitration->REVIEW_READY write (nothing further downstream to check structurally there); an in-memory handledVerdicts set (mirrors Scheduler.handled) dedupes per-evaluator KindEvalVerdict emission across poll ticks, resetting harmlessly on restart. Documented simplification: finalizeArbitration never parses the Arbitration summary for approve/reject -- always routes to REVIEW_READY; NEEDS_FIX is manually settable via PUT /api/stories/{id}. A later phase could close this with a dedicated verdict-reporting AgentChannel method instead of parsing free text. go build/vet/test -race -count=1 all pass, full suite (20 packages). Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs --- internal/api/stories.go | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) (limited to 'internal/api/stories.go') diff --git a/internal/api/stories.go b/internal/api/stories.go index 337da21..b93f8c3 100644 --- a/internal/api/stories.go +++ b/internal/api/stories.go @@ -3,8 +3,10 @@ package api import ( "encoding/json" "net/http" + "strconv" "github.com/google/uuid" + "github.com/thepeterstone/claudomator/internal/event" "github.com/thepeterstone/claudomator/internal/storage" "github.com/thepeterstone/claudomator/internal/story" ) @@ -168,3 +170,82 @@ func (s *Server) handleStoryTaskTree(w http.ResponseWriter, r *http.Request) { writeJSON(w, http.StatusOK, resp) } + +// handleListStoryEvents returns a story's observability event stream in seq +// order. Mirrors handleListTaskEvents exactly (same ?since_seq=N incremental +// polling contract), but resolves existence via GetStory rather than +// GetTask: the internal/scheduler.StoryOrchestrator (Phase 7b) attaches +// KindEvalVerdict/KindArbitrationDecided/KindHumanAccepted events to the +// story's ID rather than to any single task's ID (see that package's doc +// comments for why) — events.task_id has no enforced FK, so this is exactly +// the tolerance 7a's event.Kind doc comments anticipated ("a later phase's +// orchestration logic writes them against a story or epic ID"). +func (s *Server) handleListStoryEvents(w http.ResponseWriter, r *http.Request) { + id := r.PathValue("id") + if _, err := s.store.GetStory(id); err != nil { + writeJSON(w, http.StatusNotFound, map[string]string{"error": "story not found"}) + return + } + + var sinceSeq int64 + if v := r.URL.Query().Get("since_seq"); v != "" { + n, err := strconv.ParseInt(v, 10, 64) + if err != nil || n < 0 { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid since_seq"}) + return + } + sinceSeq = n + } + + events, err := s.store.ListEvents(id, sinceSeq) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()}) + return + } + if events == nil { + events = []*event.Event{} + } + writeJSON(w, http.StatusOK, events) +} + +// handleAcceptStory is the human accept-gate for a story: it mirrors +// handleAcceptTask's pattern exactly (validate current state, transition, +// emit an event) but operates on story.Story, which (unlike task.Task) has +// no enforced state machine (story.UpdateStory is unvalidated pass-through — +// see internal/story's doc comments) — so the "only valid from REVIEW_READY" +// check is done here, not in the storage layer. +func (s *Server) handleAcceptStory(w http.ResponseWriter, r *http.Request) { + id := r.PathValue("id") + st, err := s.store.GetStory(id) + if err != nil { + writeJSON(w, http.StatusNotFound, map[string]string{"error": "story not found"}) + return + } + if st.Status != "REVIEW_READY" { + writeJSON(w, http.StatusConflict, map[string]string{"error": "story cannot be accepted from status " + st.Status}) + return + } + + from := st.Status + st.Status = "DONE" + if err := s.store.UpdateStory(st); err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()}) + return + } + + payload, _ := json.Marshal(struct { + StoryID string `json:"story_id"` + From string `json:"from"` + To string `json:"to"` + }{StoryID: id, From: from, To: "DONE"}) + if err := s.store.CreateEvent(&event.Event{ + TaskID: id, + Kind: event.KindHumanAccepted, + Actor: event.ActorUser, + Payload: payload, + }); err != nil { + s.logger.Error("failed to record human_accepted event", "storyID", id, "error", err) + } + + writeJSON(w, http.StatusOK, map[string]string{"message": "story accepted", "story_id": id}) +} -- cgit v1.2.3