router/semantic: coarse-route contract, interface, and legacy mapping (slice 12)

Defines the six-class SemanticRoute type (conversation, knowledge,
action, memory_write, system, uncertain), the SemanticRouteDecision
output, the SemanticRouter interface, and the deterministic
Intent→SemanticRoute mapping from the current seven-intent cascade.

internal/router/semantic/contract.go

@@ -0,0 +1,60 @@
+// Package semantic defines the coarse-route contract for the learned-router
+// experiment. The existing seven-intent router remains authoritative; this
+// package provides a six-class semantic layer that runs only in eval/shadow
+// mode until it earns promotion.
+//
+// The six coarse routes are:
+//
+//   - conversation — social turns, greetings, mood, jokes, open-ended chat
+//   - knowledge    — questions seeking an answer (world, recall, calendar)
+//   - action       — executable commands and reminders (act, reminder)
+//   - memory_write — structured or unstructured writes (fact, note)
+//   - system       — time, date, quiet mode, self-management
+//   - uncertain    — too little signal to decide; the authoritative router clarifies
+//
+// No capability, function, slot, or source information lives in this artifact.
+// That is a later stage. The contract here is purely coarse-route + confidence.
+package semantic
+
+// SemanticRoute — one of six coarse semantic classes.
+type SemanticRoute string
+
+const (
+	RouteConversation SemanticRoute = "conversation"
+	RouteKnowledge    SemanticRoute = "knowledge"
+	RouteAction       SemanticRoute = "action"
+	RouteMemoryWrite  SemanticRoute = "memory_write"
+	RouteSystem       SemanticRoute = "system"
+	RouteUncertain    SemanticRoute = "uncertain"
+)
+
+// AllRoutes is the ordered set of valid routes, for iteration and confusion
+// matrix layout.
+var AllRoutes = []SemanticRoute{
+	RouteConversation,
+	RouteKnowledge,
+	RouteAction,
+	RouteMemoryWrite,
+	RouteSystem,
+	RouteUncertain,
+}
+
+// SemanticRouteDecision — the output of a coarse router. No slots, no
+// capability, no source — just the route, confidence, and whether the model
+// chose to abstain.
+type SemanticRouteDecision struct {
+	Route      SemanticRoute
+	Confidence float64
+	Abstain    bool
+	ModelID    string
+}
+
+// ValidRoute reports whether r is one of the six defined routes.
+func ValidRoute(r SemanticRoute) bool {
+	switch r {
+	case RouteConversation, RouteKnowledge, RouteAction,
+		RouteMemoryWrite, RouteSystem, RouteUncertain:
+		return true
+	}
+	return false
+}

internal/router/semantic/interface.go

@@ -0,0 +1,14 @@
+package semantic
+
+import "context"
+
+// SemanticRouter — the interface behind which experiment models run. The
+// implementation decides whether to consume MatchText; the contract here is
+// that Route returns a coarse decision without touching the authoritative
+// router's Intent, slots, capability, or source.
+//
+// A nil implementation is a valid floor — the shadow harness records
+// "no model" and continues.
+type SemanticRouter interface {
+	Route(ctx context.Context, text string) (SemanticRouteDecision, error)
+}

internal/router/semantic/legacy.go

@@ -0,0 +1,38 @@
+package semantic
+
+import "github.com/kami/maven/internal/router"
+
+// IntentToRoute maps the current seven-intent Decision.Intent to a coarse
+// semantic route. The mapping is deterministic and exists only for
+// baseline/evaluation — it does not change current routing behaviour.
+//
+// Mapping:
+//
+//	chat      → conversation
+//	query     → knowledge
+//	act       → action
+//	reminder  → action
+//	fact      → memory_write
+//	note      → memory_write
+//	system    → system
+//	unknown   → uncertain
+func IntentToRoute(intent router.Intent) SemanticRoute {
+	switch intent {
+	case router.IntentChat:
+		return RouteConversation
+	case router.IntentQuery:
+		return RouteKnowledge
+	case router.IntentAct:
+		return RouteAction
+	case router.IntentReminder:
+		return RouteAction
+	case router.IntentFact:
+		return RouteMemoryWrite
+	case router.IntentNote:
+		return RouteMemoryWrite
+	case router.IntentSystem:
+		return RouteSystem
+	default:
+		return RouteUncertain
+	}
+}