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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs

1 files changed, 81 insertions, 0 deletions

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})
+}