Complete Milestone 2 session-controller closeout (#17)

* Complete Milestone 2 session-controller closeout

* Link Milestone 2 release note to PR #17

* chore(hooks): enforce semantic commits locally

---------

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

Author: hannasdev

.githooks/commit-msg

@@ -0,0 +1,42 @@
+#!/bin/sh
+
+set -eu
+
+MSG_FILE="$1"
+MSG=$(head -n 1 "$MSG_FILE" | tr -d '\r')
+
+# Allow merge/revert commits created by Git.
+case "$MSG" in
+  Merge\ *|Revert\ *)
+    exit 0
+    ;;
+esac
+
+# Conventional/semantic commit format:
+# type(scope)!: subject
+# type!: subject
+# type: subject
+PATTERN='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?(!)?: .+$'
+
+if printf '%s' "$MSG" | grep -Eq "$PATTERN"; then
+  exit 0
+fi
+
+cat <<'EOF'
+ERROR: Commit message must follow semantic commit format.
+
+Expected:
+  type(scope): short summary
+  type: short summary
+  type!: short summary
+
+Allowed types:
+  feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+
+Examples:
+  feat(router): add session controller extraction
+  fix(cli): handle stale resume retry path
+  chore: update release log links
+EOF
+
+exit 1

.githooks/pre-commit

@@ -0,0 +1,15 @@
+#!/bin/sh
+
+set -eu
+
+branch_name=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+
+if [ "$branch_name" = "main" ]; then
+  echo "ERROR: Direct commits to main are blocked locally. Commit from a feature branch."
+  exit 1
+fi
+
+# Friendly reminder: semantic message validation runs in commit-msg.
+echo "pre-commit: branch check passed (semantic message will be validated by commit-msg)."
+
+exit 0

docs/CI-CD.md

@@ -70,3 +70,22 @@ For each release:
 1. Merge a PR into `main` with conventional commit text (`feat:`, `fix:`, or `!`/`BREAKING CHANGE`).
 2. Release workflow creates a `Release x.y.z` commit and `vX.Y.Z` tag.
 3. Publish workflow runs on the new tag and publishes to npm.
+
+## Local Hook Guardrails
+
+To reduce accidental non-semantic commit messages locally, this repo includes git hooks under `.githooks`:
+
+- `commit-msg` enforces semantic commit format (`type(scope): subject`).
+- `pre-commit` blocks direct commits to `main` and reminds that semantic validation runs at commit message time.
+
+Install once per clone:
+
+```bash
+npm run hooks:install
+```
+
+Verify current hook path:
+
+```bash
+npm run hooks:doctor
+```

docs/ROUTER-PHASE-PLAN.md

@@ -126,6 +126,10 @@ Acceptance criteria:
 
 ### Milestone 2: Session Controller And Policy Upgrade
 
+Status: complete (2026-05-11)
+
+Decision record: see `DEC-2026-05-11-milestone-2-session-controller-policy-closeout` in `docs/decision-log.md`.
+
 Move from mostly prompt-local routing to session-aware routing.
 
 Required work:

docs/decision-log.md

@@ -163,3 +163,43 @@ Consequences:
 Follow-up:
 - Next review milestone: Milestone 2 slice 2 planning.
 - Linked artifacts (logs, fixtures, docs, PRs): src/router/router.js, src/switchboard/workflow.js, test/router.test.js, test/switchboard-workflow.test.js
+
+## Milestone 2 Closeout
+
+Decision ID: DEC-2026-05-11-milestone-2-session-controller-policy-closeout
+Related deferred item: Milestone 2 staged policy depth
+Status: committed
+Date: 2026-05-11
+Owners: team
+
+Context:
+- Milestone 2 required a deterministic and testable session controller boundary, continuity-aware switching, and explicit hard/soft policy inputs in explainable router outputs.
+
+Options considered:
+- Option A: keep session mode transitions embedded in the router implementation.
+- Option B: extract session mode transition ownership into a dedicated controller module and lock behavior with direct tests.
+
+Tradeoffs:
+- Option A: lower short-term change set, weaker boundary clarity and weaker transition-focused test surface.
+- Option B: clearer boundary ownership and stronger deterministic validation, with small refactor overhead.
+
+Verification signal:
+- Expected signal from phase plan: mode transition logic deterministic and testable; policy decisions explainable with session/task/constraint/continuity context; route labels continue mapping cleanly.
+- Evidence observed:
+  - Session mode transition logic extracted to `src/router/session_controller.js` and consumed by router.
+  - Dedicated transition tests added in `test/session-controller.test.js`.
+  - Full suite passes (`npm test`) with continuity, escalation, override, and hard-constraint behavior preserved.
+
+Decision:
+- Chosen option: Option B.
+- Scope of commitment: Milestone 2 is formally complete as of 2026-05-11.
+- What remains intentionally deferred: numeric continuity scoring, taxonomy freeze, strict universal enforcement defaults, and cross-surface validation beyond Claude workflow.
+
+Consequences:
+- Near-term implementation impact: session-controller boundary is now explicit and reusable for Milestone 3 router-client integration work.
+- Test and replay impact: transition behavior is isolated and easier to validate independently of broader router selection logic.
+- Migration impact: low; external route output behavior remains stable.
+
+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

docs/release-log.md

@@ -1,5 +1,13 @@
 ## Unreleased
 
+### 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.
+- Why it matters: Completes Milestone 2 policy/controller acceptance criteria and reduces coupling before Milestone 3 Claude-workflow boundary refit.
+- Who is affected: Switchboard maintainers and contributors working on router-policy evolution.
+- Action needed: None.
+- PR: https://github.com/hannasdev/model-switchboard/pull/17
+
 ### 2026-05-10 — Add deterministic escalation policy and escalation evidence in explain output
 
 - What changed: Added explicit escalation policy handling for low-confidence turns, user corrections, repeated failures, and high-risk implementation; propagated escalation fields into route evidence and human explain output.

package.json

@@ -28,6 +28,8 @@
   },
   "scripts": {
     "test": "node --test test/*.test.js",
+    "hooks:install": "sh scripts/install-git-hooks.sh",
+    "hooks:doctor": "git config --get core.hooksPath",
     "release": "release-it",
     "test:fuzz": "node --test test/router.fuzz.js",
     "check:anthropic": "node bin/check.js --vendor anthropic",

scripts/install-git-hooks.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+set -eu
+
+git config core.hooksPath .githooks
+chmod +x .githooks/pre-commit .githooks/commit-msg
+
+echo "Installed local git hooks at .githooks"
+echo "Current core.hooksPath: $(git config --get core.hooksPath)"

src/router/router.js

@@ -1,14 +1,4 @@
-const MODE_TO_REQUIREMENTS = {
-  plan: ["chat", "reasoning", "structured_output"],
-  implement: ["repo_context", "file_read", "file_edit"],
-  debug: ["repo_context", "file_read", "shell_execution", "test_execution"],
-  review: ["repo_context", "file_read", "reasoning", "structured_output"],
-  summarize: ["chat", "structured_output"],
-  agent_workflow: ["chat", "reasoning", "structured_output"],
-  out_of_domain: ["chat"]
-};
-
-const MODE_VALUES = new Set(Object.keys(MODE_TO_REQUIREMENTS));
+import { MODE_TO_REQUIREMENTS, resolveSessionMode } from "./session_controller.js";
 
 const MODE_TO_CLASS = {
   plan: "medium_reasoning",
@@ -153,56 +143,6 @@ export function classifyPrompt(input) {
   };
 }
 
-function resolveSessionMode(session = {}, classification = {}) {
-  const currentMode = MODE_VALUES.has(session.mode) ? session.mode : null;
-  const proposedMode = MODE_VALUES.has(classification.proposedMode)
-    ? classification.proposedMode
-    : "plan";
-
-  if (!currentMode) {
-    return {
-      previousMode: null,
-      proposedMode,
-      resolvedMode: proposedMode,
-      transitionReason: "no_previous_mode"
-    };
-  }
-
-  if (classification.explicitModeShift) {
-    return {
-      previousMode: currentMode,
-      proposedMode,
-      resolvedMode: proposedMode,
-      transitionReason: "explicit_task_signal"
-    };
-  }
-
-  if (proposedMode === "summarize") {
-    return {
-      previousMode: currentMode,
-      proposedMode,
-      resolvedMode: proposedMode,
-      transitionReason: "acknowledgement_summary"
-    };
-  }
-
-  if (!classification.modeStrongSignal && ["implement", "debug", "review"].includes(currentMode)) {
-    return {
-      previousMode: currentMode,
-      proposedMode,
-      resolvedMode: currentMode,
-      transitionReason: "preserve_current_mode_for_ambiguous_turn"
-    };
-  }
-
-  return {
-    previousMode: currentMode,
-    proposedMode,
-    resolvedMode: proposedMode,
-    transitionReason: "default_mode_resolution"
-  };
-}
-
 function buildRequiredCapabilities(resolvedMode, taskType) {
   const modeRequirements = MODE_TO_REQUIREMENTS[resolvedMode] || ["chat"];
   const additionalRequirements = TASK_TYPE_TO_ADDITIONAL_REQUIREMENTS[taskType] || [];

src/router/session_controller.js

@@ -0,0 +1,63 @@
+const MODE_TO_REQUIREMENTS = {
+  plan: ["chat", "reasoning", "structured_output"],
+  implement: ["repo_context", "file_read", "file_edit"],
+  debug: ["repo_context", "file_read", "shell_execution", "test_execution"],
+  review: ["repo_context", "file_read", "reasoning", "structured_output"],
+  summarize: ["chat", "structured_output"],
+  agent_workflow: ["chat", "reasoning", "structured_output"],
+  out_of_domain: ["chat"]
+};
+
+const MODE_VALUES = new Set(Object.keys(MODE_TO_REQUIREMENTS));
+
+export { MODE_TO_REQUIREMENTS, MODE_VALUES };
+
+export function resolveSessionMode(session = {}, classification = {}) {
+  const currentMode = MODE_VALUES.has(session.mode) ? session.mode : null;
+  const proposedMode = MODE_VALUES.has(classification.proposedMode)
+    ? classification.proposedMode
+    : "plan";
+
+  if (!currentMode) {
+    return {
+      previousMode: null,
+      proposedMode,
+      resolvedMode: proposedMode,
+      transitionReason: "no_previous_mode"
+    };
+  }
+
+  if (classification.explicitModeShift) {
+    return {
+      previousMode: currentMode,
+      proposedMode,
+      resolvedMode: proposedMode,
+      transitionReason: "explicit_task_signal"
+    };
+  }
+
+  if (proposedMode === "summarize") {
+    return {
+      previousMode: currentMode,
+      proposedMode,
+      resolvedMode: proposedMode,
+      transitionReason: "acknowledgement_summary"
+    };
+  }
+
+  if (!classification.modeStrongSignal && ["implement", "debug", "review"].includes(currentMode)) {
+    return {
+      previousMode: currentMode,
+      proposedMode,
+      resolvedMode: currentMode,
+      transitionReason: "preserve_current_mode_for_ambiguous_turn"
+    };
+  }
+
+  return {
+    previousMode: currentMode,
+    proposedMode,
+    resolvedMode: proposedMode,
+    transitionReason: "default_mode_resolution"
+  };
+}