refactor: apply low-effort structural cleanup (items 1, 2, 3, 6) (#20)

* refactor: apply low-effort structural cleanup items 1, 2, 3, 6

- Move TARGET_TO_CLAUDE_CLI into model_mappings.js; import in
  claude_cli_launcher.js so target definitions have one source of truth
- Extract ensureFile/readStore/writeStore into src/switchboard/fs-utils.js;
  session_store.js and route_context.js now import shared helpers
- Define ANTHROPIC_TARGETS_PATH once in paths.js; remove duplicate
  local definitions and dead __filename/__dirname boilerplate from
  workflow.js and claude_cli_launcher.js
- Rename deriveLegacyTurnFields -> extractTurnFields in route_context.js

All 89 tests pass.

* fix(review): restore path import in claude_cli_launcher; rename legacy variable

- Re-add 'node:path' import dropped during item 3 cleanup; appendLog
  still calls path.dirname() and would have thrown at runtime
- Rename local variable 'legacy' -> 'turnFields' in saveRouteContext
  for consistency with the extractTurnFields rename from item 6

Addresses Copilot review comments on PR #20.

* docs(refactoring): refresh completed-item references in plan

- Update item 1 mapping reference to current source location
- Replace stale item 3 file/line snippets with centralized paths constant
- Update item 6 naming from deriveLegacyTurnFields to extractTurnFields

---------

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

Author: hannasdev

docs/REFACTORING-PLAN.md

@@ -0,0 +1,104 @@
+# Refactoring Plan
+
+Findings from the May 2026 architecture review. Work on these one at a time. Mark items as **Done** when complete.
+
+---
+
+## 1. Unify target mappings — LOW effort / HIGH value
+
+**Problem:** Two parallel, unconnected mapping structures had to be kept in sync manually.
+
+- `src/adapters/model_mappings.js` — `targetId → profile → model` (used by SDK adapters)
+- `src/adapters/model_mappings.js` — `TARGET_TO_CLAUDE_CLI` (`targetId → { model, effort }`) (used by CLI path)
+
+Adding or renaming a target required updates in both places with no guardrail.
+
+**Status:** Done
+
+---
+
+## 2. Extract shared fs-utils — LOW effort
+
+**Problem:** `session_store.js` and `route_context.js` each define nearly identical private helpers:
+
+```js
+function ensureFile(storePath) { ... }
+function readStore(storePath) { ... }
+function writeStore(storePath, data) { ... }
+```
+
+Divergence risk: if one is fixed, the other silently stays broken.
+
+**Status:** Done
+
+---
+
+## 3. Hard-code `ANTHROPIC_TARGETS_PATH` in one place — LOW effort
+
+**Problem:** The same path was independently resolved in two files:
+
+```js
+// now centralized in src/switchboard/paths.js
+export const ANTHROPIC_TARGETS_PATH = path.join(__dirname, "..", "router", "data", "targets.anthropic.json");
+```
+
+**Status:** Done
+
+---
+
+## 4. Extract `explain` command from `workflow.js` — MEDIUM effort
+
+**Problem:** `workflow.js` handles session loading, routing coordination, log writing, context-package building, attribution construction, serialization helpers, the `explain` command, and continuity probes. It is both orchestrator and utility module.
+
+The `explain` command is conceptually separate — it reads past logs rather than driving a new turn — so it's the most obvious thing to split out.
+
+**Fix:** Create `src/switchboard/explain.js` that owns `explainLatestSwitchboardTurn`, `reconstructReasoning`, and related read-only log helpers. Import from `workflow.js` if needed, then remove the implementation there.
+
+**Status:** Not started
+
+---
+
+## 5. Separate prompt classifier from router — MEDIUM effort
+
+**Problem:** `router.js` mixes two distinct concerns:
+
+- `classifyPrompt` — keyword-matching heuristics that produce `taskType` / `proposedMode` signals
+- `routePrompt` — policy evaluation, hard/soft constraints, continuity cost, target selection
+
+The classifier produces signals; the router consumes them. They have different change rates and different test surfaces.
+
+**Fix:** Extract `classifyPrompt` (and its supporting constants like `TASK_TYPE_TO_ADDITIONAL_REQUIREMENTS`) into `src/router/classifier.js`. Keep `router.js` as the policy engine that imports from the classifier.
+
+**Status:** Not started
+
+---
+
+## 6. Remove or promote `extractTurnFields` — LOW effort
+
+**Problem:** `route_context.js` had a function named `deriveLegacyTurnFields`. The "legacy" label signaled it had been kept alive longer than intended and imposed a cognitive tax on every reader.
+
+**Status:** Done
+
+---
+
+## 7. Align file naming convention — LOW effort
+
+**Problem:** Source files use `snake_case` (`anthropic_claude_adapter.js`, `session_store.js`); test files use `kebab-case` (`claude-cli-launcher.test.js`, `thread-session-store.test.js`). Pairing a source file with its test requires a mental translation step.
+
+**Fix:** Decide on one convention (kebab-case is more common in the JS ecosystem) and rename files accordingly. Update all imports.
+
+**Status:** Not started
+
+---
+
+## Order of execution
+
+| # | Item | Effort | Notes |
+|---|------|--------|-------|
+| 1 | Unify target mappings | Low | Do first — prevents divergence bugs |
+| 2 | Shared fs-utils | Low | Quick win, reduces duplication |
+| 3 | Paths constant | Low | Quick win, no logic changes |
+| 6 | Legacy field | Low | Audit first to confirm safe to delete |
+| 4 | Extract explain | Medium | Biggest readability gain in workflow.js |
+| 5 | Separate classifier | Medium | Makes router independently testable |
+| 7 | File naming | Low | Do last — touches many files at once |

src/adapters/model_mappings.js

@@ -34,6 +34,12 @@ export const PROFILE_MODEL_MAP = {
   }
 };
 
+export const TARGET_TO_CLAUDE_CLI = {
+  "anthropic-quick": { model: "haiku", effort: "low" },
+  "anthropic-balanced": { model: "sonnet", effort: "medium" },
+  "anthropic-coder": { model: "sonnet", effort: "high" }
+};
+
 export function getTargetProfileMap(vendor) {
   return TARGET_PROFILE_MAP[vendor] || {};
 }

src/switchboard/claude_cli_launcher.js

@@ -2,19 +2,10 @@ import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { TARGET_TO_CLAUDE_CLI } from "../adapters/model_mappings.js";
+import { ANTHROPIC_TARGETS_PATH } from "./paths.js";
 import { routePrompt } from "../router/router.js";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const ANTHROPIC_TARGETS_PATH = path.join(__dirname, "..", "router", "data", "targets.anthropic.json");
-
-const TARGET_TO_CLAUDE_CLI = {
-  "anthropic-quick": { model: "haiku", effort: "low" },
-  "anthropic-balanced": { model: "sonnet", effort: "medium" },
-  "anthropic-coder": { model: "sonnet", effort: "high" }
-};
-
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }

src/switchboard/fs-utils.js

@@ -0,0 +1,17 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function ensureFile(storePath) {
+  fs.mkdirSync(path.dirname(storePath), { recursive: true });
+  if (!fs.existsSync(storePath)) fs.writeFileSync(storePath, "{}\n", "utf8");
+}
+
+export function readStore(storePath) {
+  ensureFile(storePath);
+  return JSON.parse(fs.readFileSync(storePath, "utf8"));
+}
+
+export function writeStore(storePath, data) {
+  ensureFile(storePath);
+  fs.writeFileSync(storePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}

src/switchboard/paths.js

@@ -1,8 +1,13 @@
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 export const DEFAULT_SWITCHBOARD_STATE_DIR = path.join(os.homedir(), ".model-switchboard");
 export const DEFAULT_SWITCHBOARD_STORE_PATH = path.join(DEFAULT_SWITCHBOARD_STATE_DIR, "switchboard-sessions.json");
 export const DEFAULT_SWITCHBOARD_LOG_PATH = path.join(DEFAULT_SWITCHBOARD_STATE_DIR, "switchboard-turns.ndjson");
 export const DEFAULT_ROUTE_CONTEXT_PATH = path.join(DEFAULT_SWITCHBOARD_STATE_DIR, "switchboard-route-context.json");
 export const DEFAULT_CLAUDE_HOOK_LOG_PATH = path.join(DEFAULT_SWITCHBOARD_STATE_DIR, "claude-hook-events.ndjson");
+export const ANTHROPIC_TARGETS_PATH = path.join(__dirname, "..", "router", "data", "targets.anthropic.json");

src/switchboard/route_context.js

@@ -1,25 +1,9 @@
-import fs from "node:fs";
-import path from "node:path";
 import { DEFAULT_ROUTE_CONTEXT_PATH } from "./paths.js";
+import { readStore, writeStore } from "./fs-utils.js";
 
 export { DEFAULT_ROUTE_CONTEXT_PATH } from "./paths.js";
 
-function ensureFile(storePath) {
-  fs.mkdirSync(path.dirname(storePath), { recursive: true });
-  if (!fs.existsSync(storePath)) fs.writeFileSync(storePath, "{}\n", "utf8");
-}
-
-function readStore(storePath) {
-	ensureFile(storePath);
-	return JSON.parse(fs.readFileSync(storePath, "utf8"));
-}
-
-function writeStore(storePath, store) {
-	ensureFile(storePath);
-	fs.writeFileSync(storePath, `${JSON.stringify(store, null, 2)}\n`, "utf8");
-}
-
-function deriveLegacyTurnFields(context = {}) {
+function extractTurnFields(context = {}) {
 	const sessionState = context.sessionState || null;
 	const routingDecision = context.routingDecision || null;
 	const contextPackage = context.contextPackage || null;
@@ -83,18 +67,18 @@ export function saveRouteContext({
 
 	const store = readStore(storePath);
 	const existing = store[sessionId] || { turns: [] };
-	const legacy = deriveLegacyTurnFields(context);
+	const turnFields = extractTurnFields(context);
 	const turn = {
-		threadId: legacy.threadId,
+		threadId: turnFields.threadId,
 		claudeSessionId: sessionId,
-		turnCount: legacy.turnCount,
-		routeLabel: legacy.routeLabel,
-		targetId: legacy.targetId,
-		model: legacy.model,
-		effort: legacy.effort,
-		mode: legacy.mode,
-		executionMode: legacy.executionMode,
-		wrapperContext: legacy.wrapperContext,
+		turnCount: turnFields.turnCount,
+		routeLabel: turnFields.routeLabel,
+		targetId: turnFields.targetId,
+		model: turnFields.model,
+		effort: turnFields.effort,
+		mode: turnFields.mode,
+		executionMode: turnFields.executionMode,
+		wrapperContext: turnFields.wrapperContext,
 		sessionState: context.sessionState || null,
 		routingDecision: context.routingDecision || null,
 		contextPackage: context.contextPackage || null,

src/switchboard/session_store.js

@@ -1,20 +1,4 @@
-import fs from "node:fs";
-import path from "node:path";
-
-function ensureFile(storePath) {
-  fs.mkdirSync(path.dirname(storePath), { recursive: true });
-  if (!fs.existsSync(storePath)) fs.writeFileSync(storePath, "{}\n", "utf8");
-}
-
-function readStore(storePath) {
-  ensureFile(storePath);
-  return JSON.parse(fs.readFileSync(storePath, "utf8"));
-}
-
-function writeStore(storePath, data) {
-  ensureFile(storePath);
-  fs.writeFileSync(storePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
-}
+import { readStore, writeStore } from "./fs-utils.js";
 
 export function loadThreadSession({ storePath, threadId }) {
   const store = readStore(storePath);

src/switchboard/workflow.js

@@ -2,9 +2,9 @@ import { randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { planClaudeCliLaunch } from "./claude_cli_launcher.js";
 import {
+  ANTHROPIC_TARGETS_PATH,
   DEFAULT_SWITCHBOARD_LOG_PATH,
   DEFAULT_SWITCHBOARD_STORE_PATH
 } from "./paths.js";
@@ -23,10 +23,6 @@ export {
   DEFAULT_SWITCHBOARD_STORE_PATH
 } from "./paths.js";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const ANTHROPIC_TARGETS_PATH = path.join(__dirname, "..", "router", "data", "targets.anthropic.json");
-
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }