opencode-usage-coach 0.7.1 → 0.8.0

package/dist/index.js

@@ -41,6 +41,14 @@ function addDomainNode(node) {
   }
   return full.id;
 }
+function addDomainEdge(edge) {
+  const full = { ...edge, ts: (/* @__PURE__ */ new Date()).toISOString() };
+  try {
+    mkdirSync(BASE_DIR, { recursive: true });
+    appendFileSync(edgesFile(), JSON.stringify(full) + "\n");
+  } catch {
+  }
+}
 function writeNodes(nodes) {
   try {
     mkdirSync(BASE_DIR, { recursive: true });
@@ -97,14 +105,74 @@ function evictStale(maxAgeDays = 30, maxNodes = 1e3) {
     return { removed: 0, kept: 0 };
   }
 }
-function saveInvestigationResult(keywords, result, source) {
+function traverseNeighborhood(seedNodeIds, maxDepth = 2, opts = {}) {
+  const maxNodes = opts.maxNodes ?? 60;
+  const allNodes = readNodes();
+  const allEdges = readEdges();
+  const byId = new Map(allNodes.map((n) => [n.id, n]));
+  const seeds = seedNodeIds.filter((id) => byId.has(id));
+  if (seeds.length === 0) return { nodes: [], edges: [] };
+  const adj = /* @__PURE__ */ new Map();
+  const link = (a, b) => {
+    const s = adj.get(a) ?? /* @__PURE__ */ new Set();
+    s.add(b);
+    adj.set(a, s);
+  };
+  for (const e of allEdges) {
+    link(e.from, e.to);
+    link(e.to, e.from);
+  }
+  const distance = /* @__PURE__ */ new Map();
+  const visited = /* @__PURE__ */ new Set();
+  const frontier = [];
+  for (const s of seeds) {
+    if (visited.has(s)) continue;
+    visited.add(s);
+    distance.set(s, 0);
+    frontier.push(s);
+    if (visited.size >= maxNodes) break;
+  }
+  while (frontier.length > 0) {
+    if (visited.size >= maxNodes) break;
+    const cur = frontier.shift();
+    const d = distance.get(cur) ?? 0;
+    if (d >= maxDepth) continue;
+    for (const nxt of adj.get(cur) ?? []) {
+      if (visited.has(nxt)) continue;
+      visited.add(nxt);
+      distance.set(nxt, d + 1);
+      frontier.push(nxt);
+      if (visited.size >= maxNodes) break;
+    }
+  }
+  const nodes = [];
+  for (const id of visited) {
+    const n = byId.get(id);
+    if (n) nodes.push({ ...n, distance: distance.get(id) ?? 0 });
+  }
+  const edges = allEdges.filter((e) => visited.has(e.from) && visited.has(e.to));
+  return { nodes, edges };
+}
+function queryDomainGraph(keywords, maxDepth = 2, opts = {}) {
+  const seed = queryDomain(keywords);
+  const seedIds = seed.nodes.map((n) => n.id);
+  if (maxDepth <= 0 || seedIds.length === 0) {
+    return { nodes: seed.nodes, edges: seed.edges };
+  }
+  const graph = traverseNeighborhood(seedIds, maxDepth, opts);
+  const seedSet = new Set(seedIds);
+  const neighborIds = graph.nodes.filter((n) => !seedSet.has(n.id)).map((n) => n.id);
+  if (neighborIds.length > 0) touchNodes(new Set(neighborIds));
+  return { nodes: graph.nodes, edges: graph.edges };
+}
+function saveInvestigationResult(keywords, result, source, confidence = 0.7) {
   try {
     return addDomainNode({
       type: "fact",
       name: keywords.join(" "),
       props: { result },
       source: source || "investigation",
-      confidence: 0.7
+      confidence
     });
   } catch {
     return "";
@@ -116,6 +184,7 @@ var PLUGIN_NAME = "opencode-usage-coach";
 var TTL_MS = Number(process.env.UC_TTL_MS ?? 6e4);
 var DEFAULT_MAX_STEPS = Number(process.env.UC_MAX_STEPS ?? 30) || 30;
 var WATCHDOG_POLL_MS = Math.max(1e3, Number(process.env.UC_WATCHDOG_POLL_MS ?? 3e3) || 3e3);
+var DEFAULT_MAX_QUESTIONS = Math.max(1, Math.round(Number(process.env.UC_MAX_QUESTIONS ?? 7)) || 7);
 var PIPE_LOG = join2(homedir(), ".cache", "opencode-usage-coach", "pipeline.log");
 function pipeLog(msg) {
   try {
@@ -169,6 +238,106 @@ function readRules() {
     return "";
   }
 }
+function implNotesFile() {
+  return join2(STATE_DIR, "impl-notes.md");
+}
+var IMPL_NOTE_INSTRUCTION = `
+## Implementation Notes (important!)
+During this task, if you:
+  - Made a decision that differed from the obvious/expected approach
+  - Discovered a constraint, limitation, or surprising behavior in the codebase/API
+  - Found something that was different from what the prompt implied
+Then append a block at the END of your response in this exact format:
+
+<impl-notes>
+- **Decision**: <what you chose and why it wasn't obvious>
+- **Constraint**: <limitation/surprise you discovered>
+- **Unexpected**: <how reality differed from the prompt's assumption>
+</impl-notes>
+
+If nothing notable happened, omit the block entirely. Do not fabricate notes.
+`;
+function readImplNotes(limit = 5) {
+  try {
+    const f = implNotesFile();
+    if (!existsSync2(f)) return "";
+    const content = readFileSync2(f, "utf8").trim();
+    if (!content) return "";
+    const notes = content.split(/^## Note /m).filter(Boolean);
+    const recent = notes.slice(-limit);
+    return recent.map((n) => `## Note ${n.trim()}`).join("\n\n");
+  } catch {
+    return "";
+  }
+}
+function extractImplNotes(output) {
+  const match = output.match(/<impl-notes>([\s\S]*?)<\/impl-notes>/i);
+  if (!match) return { notes: "", cleanText: output };
+  const notes = match[1].trim();
+  const cleanText = output.replace(/<impl-notes>[\s\S]*?<\/impl-notes>\s*/i, "").trim();
+  return { notes, cleanText };
+}
+function appendImplNotes(notes, taskSummary) {
+  try {
+    const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    const shortTask = taskSummary.slice(0, 80).replace(/\n/g, " ");
+    const entry = `## Note (${date}, task: "${shortTask}")
+${notes}
+Source: generate task "${shortTask}"
+
+`;
+    mkdirSync2(STATE_DIR, { recursive: true });
+    appendFileSync2(implNotesFile(), entry);
+  } catch (e) {
+    log(`appendImplNotes err: ${String(e)}`);
+  }
+}
+function linkImplNoteToDomain(noteNodeId, noteText, maxEdges = 3) {
+  try {
+    const words = new Set(
+      noteText.toLowerCase().replace(/[^a-z0-9가-힣\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 3)
+    );
+    if (words.size === 0) return 0;
+    const existing = readNodes().filter((n) => n.id !== noteNodeId);
+    const scored = existing.map((n) => {
+      const hay = (n.name + " " + JSON.stringify(n.props)).toLowerCase();
+      let hits = 0;
+      for (const w of words) if (hay.includes(w)) hits++;
+      return { node: n, hits };
+    }).filter((s) => s.hits > 0).sort((a, b) => b.hits - a.hits).slice(0, maxEdges);
+    const edgeKey = new Set(readEdges().map((e) => `${e.from}|${e.to}|${e.rel}`));
+    let added = 0;
+    for (const { node } of scored) {
+      const k1 = `${noteNodeId}|${node.id}|related-to`;
+      const k2 = `${node.id}|${noteNodeId}|related-to`;
+      if (edgeKey.has(k1) || edgeKey.has(k2)) continue;
+      addDomainEdge({ from: noteNodeId, to: node.id, rel: "related-to", note: "impl-note auto-link" });
+      edgeKey.add(k1);
+      added++;
+    }
+    return added;
+  } catch {
+    return 0;
+  }
+}
+function readImplNotesByGraph(keywords, limit = 5) {
+  try {
+    if (!keywords.length) return readImplNotes(limit);
+    const { nodes: neighborhood } = queryDomainGraph(keywords, 2);
+    if (neighborhood.length === 0) return readImplNotes(limit);
+    const noteTexts = neighborhood.filter((n) => n.source === "impl-note" || n.source === "generate").map((n) => String(n.props?.result ?? ""));
+    if (noteTexts.length === 0) return readImplNotes(limit);
+    const f = implNotesFile();
+    const fileContent = existsSync2(f) ? readFileSync2(f, "utf8") : "";
+    if (!fileContent.trim()) return readImplNotes(limit);
+    const entries = fileContent.split(/^## Note /m).filter(Boolean);
+    const matched = entries.filter((e) => noteTexts.some((t) => t && e.includes(t.slice(0, 60)))).slice(0, limit);
+    if (matched.length === 0) return readImplNotes(limit);
+    return matched.map((e) => `## Note ${e.trim()}`).join("\n\n");
+  } catch {
+    return readImplNotes(limit);
+  }
+}
 function extractKeywords(text) {
   try {
     const STOP = /* @__PURE__ */ new Set(["the", "and", "for", "with", "that", "this", "from", "into", "your", "you", "are", "was", "but", "not", "all", "any", "use", "task", "prompt"]);
@@ -207,6 +376,136 @@ function writeHarness(sessionID, h) {
   } catch {
   }
 }
+function interviewFile(sessionID) {
+  return join2(STATE_DIR, sessionID || "_default", "interview.json");
+}
+function readInterview(sessionID) {
+  try {
+    const f = interviewFile(sessionID);
+    if (!existsSync2(f)) return null;
+    return JSON.parse(readFileSync2(f, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeInterview(sessionID, s) {
+  try {
+    const f = interviewFile(sessionID);
+    mkdirSync2(dirname(f), { recursive: true });
+    s.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    writeFileSync2(f, JSON.stringify(s, null, 2));
+  } catch {
+  }
+}
+var PRIORITY_WEIGHT = { critical: 0, high: 1, medium: 2, low: 3 };
+var CATEGORY_WEIGHT = { architecture: 0, scope: 1, constraint: 2, tradeoff: 3, preference: 4, "constraint-env": 5 };
+function resolveGraphDistance(concept, graphNodes) {
+  if (!concept) return 9;
+  const lc = concept.toLowerCase().trim();
+  if (!lc) return 9;
+  for (const n of graphNodes) {
+    if ((n.name ?? "").toLowerCase() === lc) return n.distance ?? 9;
+  }
+  for (const n of graphNodes) {
+    const nm = (n.name ?? "").toLowerCase();
+    if (nm.includes(lc) || lc.includes(nm)) return n.distance ?? 9;
+  }
+  return 9;
+}
+function parseInterviewQuestions(raw, maxQ, graphNodes) {
+  try {
+    let s = raw.trim();
+    const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fence) s = fence[1].trim();
+    const first = s.indexOf("{");
+    const last = s.lastIndexOf("}");
+    if (first >= 0 && last > first) s = s.slice(first, last + 1);
+    const p = JSON.parse(s);
+    const arr = Array.isArray(p.questions) ? p.questions : [];
+    const qs = arr.map((q) => ({
+      id: `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
+      text: String(q.text || ""),
+      why: String(q.why || ""),
+      priority: ["critical", "high", "medium", "low"].includes(String(q.priority)) ? String(q.priority) : "medium",
+      category: String(q.category || "scope"),
+      optional: Boolean(q.optional),
+      concept: q.concept ? String(q.concept) : void 0
+    })).filter((q) => q.text);
+    qs.sort((a, b) => {
+      const ka = (PRIORITY_WEIGHT[a.priority] ?? 3) * 100 + resolveGraphDistance(a.concept, graphNodes) * 10 + (CATEGORY_WEIGHT[a.category] ?? 5);
+      const kb = (PRIORITY_WEIGHT[b.priority] ?? 3) * 100 + resolveGraphDistance(b.concept, graphNodes) * 10 + (CATEGORY_WEIGHT[b.category] ?? 5);
+      return ka - kb;
+    });
+    return qs.slice(0, maxQ);
+  } catch {
+    return [];
+  }
+}
+function formatQuestionOutput(qNum, total, q) {
+  return `Interview Q${qNum}/${total} [${q.priority}]: ${q.text}
+` + (q.why ? `  Why it matters: ${q.why}
+` : "") + `
+[usage-coach NEXT] Present Q${qNum}/${total} to the user VERBATIM (copy the question text above). Do NOT answer it yourself \u2014 you are interviewing the USER, not guessing. End your turn after presenting the question. When the user responds, call reverse_interview({task: "...", answer: "<their response>"}) to record the answer and get the next question.`;
+}
+function formatCompleteOutput(state) {
+  const n = state.answers.length;
+  const lines = [`Interview complete (${n} question${n === 1 ? "" : "s"} answered).`, "", "Resolved constraints:"];
+  if (state.answers.length) {
+    state.answers.forEach((a, i) => lines.push(`${i + 1}. ${a.questionText}: ${a.answer}`));
+  } else {
+    lines.push("(no questions were asked)");
+  }
+  lines.push("");
+  lines.push("[usage-coach NEXT] Interview complete. The resolved constraints above MUST be injected into every generate prompt. Call harness_start(name, N) now, then for each task call generate with the constraints prepended to the prompt.");
+  return lines.join("\n");
+}
+async function completeInterview(state, sessionID, client, model, directory) {
+  if (state.phase === "complete") return formatCompleteOutput(state);
+  const pairs = state.answers.map((a, i) => `Q${i + 1}: ${a.questionText}
+A: ${a.answer}`).join("\n\n");
+  let summary = "";
+  const constraints = {};
+  if (model) {
+    const sumPrompt = `Summarize this reverse interview as actionable constraints for implementation.
+
+Q&A pairs:
+${pairs || "(none)"}
+
+Output JSON ONLY (no markdown fences, no prose):
+{"summary":"human-readable bullet list of resolved decisions","constraints":{"key":"value"}}`;
+    const out = await runModel(client, model, sumPrompt, directory);
+    if (!out.startsWith("ERROR:") && !out.startsWith("Task appears too large")) {
+      try {
+        let s = out.trim();
+        const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/);
+        if (fence) s = fence[1].trim();
+        const fi = s.indexOf("{");
+        const la = s.lastIndexOf("}");
+        if (fi >= 0 && la > fi) s = s.slice(fi, la + 1);
+        const p = JSON.parse(s);
+        summary = String(p.summary ?? "");
+        if (p.constraints && typeof p.constraints === "object") {
+          for (const [k, v] of Object.entries(p.constraints)) constraints[String(k)] = String(v);
+        }
+      } catch {
+      }
+    }
+  }
+  if (!summary) {
+    summary = state.answers.length ? state.answers.map((a, i) => `${i + 1}. ${a.questionText}: ${a.answer}`).join("\n") : "No significant ambiguities found. The task appears well-specified.";
+  }
+  state.summary = summary;
+  state.constraints = constraints;
+  state.phase = "complete";
+  writeInterview(sessionID, state);
+  try {
+    const kw = extractKeywords(state.task);
+    if (kw.length) saveInvestigationResult(kw, summary, "reverse_interview", 0.9);
+  } catch (e) {
+    log(`reverse_interview save err: ${String(e)}`);
+  }
+  return formatCompleteOutput(state);
+}
 function updateSubSession(sessionID, taskId, fields) {
   try {
     const h = readHarness(sessionID);
@@ -241,6 +540,308 @@ function findActiveTaskId(sessionID, status) {
     return void 0;
   }
 }
+var MANIFEST_FILES_SET = /* @__PURE__ */ new Set([
+  "package.json",
+  "go.mod",
+  "requirements.txt",
+  "pyproject.toml",
+  "Cargo.toml",
+  "deno.json",
+  "pom.xml",
+  "build.gradle",
+  "mix.exs",
+  "Gemfile"
+]);
+var FRAMEWORK_SIG = {
+  "react": ["react", "react-dom", "next"],
+  "solid-js": ["solid-js", "@opentui/solid"],
+  "vue": ["vue", "nuxt"],
+  "svelte": ["svelte", "@sveltejs/kit"],
+  "express": ["express"],
+  "fastify": ["fastify"],
+  "hono": ["hono"],
+  "vitest": ["vitest"],
+  "jest": ["jest"],
+  "tsup": ["tsup"],
+  "eslint": ["eslint"]
+};
+function parseFileList(rawList, baseDir) {
+  const empty = {
+    skipped: false,
+    language: "unknown",
+    frameworks: [],
+    structure: [],
+    manifestFiles: [],
+    keyDeps: [],
+    configFiles: [],
+    totalFiles: 0
+  };
+  try {
+    const lines = (rawList || "").split("\n").map((l) => l.trim()).filter(Boolean);
+    if (lines.length === 0) return { ...empty, skipped: true, reason: "no files found" };
+    const relFiles = lines.map((l) => l.startsWith(baseDir) ? l.slice(baseDir.length).replace(/^\//, "") : l).slice(0, 200);
+    const extCounts = {};
+    for (const f of relFiles) {
+      const dot = f.lastIndexOf(".");
+      if (dot >= 0) {
+        const ext = f.slice(dot + 1).toLowerCase();
+        extCounts[ext] = (extCounts[ext] || 0) + 1;
+      }
+    }
+    const language = detectLanguage(extCounts);
+    const manifestFiles = relFiles.filter((f) => {
+      const base = f.split("/").pop() || f;
+      return MANIFEST_FILES_SET.has(base);
+    });
+    let keyDeps = [];
+    let frameworks = [];
+    let testPattern;
+    let testFramework;
+    for (const mf of manifestFiles) {
+      const full = join2(baseDir, mf);
+      if (existsSync2(full)) {
+        try {
+          const content = JSON.parse(readFileSync2(full, "utf8"));
+          const depNames = Object.keys({ ...content.dependencies || {}, ...content.devDependencies || {} });
+          keyDeps = [.../* @__PURE__ */ new Set([...keyDeps, ...depNames])].slice(0, 50);
+          for (const [fw, sigs] of Object.entries(FRAMEWORK_SIG)) {
+            if (sigs.some((s) => depNames.includes(s))) frameworks = [.../* @__PURE__ */ new Set([...frameworks, fw])];
+          }
+          if (depNames.includes("vitest")) testFramework = "vitest";
+          else if (depNames.includes("jest")) testFramework = "jest";
+          else if (depNames.includes("pytest")) testFramework = "pytest";
+        } catch {
+        }
+      }
+    }
+    const testFiles = relFiles.filter(
+      (f) => /\.(test|spec)\.(ts|tsx|js|jsx|mjs)$/.test(f) || /(^|\/)(test_[^.]+|.+_test)\.(py|go)$/.test(f)
+    );
+    if (testFiles.length) {
+      const m = testFiles[0].match(/(\.(test|spec)\.[a-z]+|test_[a-z]+\.(py|go)|_[a-z]+_test\.(py|go))$/i);
+      if (m) testPattern = "*" + m[0];
+    }
+    const configFiles = relFiles.filter(
+      (f) => /\.(eslintrc|prettierrc|tsconfig|jsconfig|babelrc|stylelintrc)/.test(f) || f.endsWith("tsconfig.json") || f.endsWith(".eslintrc") || f.endsWith(".prettierrc")
+    );
+    const dirCounts = {};
+    for (const f of relFiles) {
+      const parts = f.split("/");
+      const dir = parts.length > 1 ? parts[0] : ".";
+      dirCounts[dir] = (dirCounts[dir] || 0) + 1;
+    }
+    const structure = Object.entries(dirCounts).map(([dir, fileCount]) => ({ dir, fileCount })).sort((a, b) => b.fileCount - a.fileCount).slice(0, 8);
+    return {
+      skipped: false,
+      language,
+      frameworks,
+      testPattern,
+      testFramework,
+      structure,
+      manifestFiles,
+      keyDeps,
+      configFiles,
+      totalFiles: lines.length
+    };
+  } catch {
+    return { ...empty, skipped: true, reason: "scan error" };
+  }
+}
+function detectLanguage(extCounts) {
+  const sum = (exts) => exts.reduce((s, e) => s + (extCounts[e] || 0), 0);
+  const ts = sum(["ts", "tsx", "mts", "cts"]);
+  const js = sum(["js", "jsx", "mjs", "cjs"]);
+  if (ts > 0 && ts >= js) return "TypeScript";
+  if (js > 0) return "JavaScript";
+  if ((extCounts["py"] || 0) > 0) return "Python";
+  if ((extCounts["go"] || 0) > 0) return "Go";
+  if ((extCounts["rs"] || 0) > 0) return "Rust";
+  if ((extCounts["java"] || 0) > 0) return "Java";
+  return "unknown";
+}
+function buildGapPrompt(userRequest, tasks, profile, domainNodes) {
+  const taskList = tasks.map((t) => `${t.id}: ${t.title}`).join("\n");
+  const profileStr = profile.skipped ? `(skipped \u2014 ${profile.reason || "unknown reason"})` : [
+    `- Language: ${profile.language}`,
+    `- Frameworks: ${profile.frameworks.join(", ") || "none detected"}`,
+    `- Test pattern: ${profile.testPattern || "not detected"} (${profile.testFramework || "?"})`,
+    `- Structure: ${profile.structure.map((s) => `${s.dir}/(${s.fileCount})`).join(", ")}`,
+    `- Manifest: ${profile.manifestFiles.join(", ") || "none"}`,
+    `- Key deps: ${profile.keyDeps.slice(0, 20).join(", ") || "none"}`,
+    `- Config: ${profile.configFiles.join(", ") || "none"}`,
+    `- Total files: ${profile.totalFiles}`
+  ].join("\n");
+  const domainStr = domainNodes.length ? domainNodes.slice(0, 15).map((n) => `- ${n.name}: ${JSON.stringify(n.props).slice(0, 200)}`).join("\n") : "(empty \u2014 no prior knowledge stored)";
+  return `You are a pre-flight gap analyst. Compare the user's request (the MAP) with the actual codebase (the TERRITORY) and classify every gap.
+
+USER REQUEST:
+${userRequest}
+
+PROPOSED TASKS:
+${taskList}
+
+CODEBASE PROFILE:
+${profileStr}
+
+EXISTING DOMAIN KNOWLEDGE (from local DB):
+${domainStr}
+
+Classify into EXACTLY these 4 categories:
+
+1. KNOWN KNOWNS \u2014 requirements explicitly stated in the user request.
+   For each: which task it maps to, and the specific requirement.
+2. KNOWN UNKNOWNS \u2014 the user left ambiguous / didn't specify.
+   For each: what is ambiguous, which task it affects, and a suggestion.
+3. UNKNOWN KNOWNS \u2014 implicit knowledge in the codebase not mentioned in the prompt
+   (conventions, patterns, dependencies, tool registration style, test framework).
+   For each: the finding and where in the codebase it comes from.
+4. UNKNOWN UNKNOWNS \u2014 blind spots: things neither the prompt nor the codebase surface,
+   but that WILL affect the work (platform quirks, hidden coupling, ordering deps).
+   For each: the finding, its impact (high/medium/low), and a mitigation.
+
+Also output:
+- QUESTIONS: questions the agent should ask the user before proceeding.
+  Only include questions where the answer materially changes the approach.
+- TASK REFINEMENTS: suggestions to split, merge, reorder, add, or remove tasks.
+
+Output as JSON ONLY (no markdown fences, no prose before or after):
+{"knownKnowns":[{"taskId":1,"title":"","note":"requirement from prompt"}],"knownUnknowns":[{"taskId":1,"gap":"what is ambiguous","suggestion":"how to resolve"}],"unknownKnowns":[{"finding":"implicit knowledge","source":"file or pattern"}],"unknownUnknowns":[{"finding":"blind spot","impact":"high","mitigation":"how to handle"}],"questions":[{"id":"Q1","question":"..."}],"taskRefinements":[{"taskId":1,"action":"split","detail":"..."}]}`;
+}
+function parseGapAnalysis(raw, profile, domainHits) {
+  const scannedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const base = {
+    scannedAt,
+    codebaseProfile: profile,
+    knownKnowns: [],
+    knownUnknowns: [],
+    unknownKnowns: [],
+    unknownUnknowns: [],
+    questions: [],
+    taskRefinements: [],
+    domainHits,
+    domainMisses: 0
+  };
+  if (!raw || raw.startsWith("ERROR:") || raw.startsWith("Task appears too large")) {
+    base.rawAnalysis = raw;
+    return base;
+  }
+  try {
+    let jsonStr = raw.trim();
+    const fence = jsonStr.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fence) jsonStr = fence[1].trim();
+    const first = jsonStr.indexOf("{");
+    const last = jsonStr.lastIndexOf("}");
+    if (first >= 0 && last > first) jsonStr = jsonStr.slice(first, last + 1);
+    const p = JSON.parse(jsonStr);
+    const arr = (v, map) => Array.isArray(v) ? v.map(map) : [];
+    base.knownKnowns = arr(p.knownKnowns, (k) => ({
+      taskId: Number(k.taskId) || 0,
+      title: String(k.title || ""),
+      note: String(k.note || "")
+    }));
+    base.knownUnknowns = arr(p.knownUnknowns, (k) => ({
+      taskId: Number(k.taskId) || 0,
+      gap: String(k.gap || ""),
+      suggestion: k.suggestion ? String(k.suggestion) : void 0
+    }));
+    base.unknownKnowns = arr(p.unknownKnowns, (k) => ({
+      finding: String(k.finding || ""),
+      source: String(k.source || "codebase")
+    }));
+    base.unknownUnknowns = arr(p.unknownUnknowns, (k) => ({
+      finding: String(k.finding || ""),
+      impact: String(k.impact || "medium"),
+      mitigation: k.mitigation ? String(k.mitigation) : void 0
+    }));
+    base.questions = arr(p.questions, (q, i) => ({
+      id: String(q.id || `Q${i + 1}`),
+      question: String(q.question || "")
+    })).filter((q) => q.question);
+    base.taskRefinements = arr(p.taskRefinements, (t) => ({
+      taskId: Number(t.taskId) || 0,
+      action: String(t.action || "split"),
+      detail: String(t.detail || "")
+    }));
+    base.domainMisses = base.unknownKnowns.length + base.unknownUnknowns.length;
+  } catch {
+    base.unknownUnknowns = [{ finding: raw.slice(0, 500), impact: "medium", mitigation: "review the raw analysis" }];
+    base.rawAnalysis = raw;
+    base.domainMisses = 1;
+  }
+  return base;
+}
+function formatReport(r) {
+  const L = [];
+  L.push(`Unknown Scan Report \u2014 ${new Date(r.scannedAt).toLocaleString()}`);
+  L.push("=".repeat(50));
+  const p = r.codebaseProfile;
+  if (p.skipped) {
+    L.push(`
+Codebase Profile: SKIPPED (${p.reason || "unknown"})`);
+  } else {
+    L.push("\nCodebase Profile:");
+    L.push(`  language: ${p.language}`);
+    if (p.frameworks.length) L.push(`  frameworks: ${p.frameworks.join(", ")}`);
+    if (p.testPattern) L.push(`  test: ${p.testPattern} (${p.testFramework || "?"})`);
+    if (p.structure.length) L.push(`  structure: ${p.structure.map((s) => `${s.dir}/(${s.fileCount})`).join(", ")}`);
+    L.push(`  total files: ${p.totalFiles}`);
+  }
+  L.push(`
+Domain DB: ${r.domainHits} hits, ${r.domainMisses} new findings`);
+  if (r.knownKnowns.length) {
+    L.push(`
+Known Knowns (${r.knownKnowns.length}):`);
+    for (const k of r.knownKnowns) L.push(`  + task ${k.taskId}: ${k.note}`);
+  }
+  if (r.knownUnknowns.length) {
+    L.push(`
+Known Unknowns (${r.knownUnknowns.length}):`);
+    for (const k of r.knownUnknowns) {
+      L.push(`  ! task ${k.taskId}: ${k.gap}`);
+      if (k.suggestion) L.push(`    -> ${k.suggestion}`);
+    }
+  }
+  if (r.unknownKnowns.length) {
+    L.push(`
+Unknown Knowns (${r.unknownKnowns.length}) \u2014 implicit, from codebase:`);
+    for (const k of r.unknownKnowns) L.push(`  i  ${k.finding}`);
+  }
+  if (r.unknownUnknowns.length) {
+    L.push(`
+Unknown Unknowns (${r.unknownUnknowns.length}) \u2014 blind spots:`);
+    for (const k of r.unknownUnknowns) {
+      L.push(`  *  ${k.finding}`);
+      L.push(`    impact: ${k.impact}`);
+      if (k.mitigation) L.push(`    mitigation: ${k.mitigation}`);
+    }
+  }
+  if (r.questions.length) {
+    L.push(`
+Questions for the user (${r.questions.length}):`);
+    for (const q of r.questions) L.push(`  [${q.id}] ${q.question}`);
+  }
+  if (r.taskRefinements.length) {
+    L.push("\nTask Refinement Suggestions:");
+    for (const t of r.taskRefinements) L.push(`  -> task ${t.taskId}: ${t.action} - ${t.detail}`);
+  }
+  if (r.rawAnalysis) L.push(`
+Raw analysis: ${r.rawAnalysis.slice(0, 200)}`);
+  L.push("\n[usage-coach NEXT] unknowns reviewed:");
+  L.push("  - If questions are flagged, ask the user first.");
+  L.push("  - If task splits are suggested, adjust via task_update.");
+  L.push("  - Then proceed to generate/generate_batch.");
+  return L.join("\n");
+}
+function writeUnknownScan(sessionID, result) {
+  try {
+    const h = readHarness(sessionID);
+    if (h) {
+      h.unknownScan = result;
+      writeHarness(sessionID, h);
+    }
+  } catch {
+  }
+}
 function readHarnessCfg(dir) {
   const tryRead = (p) => {
     try {
@@ -634,7 +1235,7 @@ async function UsageCoachPlugin(input) {
         const agent = await resolveAgent(input.client, _input.sessionID);
         currentAgent = agent;
         refreshBackground();
-        const harnessTools = ["generate", "generate_batch", "grade", "investigate", "verify_diagnosis", "generalize", "harness_start", "task_update", "harness_done", "record_failure"];
+        const harnessTools = ["unknown_scan", "generate", "generate_batch", "grade", "investigate", "verify_diagnosis", "generalize", "harness_start", "task_update", "harness_done", "record_failure", "reverse_interview"];
         if (!harnessTools.includes(_input.tool)) return;
         if (!isHarnessAgent(agent)) {
           throw new Error(`[${PLUGIN_NAME}] '${_input.tool}' is restricted to agent mode ${JSON.stringify(HARNESS_AGENTS)} (current: ${JSON.stringify(agent || "unknown")}). Switch to that agent mode to use it.`);
@@ -677,6 +1278,10 @@ async function UsageCoachPlugin(input) {
             writeHarness(ctx.sessionID, { name: args.name, total: args.total, current: 0, tasks: [], usage: {}, active: true, startedAt: (/* @__PURE__ */ new Date()).toISOString() });
             return `Harness '${args.name}' started (${args.total} tasks).
 
+PRE-FLIGHT (unknown_scan): Before starting generate, call unknown_scan to check for blind spots. This scans the codebase against your tasks and finds gaps (unknown unknowns) that could waste steps if discovered late.
+  unknown_scan({ prompt: "<user request>", tasks: [{id:1, title:"..."}, ...] })
+Review the report: if questions are flagged, ask the user first. If task splits are suggested, adjust via task_update. THEN proceed to the loop below.
+
 STEP LIMIT (default ${DEFAULT_MAX_STEPS}): each generate call creates a sub-session that is automatically aborted if it exceeds ${DEFAULT_MAX_STEPS} assistant steps. Before starting the loop, review each task: can it be completed in a focused, single-pass effort? If a task seems too broad (multiple files, multiple features, open-ended research), SPLIT it now into 2-3 smaller subtasks. A timeout wastes quota \u2014 split upfront.
 
 DETERMINISTIC LOOP \u2014 first classify the tasks:
@@ -700,6 +1305,104 @@ PATH B \u2014 DEPENDENT (sequential):
 Then: harness_done(). Follow the [usage-coach NEXT] directive each tool returns. Do NOT improvise the sequence.`;
           }
         }),
+        unknown_scan: tool({
+          description: "Pre-flight gap analysis: call AFTER harness_start, BEFORE generate. Scans the codebase against the user's request to find blind spots (unknown unknowns) that could waste 30+ steps if discovered late. Returns identified unknowns + task split suggestions + user confirmation questions. Writes results to harness.json for TUI display.",
+          args: {
+            prompt: tool.schema.string().describe("The user's original request (the full prompt that triggered the harness)."),
+            tasks: tool.schema.array(tool.schema.object({ id: tool.schema.number(), title: tool.schema.string() })).optional().describe("Tasks registered via harness_start (id + title). If omitted, a single task derived from the prompt is assumed."),
+            skip_scan: tool.schema.boolean().optional().describe("true: skip codebase scan and do prompt analysis only (default false; auto-skips for dirs with <5 files).")
+          },
+          async execute(args, ctx) {
+            const tasks = args.tasks && args.tasks.length > 0 ? args.tasks : [{ id: 1, title: args.prompt.slice(0, 80) }];
+            let profile;
+            if (args.skip_scan) {
+              profile = { skipped: true, reason: "skip_scan requested", language: "unknown", frameworks: [], structure: [], manifestFiles: [], keyDeps: [], configFiles: [], totalFiles: 0 };
+            } else {
+              try {
+                const res = await input.$`find ${ctx.directory} -maxdepth 4 -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/.cache/*' 2>/dev/null`;
+                const fileList = typeof res?.stdout === "string" ? res.stdout : res?.stdout?.toString?.() ?? "";
+                profile = parseFileList(fileList, ctx.directory);
+                if (profile.totalFiles < 5) {
+                  profile = { ...profile, skipped: true, reason: `directory nearly empty (${profile.totalFiles} files)` };
+                }
+              } catch (e) {
+                profile = { skipped: true, reason: `scan error: ${String(e).slice(0, 100)}`, language: "unknown", frameworks: [], structure: [], manifestFiles: [], keyDeps: [], configFiles: [], totalFiles: 0 };
+              }
+            }
+            let domainNodes = [];
+            let domainHits = 0;
+            try {
+              const combined = `${args.prompt} ${tasks.map((t) => t.title).join(" ")}`;
+              const kw = extractKeywords(combined);
+              if (kw.length) {
+                const graph = queryDomainGraph(kw, 2);
+                domainNodes = graph.nodes || [];
+                domainHits = domainNodes.length;
+              }
+            } catch (e) {
+              log(`unknown_scan domain query err: ${String(e)}`);
+            }
+            const cfg = readHarnessCfg(ctx.directory);
+            if (!cfg.generator) {
+              const result2 = {
+                scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                codebaseProfile: profile,
+                knownKnowns: [],
+                knownUnknowns: [],
+                unknownKnowns: [],
+                unknownUnknowns: [],
+                questions: [],
+                taskRefinements: [],
+                domainHits,
+                domainMisses: 0,
+                rawAnalysis: "ERROR: no generator configured"
+              };
+              writeUnknownScan(ctx.sessionID, result2);
+              return formatReport(result2) + '\n\nERROR: no generator model configured. Set "generator" in harness.config.json for model-assisted analysis.';
+            }
+            let decision = "GO";
+            try {
+              decision = current().decision;
+            } catch {
+            }
+            if (decision === "STOP") {
+              const result2 = {
+                scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                codebaseProfile: profile,
+                knownKnowns: [],
+                knownUnknowns: [],
+                unknownKnowns: [],
+                unknownUnknowns: [],
+                questions: [],
+                taskRefinements: [],
+                domainHits,
+                domainMisses: 0,
+                rawAnalysis: "quota STOP \u2014 model analysis skipped"
+              };
+              writeUnknownScan(ctx.sessionID, result2);
+              return formatReport(result2) + "\n\n[usage-coach] quota STOP \u2014 model-assisted analysis skipped. Proceed with caution.";
+            }
+            const throttle = decision === "THROTTLE" && cfg.lighterModel;
+            const model = throttle ? cfg.lighterModel : cfg.generator;
+            const gapPrompt = buildGapPrompt(args.prompt, tasks, profile, domainNodes);
+            const raw = await runModel(input.client, model, gapPrompt, ctx.directory, void 0, 15);
+            const result = parseGapAnalysis(raw, profile, domainHits);
+            try {
+              for (const uk of result.unknownKnowns.slice(0, 5)) {
+                const kw = extractKeywords(uk.finding);
+                if (kw.length) saveInvestigationResult(kw, uk.finding, "unknown_scan");
+              }
+              for (const uu of result.unknownUnknowns.slice(0, 3)) {
+                const kw = extractKeywords(uu.finding);
+                if (kw.length) saveInvestigationResult(kw, `${uu.finding} (impact: ${uu.impact})`, "unknown_scan");
+              }
+            } catch (e) {
+              log(`unknown_scan save err: ${String(e)}`);
+            }
+            writeUnknownScan(ctx.sessionID, result);
+            return formatReport(result);
+          }
+        }),
         task_update: tool({
           description: "Update a harness task's status on the panel. Call whenever a task transitions to generating/grading/revising/completed/failed.",
           args: {
@@ -926,6 +1629,20 @@ ${rules}
             } catch (e) {
               log(`generate domain query err: ${String(e)}`);
             }
+            try {
+              const priorNotes = keywords.length ? readImplNotesByGraph(keywords, 5) : readImplNotes(5);
+              if (priorNotes) {
+                prefix = `Notes from previous runs (context for this task):
+${priorNotes}
+
+---
+
+` + prefix;
+              }
+            } catch (e) {
+              log(`generate impl-notes read err: ${String(e)}`);
+            }
+            prefix += IMPL_NOTE_INSTRUCTION;
             const genTaskId = findActiveTaskId(ctx.sessionID, "generating");
             const maxSteps = args.max_steps ?? DEFAULT_MAX_STEPS;
             const out = await runModel(
@@ -944,6 +1661,20 @@ ${rules}
                 log(`generate save err: ${String(e)}`);
               }
             }
+            if (!isTimeoutOrError) {
+              try {
+                const { notes } = extractImplNotes(out);
+                if (notes) {
+                  appendImplNotes(notes, args.prompt);
+                  if (keywords.length) {
+                    const noteNodeId = saveInvestigationResult(keywords, notes, "impl-note", 0.5);
+                    if (noteNodeId) linkImplNoteToDomain(noteNodeId, notes);
+                  }
+                }
+              } catch (e) {
+                log(`generate impl-notes extract err: ${String(e)}`);
+              }
+            }
             if (out.startsWith("Task appears too large")) return out;
             return out + (throttle ? `
 [usage-coach] quota THROTTLE \u2014 used lighter model ${cfg.lighterModel}` : "") + `
@@ -965,18 +1696,49 @@ ${rules}
             const throttle = decision === "THROTTLE" && cfg.lighterModel;
             const model = throttle ? cfg.lighterModel : cfg.generator;
             const limit = decision === "THROTTLE" ? 2 : args.tasks.length;
+            const rules = readRules();
+            const priorNotes = readImplNotes(5);
             const results = [];
             for (let i = 0; i < args.tasks.length; i += limit) {
               const batch = args.tasks.slice(i, i + limit);
               const out = await Promise.all(batch.map(async (t) => {
+                let prefix = rules ? `Lessons learned from previous failures (apply where relevant):
+${rules}
+
+---
+
+` : "";
+                if (priorNotes) prefix = `Notes from previous runs (context for this task):
+${priorNotes}
+
+---
+
+` + prefix;
+                prefix += IMPL_NOTE_INSTRUCTION;
                 const r = await runModel(
                   input.client,
                   model,
-                  t.prompt,
+                  prefix + t.prompt,
                   ctx.directory,
                   { sessionID: ctx.sessionID, taskId: t.id },
                   args.max_steps ?? DEFAULT_MAX_STEPS
                 );
+                const isTimeoutOrError = r.startsWith("Task appears too large") || r.startsWith("ERROR:");
+                if (!isTimeoutOrError) {
+                  try {
+                    const { notes } = extractImplNotes(r);
+                    if (notes) {
+                      appendImplNotes(notes, t.prompt);
+                      const kw = extractKeywords(t.prompt);
+                      if (kw.length) {
+                        const noteNodeId = saveInvestigationResult(kw, notes, "impl-note", 0.5);
+                        if (noteNodeId) linkImplNoteToDomain(noteNodeId, notes);
+                      }
+                    }
+                  } catch (e) {
+                    log(`generate_batch impl-notes extract err: ${String(e)}`);
+                  }
+                }
                 return `[task ${t.id}] ${r}`;
               }));
               results.push(...out);
@@ -1018,6 +1780,140 @@ ${rules}
 The next generate call will automatically include the new rule.`;
             return out + "\n" + next;
           }
+        }),
+        reverse_interview: tool({
+          description: "Reverse interview: identify ambiguities in the task and ask the user one question at a time, highest design-impact first. Call WITHOUT answer to start or get the next question. Call WITH answer to record the user's response and advance. Returns the next question or a completion summary. ALWAYS present the question to the user verbatim \u2014 do NOT answer it yourself.",
+          args: {
+            task: tool.schema.string().describe(
+              "The current task description (what the user asked for)."
+            ),
+            context: tool.schema.string().optional().describe(
+              "Additional context from unknown_scan, codebase exploration, or prior turns. Injected into the question-generation prompt for better prioritization."
+            ),
+            answer: tool.schema.string().optional().describe(
+              "The user's response to the previous question. Omit on the first call (or when there is no answer to record)."
+            ),
+            force_complete: tool.schema.boolean().optional().describe(
+              "Force the interview to end now and return the summary. Use when the user says 'that's enough' or 'just proceed'."
+            )
+          },
+          async execute(args, ctx) {
+            const sessionID = ctx.sessionID;
+            const cfg = readHarnessCfg(ctx.directory);
+            const resolveModel = () => {
+              if (!cfg.generator) return null;
+              let decision = "GO";
+              try {
+                decision = current().decision;
+              } catch {
+              }
+              const throttle = decision === "THROTTLE" && cfg.lighterModel;
+              return throttle ? cfg.lighterModel : cfg.generator;
+            };
+            let state = readInterview(sessionID);
+            if (args.force_complete) {
+              if (state && state.phase !== "complete") {
+                return await completeInterview(state, sessionID, input.client, resolveModel(), ctx.directory);
+              }
+              return "No active interview to complete.\n[usage-coach NEXT] proceed to harness_start \u2192 generate.";
+            }
+            if (args.answer !== void 0 && args.answer !== null && state && state.phase === "asking" && state.currentIndex < state.questions.length) {
+              const q2 = state.questions[state.currentIndex];
+              state.answers.push({
+                questionId: q2.id,
+                questionText: q2.text,
+                answer: String(args.answer),
+                ts: (/* @__PURE__ */ new Date()).toISOString()
+              });
+              state.currentIndex++;
+              writeInterview(sessionID, state);
+              const maxQ = state.maxQuestions;
+              if (state.currentIndex >= state.questions.length || state.answers.length >= maxQ) {
+                return await completeInterview(state, sessionID, input.client, resolveModel(), ctx.directory);
+              }
+            }
+            if (!state || state.phase === "complete") {
+              if (!cfg.generator) return 'ERROR: no generator model configured. Set "generator" in harness.config.json (see harness.config.example.json).\n[usage-coach NEXT] proceed to harness_start \u2192 generate using best-effort assumptions.';
+              const model = resolveModel();
+              const userRequest = args.task;
+              const mQ = DEFAULT_MAX_QUESTIONS;
+              let graphNodes = [];
+              try {
+                const keywords = extractKeywords(args.task + " " + (args.context ?? ""));
+                if (keywords.length) {
+                  const g = queryDomainGraph(keywords, 2);
+                  graphNodes = g.nodes || [];
+                }
+              } catch (e) {
+                log(`reverse_interview domain query err: ${String(e)}`);
+              }
+              const domainSection = graphNodes.length ? `
+Domain knowledge (from local graph DB \u2014 do NOT ask about things already known):
+${graphNodes.slice(0, 20).map(
+                (n) => `- [d${n.distance ?? 9}] ${n.name} (${n.type}): ${String(n.props?.result ?? JSON.stringify(n.props)).slice(0, 150)}`
+              ).join("\n")}
+` : "";
+              const planningPrompt = `You are a senior architect conducting a reverse interview.
+Analyze this task and identify the TOP ambiguities that, if left unresolved, would lead to the WRONG implementation.
+
+Task: ${args.task}
+User request: ${userRequest}
+Additional context: ${args.context ?? "none"}${domainSection}
+
+Rules:
+1. Focus on questions whose answers CHANGE THE ARCHITECTURE or SCOPE.
+   "What database?" is high-impact. "Variable naming?" is low-impact \u2014 exclude it.
+2. Maximum ${mQ} questions.
+3. Rank by design impact: critical > high > medium > low.
+4. For each question, explain WHY it matters (the consequence of guessing wrong).
+5. Categorize each: architecture | scope | constraint | preference | constraint-env | tradeoff.
+6. For each question, name the core CONCEPT it targets (a single word/phrase).
+
+Output JSON ONLY (no markdown fences, no prose):
+{"questions":[{"text":"the question (concise, specific)","why":"what goes wrong if we guess","priority":"critical|high|medium|low","category":"architecture|scope|constraint|preference|constraint-env|tradeoff","optional":true,"concept":"single-word-concept"}]}
+If the task is already well-specified with no significant ambiguities, return {"questions":[]}.`;
+              const out = await runModel(input.client, model, planningPrompt, ctx.directory);
+              if (out.startsWith("ERROR:") || out.startsWith("Task appears too large")) {
+                return `Cannot generate interview questions: ${out}
+[usage-coach NEXT] proceed to harness_start \u2192 generate using best-effort assumptions, or wait for quota reset and retry reverse_interview.`;
+              }
+              const parsed = parseInterviewQuestions(out, mQ, graphNodes);
+              if (parsed.length === 0) {
+                state = {
+                  id: `int_${Date.now().toString(36)}`,
+                  task: args.task,
+                  userRequest,
+                  startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                  updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                  questions: [],
+                  answers: [],
+                  currentIndex: 0,
+                  phase: "complete",
+                  maxQuestions: mQ,
+                  summary: "No significant ambiguities found. The task appears well-specified."
+                };
+                writeInterview(sessionID, state);
+                return "No significant ambiguities found \u2014 the task appears well-specified.\n[usage-coach NEXT] proceed directly to harness_start \u2192 generate.";
+              }
+              state = {
+                id: `int_${Date.now().toString(36)}`,
+                task: args.task,
+                userRequest,
+                startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                questions: parsed,
+                answers: [],
+                currentIndex: 0,
+                phase: "asking",
+                maxQuestions: mQ
+              };
+              writeInterview(sessionID, state);
+            }
+            const q = state.questions[state.currentIndex];
+            const total = state.questions.length;
+            const qNum = state.currentIndex + 1;
+            return formatQuestionOutput(qNum, total, q);
+          }
         })
       }
     };