@ngockhoale/ukit 2.3.14 → 2.3.15

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.15 - 2026-09-11
+
+Vision-lane root cause, part 4 — native-first dispatch order. Found by mining the user's own
+failing sessions across four real projects (UnicDB, VSDB, BAGuide, AI-Gateway): the API `model`
+field in the transcripts proved failed specialist dispatches landed on `glm-5-turbo` / lite lanes
+(self-reported `MODEL: unic-lite`, `STATUS: WRONG_MODEL`) while the same sessions' main Claude
+lanes read images fine (`STATUS: OK` ×14 in one transcript). Two stacked defects:
+
+- **No fallback when the specialist fails.** The honored-lane hint ordered the parent to dispatch
+  `ukit-vision-analyst` and simply continue; when the gateway routed the alias to a backend that
+  cannot receive the image through the Read tool_result, the analyst returned `WRONG_MODEL` and
+  the image ended up unread even though the parent could have read it natively. The hint now
+  verifies the parent's own vision FIRST (step 2: Read the materialized files yourself, write the
+  receipts, do NOT dispatch), dispatches the specialist only when the parent's own Read yields no
+  image (step 3), and defines the fallback: on `WRONG_MODEL`/`NO_IMAGE` re-read natively, analyse
+  from your own view for pasted images, and never fabricate when no reader can see it (step 4).
+- **Refusal by name instead of by probe.** The omp analyst template mandated refusing *before
+  touching any image* when the runtime model could not be confirmed vision-capable — field
+  transcripts show exactly this refusal (`I must refuse to open, describe, or guess`). Both agent
+  templates now decide ONLY by the first image Read (the probe): a backend that self-identifies as
+  `glm-5-turbo`/`MiniMax-M3`/a lite lane does not license refusal when the probe actually shows
+  the image; a vision-sounding name with a failed probe is still `WRONG_MODEL`.
+
+Unchanged doctrine: never guess at image contents — the fix removes the two paths that turned
+"don't guess" into "don't read". omp mirrors synced. TDD: `vision-router-hint` tests 13-14 and
+`vision-agent` test 13 written RED first, then GREEN; all vision suites pass.
+
 ## 2.3.14 - 2026-09-11
 
 Vision-lane root cause, part 3 — the decisive one: the extractor could not see images in REAL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.14",
+  "version": "2.3.15",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/templates/.claude/agents/ukit-vision-analyst.md

@@ -27,6 +27,12 @@ demonstrated, never assumed from a name:
   actually give you the image (error, empty result, or you can only see text you were told about),
   you are not vision-capable right now: emit `STATUS: WRONG_MODEL` and stop immediately. Do not
   describe, summarise, or guess at any image content.
+- Decide ONLY by the probe result — never by the lane's name. A mapping that sounds non-visual
+  (e.g. your environment says you are a lite lane) does NOT license refusal when the probe
+  actually shows you the image: if you can see it, you are vision-capable right now — report the
+  mapping you actually ran on in `MODEL:` and continue. Conversely, a vision-sounding name with a
+  failed probe is still `STATUS: WRONG_MODEL`. Refusing by name without probing was the exact
+  failure that left images unread in the field.
 - Never guess at image contents. A non-visual "analysis" is worse than no analysis at all, because
   it looks authoritative while being fabricated. Refusing loudly is always safer than guessing
   quietly.

package/templates/.claude/hooks/vision-router.sh

@@ -283,31 +283,34 @@ const { pathToFileURL } = require('url');
   }
 
   // Lane honored (or unverified — missing aliasAvailable defaults to today's
-  // unic-vision dispatch). Capability-framed, never provider identity: the
-  // remedy is "don't guess — use a verified reader", which holds whether the
-  // active model reads images natively or hands off to the specialist.
+  // dispatch). NATIVE-FIRST ordering (2026-09-11): field evidence showed
+  // specialist dispatches landing on gateways/backends that could not return
+  // the image through the Read tool_result (STATUS: WRONG_MODEL, self-reported
+  // unic-lite / glm-5-turbo) while the parent — usually a Claude lane — could
+  // have read the image itself. So the hint verifies the parent's own vision
+  // FIRST by reading the materialized file, dispatches the specialist only as
+  // a fallback, and defines a fallback when the specialist fails anyway —
+  // an image must never end up unread just because one lane failed.
   const unicNote = (unicMode === true && gatewayResult?.visionModel)
     ? `  (UNIC gateway active — ${gatewayResult.visionModel} routes through it.)`
     : '';
 
-  const reasonLines = [
-    'Advisory: never guess at image contents. If the active model has VERIFIED native',
-    'vision for these images it may read them directly; otherwise dispatch the specialist',
-    'before relying on them:',
-  ];
-
   const lines = [
     `UKIT VISION ROUTE — new image input detected (${cases.join(', ')}).`,
-    ...reasonLines,
+    'Advisory: never guess at image contents. Verify a real reader before relying on them:',
     `  1. ${materializeCmd}`,
-    '     Materialize the images to disk. With --session the extractor targets the',
-    '     PARENT transcript explicitly, so a subagent spawn cannot drop the image.',
-    '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]',
-    '     Send the ABSOLUTE paths from images[].path as TEXT (subagents do NOT inherit',
-    '     image blocks; they can only Read files). Include the task envelope: the ORIGINAL',
-    '     user prompt verbatim, the visual question, and the task goal — the analyst must',
-    '     know what the images are FOR.',
-    '  3. Continue the real task using the analyst\'s OBSERVATIONS + INFERENCES.',
+    '     Materialize to disk (--session targets the PARENT transcript, so a subagent',
+    '     spawn cannot drop the image).',
+    '  2. Read each ABSOLUTE path in images[].path YOURSELF, in the main session. If',
+    '     the image actually arrives you have VERIFIED native vision: analyse it and',
+    '     write receipts (analyzed-<sha>.json; sha/sessionId from the extractor output;',
+    '     model = your actual model). No dispatch.',
+    '  3. Only if your own Read shows no image: Agent(subagent_type: "ukit-vision-analyst")',
+    '     [model: unic-vision] — send paths as TEXT (subagents do NOT inherit image',
+    '     blocks) plus the task envelope: original prompt, visual question, goal.',
+    '  4. Specialist answers WRONG_MODEL or NO_IMAGE → do not leave the image unread:',
+    '     re-Read yourself; for a pasted image you can see directly, analyse from your',
+    '     own view. No reader can see it → say so plainly, never fabricate.',
   ];
   if (sessionId) {
     lines.push(`  Markers armed under sessionId: ${sessionId} (receipts: analyzed-<sha>.json).`);

package/templates/.omp/agents/ukit-vision-analyst.md

@@ -17,19 +17,23 @@ actually in them. You never write, edit, or refactor product code — you analys
 - Stay end-user-invisible: this lane is internal UKit orchestration, not something end users invoke
   by name.
 
-## 2. Model self-check — first action, before touching any image
-
-Before reading any image, determine the model you are actually running on right now.
-
-- Vision-capable means: `unic-vision`, or — when `unicMode` is off — whatever
-  `modelTiers.vision.fallbackModel` resolves to per
-  `node .claude/ukit/index/unic-gateway.mjs --json`.
-- If you cannot confirm you are running on a vision-capable model, you must **refuse**: emit
-  `STATUS: WRONG_MODEL` in the output block below and stop immediately. Do not open, describe, or
-  guess at any image content.
-- Never guess at image contents. A wrong-model "analysis" is worse than no analysis at all,
-  because it looks authoritative while being fabricated. Refusing loudly is always safer than
-  guessing quietly.
+## 2. Capability self-check — the first image read is the probe
+
+Model names are gateway mappings whose backend can change at any time, so capability is
+demonstrated, never assumed from a name:
+
+- Your first `read` of an image file doubles as the capability probe. If the tool result does not
+  actually give you the image (error, empty result, or you can only see text you were told about),
+  you are not vision-capable right now: emit `STATUS: WRONG_MODEL` in the output block below and
+  stop immediately. Do not describe, summarise, or guess at any image content.
+- Decide ONLY by the probe result — never by the lane's name. A backend that self-identifies as
+  something else (e.g. `glm-5-turbo`, `MiniMax-M3`, a lite lane) does NOT license refusal when the
+  probe actually shows you the image: if you can see it, you are vision-capable right now — report
+  what you actually ran on in `MODEL:` and continue. Refusing by name without probing was the
+  exact failure that left images unread in the field.
+- Never guess at image contents. A non-visual "analysis" is worse than no analysis at all, because
+  it looks authoritative while being fabricated. Refusing loudly is always safer than guessing
+  quietly.
 
 ## 3. Input protocol (priority order)