test(router): add explicit coverage for llm → semantic routing

.github/agents/refiner.agent.md

@@ -31,6 +31,20 @@ If critical input is missing, ask concise clarification questions first.
 
 ## Workflow
 
+0. RFC Gate (Architecture/Decision Precondition)
+- Before deep refinement, detect whether foundational decisions are unresolved.
+- Treat unresolved items as RFC blockers when they affect architecture, contracts, migration strategy, sequencing, security/compliance posture, or cross-team interfaces.
+- RFCs must be human-in-the-loop friendly:
+  - Prefer one RFC per decision question (avoid bundling unrelated decisions).
+  - Keep each RFC digestible for a human reviewer (clear problem, options, trade-offs, recommendation, explicit decision request).
+  - Avoid overwhelming wall-of-text RFCs; split large topics into focused RFCs.
+- If RFC blockers exist:
+  - Create or reference explicit RFC issue(s) that capture the open questions and decision options.
+  - Stop at RFC scope (do not produce full downstream implementation-ready sub-issue breakdown yet).
+  - State clearly that further refinement is blocked pending RFC resolution.
+  - Provide the minimal next-step checklist to unblock (owners, decision deadline, required outputs).
+- If no RFC blockers exist, continue with full refinement workflow.
+
 1. Analyze Scope
 - Read the epic and all linked issues fully.
 - Identify unknowns, assumptions, constraints, and external dependencies.
@@ -65,6 +79,23 @@ If critical input is missing, ask concise clarification questions first.
 - Add progress comments whenever substantive updates are made.
 - Summarize decisions and rationale in each issue comment.
 
+## KISS Project-Management Heuristic
+
+Default to the simplest tracking structure that preserves clarity.
+
+- **Do not create sub-issues** when work is tightly coupled, likely delivered in one PR, and estimated to stay small (rule of thumb: **~500 LOC or less** total change across touched files).
+- In those cases, keep a **single issue** with:
+  - one clear implementation approach,
+  - required vs preferred checklist items,
+  - one AC/DoD/Non-goal matrix.
+- Only split into sub-issues when at least one of these is true:
+  - distinct owners or teams are expected,
+  - independent sequencing/blocking relationships are required,
+  - meaningful parallelization is possible without merge contention,
+  - scope is large/uncertain enough that one issue reduces clarity.
+
+When uncertain, choose the single-issue path first and justify any split explicitly in the decision log.
+
 ## Output Requirements
 
 Deliverables must be clear, structured, and implementation-ready:
@@ -103,11 +134,13 @@ A refinement is complete only when:
 - Dependencies and sequencing are explicit
 - Coding agents can start without further product/architecture clarification
 
+If unresolved foundational decisions are present, refinement is not complete: it must stop at RFC issue(s) and explicitly mark deeper refinement as blocked until RFCs are resolved.
+
 If the source issue has no DoD section, refinement is not complete until a proposed DoD is authored and published in the tracking artifacts.
 
 ## Guardrails
 
 - Do not implement code.
 - Do not add unnecessary code examples.
 - Prefer generic, technology-agnostic requirement language unless stack specifics are essential.
-- Keep issue comments factual, decision-oriented, and audit-friendly.
+- Keep issue comments factual, decision-oriented, and audit-friendly.

api/src/services/query-router.test.ts

@@ -258,6 +258,23 @@ describe("classifyQuery — LLM fallback", () => {
     expect(result.strategy).toBe("graph");
     expect(result.confidence).toBe(0.9);
   });
+
+  it("accepts semantic strategy returned by LLM on low-confidence entity_pattern path", async () => {
+    vi.stubEnv("ROUTER_LLM_ENABLED", "true");
+    vi.stubEnv("OLLAMA_URL", "http://localhost:11434");
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ response: '{"strategy":"semantic","confidence":0.8}' }),
+    } as unknown as Response);
+    vi.stubGlobal("fetch", fetchMock);
+
+    const result = await classifyQuery({ query: "who is AuthService" });
+    expect(result.method).toBe("llm");
+    expect(result.strategy).toBe("semantic");
+    expect(result.confidence).toBe(0.8);
+    expect(result.rule).toBe("entity_pattern");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -337,6 +354,26 @@ describe("classifyQuery — OpenAI provider", () => {
     const body = JSON.parse(String(firstCall[1].body)) as { model: string };
     expect(body.model).toBe("gpt-4o-mini");
   });
+
+  it("accepts semantic strategy from OpenAI chat-completions on low-confidence entity_pattern path", async () => {
+    vi.stubEnv("ROUTER_LLM_ENABLED", "true");
+    vi.stubEnv("EMBED_PROVIDER", "openai");
+    vi.stubEnv("OPENAI_API_KEY", "test-key");
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        choices: [{ message: { content: '{"strategy":"semantic","confidence":0.8}' } }],
+      }),
+    } as unknown as Response);
+    vi.stubGlobal("fetch", fetchMock);
+
+    const result = await classifyQuery({ query: "who is AuthService" });
+    expect(result.method).toBe("llm");
+    expect(result.strategy).toBe("semantic");
+    expect(result.confidence).toBe(0.8);
+    expect(result.rule).toBe("entity_pattern");
+  });
 });
 
 // ---------------------------------------------------------------------------