feat(workflow): close milestone 3 router boundary (#18)

* feat(workflow): close milestone 3 router boundary

* docs(release-log): link milestone 3 pr

* fix(workflow): normalize routing decision contract

---------

Co-authored-by: Hanna Rosengren <4538260+hannasoderstromdev@users.noreply.github.com>

Author: hannasdev

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### Unreleased
+
+- feat(workflow): close milestone 3 with contract-backed router and Claude evidence
+
 #### [v1.2.1](https://github.com/hannasdev/model-switchboard/compare/v1.2.0...v1.2.1)
 
 - Complete Milestone 2 session-controller closeout [`#17`](https://github.com/hannasdev/model-switchboard/pull/17)

README.md

@@ -28,7 +28,7 @@ High-level flow:
 1. You send a prompt through Switchboard.
 2. Switchboard classifies the turn and selects a route label.
 3. Switchboard launches or resumes Claude with matching model and effort settings.
-4. Route context and hook evidence are recorded for explainability and governance.
+4. Route context, session state, and hook evidence are recorded for explainability, replay, and governance.
 
 ## What It Is Not
 
@@ -49,7 +49,9 @@ High-level flow:
 
 Version 1.0.0 is the first stable release of the prompt-driven Switchboard workflow for Claude Code.
 
-Non-interactive continuity is verified for routed turns. Interactive continuity is verified for session reuse, resume semantics, hook correlation, and override handling, while stale-resume recovery and fail-closed error handling remain explicitly tracked as follow-up validation for fully supported interactive parity.
+Milestones 1 through 3 are now complete: router contracts, session-aware policy/controller boundaries, and the Claude workflow refit onto contract-backed router/session/context evidence.
+
+Non-interactive continuity is verified for routed turns. Interactive continuity is verified for session reuse, resume semantics, hook correlation, stale-resume recovery, and fail-closed error handling.
 
 ## Delivery Model
 

docs/ROUTER-PHASE-PLAN.md

@@ -154,6 +154,10 @@ Acceptance criteria:
 
 ### Milestone 3: Claude Workflow On Router Boundary
 
+Status: complete (2026-05-11)
+
+Decision record: see `DEC-2026-05-11-milestone-3-claude-workflow-boundary-closeout` in `docs/decision-log.md`.
+
 Refit the existing Claude workflow so it consumes the router as a client integration rather than embedding router assumptions directly.
 
 Required work:

docs/contracts/router-contracts.md

@@ -326,6 +326,8 @@ Current workflow signals in the switchboard implementation map as follows:
 * current route mode -> `SessionState.mode`
 * `routingOverride` -> `SessionState.routingOverride`
 
+Current workflow persistence now records a contract-backed `sessionState` object alongside compatibility fields in route-context storage.
+
 ### A.2 Target Mapping
 
 Current route labels map to target classes in the Claude integration:
@@ -346,6 +348,8 @@ Current continuity semantics are:
 
 These semantics belong to workflow execution behavior, not router decision semantics.
 
+Current workflow evidence now separates router-decision data from Claude execution data in wrapper logs while preserving continuity semantics and stale-resume recovery behavior.
+
 ### A.4 Hook Correlation Mapping
 
 Current hook evidence maps to `RoutingLogEvent.correlation`:
@@ -356,6 +360,8 @@ Current hook evidence maps to `RoutingLogEvent.correlation`:
 
 Hook timing and correlation quality remain surface-specific and should not be treated as universal across clients.
 
+Current route-context persistence also records a contract-backed `ContextPackage` and `claudeExecution` block so hook correlation can consume stable handoff fields without depending only on legacy flat fields.
+
 ## Appendix B: Open Questions
 
 1. Should `riskLevel` be router-owned or adapter-provided in v0.2?

docs/decision-log.md

@@ -203,3 +203,44 @@ Consequences:
 Follow-up:
 - Next review milestone: Milestone 3 plan-to-implementation checkpoint.
 - Linked artifacts (logs, fixtures, docs, PRs): src/router/router.js, src/router/session_controller.js, test/session-controller.test.js, test/router.test.js, docs/ROUTER-PHASE-PLAN.md
+
+## Milestone 3 Closeout
+
+Decision ID: DEC-2026-05-11-milestone-3-claude-workflow-boundary-closeout
+Related deferred item: Milestone 3 Claude workflow boundary refit
+Status: committed
+Date: 2026-05-11
+Owners: team
+
+Context:
+- Milestone 3 required the Claude workflow to consume router contracts as a client integration, preserve continuity semantics, and separate router decision evidence from Claude execution evidence.
+
+Options considered:
+- Option A: keep the existing workflow-specific route context format and explain shape, and defer contract-backed persistence until Milestone 4.
+- Option B: refit workflow persistence and explain now so Claude consumes and emits contract-aligned router/session/context shapes while keeping compatibility fields for existing consumers.
+
+Tradeoffs:
+- Option A: smaller short-term diff, but leaves Milestone 3 structurally incomplete and pushes risk into Milestone 4.
+- Option B: slightly larger boundary refit now, but cleaner milestone ownership, stronger replay/explain foundation, and lower follow-on ambiguity.
+
+Verification signal:
+- Expected signal from phase plan: Claude workflow remains functional; router can be exercised independently of Claude launch details; logs distinguish router and Claude execution data; handoff/context fields match the core contract.
+- Evidence observed:
+  - `src/switchboard/workflow.js` now emits separated `router` and `claude` evidence blocks while retaining compatibility summaries.
+  - `src/switchboard/route_context.js` now persists canonical `sessionState`, `routingDecision`, `contextPackage`, and `claudeExecution` fields.
+  - `switchboard explain` now surfaces contract-backed router and Claude evidence.
+  - Full suite passes (`npm test`) including new workflow and explain tests for contract-backed evidence.
+
+Decision:
+- Chosen option: Option B.
+- Scope of commitment: Milestone 3 is formally complete as of 2026-05-11.
+- What remains intentionally deferred: routing log-event normalization across all surfaces, outcome attribution taxonomy, replay-oriented evaluation tooling, and second-surface validation.
+
+Consequences:
+- Near-term implementation impact: Claude workflow is now a cleaner consumer of router outputs with a more explicit control-plane boundary.
+- Test and replay impact: route context and explain data now carry contract-backed session and handoff fields suitable for Milestone 4 normalization.
+- Migration impact: low; legacy route-context fields remain present for current hook correlation and explain consumers.
+
+Follow-up:
+- Next review milestone: Milestone 4 plan-to-implementation checkpoint.
+- Linked artifacts (logs, fixtures, docs, PRs): src/switchboard/workflow.js, src/switchboard/route_context.js, src/switchboard/cli.js, src/switchboard/claude_hook_bridge.js, test/switchboard-workflow.test.js, test/switchboard-cli.test.js, docs/ROUTER-PHASE-PLAN.md

docs/release-log.md

@@ -1,5 +1,13 @@
 ## Unreleased
 
+### 2026-05-11 — Close Milestone 3 with contract-backed Claude workflow evidence
+
+- What changed: Refit the Claude workflow so route-context persistence and explain output now carry contract-backed router decision, session state, and context-package evidence while separating router and Claude execution data.
+- Why it matters: Completes the Milestone 3 control-plane boundary by making Claude a cleaner consumer of router outputs and by preserving stable fields for explain, replay, and hook correlation.
+- Who is affected: Switchboard maintainers and contributors working on explainability, replay, and future non-Claude integrations.
+- Action needed: None.
+- PR: https://github.com/hannasdev/model-switchboard/pull/18
+
 ### 2026-05-11 — Close Milestone 2 with explicit session-controller boundary
 
 - What changed: Extracted deterministic session mode-transition ownership into a dedicated controller module, wired router mode resolution through that boundary, and added focused transition tests while preserving existing routing behavior.

src/switchboard/claude_hook_bridge.js

@@ -48,12 +48,16 @@ function routeContextText(routeResult) {
 function correlatedRouteContextText(correlation) {
 	const latest = correlation.context?.latest;
 	if (!latest) return null;
+	const contextPackage = latest.contextPackage || null;
+	const claudeExecution = latest.claudeExecution || null;
 	return [
 		"Switchboard wrapper route for this Claude Code session:",
-		`Thread: ${latest.threadId || "unknown"}`,
-		`Target label: ${latest.routeLabel || "unknown"}`,
-		`Claude model/effort: ${latest.model || "unknown"}/${latest.effort || "unknown"}`,
-		latest.wrapperContext?.text ? `Summary: ${latest.wrapperContext.text}` : null
+		`Thread: ${latest.threadId || contextPackage?.threadId || "unknown"}`,
+		`Target label: ${latest.routeLabel || contextPackage?.routeLabel || "unknown"}`,
+		`Claude model/effort: ${latest.model || claudeExecution?.model || "unknown"}/${latest.effort || claudeExecution?.effort || "unknown"}`,
+		(latest.wrapperContext?.text || contextPackage?.wrapperContext?.text)
+			? `Summary: ${latest.wrapperContext?.text || contextPackage?.wrapperContext?.text}`
+			: null
 	].filter(Boolean).join("\n");
 }
 

src/switchboard/cli.js

@@ -63,15 +63,24 @@ function printHumanExplain(explanation, stdout) {
     return;
   }
 
+  const routerDecision = explanation.routerEvidence?.routeDecision || explanation.routeDecision;
+  const routingDecision = explanation.routerEvidence?.routingDecision || explanation.routingDecision;
+  const claudeSelected = explanation.claudeEvidence?.selectedClaude || explanation.selectedClaude;
+  const claudeExecution = explanation.claudeEvidence?.execution || explanation.execution;
+
   stdout.write(`${explanation.wrapperContext?.text || "Switchboard: no wrapper context"}\n`);
   stdout.write(`Thread: ${explanation.threadId || "unknown"}\n`);
-  stdout.write(`Claude session: ${explanation.selectedClaude?.sessionId || "unknown"}\n`);
-  stdout.write(`Claude target: ${explanation.selectedClaude?.model || "unknown"}/${explanation.selectedClaude?.effort || "unknown"}\n`);
-  stdout.write(`Route: ${explanation.routeDecision?.label || "unknown"} (${explanation.routeDecision?.mode || "unknown"})\n`);
-  const escalation = explanation.routeDecision?.escalationPolicy;
+  stdout.write(`Claude session: ${claudeSelected?.sessionId || "unknown"}\n`);
+  stdout.write(`Claude target: ${claudeSelected?.model || "unknown"}/${claudeSelected?.effort || "unknown"}\n`);
+  stdout.write(`Router route: ${routerDecision?.label || "unknown"} (${routerDecision?.mode || "unknown"})\n`);
+  stdout.write(`Router status: ${routingDecision?.status || routerDecision?.status || "unknown"}\n`);
+  const escalation = routerDecision?.escalationPolicy;
   if (escalation?.applied && Array.isArray(escalation.reasons) && escalation.reasons.length > 0) {
     stdout.write(`Escalation: ${escalation.reasons.join(",")}\n`);
   }
+  if (claudeExecution?.status) {
+    stdout.write(`Claude execution: ${claudeExecution.status}\n`);
+  }
   stdout.write(`Route context: ${explanation.routeContext.status}\n`);
   stdout.write(`Hook events: ${explanation.hookEvents.length}\n`);
   for (const event of explanation.hookEvents) {

src/switchboard/route_context.js

@@ -19,6 +19,59 @@ function writeStore(storePath, store) {
 	fs.writeFileSync(storePath, `${JSON.stringify(store, null, 2)}\n`, "utf8");
 }
 
+function deriveLegacyTurnFields(context = {}) {
+	const sessionState = context.sessionState || null;
+	const routingDecision = context.routingDecision || null;
+	const contextPackage = context.contextPackage || null;
+	const claudeExecution = context.claudeExecution || null;
+
+	return {
+		threadId:
+			context.threadId ||
+			sessionState?.threadId ||
+			contextPackage?.threadId ||
+			null,
+		turnCount:
+			context.turnCount ??
+			sessionState?.turnCount ??
+			contextPackage?.turnIndex ??
+			null,
+		routeLabel:
+			context.routeLabel ||
+			contextPackage?.routeLabel ||
+			routingDecision?.selectedTarget?.label ||
+			null,
+		targetId:
+			context.targetId ||
+			contextPackage?.targetId ||
+			routingDecision?.selectedTarget?.id ||
+			sessionState?.currentTargetId ||
+			null,
+		model:
+			context.model ||
+			claudeExecution?.model ||
+			null,
+		effort:
+			context.effort ||
+			claudeExecution?.effort ||
+			null,
+		mode:
+			context.mode ||
+			routingDecision?.mode ||
+			sessionState?.mode ||
+			contextPackage?.mode ||
+			null,
+		executionMode:
+			context.executionMode ||
+			claudeExecution?.executionMode ||
+			null,
+		wrapperContext:
+			context.wrapperContext ||
+			contextPackage?.wrapperContext ||
+			null
+	};
+}
+
 export function saveRouteContext({
 	storePath = DEFAULT_ROUTE_CONTEXT_PATH,
 	context
@@ -30,17 +83,22 @@ export function saveRouteContext({
 
 	const store = readStore(storePath);
 	const existing = store[sessionId] || { turns: [] };
+	const legacy = deriveLegacyTurnFields(context);
 	const turn = {
-		threadId: context.threadId || null,
+		threadId: legacy.threadId,
 		claudeSessionId: sessionId,
-		turnCount: context.turnCount ?? null,
-		routeLabel: context.routeLabel || null,
-		targetId: context.targetId || null,
-		model: context.model || null,
-		effort: context.effort || null,
-		mode: context.mode || null,
-		executionMode: context.executionMode || null,
-		wrapperContext: context.wrapperContext || null,
+		turnCount: legacy.turnCount,
+		routeLabel: legacy.routeLabel,
+		targetId: legacy.targetId,
+		model: legacy.model,
+		effort: legacy.effort,
+		mode: legacy.mode,
+		executionMode: legacy.executionMode,
+		wrapperContext: legacy.wrapperContext,
+		sessionState: context.sessionState || null,
+		routingDecision: context.routingDecision || null,
+		contextPackage: context.contextPackage || null,
+		claudeExecution: context.claudeExecution || null,
 		updatedAt: new Date().toISOString()
 	};