opencode-usage-coach 0.8.1 → 0.8.2

package/agents/usage-coach-harness.md

@@ -50,14 +50,15 @@ The user's message is the task source. If it has multiple distinct parts, decomp
 DEPENDENT tasks (B needs A) → always sequential `generate` calls, regardless of quota.
 
 1. Call `harness_start(name, N)` to register the run on the panel.
-2. **PRE-FLIGHT — unknown_scan:** Call `unknown_scan({prompt, tasks: [{id, title}, ...]})`.
+2. **DIAGNOSIS GATE — unknown_scan (REQUIRED, not optional):** Call `unknown_scan({prompt, tasks: [{id, title}, ...]})`.
+   This is enforced: if you skip it, `generate` will inject a ⚠ warning into the sub-session prompt.
    Review the report:
    - If QUESTIONS are flagged → ask the user concisely, then adjust tasks.
    - If TASK REFINEMENTS are suggested → apply via `task_update` (split/add/remove).
-   - If UNKNOWN UNKNOWNS with high impact are found → acknowledge them in the
-     generate prompts (the domain DB injection will help, but explicitly call them out).
-   This step prevents wasted steps from wrong assumptions. Skip only if the
-   task is trivially clear.
+   - If UNKNOWN UNKNOWNS with high impact are found → they will be auto-injected into
+     generate prompts via scanSummary, but you should explicitly acknowledge them.
+   You may skip unknown_scan ONLY for: revisions (applying grade feedback), trivial
+   single-file edits, or empty directories. Skipping must be a conscious choice.
 3. For each task i (1..N):
    a. `task_update(i, title, "generating")`.
    b. **Generate** — call `generate({ prompt: "Task: {title}. Perform it for real in the current directory (write/edit files)." })`. The generator model runs in a sub-session and writes files directly — its return value is a summary, NOT the work itself.
@@ -72,6 +73,7 @@ DEPENDENT tasks (B needs A) → always sequential `generate` calls, regardless o
 4. When all tasks are done → `harness_done()`.
 
 ## Rules
+- **Diagnose before acting.** Never implement a fix based on a problem description without verifying what actually happened. Read logs, check source code, reproduce the issue. If you find yourself writing code within 60 seconds of reading a problem, STOP and verify your assumptions first.
 - **Follow the [usage-coach NEXT] directive each tool returns.** `harness_start`, `generate`, and `grade` all append a `NEXT` line telling you exactly what to call next. This makes the loop deterministic — do not improvise the sequence, follow `NEXT`.
 - In the loop, do NOT do the work yourself — call `generate`/`grade` (they run the configured models). You orchestrate. (Outside the loop, for trivial requests, act directly.)
 - Call `task_update` on every state transition — the sidebar panel reads it for live visibility.

package/dist/index.js

@@ -837,11 +837,48 @@ function writeUnknownScan(sessionID, result) {
     const h = readHarness(sessionID);
     if (h) {
       h.unknownScan = result;
+      h.scanDone = true;
+      h.scanSummary = buildScanSummary(result);
       writeHarness(sessionID, h);
     }
   } catch {
   }
 }
+function buildScanSummary(r) {
+  const lines = [];
+  if (r.unknownUnknowns?.length) {
+    lines.push(`Unknown Unknowns (${r.unknownUnknowns.length}):`);
+    for (const uu of r.unknownUnknowns.slice(0, 5)) {
+      lines.push(`  [${uu.impact?.toUpperCase() ?? "?"}] ${uu.finding}${uu.mitigation ? ` \u2192 ${uu.mitigation}` : ""}`);
+    }
+  }
+  if (r.unknownKnowns?.length) {
+    lines.push(`Implicit knowledge (${r.unknownKnowns.length}):`);
+    for (const uk of r.unknownKnowns.slice(0, 5)) {
+      lines.push(`  \u2139 ${uk.finding}`);
+    }
+  }
+  if (r.questions?.length) {
+    lines.push(`Pending questions (${r.questions.length}):`);
+    for (const q of r.questions.slice(0, 5)) {
+      lines.push(`  [Q] ${q.question}`);
+    }
+  }
+  return lines.join("\n");
+}
+function checkScanGate(sessionID) {
+  try {
+    const h = readHarness(sessionID);
+    if (!h || !h.scanRequired) return { warning: null, summary: null };
+    if (h.scanDone) return { warning: null, summary: h.scanSummary ?? null };
+    return {
+      warning: `\u26A0 DIAGNOSIS GATE: unknown_scan was NOT called before this generate. You are generating without pre-flight gap analysis. Blind spots (unknown unknowns) may cause wrong assumptions and waste steps. Call unknown_scan first, OR proceed consciously accepting the risk.`,
+      summary: null
+    };
+  } catch {
+    return { warning: null, summary: null };
+  }
+}
 function readHarnessCfg(dir) {
   const tryRead = (p) => {
     try {
@@ -1275,12 +1312,15 @@ async function UsageCoachPlugin(input) {
           description: "Start the harness: register the total task count on the panel. Call once when the harness loop begins. IMPORTANT: each generate/generate_batch sub-session is step-limited (default 30). If any task seems too large, split it into smaller subtasks BEFORE starting \u2014 oversized tasks will timeout.",
           args: { name: tool.schema.string(), total: tool.schema.number() },
           async execute(args, ctx) {
-            writeHarness(ctx.sessionID, { name: args.name, total: args.total, current: 0, tasks: [], usage: {}, active: true, startedAt: (/* @__PURE__ */ new Date()).toISOString() });
+            writeHarness(ctx.sessionID, { name: args.name, total: args.total, current: 0, tasks: [], usage: {}, active: true, scanRequired: 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.
+\u26A0 DIAGNOSIS GATE \u2014 unknown_scan is REQUIRED before generate/generate_batch.
   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.
+  If you skip it, generate will inject a \u26A0 warning into the sub-session prompt.
+  Review the report: if QUESTIONS are flagged \u2192 ask the user first. If TASK
+  REFINEMENTS are suggested \u2192 apply via task_update. Unknown unknowns found will
+  be automatically injected into generate prompts as context.
 
 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.
 
@@ -1643,6 +1683,22 @@ ${priorNotes}
               log(`generate impl-notes read err: ${String(e)}`);
             }
             prefix += IMPL_NOTE_INSTRUCTION;
+            const gate = checkScanGate(ctx.sessionID);
+            if (gate.warning) {
+              prefix = `${gate.warning}
+
+---
+
+` + prefix;
+            }
+            if (gate.summary) {
+              prefix = `Pre-flight scan findings (from unknown_scan \u2014 heed these):
+${gate.summary}
+
+---
+
+` + prefix;
+            }
             const genTaskId = findActiveTaskId(ctx.sessionID, "generating");
             const maxSteps = args.max_steps ?? DEFAULT_MAX_STEPS;
             const out = await runModel(
@@ -1699,8 +1755,20 @@ ${priorNotes}
             const rules = readRules();
             const priorNotes = readImplNotes(5);
             const maxSteps = args.max_steps ?? DEFAULT_MAX_STEPS;
+            const gate = checkScanGate(ctx.sessionID);
+            const gatePrefix = gate.warning ? `${gate.warning}
+
+---
+
+` : gate.summary ? `Pre-flight scan findings (from unknown_scan \u2014 heed these):
+${gate.summary}
+
+---
+
+` : "";
             const runOne = async (t) => {
-              let prefix = rules ? `Lessons learned from previous failures (apply where relevant):
+              let prefix = gatePrefix;
+              prefix += rules ? `Lessons learned from previous failures (apply where relevant):
 ${rules}
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-usage-coach",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "opencode closed-loop usage coach — quota SENSE -> coaching DECIDE -> loop ACT + TUI integration",
   "type": "module",
   "main": "./dist/index.js",