summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorClaude Sonnet 5 <noreply@anthropic.com>2026-07-04 04:08:41 +0000
committerClaude Sonnet 5 <noreply@anthropic.com>2026-07-04 04:08:41 +0000
commite4087a7dc133fe8c8523ca585b1841ff2b0be2d9 (patch)
treeae3de24d5d1b6abd5634eeab6fd99424baf847dc
parent392c7c1ada310b2f928dca89b75ba628478f7694 (diff)
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
-rw-r--r--CLAUDE.md169
-rw-r--r--internal/api/server.go2
-rw-r--r--internal/api/stories.go81
-rw-r--r--internal/api/stories_test.go131
-rw-r--r--internal/cli/serve.go14
-rw-r--r--internal/scheduler/story_orchestrator.go482
-rw-r--r--internal/scheduler/story_orchestrator_test.go769
7 files changed, 1629 insertions, 19 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
index 90356e5..32bca69 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -78,8 +78,8 @@ Config defaults to `~/.claudomator/config.toml`. Data is stored in `~/.claudomat
| `internal/agentloop` | Provider-neutral tool-use control-flow loop shared by all `NativeRunner`s |
| `internal/sandbox` | `Sandbox` interface (`HostSandbox`/`DockerSandbox`) + pre-tool-use guardrail hooks |
| `internal/role` | `RoleConfig`/`Tier`/`Rung` — per-role system prompt + provider/model escalation ladder |
-| `internal/scheduler` | `Scheduler` — polls role-typed FAILED tasks and retries/escalates them per their role's ladder |
-| `internal/story` | `Epic`/`Story` — planning layer above the flat task tree; data model only (Phase 7a), no orchestration |
+| `internal/scheduler` | `Scheduler` — polls role-typed FAILED tasks and retries/escalates them per their role's ladder; `StoryOrchestrator` (Phase 7b) — polls stories and drives Builder → Evaluators → Arbitration → REVIEW_READY |
+| `internal/story` | `Epic`/`Story` — planning layer above the flat task tree; data model + CRUD only (see `internal/scheduler.StoryOrchestrator` for the orchestration that drives it) |
| `web` | Embedded static UI (`embed.go`) |
### Key Data Flows
@@ -108,8 +108,8 @@ PENDING ──→ QUEUED ──→ RUNNING ──→ READY ──→ COMPLETED
```
- **BLOCKED**: Parent task completed but has subtasks that are not yet COMPLETED, OR the agent called `ask_user`. Unblocked by `maybeUnblockParent()` or a user/chatbot answer via `/api/tasks/{id}/answer` (or the chatbot MCP `answer_question` tool).
-- **READY**: Execution succeeded; awaits manual accept/reject via `/api/tasks/{id}/accept` or `/api/tasks/{id}/reject`.
-- **COMPLETED**: Terminal — entered only via user accept (top-level) or automatic subtask completion.
+- **READY**: Execution succeeded; awaits manual accept/reject via `/api/tasks/{id}/accept` or `/api/tasks/{id}/reject`. Exception: a Builder/Evaluator/Arbitration task belonging to a story's pipeline is auto-accepted straight to `COMPLETED` by `internal/scheduler.StoryOrchestrator` (Phase 7b) instead of waiting for a manual accept — see "Story orchestrator" below.
+- **COMPLETED**: Terminal — entered via user accept (top-level), `StoryOrchestrator` auto-accept (story-pipeline top-level tasks), or automatic subtask completion.
- `FAILED/TIMED_OUT/CANCELLED/BUDGET_EXCEEDED` all re-enter at `QUEUED` for retry/resume.
**WebSocket:** `Hub` fans out task completion events to all connected clients. `Server.StartHub()` must be called before `ListenAndServe`.
@@ -324,15 +324,19 @@ Two prerequisites for fan-out patterns (e.g. a Builder task with several role-ty
- **Auto-cascade-fail** (`internal/executor.Pool.cascadeFail`): the moment a task lands in a terminal failure state (`FAILED`/`TIMED_OUT`/`CANCELLED`/`BUDGET_EXCEEDED` — checked in `handleRunResult` plus the two direct-cancel paths in `execute()` for budget-gate and dependency-failure), the pool looks up `Store.ListDependents(taskID)` (a full-table scan over `depends_on_json` — no reverse index, same tradeoff already accepted elsewhere for JSON-blob columns) and cancels every direct dependent still waiting (`PENDING`/`QUEUED`), recording a `CANCELLED` execution whose `error_msg` references the upstream task and writing the ordinary `KindStateChange` event via `UpdateTaskState` (no new event kind). It recurses into each cancelled dependent's own dependents (visited-set guarded against a pathological dependency cycle — task creation does not itself reject cycles), so a multi-level chain cascades all the way down. `execute()`'s dependency-wait requeue loop re-checks the task's fresh DB state before dispatching so a task cascade-cancelled out from under it is never actually run.
- **Role-typed subtask spawning** (`agentchannel.SubtaskSpec.Role`, threaded through `storeChannel.SpawnSubtask` in `internal/executor/channel.go`): when a spawning agent sets `role` (available as an optional `spawn_subtask` tool parameter on both transports — `internal/agentloop/tools.go` for the native tool-use loop, `internal/executor/agentmcp.go` for the MCP transport), the child task gets `Agent.Role` set and `Agent.Type`/`Agent.Model` left empty, so Phase 5's role-based dispatch resolves them from the role's escalation ladder on the child's own first dispatch. Omitting `role` (every pre-Phase-6 caller) preserves the exact prior behavior (`Agent.Type: "claude"`, `Agent.Model` from the `model` argument).
-### Planning layer: epics & stories (data model only)
+### Planning layer: epics & stories
`internal/story` defines `Epic` and `Story` — a planning layer above the flat
-task tree (`epics`/`stories` tables, see Storage Schema above). This is
-Phase 7a: **pure data model + CRUD**. Nothing creates, transitions, or reads
-these rows automatically yet — no watcher spawns Builder/Evaluator/
-Arbitration tasks from a story, no deploy-gating, no epic-proposal agent
-tooling. A later phase builds that orchestration on top of what's stored
-here.
+task tree (`epics`/`stories` tables, see Storage Schema above). Phase 7a
+built pure data model + CRUD. Phase 7b (`internal/scheduler.StoryOrchestrator`)
+adds the first slice of automated orchestration on top of it: driving a story
+through Builder → 4 parallel Evaluators → Arbitration → a single human
+accept-gate **at the story level**. Every task along the way (Builder,
+Evaluators, Arbitration) is auto-accepted by the orchestrator itself — see
+"Story orchestrator" below — so `POST /api/stories/{id}/accept` is the
+*only* manual accept a human/chatbot ever has to make for the whole chain.
+Planner→Builder chain automation, epic-proposal tooling, and deploy-gating
+are still out of scope — see that type's non-goals.
- **Epic** (`epics` table): a loosely-scoped initiative that decomposes into
Stories. `status` is `OPEN`/`CLOSED`, unvalidated pass-through (`UpdateEpic`
@@ -342,9 +346,11 @@ here.
`root_task_id` are loose references (plain strings, no FK enforcement) —
same tolerance the codebase already has for `tasks.project`. `status` is
one of `DISCOVERY|FRAMING|BACKLOG|PRIORITIZED|IN_PROGRESS|SHIPPABLE|
- DEPLOYED|VALIDATING|REVIEW_READY|NEEDS_FIX|DONE|CANCELLED`, also
- unvalidated pass-through in this phase (no `task.ValidTransition`-style
- enforcement — there's no orchestrator yet to make transitions meaningful).
+ DEPLOYED|VALIDATING|REVIEW_READY|NEEDS_FIX|DONE|CANCELLED`, still
+ unvalidated pass-through at the storage layer (no `task.ValidTransition`-
+ style enforcement in `UpdateStory`/`PUT /api/stories/{id}`) — `StoryOrchestrator`
+ itself only ever writes `VALIDATING` and `REVIEW_READY`, and only after
+ checking the story's current status/dependents first (see below).
- **`GET /api/stories/{id}/task-tree`** walks the task graph realizing a
story: starting at `root_task_id`, it follows both `parent_task_id`
children (`ListSubtasks`) and `depends_on_json` edges in either direction
@@ -354,15 +360,115 @@ here.
state, agent_type, role, parent_task_id, depends_on}]}`); clients
reconstruct the graph from each node's `parent_task_id`/`depends_on`. An
unset `root_task_id` returns an empty node list, not an error.
-- New `event.Kind` constants for the ceremony this layer will eventually
- drive (`epic_proposed`, `discovery_proposed`, `framing_decided`,
- `groomed`, `prioritized`, `eval_verdict`, `arbitration_decided`,
- `retro_captured`, `human_accepted`) are defined in `internal/event` but
- nothing emits them yet.
- REST endpoints are not gated by `api_token`, consistent with
`/api/projects`/`/api/tasks` (only chatbot MCP, agent MCP, and WebSocket
require it).
+#### Story orchestrator (Phase 7b)
+
+`internal/scheduler.StoryOrchestrator` (same file group as `Scheduler`, see
+`internal/scheduler/story_orchestrator.go`) is a poll-based watcher
+(`Tick`/`Run`, `DefaultStoryPollInterval` = 15s), not a hook into
+`executor.Pool.handleRunResult`. This is a deliberate choice, not the default:
+every task the orchestrator reacts to (the story's Builder/root task, the 4
+Evaluators, the Arbitration task) is a **top-level** task
+(`parent_task_id == ""`), and per the task state machine above, the *only*
+way one of them would ever reach `COMPLETED` on its own is via a
+human/chatbot `POST /api/tasks/{id}/accept` (`READY → COMPLETED`, in
+`internal/api`'s `acceptTask`) — `handleRunResult` only ever lands a
+top-level task at `READY` or `BLOCKED`, never `COMPLETED` directly. Rather
+than requiring a human to make that call 6 times per story (builder + 4
+evaluators + arbitration), **the orchestrator auto-accepts these specific
+tasks itself** (`autoAccept`, see below) — so the *only* manual accept
+anywhere in this chain is the final story-level
+`POST /api/stories/{id}/accept`. A `handleRunResult` hook would never observe
+either transition (the human-driven one or this orchestrator's own
+auto-accept) cleanly, since both happen outside `executor`; polling
+sidesteps the question of *how*/*by whom* a task reached `COMPLETED`
+entirely — the same way `Scheduler` doesn't care how a task got to `FAILED`.
+
+Stage-by-stage:
+
+1. **Builder → Evaluators**: once a story's `root_task_id` task is `READY`,
+ the orchestrator auto-accepts it to `COMPLETED` itself (see "Auto-accept"
+ below); once it's `COMPLETED`, spawns 4 new top-level tasks
+ (`Store.CreateTask`, not `SpawnSubtask` — no `parent_task_id`,
+ `depends_on: [root_task_id]`) with `agent.role` =
+ `evaluator_quality`/`evaluator_security`/`evaluator_correctness`/
+ `evaluator_performance`, queues and submits each to the pool, and sets the
+ story's `status` to `VALIDATING`. Idempotency is **structural**, not a
+ marker: it inspects `Store.ListDependents(root_task_id)` for existing
+ tasks whose role already matches one of the four, and only creates the
+ missing ones — safe to call every tick forever, and safe across a process
+ restart (unlike an in-memory guard would be).
+2. **Per-evaluator verdicts**: each Evaluator task is likewise auto-accepted
+ from `READY` to `COMPLETED`. As each is observed `COMPLETED`, emits
+ `event.KindEvalVerdict` — payload `{task_id, role, summary}` — attached to
+ the **story's** ID (not the evaluator task's ID), via
+ `GET /api/stories/{id}/events` (new in this phase, mirrors
+ `GET /api/tasks/{id}/events` but resolves existence via `GetStory`).
+ Attaching to the story ID means one call surfaces every verdict for a
+ story; `events.task_id` has no enforced FK, which is exactly the tolerance
+ 7a's `event.Kind` doc comments anticipated. De-duplication here is an
+ in-memory, per-process "already emitted" set keyed by evaluator task ID
+ (mirrors `Scheduler.handled` exactly) — the only place in this type that
+ isn't structurally idempotent, because there's no persisted marker for
+ "this specific verdict was already emitted"; a restart can produce at most
+ one duplicate `eval_verdict` event per evaluator, never more.
+3. **Evaluators → Arbitration**: once all 4 Evaluators for a story are
+ `COMPLETED`, spawns one more top-level task, `agent.role: "planner"`,
+ `depends_on` = all 4 evaluator task IDs. Idempotency is again structural:
+ looks for an existing `planner`-role dependent of the first evaluator task
+ whose `depends_on` already contains all 4 IDs, rather than trusting
+ `story.status` (a human can freely rewrite it via `PUT /api/stories/{id}`).
+4. **Arbitration → REVIEW_READY**: the Arbitration task is likewise
+ auto-accepted from `READY` to `COMPLETED`. When it reaches `COMPLETED`,
+ emits `event.KindArbitrationDecided` (payload `{task_id, summary}`,
+ attached to the story ID) and sets `status` to `REVIEW_READY`. **Gated on
+ `status == "VALIDATING"`** — the one place this type's idempotency check
+ is the story's own status field rather than a structural "does a
+ downstream task exist" check, because the Arbitration task is the last
+ task in the chain, so there's no further task existence to check against.
+ **Documented simplification:** this does **not** parse the Arbitration
+ task's summary for an approve/reject verdict — it always routes to
+ `REVIEW_READY`. A human or chatbot who reads the summary and disagrees
+ sets `NEEDS_FIX` manually via `PUT /api/stories/{id}`. A later phase could
+ close this gap with a dedicated verdict-reporting tool for the Arbitration
+ task (a new `AgentChannel` method) instead of parsing free text.
+5. **Human accept-gate (the only one)**: `POST /api/stories/{id}/accept`
+ (new in this phase) mirrors `handleAcceptTask`'s pattern: only valid from
+ `REVIEW_READY` (409 otherwise), transitions to `DONE`, emits
+ `event.KindHumanAccepted` (payload `{story_id, from, to}`, attached to the
+ story ID). Because of auto-accept (below), this is the *only*
+ story-status transition — indeed the only task/story state transition at
+ all — in this whole chain that requires a human/chatbot to act.
+
+**Auto-accept** (`StoryOrchestrator.autoAccept`): on every tick, for the
+story's root/Builder task and each structurally-discovered
+Evaluator/Arbitration dependent (i.e. only tasks the orchestrator has already
+established are part of *this* story's pipeline — never a blanket "auto-
+accept every READY task" sweep), if that task is `READY`, the orchestrator
+transitions it straight to `COMPLETED` itself, using the exact same
+state-machine-respecting write `internal/api`'s `acceptTask` uses
+(`Store.UpdateTaskState`, which wraps `storage.DB.UpdateTaskStateBy` —
+validates `task.ValidTransition` and writes the `state_change` event
+atomically, not a raw/unchecked write). This is what makes the story-level
+accept-gate the system's only required human/chatbot touchpoint: without it,
+a human would have to separately `POST /api/tasks/{id}/accept` the Builder,
+each of the 4 Evaluators, and the Arbitration task, since none of those
+top-level tasks can reach `COMPLETED` any other way. `FAILED`/`TIMED_OUT`/
+`CANCELLED`/`BUDGET_EXCEEDED` outcomes for these same tasks are untouched by
+this — they still go through `Scheduler`'s existing retry-then-escalate path
+exactly as before; auto-accept only ever fires on the `READY` (success)
+path.
+
+`evaluator_quality`/`evaluator_security`/`evaluator_correctness`/
+`evaluator_performance`/`planner`/`builder` `role_configs` rows are assumed to
+be seeded separately (this phase doesn't create them); a role-typed task
+spawned here with no matching active `role_configs` row dispatches in the
+same degraded (no role resolution) mode `Pool.execute()` already logs a
+warning and falls back to for any other role-typed task.
+
---
@@ -382,6 +488,29 @@ Same pattern as `task.Priority`/`RetryConfig` below: `internal/role.RoleConfig.T
`Scheduler.handled` (keyed by execution ID) prevents re-emitting a `final: true` `KindEscalated` event on every poll tick once a role-typed task's ladder is exhausted, but it's per-process and resets on restart. A restart can produce one extra "reconsideration" (and, if still exhausted/denied, one more `KindEscalated` event) — not an infinite loop, just not persisted. A future phase could persist this via a `tasks` column if that turns out to matter.
+### StoryOrchestrator's Arbitration outcome always routes to REVIEW_READY
+
+`internal/scheduler.StoryOrchestrator.finalizeArbitration` does not parse the
+Arbitration task's summary for an approve/reject verdict — every completed
+Arbitration moves the story to `REVIEW_READY`, never directly to `NEEDS_FIX`.
+A human or chatbot who reads the Arbitration summary and disagrees must
+manually set the story to `NEEDS_FIX` via `PUT /api/stories/{id}`. A later
+phase could close this by giving the Arbitration task a dedicated
+verdict-reporting tool (a new `AgentChannel` method) instead of parsing free
+text.
+
+### StoryOrchestrator's per-evaluator verdict de-dup is in-memory only
+
+`StoryOrchestrator.handledVerdicts` (keyed by evaluator task ID) prevents
+re-emitting `KindEvalVerdict` on every poll tick while sibling evaluators are
+still running, but — like `Scheduler.handled` above — it's per-process and
+resets on restart. A restart can produce at most one duplicate `eval_verdict`
+event per evaluator; the structural idempotency checks that actually prevent
+duplicate task creation and duplicate story-status transitions
+(`ensureEvaluators`/`ensureArbitration`'s dependents-based checks, and
+`finalizeArbitration`'s `status == "VALIDATING"` gate) are unaffected by a
+restart.
+
### Deprecated task columns not yet dropped (Phase 8 follow-up)
`tasks.question_json`, `summary`, `interactions_json`, `elaboration_input` are
@@ -472,6 +601,8 @@ In `executor.go`, `withFailureHistory` creates a copy of the task struct (`copy
| GET | `/api/stories/{id}` | Get story |
| PUT | `/api/stories/{id}` | Update story (all fields but id/created_at; unvalidated status pass-through) |
| GET | `/api/stories/{id}/task-tree` | Walk the task graph realizing a story (parent_task_id + depends_on edges) |
+| GET | `/api/stories/{id}/events` | Story observability event stream (`?since_seq=N`); surfaces `eval_verdict`/`arbitration_decided`/`human_accepted` events the story orchestrator/accept-gate attach to the story's own ID |
+| POST | `/api/stories/{id}/accept` | Accept a `REVIEW_READY` story → `DONE`; emits `KindHumanAccepted` |
---
diff --git a/internal/api/server.go b/internal/api/server.go
index 9f0eb7c..8bd5b0e 100644
--- a/internal/api/server.go
+++ b/internal/api/server.go
@@ -182,6 +182,8 @@ func (s *Server) routes() {
s.mux.HandleFunc("GET /api/stories/{id}", s.handleGetStory)
s.mux.HandleFunc("PUT /api/stories/{id}", s.handleUpdateStory)
s.mux.HandleFunc("GET /api/stories/{id}/task-tree", s.handleStoryTaskTree)
+ s.mux.HandleFunc("GET /api/stories/{id}/events", s.handleListStoryEvents)
+ s.mux.HandleFunc("POST /api/stories/{id}/accept", s.handleAcceptStory)
s.mux.HandleFunc("POST /api/roles/{role}/versions", s.handleCreateRoleVersion)
s.mux.HandleFunc("GET /api/roles/{role}/versions", s.handleListRoleVersions)
s.mux.HandleFunc("POST /api/roles/{role}/activate", s.handleActivateRoleVersion)
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})
+}
diff --git a/internal/api/stories_test.go b/internal/api/stories_test.go
index b346af5..4cc2f17 100644
--- a/internal/api/stories_test.go
+++ b/internal/api/stories_test.go
@@ -8,6 +8,7 @@ import (
"testing"
"time"
+ "github.com/thepeterstone/claudomator/internal/event"
"github.com/thepeterstone/claudomator/internal/story"
"github.com/thepeterstone/claudomator/internal/task"
)
@@ -276,3 +277,133 @@ func TestServer_StoryTaskTree_UnknownStory_Returns404(t *testing.T) {
t.Fatalf("expected 404, got %d: %s", w.Code, w.Body.String())
}
}
+
+// TestServer_AcceptStory_SucceedsFromReviewReady is verification item (e)
+// from the Phase 7b task description: POST /api/stories/{id}/accept
+// transitions REVIEW_READY -> DONE and emits a KindHumanAccepted event
+// attached to the story's ID.
+func TestServer_AcceptStory_SucceedsFromReviewReady(t *testing.T) {
+ srv, store := testServer(t)
+ if err := store.CreateStory(&story.Story{ID: "s1", Name: "story", Status: "REVIEW_READY"}); err != nil {
+ t.Fatal(err)
+ }
+
+ req := httptest.NewRequest("POST", "/api/stories/s1/accept", nil)
+ w := httptest.NewRecorder()
+ srv.Handler().ServeHTTP(w, req)
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+
+ got, err := store.GetStory("s1")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.Status != "DONE" {
+ t.Errorf("Status: want DONE, got %q", got.Status)
+ }
+
+ evs, err := store.ListEvents("s1", 0)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var found bool
+ for _, e := range evs {
+ if e.Kind == event.KindHumanAccepted {
+ found = true
+ var payload struct {
+ StoryID string `json:"story_id"`
+ From string `json:"from"`
+ To string `json:"to"`
+ }
+ if err := json.Unmarshal(e.Payload, &payload); err != nil {
+ t.Fatalf("unmarshal payload: %v", err)
+ }
+ if payload.StoryID != "s1" || payload.From != "REVIEW_READY" || payload.To != "DONE" {
+ t.Errorf("unexpected payload: %+v", payload)
+ }
+ }
+ }
+ if !found {
+ t.Error("expected a KindHumanAccepted event attached to the story's event stream")
+ }
+}
+
+// TestServer_AcceptStory_FailsFromOtherStatuses is the other half of
+// verification item (e): accept must be rejected (409) from any status other
+// than REVIEW_READY.
+func TestServer_AcceptStory_FailsFromOtherStatuses(t *testing.T) {
+ for _, status := range []string{"DISCOVERY", "VALIDATING", "NEEDS_FIX", "DONE", "IN_PROGRESS"} {
+ t.Run(status, func(t *testing.T) {
+ srv, store := testServer(t)
+ id := "s-" + status
+ if err := store.CreateStory(&story.Story{ID: id, Name: "story", Status: status}); err != nil {
+ t.Fatal(err)
+ }
+
+ req := httptest.NewRequest("POST", "/api/stories/"+id+"/accept", nil)
+ w := httptest.NewRecorder()
+ srv.Handler().ServeHTTP(w, req)
+ if w.Code != http.StatusConflict {
+ t.Fatalf("expected 409, got %d: %s", w.Code, w.Body.String())
+ }
+
+ got, err := store.GetStory(id)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.Status != status {
+ t.Errorf("status must not change on rejected accept: want %q, got %q", status, got.Status)
+ }
+ })
+ }
+}
+
+func TestServer_AcceptStory_NotFound(t *testing.T) {
+ srv, _ := testServer(t)
+ req := httptest.NewRequest("POST", "/api/stories/does-not-exist/accept", nil)
+ w := httptest.NewRecorder()
+ srv.Handler().ServeHTTP(w, req)
+ if w.Code != http.StatusNotFound {
+ t.Fatalf("expected 404, got %d: %s", w.Code, w.Body.String())
+ }
+}
+
+// TestServer_ListStoryEvents_ReturnsEvalVerdictAndArbitrationEvents proves
+// GET /api/stories/{id}/events surfaces events written against the story's
+// own ID (not any task's ID) — the attachment point
+// internal/scheduler.StoryOrchestrator uses for KindEvalVerdict/
+// KindArbitrationDecided.
+func TestServer_ListStoryEvents_ReturnsEvalVerdictAndArbitrationEvents(t *testing.T) {
+ srv, store := testServer(t)
+ if err := store.CreateStory(&story.Story{ID: "s1", Name: "story", Status: "VALIDATING"}); err != nil {
+ t.Fatal(err)
+ }
+ if err := store.CreateEvent(&event.Event{TaskID: "s1", Kind: event.KindEvalVerdict, Actor: event.ActorSystem, Payload: []byte(`{"role":"evaluator_quality"}`)}); err != nil {
+ t.Fatal(err)
+ }
+
+ req := httptest.NewRequest("GET", "/api/stories/s1/events", nil)
+ w := httptest.NewRecorder()
+ srv.Handler().ServeHTTP(w, req)
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+ var got []event.Event
+ if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+ t.Fatalf("decode: %v", err)
+ }
+ if len(got) != 1 || got[0].Kind != event.KindEvalVerdict {
+ t.Fatalf("want 1 eval_verdict event, got %+v", got)
+ }
+}
+
+func TestServer_ListStoryEvents_UnknownStory_Returns404(t *testing.T) {
+ srv, _ := testServer(t)
+ req := httptest.NewRequest("GET", "/api/stories/does-not-exist/events", nil)
+ w := httptest.NewRecorder()
+ srv.Handler().ServeHTTP(w, req)
+ if w.Code != http.StatusNotFound {
+ t.Fatalf("expected 404, got %d: %s", w.Code, w.Body.String())
+ }
+}
diff --git a/internal/cli/serve.go b/internal/cli/serve.go
index 656ee66..7ee8d49 100644
--- a/internal/cli/serve.go
+++ b/internal/cli/serve.go
@@ -265,6 +265,20 @@ func serve(addr, basePath string) error {
}
go sch.Run(ctx, cfg.Scheduler.PollInterval())
+ // Story orchestrator (internal/scheduler.StoryOrchestrator, Phase 7b):
+ // drives stories through Builder -> Evaluators -> Arbitration ->
+ // REVIEW_READY as their root/evaluator/arbitration tasks reach COMPLETED
+ // (always via human/chatbot accept, since these are all top-level
+ // tasks — see that type's doc comment for why this is poll-based rather
+ // than hooked into executor.Pool.handleRunResult). Also `serve`-only,
+ // same reasoning as the scheduler above.
+ storyOrch := &scheduler.StoryOrchestrator{
+ Store: store,
+ Pool: pool,
+ Logger: logger,
+ }
+ go storyOrch.Run(ctx, scheduler.DefaultStoryPollInterval)
+
httpSrv := &http.Server{
Addr: addr,
Handler: srv.Handler(),
diff --git a/internal/scheduler/story_orchestrator.go b/internal/scheduler/story_orchestrator.go
new file mode 100644
index 0000000..6ad0f86
--- /dev/null
+++ b/internal/scheduler/story_orchestrator.go
@@ -0,0 +1,482 @@
+// This file implements Phase 7b's story orchestrator: a deterministic,
+// poll-based watcher that drives a story.Story through
+// Builder -> 4 parallel Evaluators -> Arbitration -> a single human
+// accept-gate at the *story* level, exactly the way Scheduler (above, in
+// scheduler.go) drives a role-typed task through its retry/escalation
+// ladder. It lives in this package rather than internal/story for a
+// structural reason, not just stylistic taste: internal/storage already
+// imports internal/story (storage/story.go), so internal/story cannot
+// import internal/storage back — and this orchestrator's Store interface
+// needs storage.StoryFilter/*task.Task/etc. internal/scheduler already
+// imports both internal/storage and internal/task (and has zero risk of
+// internal/story importing scheduler back), so it's a clean home. It also
+// matches the design note this phase's task description invited: "fold it
+// into internal/scheduler as a sibling to the existing Scheduler".
+//
+// Mechanism choice: poll-based, not a handleRunResult hook. Every task this
+// orchestrator cares about (the story's root Builder task, the 4 Evaluators,
+// the Arbitration task) is a top-level task (ParentTaskID == ""), so per
+// task.go's state machine the *only* way one of them would ever reach
+// COMPLETED on its own is via a human/chatbot POST /api/tasks/{id}/accept
+// (internal/api.acceptTask), READY -> COMPLETED — executor.Pool.handleRunResult
+// never transitions a top-level task to COMPLETED directly (only READY, or
+// BLOCKED if it has subtasks). That's exactly the gap this orchestrator
+// closes itself (see autoAccept below): the whole point of the story-level
+// ceremony is that a human/chatbot should only ever have to make *one*
+// accept decision (the final POST /api/stories/{id}/accept, REVIEW_READY ->
+// DONE) — not six (builder + 4 evaluators + arbitration) along the way. So
+// on every tick, for the specific Builder/Evaluator/Arbitration tasks it
+// already knows are wired into a story's pipeline, this orchestrator
+// auto-accepts (READY -> COMPLETED) them itself, using the same
+// state-machine-respecting write internal/api's acceptTask uses
+// (Store.UpdateTaskState, which wraps storage.DB.UpdateTaskStateBy —
+// validates task.ValidTransition and writes the state_change event
+// atomically, not a raw/unchecked write). This is narrowly scoped: it only
+// ever touches the root task a story actually tracks (st.RootTaskID) and
+// that root's structurally-discovered evaluator/arbitration dependents
+// (found via ensureEvaluators/ensureArbitration's own role-matching) — never
+// a blanket "auto-accept every READY task" sweep. Polling (rather than a
+// handleRunResult hook) is still the right mechanism regardless of who does
+// the accepting: the transition happens via a *write this orchestrator
+// itself performs* on a poll tick, which is inherently poll-driven, not an
+// executor-package callback.
+package scheduler
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "log/slog"
+ "time"
+
+ "github.com/google/uuid"
+ "github.com/thepeterstone/claudomator/internal/event"
+ "github.com/thepeterstone/claudomator/internal/storage"
+ "github.com/thepeterstone/claudomator/internal/story"
+ "github.com/thepeterstone/claudomator/internal/task"
+)
+
+// evaluatorRoles is the fixed fan-out of Evaluator roles spawned once a
+// story's Builder (root_task_id) task completes. Order here is preserved
+// wherever evaluator tasks are collected into a slice (e.g. building the
+// Arbitration task's DependsOn), purely for determinism/testability — the
+// orchestrator does not otherwise care about ordering.
+var evaluatorRoles = []string{
+ "evaluator_quality",
+ "evaluator_security",
+ "evaluator_correctness",
+ "evaluator_performance",
+}
+
+// arbitrationRole is the role assigned to the single task spawned once all
+// Evaluators for a story complete. It depends on all 4 Evaluator tasks and,
+// per this phase's documented simplification (see finalizeArbitration),
+// always routes the story to REVIEW_READY on completion rather than parsing
+// its summary for an approve/reject verdict.
+const arbitrationRole = "planner"
+
+// StoryStore is the subset of storage.DB methods StoryOrchestrator needs.
+// Defining it as an interface (mirroring executor.Store/scheduler.Store)
+// allows tests to supply an in-memory fake with no real SQLite database.
+type StoryStore interface {
+ ListStories(filter storage.StoryFilter) ([]*story.Story, error)
+ UpdateStory(st *story.Story) error
+ GetTask(id string) (*task.Task, error)
+ ListDependents(taskID string) ([]*task.Task, error)
+ CreateTask(t *task.Task) error
+ UpdateTaskState(id string, newState task.State) error
+ CreateEvent(e *event.Event) error
+}
+
+// StoryOrchestrator polls stories with a root_task_id set and drives them
+// through the Builder -> Evaluators -> Arbitration -> REVIEW_READY ceremony,
+// auto-accepting (READY -> COMPLETED) the Builder/Evaluator/Arbitration tasks
+// along the way (see autoAccept) so that a human/chatbot never has to touch
+// POST /api/tasks/{id}/accept for any of them. The final REVIEW_READY -> DONE
+// transition is the *only* remaining human/chatbot action (see internal/api's
+// POST /api/stories/{id}/accept), not something this type does itself.
+type StoryOrchestrator struct {
+ Store StoryStore
+ // Pool reuses the same minimal interface Scheduler depends on
+ // (Submit(ctx, *task.Task) error) — satisfied directly by
+ // *executor.Pool, declared once in scheduler.go.
+ Pool Pool
+ Logger *slog.Logger
+
+ // handledVerdicts dedupes per-evaluator KindEvalVerdict emission within a
+ // single running process, keyed by evaluator task ID. Without it, an
+ // evaluator that completes while its siblings are still running would
+ // get a fresh eval_verdict event on every poll tick until the last
+ // sibling finishes. This mirrors Scheduler.handled exactly: an in-memory,
+ // per-process guard that resets on restart. That's an accepted
+ // simplification here for the same reason it is for Scheduler — this is
+ // idempotent bookkeeping on an append-only observability stream, not
+ // orchestration state; a restart can produce at most one duplicate
+ // eval_verdict event per evaluator, never an infinite loop, because the
+ // *structural* idempotency checks (ensureEvaluators/ensureArbitration
+ // below, and the story.Status=="VALIDATING" gate in
+ // finalizeArbitration) are what actually prevent duplicate task
+ // creation and duplicate story-status transitions — the two things that
+ // would matter if repeated forever.
+ handledVerdicts map[string]bool
+}
+
+// DefaultStoryPollInterval is used by Run when pollInterval <= 0.
+const DefaultStoryPollInterval = 15 * time.Second
+
+// Run polls all stories with a root_task_id set every pollInterval until ctx
+// is cancelled.
+func (o *StoryOrchestrator) Run(ctx context.Context, pollInterval time.Duration) {
+ if pollInterval <= 0 {
+ pollInterval = DefaultStoryPollInterval
+ }
+ ticker := time.NewTicker(pollInterval)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-ctx.Done():
+ return
+ case <-ticker.C:
+ o.Tick(ctx)
+ }
+ }
+}
+
+// Tick runs a single poll pass over every story. Exported so tests can drive
+// it directly without waiting on a ticker.
+func (o *StoryOrchestrator) Tick(ctx context.Context) {
+ stories, err := o.Store.ListStories(storage.StoryFilter{})
+ if err != nil {
+ o.logf("story orchestrator: list stories", "error", err)
+ return
+ }
+ for _, st := range stories {
+ if st.RootTaskID == "" {
+ continue // no execution tree yet — nothing for this orchestrator to do
+ }
+ if st.Status == "DONE" || st.Status == "CANCELLED" {
+ continue // terminal; this orchestrator never revives a story from here
+ }
+ o.processStory(ctx, st)
+ }
+}
+
+func (o *StoryOrchestrator) logf(msg string, args ...any) {
+ if o.Logger != nil {
+ o.Logger.Warn(msg, args...)
+ }
+}
+
+// processStory advances a single story by at most one stage per tick (it
+// returns as soon as it finds a stage that isn't ready to progress yet — the
+// next tick picks up where this one left off).
+func (o *StoryOrchestrator) processStory(ctx context.Context, st *story.Story) {
+ root, err := o.Store.GetTask(st.RootTaskID)
+ if err != nil {
+ o.logf("story orchestrator: get root task", "storyID", st.ID, "rootTaskID", st.RootTaskID, "error", err)
+ return
+ }
+ root = o.autoAccept(st, root)
+ if root.State != task.StateCompleted {
+ return // Builder hasn't reached COMPLETED yet (still running, or not yet READY to auto-accept)
+ }
+
+ // Stage 1: Builder -> Evaluators (+ story -> VALIDATING).
+ evaluators, ok := o.ensureEvaluators(ctx, st, root)
+ if !ok {
+ return // not all 4 could be found/created yet; retry next tick
+ }
+
+ // Auto-accept each evaluator that's reached READY, emit per-evaluator
+ // verdicts, and check whether all 4 are done.
+ allDone := true
+ for i, ev := range evaluators {
+ ev = o.autoAccept(st, ev)
+ evaluators[i] = ev
+ o.maybeEmitVerdict(st, ev)
+ if ev.State != task.StateCompleted {
+ allDone = false
+ }
+ }
+ if !allDone {
+ return
+ }
+
+ // Stage 2: Evaluators -> Arbitration.
+ arbitration, ok := o.ensureArbitration(ctx, st, evaluators)
+ if !ok {
+ return
+ }
+ arbitration = o.autoAccept(st, arbitration)
+
+ // Stage 3: Arbitration -> REVIEW_READY.
+ if arbitration.State == task.StateCompleted {
+ o.finalizeArbitration(st, arbitration)
+ }
+}
+
+// autoAccept transitions t from READY to COMPLETED if that's its current
+// state, using the same state-machine-respecting write internal/api's
+// acceptTask uses (Store.UpdateTaskState wraps storage.DB.UpdateTaskStateBy,
+// which validates task.ValidTransition and writes the state_change event
+// atomically — not a raw/unchecked write). Returns t unchanged if it wasn't
+// READY (including if it's already COMPLETED, or still RUNNING/BLOCKED/etc.)
+// or if the update failed.
+//
+// This is the mechanism that makes the story-level accept-gate
+// (POST /api/stories/{id}/accept) the *only* human/chatbot interaction
+// required to drive a story from a completed Builder run all the way to
+// REVIEW_READY: without it, a human would have to separately call
+// POST /api/tasks/{id}/accept on the Builder task, each of the 4 Evaluator
+// tasks, and the Arbitration task, since none of those top-level tasks can
+// reach COMPLETED any other way (see this file's package doc comment).
+// Callers only ever pass tasks they've already established are part of a
+// specific story's pipeline — the root task a story tracks via
+// st.RootTaskID, or a role-matched dependent discovered by
+// ensureEvaluators/ensureArbitration — so this never touches an unrelated
+// READY task sitting outside any story's pipeline.
+func (o *StoryOrchestrator) autoAccept(st *story.Story, t *task.Task) *task.Task {
+ if t.State != task.StateReady {
+ return t
+ }
+ if err := o.Store.UpdateTaskState(t.ID, task.StateCompleted); err != nil {
+ o.logf("story orchestrator: auto-accept", "storyID", st.ID, "taskID", t.ID, "error", err)
+ return t
+ }
+ accepted := *t
+ accepted.State = task.StateCompleted
+ return &accepted
+}
+
+// ensureEvaluators returns the 4 Evaluator tasks fanned out from root,
+// spawning any missing ones. Idempotency is structural, not a marker on the
+// story: it looks at root's actual dependents and checks which of
+// evaluatorRoles are already represented, so calling this repeatedly for the
+// same story never spawns duplicates (test (b) in the phase description) —
+// even across a process restart, unlike a purely in-memory guard would be.
+// Returns ok=false if any missing evaluator couldn't be created this tick
+// (transient store error); the caller retries on the next tick.
+func (o *StoryOrchestrator) ensureEvaluators(ctx context.Context, st *story.Story, root *task.Task) ([]*task.Task, bool) {
+ dependents, err := o.Store.ListDependents(root.ID)
+ if err != nil {
+ o.logf("story orchestrator: list root dependents", "storyID", st.ID, "error", err)
+ return nil, false
+ }
+ found := make(map[string]*task.Task, len(evaluatorRoles))
+ for _, d := range dependents {
+ for _, r := range evaluatorRoles {
+ if d.Agent.Role == r {
+ found[r] = d
+ }
+ }
+ }
+
+ spawnedAny := false
+ for _, r := range evaluatorRoles {
+ if _, ok := found[r]; ok {
+ continue
+ }
+ nt, err := o.spawnRoleTask(ctx, fmt.Sprintf("%s: %s", r, st.Name), r, []string{root.ID}, root,
+ fmt.Sprintf("Evaluate the changes made by task %s against the %q dimension for story %q.\n\nStory spec:\n%s", root.ID, r, st.Name, st.Spec))
+ if err != nil {
+ o.logf("story orchestrator: spawn evaluator", "storyID", st.ID, "role", r, "error", err)
+ continue
+ }
+ found[r] = nt
+ spawnedAny = true
+ }
+
+ if spawnedAny {
+ st.Status = "VALIDATING"
+ if err := o.Store.UpdateStory(st); err != nil {
+ o.logf("story orchestrator: update story to VALIDATING", "storyID", st.ID, "error", err)
+ }
+ }
+
+ if len(found) != len(evaluatorRoles) {
+ return nil, false
+ }
+ ordered := make([]*task.Task, len(evaluatorRoles))
+ for i, r := range evaluatorRoles {
+ ordered[i] = found[r]
+ }
+ return ordered, true
+}
+
+// ensureArbitration returns the single Arbitration task depending on all 4
+// evaluators, spawning it if it doesn't exist yet. Idempotency is again
+// structural: it looks for an existing "planner"-role dependent of the first
+// evaluator task that depends on every evaluator ID, rather than relying on
+// story.Status (which a human can freely rewrite via PUT /api/stories/{id}).
+func (o *StoryOrchestrator) ensureArbitration(ctx context.Context, st *story.Story, evaluators []*task.Task) (*task.Task, bool) {
+ ids := make([]string, len(evaluators))
+ for i, ev := range evaluators {
+ ids[i] = ev.ID
+ }
+
+ dependents, err := o.Store.ListDependents(evaluators[0].ID)
+ if err != nil {
+ o.logf("story orchestrator: list evaluator dependents", "storyID", st.ID, "error", err)
+ return nil, false
+ }
+ for _, d := range dependents {
+ if d.Agent.Role == arbitrationRole && dependsOnAll(d, ids) {
+ return d, true
+ }
+ }
+
+ instructions := fmt.Sprintf(
+ "Arbitrate the 4 evaluator verdicts for story %q (task %s). Read each evaluator task's summary/events "+
+ "and decide whether the story is ready to ship. Acceptance criteria:\n%s",
+ st.Name, st.ID, formatAcceptanceCriteria(st.AcceptanceCriteria))
+ nt, err := o.spawnRoleTask(ctx, "Arbitration: "+st.Name, arbitrationRole, ids, evaluators[0], instructions)
+ if err != nil {
+ o.logf("story orchestrator: spawn arbitration", "storyID", st.ID, "error", err)
+ return nil, false
+ }
+ return nt, true
+}
+
+// finalizeArbitration handles the Arbitration task reaching COMPLETED: it
+// emits KindArbitrationDecided and moves the story to REVIEW_READY.
+//
+// Documented simplification (Phase 7b, see CLAUDE.md Design Debt): this does
+// NOT parse the arbitration task's summary for an approve/reject verdict —
+// it always routes to REVIEW_READY. A human or chatbot who reads the
+// arbitration summary and disagrees can manually set the story to NEEDS_FIX
+// via the existing PUT /api/stories/{id}. A later phase could close this gap
+// by giving the arbitration task a dedicated verdict-reporting tool (e.g. a
+// new AgentChannel method) whose structured output this orchestrator could
+// trust instead of free-text parsing.
+//
+// Gated on st.Status == "VALIDATING" so repeated ticks (or a story a human
+// already advanced past REVIEW_READY) don't re-emit the event or re-write the
+// status — this is the one place in the orchestrator where the story's own
+// status field, not a structural dependents check, is the idempotency guard,
+// because by this stage there's nothing further to check structurally: the
+// Arbitration task is the last task in the chain, so "does a subsequent task
+// exist" isn't an available signal.
+func (o *StoryOrchestrator) finalizeArbitration(st *story.Story, arbitration *task.Task) {
+ if st.Status != "VALIDATING" {
+ return
+ }
+
+ payload, _ := json.Marshal(struct {
+ TaskID string `json:"task_id"`
+ Summary string `json:"summary"`
+ }{TaskID: arbitration.ID, Summary: arbitration.Summary})
+ if err := o.Store.CreateEvent(&event.Event{
+ TaskID: st.ID,
+ Kind: event.KindArbitrationDecided,
+ Actor: event.ActorSystem,
+ Payload: payload,
+ }); err != nil {
+ o.logf("story orchestrator: emit arbitration_decided", "storyID", st.ID, "error", err)
+ }
+
+ st.Status = "REVIEW_READY"
+ if err := o.Store.UpdateStory(st); err != nil {
+ o.logf("story orchestrator: update story to REVIEW_READY", "storyID", st.ID, "error", err)
+ }
+}
+
+// maybeEmitVerdict records a KindEvalVerdict event, attached to the story's
+// ID (not the evaluator task's ID), the first time a given evaluator task is
+// observed COMPLETED. Attaching to the story ID — the same choice
+// finalizeArbitration makes for KindArbitrationDecided — means a single
+// GET /api/stories/{id}/events call surfaces every verdict for a story,
+// rather than requiring a client to separately fetch each evaluator task's
+// own event stream and reassemble them; events.task_id has no enforced FK
+// (see internal/event's doc comment), so this is exactly the tolerance the
+// 7a phase already built in anticipation of this use.
+func (o *StoryOrchestrator) maybeEmitVerdict(st *story.Story, ev *task.Task) {
+ if ev.State != task.StateCompleted {
+ return
+ }
+ if o.handledVerdicts == nil {
+ o.handledVerdicts = make(map[string]bool)
+ }
+ if o.handledVerdicts[ev.ID] {
+ return
+ }
+ o.handledVerdicts[ev.ID] = true
+
+ payload, _ := json.Marshal(struct {
+ TaskID string `json:"task_id"`
+ Role string `json:"role"`
+ Summary string `json:"summary"`
+ }{TaskID: ev.ID, Role: ev.Agent.Role, Summary: ev.Summary})
+ if err := o.Store.CreateEvent(&event.Event{
+ TaskID: st.ID,
+ Kind: event.KindEvalVerdict,
+ Actor: event.ActorSystem,
+ Payload: payload,
+ }); err != nil {
+ o.logf("story orchestrator: emit eval_verdict", "storyID", st.ID, "taskID", ev.ID, "error", err)
+ }
+}
+
+// spawnRoleTask creates a new role-typed, top-level task (no ParentTaskID —
+// these are DAG siblings via DependsOn, not delegated subtasks; see
+// internal/executor.Pool.cascadeFail's doc comment for why that distinction
+// matters) and submits it to the pool. Agent.Type/Model are left empty so
+// Phase 5's role-based dispatch resolves them from the role's escalation
+// ladder on first dispatch (internal/executor.Pool.execute()); if no active
+// role_configs row exists for the role, that same code path logs a warning
+// and dispatches without role resolution — an accepted degraded mode we
+// don't special-case here either.
+func (o *StoryOrchestrator) spawnRoleTask(ctx context.Context, name, roleName string, dependsOn []string, template *task.Task, instructions string) (*task.Task, error) {
+ nt := &task.Task{
+ ID: uuid.NewString(),
+ Name: name,
+ Project: template.Project,
+ RepositoryURL: template.RepositoryURL,
+ Agent: task.AgentConfig{
+ Role: roleName,
+ Instructions: instructions,
+ },
+ Priority: task.PriorityNormal,
+ Tags: []string{"story-orchestrator"},
+ DependsOn: dependsOn,
+ Retry: task.RetryConfig{MaxAttempts: 1, Backoff: "exponential"},
+ State: task.StatePending,
+ }
+ if err := o.Store.CreateTask(nt); err != nil {
+ return nil, err
+ }
+ if err := o.Store.UpdateTaskState(nt.ID, task.StateQueued); err != nil {
+ return nil, err
+ }
+ nt.State = task.StateQueued
+ if err := o.Pool.Submit(ctx, nt); err != nil {
+ return nil, err
+ }
+ return nt, nil
+}
+
+// dependsOnAll reports whether t.DependsOn contains every ID in ids.
+func dependsOnAll(t *task.Task, ids []string) bool {
+ have := make(map[string]bool, len(t.DependsOn))
+ for _, d := range t.DependsOn {
+ have[d] = true
+ }
+ for _, id := range ids {
+ if !have[id] {
+ return false
+ }
+ }
+ return true
+}
+
+// formatAcceptanceCriteria renders a story's acceptance criteria as a
+// markdown bullet list, or a placeholder line if there are none.
+func formatAcceptanceCriteria(criteria []string) string {
+ if len(criteria) == 0 {
+ return "(none specified)"
+ }
+ out := ""
+ for _, c := range criteria {
+ out += "- " + c + "\n"
+ }
+ return out
+}
diff --git a/internal/scheduler/story_orchestrator_test.go b/internal/scheduler/story_orchestrator_test.go
new file mode 100644
index 0000000..bee326d
--- /dev/null
+++ b/internal/scheduler/story_orchestrator_test.go
@@ -0,0 +1,769 @@
+package scheduler
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "sync"
+ "testing"
+
+ "github.com/google/uuid"
+ "github.com/thepeterstone/claudomator/internal/event"
+ "github.com/thepeterstone/claudomator/internal/storage"
+ "github.com/thepeterstone/claudomator/internal/story"
+ "github.com/thepeterstone/claudomator/internal/task"
+)
+
+// fakeStoryStore is a minimal, in-memory implementation of StoryStore for
+// unit-testing StoryOrchestrator without a real SQLite database. Mirrors the
+// fakeStore pattern already used by scheduler_test.go for the Phase 5
+// Scheduler.
+type fakeStoryStore struct {
+ mu sync.Mutex
+ stories map[string]*story.Story
+ tasks map[string]*task.Task
+ events []*event.Event
+}
+
+func newFakeStoryStore() *fakeStoryStore {
+ return &fakeStoryStore{
+ stories: make(map[string]*story.Story),
+ tasks: make(map[string]*task.Task),
+ }
+}
+
+func (f *fakeStoryStore) ListStories(_ storage.StoryFilter) ([]*story.Story, error) {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ var out []*story.Story
+ for _, s := range f.stories {
+ cp := *s
+ out = append(out, &cp)
+ }
+ return out, nil
+}
+
+func (f *fakeStoryStore) UpdateStory(st *story.Story) error {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ if _, ok := f.stories[st.ID]; !ok {
+ return fmt.Errorf("story %q not found", st.ID)
+ }
+ cp := *st
+ f.stories[st.ID] = &cp
+ return nil
+}
+
+func (f *fakeStoryStore) GetTask(id string) (*task.Task, error) {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ t, ok := f.tasks[id]
+ if !ok {
+ return nil, fmt.Errorf("task %q not found", id)
+ }
+ cp := *t
+ return &cp, nil
+}
+
+func (f *fakeStoryStore) ListDependents(taskID string) ([]*task.Task, error) {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ var out []*task.Task
+ for _, t := range f.tasks {
+ for _, d := range t.DependsOn {
+ if d == taskID {
+ cp := *t
+ out = append(out, &cp)
+ break
+ }
+ }
+ }
+ return out, nil
+}
+
+func (f *fakeStoryStore) CreateTask(t *task.Task) error {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ if _, ok := f.tasks[t.ID]; ok {
+ return fmt.Errorf("task %q already exists", t.ID)
+ }
+ cp := *t
+ f.tasks[t.ID] = &cp
+ return nil
+}
+
+func (f *fakeStoryStore) UpdateTaskState(id string, newState task.State) error {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ t, ok := f.tasks[id]
+ if !ok {
+ return fmt.Errorf("task %q not found", id)
+ }
+ t.State = newState
+ return nil
+}
+
+func (f *fakeStoryStore) CreateEvent(e *event.Event) error {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ e.ID = uuid.NewString()
+ f.events = append(f.events, e)
+ return nil
+}
+
+func (f *fakeStoryStore) setTaskState(id string, s task.State) {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ if t, ok := f.tasks[id]; ok {
+ t.State = s
+ }
+}
+
+func (f *fakeStoryStore) setTaskSummary(id, summary string) {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ if t, ok := f.tasks[id]; ok {
+ t.Summary = summary
+ }
+}
+
+func (f *fakeStoryStore) eventsOfKind(k event.Kind) []*event.Event {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ var out []*event.Event
+ for _, e := range f.events {
+ if e.Kind == k {
+ out = append(out, e)
+ }
+ }
+ return out
+}
+
+func (f *fakeStoryStore) dependentsWithRole(taskID, role string) []*task.Task {
+ deps, _ := f.ListDependents(taskID)
+ var out []*task.Task
+ for _, d := range deps {
+ if d.Agent.Role == role {
+ out = append(out, d)
+ }
+ }
+ return out
+}
+
+func builderTask(id string, state task.State) *task.Task {
+ return &task.Task{
+ ID: id,
+ Name: "Builder",
+ Agent: task.AgentConfig{Type: "claude", Role: "builder", Instructions: "build it"},
+ RepositoryURL: "git@example.com:org/repo.git",
+ State: state,
+ }
+}
+
+func newStoryWithRoot(id, rootTaskID, status string) *story.Story {
+ return &story.Story{ID: id, Name: "Test Story", Status: status, RootTaskID: rootTaskID}
+}
+
+// TestStoryOrchestrator_SpawnsEvaluators_WhenBuilderCompletes is verification
+// item (a): a builder task reaching COMPLETED for a story spawns exactly 4
+// evaluator tasks with correct roles/depends_on, moves the story to
+// VALIDATING.
+func TestStoryOrchestrator_SpawnsEvaluators_WhenBuilderCompletes(t *testing.T) {
+ store := newFakeStoryStore()
+ root := builderTask("builder-1", task.StateCompleted)
+ store.tasks[root.ID] = root
+ st := newStoryWithRoot("story-1", root.ID, "IN_PROGRESS")
+ store.stories[st.ID] = st
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+
+ deps, err := store.ListDependents(root.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(deps) != 4 {
+ t.Fatalf("expected 4 evaluator tasks, got %d: %+v", len(deps), deps)
+ }
+ gotRoles := map[string]bool{}
+ for _, d := range deps {
+ gotRoles[d.Agent.Role] = true
+ if len(d.DependsOn) != 1 || d.DependsOn[0] != root.ID {
+ t.Errorf("evaluator %s: DependsOn = %+v, want [%s]", d.ID, d.DependsOn, root.ID)
+ }
+ if d.ParentTaskID != "" {
+ t.Errorf("evaluator %s: ParentTaskID = %q, want empty (DAG sibling, not subtask)", d.ID, d.ParentTaskID)
+ }
+ if d.State != task.StateQueued {
+ t.Errorf("evaluator %s: State = %v, want QUEUED", d.ID, d.State)
+ }
+ }
+ for _, r := range evaluatorRoles {
+ if !gotRoles[r] {
+ t.Errorf("missing evaluator with role %q", r)
+ }
+ }
+ if pool.submitCount() != 4 {
+ t.Fatalf("expected 4 pool submissions, got %d", pool.submitCount())
+ }
+
+ got, err := func() (*story.Story, error) {
+ stories, err := store.ListStories(storage.StoryFilter{})
+ if err != nil {
+ return nil, err
+ }
+ for _, s := range stories {
+ if s.ID == st.ID {
+ return s, nil
+ }
+ }
+ return nil, fmt.Errorf("not found")
+ }()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.Status != "VALIDATING" {
+ t.Errorf("story status: want VALIDATING, got %q", got.Status)
+ }
+}
+
+// TestStoryOrchestrator_DoesNotDuplicateEvaluators is verification item (b):
+// re-checking the same story after evaluators already exist does not spawn
+// duplicates.
+func TestStoryOrchestrator_DoesNotDuplicateEvaluators(t *testing.T) {
+ store := newFakeStoryStore()
+ root := builderTask("builder-1", task.StateCompleted)
+ store.tasks[root.ID] = root
+ st := newStoryWithRoot("story-1", root.ID, "IN_PROGRESS")
+ store.stories[st.ID] = st
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+ orch.Tick(context.Background())
+ orch.Tick(context.Background())
+
+ deps, _ := store.ListDependents(root.ID)
+ if len(deps) != 4 {
+ t.Fatalf("expected exactly 4 evaluator tasks after 3 ticks, got %d", len(deps))
+ }
+ if pool.submitCount() != 4 {
+ t.Fatalf("expected exactly 4 submissions after 3 ticks, got %d", pool.submitCount())
+ }
+}
+
+// evaluatorTask builds a completed (or not) evaluator task depending on
+// rootID with the given role.
+func evaluatorTask(id, rootID, role string, state task.State) *task.Task {
+ return &task.Task{
+ ID: id,
+ Name: role,
+ Agent: task.AgentConfig{Role: role},
+ DependsOn: []string{rootID},
+ State: state,
+ Summary: "looks good",
+ }
+}
+
+// seedStoryWithEvaluators wires up a story whose builder is COMPLETED and
+// whose 4 evaluators already exist (in the given state), returning the
+// fakeStoryStore, story, and evaluator tasks (in evaluatorRoles order).
+func seedStoryWithEvaluators(t *testing.T, evalState task.State) (*fakeStoryStore, *story.Story, []*task.Task) {
+ t.Helper()
+ store := newFakeStoryStore()
+ root := builderTask("builder-1", task.StateCompleted)
+ store.tasks[root.ID] = root
+ st := newStoryWithRoot("story-1", root.ID, "VALIDATING")
+ store.stories[st.ID] = st
+
+ evaluators := make([]*task.Task, len(evaluatorRoles))
+ for i, r := range evaluatorRoles {
+ ev := evaluatorTask(fmt.Sprintf("eval-%d", i), root.ID, r, evalState)
+ store.tasks[ev.ID] = ev
+ evaluators[i] = ev
+ }
+ return store, st, evaluators
+}
+
+// TestStoryOrchestrator_SpawnsArbitration_WhenAllEvaluatorsComplete is
+// verification item (c): all 4 evaluators reaching COMPLETED spawns exactly
+// 1 arbitration task depending on all 4.
+func TestStoryOrchestrator_SpawnsArbitration_WhenAllEvaluatorsComplete(t *testing.T) {
+ store, _, evaluators := seedStoryWithEvaluators(t, task.StateCompleted)
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+
+ arbitrations := store.dependentsWithRole(evaluators[0].ID, "planner")
+ if len(arbitrations) != 1 {
+ t.Fatalf("expected exactly 1 arbitration task, got %d: %+v", len(arbitrations), arbitrations)
+ }
+ arb := arbitrations[0]
+ if len(arb.DependsOn) != len(evaluators) {
+ t.Fatalf("arbitration DependsOn = %+v, want all %d evaluator IDs", arb.DependsOn, len(evaluators))
+ }
+ for _, ev := range evaluators {
+ if !dependsOnAll(arb, []string{ev.ID}) {
+ t.Errorf("arbitration does not depend on evaluator %s", ev.ID)
+ }
+ }
+ if arb.ParentTaskID != "" {
+ t.Errorf("arbitration ParentTaskID = %q, want empty", arb.ParentTaskID)
+ }
+ if arb.State != task.StateQueued {
+ t.Errorf("arbitration State = %v, want QUEUED", arb.State)
+ }
+
+ // Re-ticking must not spawn a second arbitration task.
+ orch.Tick(context.Background())
+ orch.Tick(context.Background())
+ arbitrations = store.dependentsWithRole(evaluators[0].ID, "planner")
+ if len(arbitrations) != 1 {
+ t.Fatalf("expected exactly 1 arbitration task after repeated ticks, got %d", len(arbitrations))
+ }
+}
+
+// TestStoryOrchestrator_DoesNotSpawnArbitration_UntilAllEvaluatorsComplete
+// proves the fan-in gate: even with 3 of 4 evaluators COMPLETED, no
+// arbitration task is created yet.
+func TestStoryOrchestrator_DoesNotSpawnArbitration_UntilAllEvaluatorsComplete(t *testing.T) {
+ store, _, evaluators := seedStoryWithEvaluators(t, task.StateCompleted)
+ // Knock one evaluator back to RUNNING.
+ store.setTaskState(evaluators[0].ID, task.StateRunning)
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+
+ arbitrations := store.dependentsWithRole(evaluators[0].ID, "planner")
+ if len(arbitrations) != 0 {
+ t.Fatalf("expected no arbitration task while an evaluator is incomplete, got %d", len(arbitrations))
+ }
+}
+
+// TestStoryOrchestrator_EmitsEvalVerdict_OncePerEvaluator proves
+// maybeEmitVerdict fires exactly once per completed evaluator, attached to
+// the story's ID, even across repeated ticks.
+func TestStoryOrchestrator_EmitsEvalVerdict_OncePerEvaluator(t *testing.T) {
+ store, st, evaluators := seedStoryWithEvaluators(t, task.StateCompleted)
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+ orch.Tick(context.Background())
+ orch.Tick(context.Background())
+
+ verdicts := store.eventsOfKind(event.KindEvalVerdict)
+ if len(verdicts) != len(evaluators) {
+ t.Fatalf("expected exactly %d eval_verdict events, got %d", len(evaluators), len(verdicts))
+ }
+ seenTaskIDs := map[string]bool{}
+ for _, e := range verdicts {
+ if e.TaskID != st.ID {
+ t.Errorf("eval_verdict event attached to %q, want story ID %q", e.TaskID, st.ID)
+ }
+ var payload struct {
+ TaskID string `json:"task_id"`
+ Role string `json:"role"`
+ Summary string `json:"summary"`
+ }
+ if err := json.Unmarshal(e.Payload, &payload); err != nil {
+ t.Fatalf("unmarshal payload: %v", err)
+ }
+ seenTaskIDs[payload.TaskID] = true
+ if payload.Role == "" {
+ t.Errorf("payload missing role: %+v", payload)
+ }
+ if payload.Summary != "looks good" {
+ t.Errorf("payload summary = %q, want %q", payload.Summary, "looks good")
+ }
+ }
+ for _, ev := range evaluators {
+ if !seenTaskIDs[ev.ID] {
+ t.Errorf("no eval_verdict event found for evaluator %s", ev.ID)
+ }
+ }
+}
+
+// TestStoryOrchestrator_ArbitrationCompletes_EmitsDecisionAndReviewReady is
+// verification item (d): arbitration reaching COMPLETED emits
+// KindArbitrationDecided and moves the story to REVIEW_READY.
+func TestStoryOrchestrator_ArbitrationCompletes_EmitsDecisionAndReviewReady(t *testing.T) {
+ store, st, evaluators := seedStoryWithEvaluators(t, task.StateCompleted)
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ // Tick 1: spawns the arbitration task.
+ orch.Tick(context.Background())
+
+ arbitrations := store.dependentsWithRole(evaluators[0].ID, "planner")
+ if len(arbitrations) != 1 {
+ t.Fatalf("expected 1 arbitration task, got %d", len(arbitrations))
+ }
+ arb := arbitrations[0]
+ store.setTaskState(arb.ID, task.StateCompleted)
+ store.setTaskSummary(arb.ID, "ship it")
+
+ // Tick 2: arbitration is now COMPLETED.
+ orch.Tick(context.Background())
+
+ decided := store.eventsOfKind(event.KindArbitrationDecided)
+ if len(decided) != 1 {
+ t.Fatalf("expected exactly 1 arbitration_decided event, got %d", len(decided))
+ }
+ if decided[0].TaskID != st.ID {
+ t.Errorf("arbitration_decided attached to %q, want story ID %q", decided[0].TaskID, st.ID)
+ }
+ var payload struct {
+ TaskID string `json:"task_id"`
+ Summary string `json:"summary"`
+ }
+ if err := json.Unmarshal(decided[0].Payload, &payload); err != nil {
+ t.Fatalf("unmarshal payload: %v", err)
+ }
+ if payload.TaskID != arb.ID || payload.Summary != "ship it" {
+ t.Errorf("unexpected payload: %+v", payload)
+ }
+
+ stories, _ := store.ListStories(storage.StoryFilter{})
+ var got *story.Story
+ for _, s := range stories {
+ if s.ID == st.ID {
+ got = s
+ }
+ }
+ if got == nil {
+ t.Fatal("story not found")
+ }
+ if got.Status != "REVIEW_READY" {
+ t.Errorf("story status: want REVIEW_READY, got %q", got.Status)
+ }
+
+ // Tick 3+: must not re-emit or re-decide.
+ orch.Tick(context.Background())
+ orch.Tick(context.Background())
+ decided = store.eventsOfKind(event.KindArbitrationDecided)
+ if len(decided) != 1 {
+ t.Fatalf("expected still exactly 1 arbitration_decided event after repeated ticks, got %d", len(decided))
+ }
+}
+
+// TestStoryOrchestrator_DoesNothing_WhenBuilderNotComplete proves the
+// orchestrator is inert for a story whose builder task hasn't reached
+// COMPLETED yet and isn't auto-acceptable either (still RUNNING — not
+// READY, so autoAccept has nothing to do).
+func TestStoryOrchestrator_DoesNothing_WhenBuilderNotComplete(t *testing.T) {
+ store := newFakeStoryStore()
+ root := builderTask("builder-1", task.StateRunning)
+ store.tasks[root.ID] = root
+ st := newStoryWithRoot("story-1", root.ID, "IN_PROGRESS")
+ store.stories[st.ID] = st
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+
+ deps, _ := store.ListDependents(root.ID)
+ if len(deps) != 0 {
+ t.Fatalf("expected no evaluator tasks while builder is RUNNING, got %d", len(deps))
+ }
+ if pool.submitCount() != 0 {
+ t.Fatalf("expected no submissions, got %d", pool.submitCount())
+ }
+ got, err := store.GetTask(root.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.State != task.StateRunning {
+ t.Errorf("builder state must be untouched: want RUNNING, got %v", got.State)
+ }
+}
+
+// TestStoryOrchestrator_AutoAcceptsReadyBuilder is the core regression test
+// for the auto-accept fix: a builder task sitting at READY (execution
+// succeeded, awaiting what would otherwise be a manual
+// POST /api/tasks/{id}/accept) is transitioned to COMPLETED by the
+// orchestrator itself — with no external accept call — and, because that
+// unblocks Stage 1 in the same tick, the 4 evaluators are spawned
+// immediately too.
+func TestStoryOrchestrator_AutoAcceptsReadyBuilder(t *testing.T) {
+ store := newFakeStoryStore()
+ root := builderTask("builder-1", task.StateReady)
+ store.tasks[root.ID] = root
+ st := newStoryWithRoot("story-1", root.ID, "IN_PROGRESS")
+ store.stories[st.ID] = st
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+
+ got, err := store.GetTask(root.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.State != task.StateCompleted {
+ t.Fatalf("builder should be auto-accepted to COMPLETED, got %v", got.State)
+ }
+
+ deps, _ := store.ListDependents(root.ID)
+ if len(deps) != 4 {
+ t.Fatalf("expected 4 evaluator tasks spawned in the same tick the builder auto-accepts, got %d", len(deps))
+ }
+}
+
+// TestStoryOrchestrator_AutoAcceptsReadyEvaluators proves READY evaluator
+// tasks are auto-accepted to COMPLETED by the orchestrator, with no external
+// accept call, and that doing so unblocks arbitration spawning.
+func TestStoryOrchestrator_AutoAcceptsReadyEvaluators(t *testing.T) {
+ store, _, evaluators := seedStoryWithEvaluators(t, task.StateReady)
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+
+ for _, ev := range evaluators {
+ got, err := store.GetTask(ev.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.State != task.StateCompleted {
+ t.Errorf("evaluator %s should be auto-accepted to COMPLETED, got %v", ev.ID, got.State)
+ }
+ }
+
+ arbitrations := store.dependentsWithRole(evaluators[0].ID, "planner")
+ if len(arbitrations) != 1 {
+ t.Fatalf("expected arbitration spawned once all evaluators auto-accept, got %d", len(arbitrations))
+ }
+}
+
+// TestStoryOrchestrator_AutoAcceptsReadyArbitration proves a READY
+// arbitration task is auto-accepted to COMPLETED by the orchestrator, with
+// no external accept call, and that this in turn triggers
+// finalizeArbitration (KindArbitrationDecided + REVIEW_READY) in the same
+// tick.
+func TestStoryOrchestrator_AutoAcceptsReadyArbitration(t *testing.T) {
+ store, st, evaluators := seedStoryWithEvaluators(t, task.StateCompleted)
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ // Tick 1: spawns the arbitration task (starts at QUEUED).
+ orch.Tick(context.Background())
+
+ arbitrations := store.dependentsWithRole(evaluators[0].ID, "planner")
+ if len(arbitrations) != 1 {
+ t.Fatalf("expected 1 arbitration task, got %d", len(arbitrations))
+ }
+ arb := arbitrations[0]
+ // Simulate the arbitration's execution succeeding (RUNNING -> READY),
+ // exactly as executor.Pool.handleRunResult would do for any top-level
+ // task — without ever calling POST /api/tasks/{id}/accept.
+ store.setTaskState(arb.ID, task.StateReady)
+ store.setTaskSummary(arb.ID, "approved")
+
+ // Tick 2: orchestrator must auto-accept READY -> COMPLETED itself.
+ orch.Tick(context.Background())
+
+ got, err := store.GetTask(arb.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.State != task.StateCompleted {
+ t.Fatalf("arbitration should be auto-accepted to COMPLETED, got %v", got.State)
+ }
+
+ decided := store.eventsOfKind(event.KindArbitrationDecided)
+ if len(decided) != 1 {
+ t.Fatalf("expected exactly 1 arbitration_decided event after auto-accept, got %d", len(decided))
+ }
+
+ stories, _ := store.ListStories(storage.StoryFilter{})
+ for _, s := range stories {
+ if s.ID == st.ID && s.Status != "REVIEW_READY" {
+ t.Errorf("story status: want REVIEW_READY after arbitration auto-accepts, got %q", s.Status)
+ }
+ }
+}
+
+// TestStoryOrchestrator_AutoAccept_DoesNotTouchUnrelatedReadyTask proves the
+// auto-accept behavior is scoped to a story's own pipeline tasks (root task
+// + its role-matched evaluator/arbitration dependents) and does not sweep up
+// an unrelated READY task that merely happens to exist in the store.
+func TestStoryOrchestrator_AutoAccept_DoesNotTouchUnrelatedReadyTask(t *testing.T) {
+ store := newFakeStoryStore()
+ root := builderTask("builder-1", task.StateCompleted)
+ store.tasks[root.ID] = root
+ st := newStoryWithRoot("story-1", root.ID, "IN_PROGRESS")
+ store.stories[st.ID] = st
+
+ unrelated := &task.Task{ID: "unrelated-1", Name: "unrelated", Agent: task.AgentConfig{Type: "claude"}, State: task.StateReady}
+ store.tasks[unrelated.ID] = unrelated
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+
+ got, err := store.GetTask(unrelated.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.State != task.StateReady {
+ t.Errorf("unrelated task must not be auto-accepted: want READY, got %v", got.State)
+ }
+}
+
+// TestStoryOrchestrator_SkipsStoriesWithNoRootTask proves a story with no
+// root_task_id set is left completely untouched.
+func TestStoryOrchestrator_SkipsStoriesWithNoRootTask(t *testing.T) {
+ store := newFakeStoryStore()
+ st := &story.Story{ID: "story-1", Name: "no root yet", Status: "DISCOVERY"}
+ store.stories[st.ID] = st
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background()) // must not panic or error despite no root task existing
+
+ if pool.submitCount() != 0 {
+ t.Fatalf("expected no submissions, got %d", pool.submitCount())
+ }
+}
+
+// TestStoryOrchestrator_SkipsTerminalStories proves DONE/CANCELLED stories
+// are never revisited, even if (hypothetically) their root task is
+// COMPLETED and evaluators don't yet exist.
+func TestStoryOrchestrator_SkipsTerminalStories(t *testing.T) {
+ for _, status := range []string{"DONE", "CANCELLED"} {
+ t.Run(status, func(t *testing.T) {
+ store := newFakeStoryStore()
+ root := builderTask("builder-1", task.StateCompleted)
+ store.tasks[root.ID] = root
+ st := newStoryWithRoot("story-1", root.ID, status)
+ store.stories[st.ID] = st
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+ orch.Tick(context.Background())
+
+ deps, _ := store.ListDependents(root.ID)
+ if len(deps) != 0 {
+ t.Fatalf("status %s: expected no evaluator tasks spawned, got %d", status, len(deps))
+ }
+ })
+ }
+}
+
+// TestStoryOrchestrator_EndToEnd drives a story through the full chain —
+// builder complete -> evaluators -> arbitration -> REVIEW_READY — using only
+// the fake store/pool, proving the whole ceremony holds together end to end
+// at the orchestrator level (verification item 5, the higher-level test).
+//
+// Every task in the chain is driven to READY (never directly to COMPLETED),
+// mirroring exactly what executor.Pool.handleRunResult does for a real
+// top-level task whose execution succeeds — proving the orchestrator's own
+// auto-accept (not an external POST /api/tasks/{id}/accept call, which this
+// test never makes) is what carries each task the rest of the way to
+// COMPLETED and advances the story. The only accept call anywhere in this
+// flow is the story-level one, which isn't part of this test — it's covered
+// separately in internal/api's story accept-gate tests.
+func TestStoryOrchestrator_EndToEnd(t *testing.T) {
+ store := newFakeStoryStore()
+ root := builderTask("builder-1", task.StatePending)
+ store.tasks[root.ID] = root
+ st := newStoryWithRoot("story-1", root.ID, "IN_PROGRESS")
+ store.stories[st.ID] = st
+
+ pool := &fakePool{}
+ orch := &StoryOrchestrator{Store: store, Pool: pool}
+
+ // Before the builder completes, nothing happens.
+ orch.Tick(context.Background())
+ if deps, _ := store.ListDependents(root.ID); len(deps) != 0 {
+ t.Fatalf("expected no evaluators before builder completes, got %d", len(deps))
+ }
+
+ // Builder's execution succeeds (RUNNING -> READY, exactly like
+ // handleRunResult) — no POST /api/tasks/{id}/accept call here.
+ store.setTaskState(root.ID, task.StateReady)
+ orch.Tick(context.Background())
+
+ rootAfter, err := store.GetTask(root.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if rootAfter.State != task.StateCompleted {
+ t.Fatalf("builder should be auto-accepted to COMPLETED without an accept call, got %v", rootAfter.State)
+ }
+
+ deps, _ := store.ListDependents(root.ID)
+ if len(deps) != 4 {
+ t.Fatalf("expected 4 evaluators, got %d", len(deps))
+ }
+ statusOf := func() string {
+ stories, _ := store.ListStories(storage.StoryFilter{})
+ for _, s := range stories {
+ if s.ID == st.ID {
+ return s.Status
+ }
+ }
+ return ""
+ }
+ if statusOf() != "VALIDATING" {
+ t.Fatalf("expected VALIDATING after evaluators spawn, got %q", statusOf())
+ }
+
+ // Evaluators' executions succeed one by one (READY, not COMPLETED);
+ // arbitration must not spawn early.
+ for i, d := range deps {
+ store.setTaskState(d.ID, task.StateReady)
+ store.setTaskSummary(d.ID, fmt.Sprintf("verdict %d", i))
+ orch.Tick(context.Background())
+ arbs := store.dependentsWithRole(deps[0].ID, "planner")
+ if i < len(deps)-1 && len(arbs) != 0 {
+ t.Fatalf("arbitration spawned too early, after %d/%d evaluators complete", i+1, len(deps))
+ }
+ }
+
+ for _, d := range deps {
+ got, err := store.GetTask(d.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.State != task.StateCompleted {
+ t.Errorf("evaluator %s should be auto-accepted to COMPLETED, got %v", d.ID, got.State)
+ }
+ }
+
+ arbs := store.dependentsWithRole(deps[0].ID, "planner")
+ if len(arbs) != 1 {
+ t.Fatalf("expected exactly 1 arbitration task, got %d", len(arbs))
+ }
+ arb := arbs[0]
+
+ verdicts := store.eventsOfKind(event.KindEvalVerdict)
+ if len(verdicts) != 4 {
+ t.Fatalf("expected 4 eval_verdict events, got %d", len(verdicts))
+ }
+
+ // Arbitration's execution succeeds (READY, not COMPLETED).
+ store.setTaskState(arb.ID, task.StateReady)
+ store.setTaskSummary(arb.ID, "approved")
+ orch.Tick(context.Background())
+
+ arbAfter, err := store.GetTask(arb.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if arbAfter.State != task.StateCompleted {
+ t.Fatalf("arbitration should be auto-accepted to COMPLETED, got %v", arbAfter.State)
+ }
+
+ if statusOf() != "REVIEW_READY" {
+ t.Fatalf("expected REVIEW_READY after arbitration completes, got %q", statusOf())
+ }
+ decided := store.eventsOfKind(event.KindArbitrationDecided)
+ if len(decided) != 1 {
+ t.Fatalf("expected exactly 1 arbitration_decided event, got %d", len(decided))
+ }
+}