feat(story,role): add retro ceremony -- closes the self-improvement loop (Phase 8)

The final mechanism the versioned role-config model (Phase 5) was built for:
when a story reaches DONE, StoryOrchestrator spawns a retro-role task that
reflects on the story's full history and proposes draft role_configs
versions for a human to review and activate via the existing (unchanged)
POST /api/roles/{role}/activate.

- AgentChannel gains a 6th method, ProposeRoleConfig(ctx, role.RoleConfig)
  (version, err), following ProposeEpic's precedent (Phase 7c): a structured
  tool call, not summary-parsing. storeChannel.ProposeRoleConfig calls the
  same Store.CreateRoleConfig the human-facing POST /api/roles/{role}/versions
  endpoint already uses (proposed_by: "retro"), landing a new draft row
  without touching whatever's currently active. Wired through both
  transports exactly like ProposeEpic: internal/agentloop/tools.go (native
  loop) and internal/executor/agentmcp.go (MCP).
- StoryOrchestrator.Tick now routes a story at status DONE to a new
  processRetro stage instead of processStory -- a sibling stage, not a
  continuation, since the Builder->Evaluators->Arbitration chain is long
  settled by then. processRetro only *reads* that settled pipeline
  (read-only findEvaluators/findArbitration counterparts to
  ensureEvaluators/ensureArbitration -- it never spawns/mutates
  Builder-pipeline tasks) to locate the Arbitration task the retro task
  depends on, then spawns (idempotently -- checks for an existing
  retro-role dependent first) one retro-role task with instructions
  assembled from the story's spec/acceptance-criteria, full task tree, per-
  task cost/escalation history, active role_configs per role encountered,
  and the story's own event stream (evaluator verdicts, arbitration
  decision).
- event.KindRetroCaptured (attached to the story's ID, matching
  KindEvalVerdict/KindArbitrationDecided's convention) fires once the retro
  task completes (auto-accepted like every other pipeline task), aggregating
  every event.KindRoleConfigProposed the retro task recorded (one per
  propose_role_config call) into {task_id, proposals: [{role, version}],
  summary} -- the summary is the "capturing lessons" half of this ceremony,
  the proposals are the versioned-config half.
- Human activation is completely untouched: drafts land through the
  identical CreateRoleConfig/config_json path Phase 5's endpoints already
  handle, confirmed via existing role-endpoint tests passing unmodified.

go build/vet/test -race -count=1 all pass, full suite (20 packages) -- one
run hit a known, pre-existing, intermittent flake under full-suite load
(unrelated to this phase's files) that did not reproduce on two immediate
reruns, both in isolation and full-suite.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs

1 files changed, 56 insertions, 7 deletions

diff --git a/internal/agentloop/tools.go b/internal/agentloop/tools.go
index d803c23..ad1aecf 100644
--- a/internal/agentloop/tools.go
+++ b/internal/agentloop/tools.go
@@ -8,16 +8,17 @@ import (
 
 	"github.com/thepeterstone/claudomator/internal/agentchannel"
 	"github.com/thepeterstone/claudomator/internal/provider"
+	"github.com/thepeterstone/claudomator/internal/role"
 	"github.com/thepeterstone/claudomator/internal/sandbox"
 )
 
-// agentToolSpecs returns the nine tools available to the loop: the five
-// agent back-channel tools (mirroring the MCP tools ContainerRunner exposes;
-// propose_epic was added in Phase 7c) plus the four sandbox tools, as
-// provider-neutral ToolSpecs. The original four (ask_user/report_summary/
-// spawn_subtask/record_progress) plus the sandbox tools were ported verbatim
-// (same names/descriptions/JSON schemas) from the former
-// executor.agentToolDefs (internal/executor/localtools.go).
+// agentToolSpecs returns the tools available to the loop: the agent
+// back-channel tools (mirroring the MCP tools ContainerRunner exposes;
+// propose_epic was added in Phase 7c, propose_role_config in Phase 8) plus
+// the four sandbox tools, as provider-neutral ToolSpecs. The original four
+// (ask_user/report_summary/spawn_subtask/record_progress) plus the sandbox
+// tools were ported verbatim (same names/descriptions/JSON schemas) from the
+// former executor.agentToolDefs (internal/executor/localtools.go).
 func agentToolSpecs() []provider.ToolSpec {
 	strProp := func(desc string) map[string]any {
 		return map[string]any{"type": "string", "description": desc}
@@ -82,6 +83,45 @@ func agentToolSpecs() []provider.ToolSpec {
 			},
 		},
 		{
+			Name:        "propose_role_config",
+			Description: "Propose a new draft configuration version for a role, after reflecting on what happened (e.g. during a story retro). Creates a new draft role_configs row for a human to review and activate -- it never changes what is currently active.",
+			ParametersJSONSchema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"role":               strProp("the role name this config applies to (e.g. an existing role like builder, or a new one)"),
+					"system_prompt":      strProp("system prompt appended for tasks dispatched through this role"),
+					"tools":              map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "optional tool allowlist for this role"},
+					"sandbox_kind":       strProp("optional sandbox kind for this role"),
+					"default_budget_usd": map[string]any{"type": "number", "description": "optional estimated budget in USD, used when the scheduler considers escalating this role's tasks"},
+					"escalation_ladder": map[string]any{
+						"type":        "array",
+						"description": "ordered list of escalation tiers",
+						"items": map[string]any{
+							"type": "object",
+							"properties": map[string]any{
+								"candidates": map[string]any{
+									"type": "array",
+									"items": map[string]any{
+										"type": "object",
+										"properties": map[string]any{
+											"provider": strProp("executor runner key, e.g. anthropic, google, groq, openrouter, openai, local"),
+											"model":    strProp("model name"),
+										},
+										"required": []string{"provider", "model"},
+									},
+									"description": "candidate provider/model rungs for this tier",
+								},
+								"selection_mode": strProp("round_robin (default) or single"),
+								"max_retries":    map[string]any{"type": "integer", "description": "attempts allowed at this tier before escalating to the next"},
+							},
+							"required": []string{"candidates"},
+						},
+					},
+				},
+				"required": []string{"role"},
+			},
+		},
+		{
 			Name:        "read_file",
 			Description: "Read the contents of a file in the sandbox working directory.",
 			ParametersJSONSchema: map[string]any{
@@ -211,6 +251,15 @@ func (l *Loop) dispatchTool(ctx context.Context, name, argsJSON string) (result
 		}
 		return "Proposed epic " + id, false, nil
 
+	case "propose_role_config":
+		var a role.RoleConfig
+		_ = json.Unmarshal([]byte(argsJSON), &a)
+		version, prErr := l.Channel.ProposeRoleConfig(ctx, a)
+		if prErr != nil {
+			return "", false, prErr
+		}
+		return fmt.Sprintf("Proposed role config %s v%d (draft)", a.Role, version), false, nil
+
 	case "read_file":
 		var a struct {
 			Path string `json:"path"`