docs: fix workflow diagram — create_story does not auto-spawn a builder taskHEADmain

The StoryOrchestrator skips stories with no root_task_id (if st.RootTaskID == "")
so create_story / POST /api/stories do not trigger Builder spawning on the next tick
as the diagram incorrectly claimed. Corrected the flowchart node, the entry-point
table rows, and added an explanatory note on the story lifecycle kickoff flow.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

1 files changed, 13 insertions, 4 deletions

diff --git a/docs/workflow-and-entry-points.md b/docs/workflow-and-entry-points.md
index 367c5ba..afc7a70 100644
--- a/docs/workflow-and-entry-points.md
+++ b/docs/workflow-and-entry-points.md
@@ -26,7 +26,7 @@ flowchart TD
 
     subgraph CHATBOT["Chatbot MCP (/chatbot/mcp)"]
         CB_SUBMIT["submit_task tool\n(creates + submits in one step)"]
-        CB_STORY["create_story tool\n(creates Story row in storage only;\nStoryOrchestrator spawns Builder on next tick)"]
+        CB_STORY["create_story tool\n(creates Story row with DISCOVERY status;\nno root_task_id set;\norchestrator skips until root_task_id\nis set via PUT /api/stories/{id})"]
         CB_ACCEPT["accept_story tool\n(REVIEW_READY → DONE;\norchestrator triggers retro next tick)"]
     end
 
@@ -116,9 +116,9 @@ flowchart TD
 | `claudomator run <file>` | `internal/cli/run.go` | Task(s) from YAML | `cli` directly: `CreateTask` → `UpdateTaskState(QUEUED)` → `Pool.Submit` |
 | `POST /api/tasks` + `POST /api/tasks/{id}/run` | `internal/api/server.go`, `taskops.go` | PENDING task, then QUEUED | `handleRunTask` via `Pool.Submit` |
 | Chatbot MCP `submit_task` | `internal/api/chatbotmcp.go` | Task (PENDING→QUEUED in one step) | `submitTask()` via `Pool.Submit` |
-| Chatbot MCP `create_story` | `internal/api/chatbotmcp.go` | Story row in storage | `StoryOrchestrator` (next tick): creates + submits Builder task |
-| Chatbot MCP `accept_story` | `internal/api/chatbotmcp.go` | Story status DONE in storage | `StoryOrchestrator` (next tick): spawns retro task |
-| `POST /api/stories` | `internal/api/stories.go` | Story row in storage | `StoryOrchestrator` (next tick) |
+| Chatbot MCP `create_story` | `internal/api/chatbotmcp.go` | Story row in storage (`DISCOVERY` status, no `root_task_id`) | **Not auto-submitted** — a builder-role root task must be created separately and linked via `PUT /api/stories/{id}`; orchestrator skips stories with no `root_task_id` |
+| Chatbot MCP `accept_story` | `internal/api/chatbotmcp.go` | Story status `DONE` in storage | `StoryOrchestrator` (next tick): spawns retro task |
+| `POST /api/stories` | `internal/api/stories.go` | Story row in storage (`DISCOVERY` status, no `root_task_id`) | **Not auto-submitted** — same as `create_story`; `root_task_id` must be set via `PUT /api/stories/{id}` |
 | `POST /api/stories/{id}/accept` | `internal/api/stories.go` | Story status DONE in storage | `StoryOrchestrator` (next tick): spawns retro task |
 | `POST /api/webhooks/github` | `internal/api/webhook.go` | Task in **PENDING** state only | Human/chatbot/script must call `POST /api/tasks/{id}/run` |
 | Agent `spawn_subtask` (no `role=`) | `internal/executor/agentmcp.go`, `internal/agentloop/tools.go` | Child task with `parent_task_id`, `agent.type=claude` | **Not auto-submitted**; parent goes BLOCKED; child is dispatched later |
@@ -290,3 +290,12 @@ flowchart LR
   resume). The `StoryOrchestrator` handles story-specific pipeline orchestration
   (Builder → Evaluators → Arbitration). They run in the same process but poll
   independently and write to separate concerns.
+
+- **Story lifecycle kickoff**: `create_story` (chatbot MCP) and `POST /api/stories` both create a story in
+  `DISCOVERY` status with no `root_task_id`. The `StoryOrchestrator` skips stories that have no
+  `root_task_id` (code: `if st.RootTaskID == "" { continue }`). To kick off execution, a human or
+  chatbot must (1) create a builder-role task (e.g. via `submit_task` with `agent.role="builder"`),
+  then (2) link it as the story's root via `PUT /api/stories/{id}` with `root_task_id` set. Once
+  linked, the orchestrator will drive the builder node through Evaluators → Arbitration on each
+  poll tick. The orchestrator never spawns the initial builder task itself — only the
+  Evaluator, Arbitration, fix-attempt, and retro tasks are ever auto-spawned by `spawnRoleTask`.