refactor: clarify investigation map as ux placeholder

lib/map/investigation-map-adapter.js

@@ -1,50 +1,46 @@
 /**
- * Investigation Map Mock Adapter
- *
- * Provides the Investigation Map with a set of investigation topics and their
- * current status (established / current / unknown).
- *
- * TODO: Replace this mock adapter when the reasoning engine emits real
- * investigation data. The eventual contract should provide:
- *   - `investigationTopics`: [{ title, status, evidenceCount? }]
- *   - `topicStatus` values: "established" | "current" | "unknown"
- *   - `topicOrdering`: the reasoning-engine-determined sequence
- *   - `evidenceCount`: optional count of supporting evidence per topic
- *
- * Until then, this adapter drives a realistic mock progression across turns.
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  INVESTIGATION MAP — UX PLACEHOLDER ADAPTER                          │
+ * │                                                                      │
+ * │  This adapter drives a minimal mock to validate UX placement,        │
+ * │  spacing, status appearance, responsive behaviour, and state         │
+ * │  change across turns.                                                │
+ * │                                                                      │
+ * │  The topic names below are mock-only placeholders. They are NOT       │
+ * │  part of the reasoning contract and do NOT imply the final map       │
+ * │  structure — which may be hierarchical, grouped, branching, or       │
+ * │  something else entirely.                                            │
+ * │                                                                      │
+ * │  The UI will eventually consume real reasoning output once that      │
+ * │  design stabilises.                                                  │
+ * └─────────────────────────────────────────────────────────────────────┘
  */
 
-/** @type {Array<{ title: string }>} */
+/** @type {Array<{ title: string }>} — mock-only placeholder names */
 const TOPICS = [
-  { title: "Central situation" },
-  { title: "Complaint trend direction" },
-  { title: "Measurement basis" },
-  { title: "Production volume context" },
-  { title: "QA process changes" },
-  { title: "Product change log" },
-  { title: "Support response patterns" },
-  { title: "Prior similar cases" },
+  { title: "Starting point" },
+  { title: "What is known" },
+  { title: "Current focus" },
+  { title: "Questions still open" },
+  { title: "Possible explanations" },
 ];
 
 /**
  * Status progression per turn index.
  * The reasoning engine will eventually determine these values.
+ *
+ * With N placeholder topics we have N-1 progressive states (indices 0 to N-2).
+ * Beyond that the map stabilises: all topics established except the last one current.
  */
 const PROGRESSION = [
   // Turn 0 — initial analysis just started
-  ["established", "unknown", "unknown", "unknown", "unknown", "unknown", "unknown", "unknown"],
+  ["established", "current", "unknown", "unknown", "unknown"],
   // Turn 1 — first question answered
-  ["established", "established", "current", "unknown", "unknown", "unknown", "unknown", "unknown"],
+  ["established", "established", "current", "unknown", "unknown"],
   // Turn 2 — second question answered
-  ["established", "established", "established", "current", "unknown", "unknown", "unknown", "unknown"],
-  // Turn 3 — third question answered
-  ["established", "established", "established", "established", "current", "unknown", "unknown", "unknown"],
-  // Turn 4 — fourth question answered
-  ["established", "established", "established", "established", "established", "current", "unknown", "unknown"],
-  // Turn 5 — fifth question answered
-  ["established", "established", "established", "established", "established", "established", "current", "unknown"],
-  // Turn 6+ — final turn
-  ["established", "established", "established", "established", "established", "established", "established", "current"],
+  ["established", "established", "established", "current", "unknown"],
+  // Turn 3+ — third answer and beyond (all topics resolved, last in progress)
+  ["established", "established", "established", "established", "current"],
 ];
 
 /**
@@ -53,7 +49,8 @@ const PROGRESSION = [
  * @returns {{ title: string, status: 'established' | 'current' | 'unknown' }[]}
  */
 export function getInvestigationMapTopics(turnIndex) {
-  const idx = Math.min(turnIndex, PROGRESSION.length - 1);
+  // Clamp to last progression entry so the map stabilises when all topics are covered
+  const idx = Math.min(Math.max(turnIndex, 0), PROGRESSION.length - 1);
   return TOPICS.map((topic, i) => ({
     title: topic.title,
     status: PROGRESSION[idx][i],