@ngockhoale/ukit 2.2.16 → 2.3.1

package/CHANGELOG.md

@@ -2,6 +2,110 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.1 - 2026-09-09
+
+"1 prompt mà đứng 10 lần" is fixed at the root. Four stall vectors in the completion
+gate and router are gone, no stop is silent anymore, and routine backend model swaps
+are now worked through instead of stalled on. All found by root-cause debugging with a
+failing regression test per fix.
+
+1) Stop-hook recursion: `execution-ledger.mjs --evaluate-stop` re-blocked the reentrant
+Stop event (Claude Code re-invokes Stop with `stop_hook_active: true` after a block), so
+one block became a self-sustaining block/continue chain ending in a cap-forced mid-task
+stop. The gate now honors `stop_hook_active` and, when evidence is still missing, emits
+a user-visible `systemMessage` instead of silently ending.
+
+2) requestKey churn wiped evidence: `skill-router.sh` rebuilds requestKey per tool call
+(commandText/targetFile are hashed in), so the first verification command re-keyed the
+route mid-request and `--record` took the freshLedger path, erasing the write/verification
+evidence the same request had produced — the gate then re-blocked until the cap forced a
+silent stop. The ledger now keys evidence identity by the user prompt text
+(`promptKey`); a re-key within one logical request carries evidence forward, a genuinely
+new prompt starts clean.
+
+3) Subagent stalls: subagent tool calls run the same hooks against the same session
+ledger and route state (docs-confirmed; sidechain payloads carry `agent_id`/
+`agent_type`). A subagent's Edit could re-route the request to a different
+executionMode, which both broke the old promptKey identity (wiping main evidence) and
+replaced the main route's completionEvidence. Fixes: promptKey is the prompt text alone
+(null prompt never carries), and `skill-router.sh` early-exits on sidechain payloads so
+subagent tool calls never touch the main route state. omp's bridge invokes the same
+script, so every harness is covered.
+
+4) No silent endings: the non-gated modes' `notify` and the post-cap `capped` paths now
+emit a `systemMessage` alongside their stderr line — previously these ended turns with
+the user seeing nothing.
+
+Gateway model swaps (limit hit → a different vendor model behind the same alias) are
+detected from the transcript's per-assistant `message.model` and surfaced in
+`context-window-guard.sh` as ONE routine line per hour: keep working, do not restart or
+re-plan; if a tool call errors after a swap, re-check the tool and call it again. The
+swap itself cold-reads the prompt cache once — that latency is transport-level and
+cannot be removed by hooks; everything after it now continues automatically.
+
+Integrated on top of 2.3.0 (rebased; not published as 2.2.17): 2.3.0's stricter gates
+made the re-key carry load-bearing for `targetedVerificationSucceeded`/`sourceFiles`
+too — without carrying them, a mid-request re-key re-demanded targeted evidence and
+re-introduced the stall this release fixes (regression-tested RED→GREEN). The 2.3.0
+notify test that expected a silent stdout was updated to the no-silent-stops contract.
+
+Verified: executionLedgerCli 29/29, skillRouterHook 33/33, contextWindowGuard 18/18;
+full suite 1280/1280 (74 files) and `release:verify` green on the integrated tree;
+template↔live mirrors byte-identical (live settings.json re-rendered through the install
+pipeline, not copied raw).
+
+## 2.3.0 - 2026-09-08
+
+Model-agnostic hardening release. Every configured model name is treated as a gateway
+mapping whose backend can change at any time, so correctness now comes from stable role
+contracts, explicit evidence, and regression fixtures — never provider identity.
+
+**Sensitive-data gate (fail-closed, default ON).** NEW `sensitive-data-guard.sh` scans
+PreToolUse Read/Grep paths, Bash commands (secret-dump shapes, inline credentials,
+high-confidence token patterns like `sk-…`), and UserPromptSubmit text; on suspicion it
+blocks with exit 2 and shows only redacted previews (3-char prefix + length + sha256
+prefix) — never the value. The only approval path is the USER editing the protected
+allowlist `.ukit/storage/security/allowlist.json` (sha256 of the value, or an allowed file
+path); `security.sensitiveDataGate: true` ships as the default and the gate can be disabled
+in `.ukit/storage/config.json` for debugging. Wired into Claude settings hook chains, the
+omp bridge, and the install manifest. Live-fire verified across all four channels.
+
+**Contract tables unified to one source.** NEW `src/core/executionContracts.js` is the
+canonical table set (execution modes, contracts, contract→tier mapping, risk profiles).
+`taskRouting.js` imports it, runtime config defaults derive from it, and the shipped
+`route-task.mjs` keeps a literal copy locked by a new sync test — fixing a real drift where
+route-task's `local-build` contract was missing verification evidence and the post-edit
+review policy. `config.json` no longer duplicates `modelTier` per contract.
+
+**Tier-role wiring.** Route state now carries a `tierLane` hand-off: silent when the
+contract tier is `code` (the default implementation lane), an explicit "hand this to an
+agent bound to the lite/smart tier" instruction otherwise, and it follows `escalatedTier`
+on repeat failures. This surfaced and fixed a real gap: `compactRouteSummary` is a
+whitelist and was silently dropping `expectedSourceFiles`, which made target-aware
+completion evidence inert on the real CLI path.
+
+**Evidence tightening.** Completion-gate `impact-evidence` now requires reading one of the
+routed target files (any random read no longer counts), and verification receipts record
+`targeted` vs `broad` scope against the routed verification plan; recovery instructions
+name the exact files expected.
+
+**Vision flow smoothing.** Already-analysed images no longer re-trigger route hints
+(`alreadyAnalyzed[]` from `extract-image.mjs --json`); unresolvable image paths get a short
+note instead of a wrong remedy; the vision analyst gets a capability self-check (first
+image Read is the probe), a task envelope carrying the ORIGINAL user prompt verbatim, and
+an observations-vs-inference output block; hook-chain budgets now scale with chain size so
+growing Edit/Write chains never orphan the runner.
+
+**Mapping fingerprint fixtures.** New consistency tests lock agent↔tier bindings across
+Claude Code and omp, the omp modelRoles → `unic-*` labels, and the tier structure
+(vision stays a capability tier outside the escalation ladder) — provider identities are
+deliberately left unpinned so gateway mappings can change freely without breaking
+behavior contracts.
+
+Verified: `yarn test` 1277/1277 (74 files), `test:release-core` 1270, `test:artifact` 7,
+`release:verify` all checks passed, 13/13 handoff node suites, sensitive-data-guard
+live-fire 5/5 as designed.
+
 ## 2.2.16 - 2026-09-06
 
 The vision gate is gone — image work is advisory-routed, never blocked. Since TASK-008, a

package/manifests/platform.full.yaml

@@ -1094,6 +1094,17 @@ items:
     packs:
       - core
 
+  - id: hook-sensitive-data-guard
+    type: hook
+    sourceTemplate: .claude/hooks/sensitive-data-guard.sh
+    targetPath: .claude/hooks/sensitive-data-guard.sh
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-handoff-model-guard
     type: hook
     sourceTemplate: .claude/hooks/handoff-model-guard.sh

package/package.json

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

package/src/core/executionContracts.js

@@ -0,0 +1,130 @@
+// Single source of truth for UKit execution contracts (WS-D contract table unification).
+//
+// Every routing decision that is keyed on an execution contract derives from the tables in
+// this file:
+//   - src/index/taskRouting.js  (in-process routing: contracts + risk profiles + mode order)
+//   - src/core/runtimeConfig.js (config defaults: contracts minus runtime-only keys)
+//   - templates/ukit/storage/config.json (literal mirror of the config defaults)
+//   - templates/.claude/ukit/index/route-task.mjs (shipped standalone CLI: contracts + tiers)
+//
+// route-task.mjs runs inside target projects and cannot import from src/, so it keeps a
+// literal copy — tests/consistency/executionContractSync.test.js locks that copy to these
+// tables so the four can never drift again (the local-build completionEvidence drift that
+// motivated this module is the failure mode it exists to prevent).
+
+export const EXECUTION_MODE_ORDER = [
+  'tiny-fix',
+  'local-fix',
+  'local-build',
+  'find-cause',
+  'shared-edit',
+  'map-impact',
+  'review-release',
+];
+
+export const EXECUTION_CONTRACTS = {
+  'tiny-fix': {
+    maxReadPasses: 0,
+    maxContextPulls: 0,
+    verificationPolicy: 'minimal-or-targeted',
+    completionRule: 'never-claim-done-without-write',
+    delegationPolicy: 'disallow',
+    completionEvidence: ['write-evidence'],
+  },
+  'local-fix': {
+    maxReadPasses: 1,
+    maxContextPulls: 1,
+    verificationPolicy: 'targeted-if-covered',
+    completionRule: 'require-write',
+    delegationPolicy: 'disallow',
+    completionEvidence: ['write-evidence'],
+  },
+  'local-build': {
+    maxReadPasses: 2,
+    maxContextPulls: 1,
+    verificationPolicy: 'targeted-if-covered',
+    completionRule: 'require-write-and-verification',
+    delegationPolicy: 'disallow-by-default',
+    completionEvidence: ['write-evidence', 'verification-evidence'],
+    postEditReviewPolicy: 'sidecar-non-blocking',
+  },
+  'find-cause': {
+    maxReadPassesBeforeReassess: 3,
+    verificationPolicy: 'root-cause-then-targeted',
+    completionRule: 'never-claim-fixed-without-write-and-verification',
+    delegationPolicy: 'allow-specialized-debug-lane',
+    completionEvidence: ['write-evidence', 'verification-evidence'],
+  },
+  'shared-edit': {
+    maxReadPasses: 2,
+    maxContextPulls: 2,
+    verificationPolicy: 'targeted-then-widen-on-risk',
+    completionRule: 'require-write-and-verification',
+    delegationPolicy: 'allow-qualified-sidecar',
+    completionEvidence: ['write-evidence', 'verification-evidence'],
+    mirrorConsistencyRequired: true,
+    postEditReviewPolicy: 'sidecar-non-blocking',
+  },
+  'map-impact': {
+    maxReadPasses: 3,
+    maxContextPulls: 3,
+    verificationPolicy: 'impact-first-then-targeted-then-widen-on-risk',
+    completionRule: 'require-impact-evidence-before-edit-claim',
+    delegationPolicy: 'allow-impact-sidecar',
+    completionEvidence: ['impact-evidence', 'write-evidence', 'verification-evidence'],
+    mirrorConsistencyRequired: true,
+  },
+  'review-release': {
+    verificationPolicy: 'evidence-first',
+    completionRule: 'report-findings-not-implementation',
+    delegationPolicy: 'allow-review-sidecar',
+    completionEvidence: ['verification-evidence'],
+  },
+};
+
+export const MODEL_TIER_BY_CONTRACT = {
+  'tiny-fix': 'lite',
+  'local-fix': 'code',
+  'local-build': 'code',
+  'find-cause': 'code',
+  'shared-edit': 'code',
+  'map-impact': 'code',
+  'review-release': 'smart',
+};
+
+export const CONTRACT_RISK_PROFILES = {
+  'tiny-fix': { riskLevel: 'minimal', contextPolicy: 'confirm-target-only' },
+  'local-fix': { riskLevel: 'local', contextPolicy: 'bounded-local' },
+  'local-build': { riskLevel: 'local', contextPolicy: 'bounded-with-related-files' },
+  'find-cause': { riskLevel: 'investigation', contextPolicy: 'trace-then-bounded-context' },
+  'shared-edit': { riskLevel: 'shared', contextPolicy: 'bounded-with-related-tests' },
+  'map-impact': { riskLevel: 'wide', contextPolicy: 'impact-map-first' },
+  'review-release': { riskLevel: 'release', contextPolicy: 'evidence-review-only' },
+};
+
+const CONFIG_EXCLUDED_KEYS = new Set(['modelTier', 'completionEvidence', 'mirrorConsistencyRequired']);
+
+/** The user-facing config subset of a contract: runtime-only bookkeeping keys stripped. */
+export function stripContractForConfig(contract = {}) {
+  return Object.fromEntries(
+    Object.entries(contract).filter(([key]) => !CONFIG_EXCLUDED_KEYS.has(key))
+  );
+}
+
+export function buildExecutionContract(executionMode = null) {
+  if (!executionMode) {
+    return null;
+  }
+  const contract = EXECUTION_CONTRACTS[executionMode];
+  if (!contract) {
+    return null;
+  }
+  return { ...contract, modelTier: MODEL_TIER_BY_CONTRACT[executionMode] };
+}
+
+/** Config-default shape: contracts without modelTier/completionEvidence/mirror keys. */
+export function buildConfigContracts() {
+  return Object.fromEntries(
+    Object.entries(EXECUTION_CONTRACTS).map(([mode, contract]) => [mode, stripContractForConfig(contract)])
+  );
+}

package/src/core/runtimeConfig.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import { buildRuntimePaths } from './runtimePaths.js';
 import { loadShippedCompactBudget } from './compact/contextBudget.js';
+import { buildConfigContracts } from './executionContracts.js';
 
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION } = require('../../package.json');
@@ -69,6 +70,10 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       affectVerification: true,
       affectDelegation: true,
     },
+    security: {
+      sensitiveDataGate: true,
+      allowlistPath: '.ukit/storage/security/allowlist.json',
+    },
     compact: {
       enabled: true,
       tokenThreshold: loadShippedCompactBudget().tokenThreshold,
@@ -132,56 +137,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       enabled: true,
       orchestratorModel: 'claude-sonnet-5',
       advisorEnabled: true,
-      contracts: {
-        'tiny-fix': {
-          maxReadPasses: 0,
-          maxContextPulls: 0,
-          verificationPolicy: 'minimal-or-targeted',
-          completionRule: 'never-claim-done-without-write',
-          delegationPolicy: 'disallow',
-        },
-        'local-fix': {
-          maxReadPasses: 1,
-          maxContextPulls: 1,
-          verificationPolicy: 'targeted-if-covered',
-          completionRule: 'require-write',
-          delegationPolicy: 'disallow',
-        },
-        'local-build': {
-          maxReadPasses: 2,
-          maxContextPulls: 1,
-          verificationPolicy: 'targeted-if-covered',
-          completionRule: 'require-write-and-verification',
-          delegationPolicy: 'disallow-by-default',
-          postEditReviewPolicy: 'sidecar-non-blocking',
-        },
-        'find-cause': {
-          maxReadPassesBeforeReassess: 3,
-          verificationPolicy: 'root-cause-then-targeted',
-          completionRule: 'never-claim-fixed-without-write-and-verification',
-          delegationPolicy: 'allow-specialized-debug-lane',
-        },
-        'shared-edit': {
-          maxReadPasses: 2,
-          maxContextPulls: 2,
-          verificationPolicy: 'targeted-then-widen-on-risk',
-          completionRule: 'require-write-and-verification',
-          delegationPolicy: 'allow-qualified-sidecar',
-          postEditReviewPolicy: 'sidecar-non-blocking',
-        },
-        'map-impact': {
-          maxReadPasses: 3,
-          maxContextPulls: 3,
-          verificationPolicy: 'impact-first-then-targeted-then-widen-on-risk',
-          completionRule: 'require-impact-evidence-before-edit-claim',
-          delegationPolicy: 'allow-impact-sidecar',
-        },
-        'review-release': {
-          verificationPolicy: 'evidence-first',
-          completionRule: 'report-findings-not-implementation',
-          delegationPolicy: 'allow-review-sidecar',
-        },
-      },
+      contracts: buildConfigContracts(),
       modelTiers: {
         lite: { claudeModel: 'claude-haiku-4-5', genericModel: 'unic-lite' },
         code: { claudeModel: 'claude-sonnet-5', genericModel: 'unic-code' },
@@ -312,6 +268,13 @@ export function validateRuntimeConfig(config) {
     pushBooleanError(errors, config.autonomy.affectDelegation, 'autonomy.affectDelegation');
   }
 
+  if (!isPlainObject(config.security)) {
+    errors.push('security must be an object.');
+  } else {
+    pushBooleanError(errors, config.security.sensitiveDataGate, 'security.sensitiveDataGate');
+    pushNonEmptyStringError(errors, config.security.allowlistPath, 'security.allowlistPath');
+  }
+
   if (!VALID_AGENTS.has(config.agent)) {
     errors.push(`agent must be one of: ${[...VALID_AGENTS].join(', ')}.`);
   }

package/src/index/taskRouting.js

@@ -6,6 +6,11 @@ import { buildRouteSignalText } from './languageTools.js';
 import { resolveContext } from './resolveContext.js';
 import { deriveVerificationPlan } from './verificationPlan.js';
 import { isSharedImpactFile } from './impactCatalog.js';
+import {
+  CONTRACT_RISK_PROFILES,
+  EXECUTION_CONTRACTS,
+  EXECUTION_MODE_ORDER,
+} from '../core/executionContracts.js';
 
 const MAX_ACTIVE_ROUTE_SKILLS = 2;
 
@@ -545,18 +550,8 @@ function applySafeUpwardBias(candidates = [], fallbackMode = 'local-build') {
 }
 
 function executionModeRank(mode = '') {
-  const orderedModes = [
-    'tiny-fix',
-    'local-fix',
-    'local-build',
-    'find-cause',
-    'shared-edit',
-    'map-impact',
-    'review-release',
-  ];
-
-  const index = orderedModes.indexOf(mode);
-  return index >= 0 ? index : orderedModes.length;
+  const index = EXECUTION_MODE_ORDER.indexOf(mode);
+  return index >= 0 ? index : EXECUTION_MODE_ORDER.length;
 }
 
 function buildExecutionContract(executionMode = null) {
@@ -564,67 +559,8 @@ function buildExecutionContract(executionMode = null) {
     return null;
   }
 
-  const contracts = {
-    'tiny-fix': {
-      maxReadPasses: 0,
-      maxContextPulls: 0,
-      verificationPolicy: 'minimal-or-targeted',
-      completionRule: 'never-claim-done-without-write',
-      delegationPolicy: 'disallow',
-      completionEvidence: ['write-evidence'],
-    },
-    'local-fix': {
-      maxReadPasses: 1,
-      maxContextPulls: 1,
-      verificationPolicy: 'targeted-if-covered',
-      completionRule: 'require-write',
-      delegationPolicy: 'disallow',
-      completionEvidence: ['write-evidence'],
-    },
-    'local-build': {
-      maxReadPasses: 2,
-      maxContextPulls: 1,
-      verificationPolicy: 'targeted-if-covered',
-      completionRule: 'require-write-and-verification',
-      delegationPolicy: 'disallow-by-default',
-      completionEvidence: ['write-evidence', 'verification-evidence'],
-      postEditReviewPolicy: 'sidecar-non-blocking',
-    },
-    'find-cause': {
-      maxReadPassesBeforeReassess: 3,
-      verificationPolicy: 'root-cause-then-targeted',
-      completionRule: 'never-claim-fixed-without-write-and-verification',
-      delegationPolicy: 'allow-specialized-debug-lane',
-      completionEvidence: ['write-evidence', 'verification-evidence'],
-    },
-    'shared-edit': {
-      maxReadPasses: 2,
-      maxContextPulls: 2,
-      verificationPolicy: 'targeted-then-widen-on-risk',
-      completionRule: 'require-write-and-verification',
-      delegationPolicy: 'allow-qualified-sidecar',
-      completionEvidence: ['write-evidence', 'verification-evidence'],
-      mirrorConsistencyRequired: true,
-      postEditReviewPolicy: 'sidecar-non-blocking',
-    },
-    'map-impact': {
-      maxReadPasses: 3,
-      maxContextPulls: 3,
-      verificationPolicy: 'impact-first-then-targeted-then-widen-on-risk',
-      completionRule: 'require-impact-evidence-before-edit-claim',
-      delegationPolicy: 'allow-impact-sidecar',
-      completionEvidence: ['impact-evidence', 'write-evidence', 'verification-evidence'],
-      mirrorConsistencyRequired: true,
-    },
-    'review-release': {
-      verificationPolicy: 'evidence-first',
-      completionRule: 'report-findings-not-implementation',
-      delegationPolicy: 'allow-review-sidecar',
-      completionEvidence: ['verification-evidence'],
-    },
-  };
-
-  return contracts[executionMode] ? { ...contracts[executionMode] } : null;
+  const contract = EXECUTION_CONTRACTS[executionMode];
+  return contract ? { ...contract } : null;
 }
 
 function buildApproachSelectorResult({
@@ -637,36 +573,7 @@ function buildApproachSelectorResult({
   }
 
   const executionContract = buildExecutionContract(executionMode);
-  const policyByMode = {
-    'tiny-fix': {
-      riskLevel: 'minimal',
-      contextPolicy: 'confirm-target-only',
-    },
-    'local-fix': {
-      riskLevel: 'local',
-      contextPolicy: 'bounded-local',
-    },
-    'local-build': {
-      riskLevel: 'local',
-      contextPolicy: 'bounded-with-related-files',
-    },
-    'find-cause': {
-      riskLevel: 'investigation',
-      contextPolicy: 'trace-then-bounded-context',
-    },
-    'shared-edit': {
-      riskLevel: 'shared',
-      contextPolicy: 'bounded-with-related-tests',
-    },
-    'map-impact': {
-      riskLevel: 'wide',
-      contextPolicy: 'impact-map-first',
-    },
-    'review-release': {
-      riskLevel: 'release',
-      contextPolicy: 'evidence-review-only',
-    },
-  };
+  const policyByMode = CONTRACT_RISK_PROFILES;
   const selectedPolicy = policyByMode[executionMode] ?? {
     riskLevel: 'local',
     contextPolicy: 'bounded-local',

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

@@ -1,7 +1,7 @@
 ---
 name: ukit-vision-analyst
-description: "The only lane permitted to interpret images in this repo. Use whenever a prompt references, attaches, or points at an image (screenshot, mockup, diagram, photo of an error) and the caller needs to know what is actually in it. unic-code/unic-smart cannot read images on this gateway and must never guess at their contents — route image analysis here instead. Reports findings only; never writes product code."
-model: unic-vision  # real gateway model name, NOT an alias. unic-code/unic-smart cannot read images on this gateway — do NOT "fix" this to sonnet/opus.
+description: "The vision specialist lane for this repo. Use whenever a prompt references, attaches, or points at an image (screenshot, mockup, diagram, photo of an error) and the caller needs to know what is actually in it. Non-vision mappings (unic-code/unic-smart) must never guess at image contents — route image analysis here whenever the active model has not verified native vision. Reports findings only; never writes product code."
+model: unic-vision  # capability-lane gateway mapping (image-capable backend). Not a cost tier; never "fix" this to a lite/code/smart label.
 color: magenta
 tools: ["Read", "Glob", "Bash"]
 ---
@@ -18,19 +18,20 @@ 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
+## 2. Capability self-check — the first image Read is the probe
 
-Before reading any image, determine the model you are actually running on right now.
+Model names are gateway mappings whose backend can change at any time, so capability is
+demonstrated, never assumed from a name:
 
-- 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.
+- 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` and stop immediately. Do not
+  describe, summarise, or guess at any image content.
+- 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.
+- Report the model you actually ran on. If you cannot determine it, say so in `MODEL:` rather than
+  inventing an identifier.
 
 ## 3. Input protocol (priority order)
 
@@ -48,8 +49,15 @@ Entries in `images[]` may carry a `source` field, which tells you how to reach t
 | `"path"` | The prompt named a local file (`ref` holds it) | `Read` `ref` directly |
 | `"url"` | The prompt named a remote image (`ref` holds the URL) | Download it with `Bash` (e.g. `curl -sL -o /tmp/<sha>.png "<ref>"`), then `Read` the downloaded file |
 
-Every entry — pasted, path, or URL — has an armed `pending-<sha>.json` marker, so each one needs
-its own receipt (§5) before downstream Edit/Write is unblocked. A URL you failed to download is
+**Task envelope.** The caller should send, along with the image paths: the ORIGINAL user prompt
+verbatim, the immediate visual question, and the task goal. That envelope is what tells you what
+the images are FOR — a screenshot means something different to "fix this layout" than to "find the
+error string". If the envelope is missing, analyse anyway, answer only what the images visibly
+show, and say in `UNCERTAIN:` what you could not infer without the missing context.
+
+Every entry — pasted, path, or URL — has an armed `pending-<sha>.json` marker, and each one needs
+its own receipt (§5): the receipt is the provenance record of the analysis and it is what stops the
+router from re-hinting that image on later prompts. A URL you failed to download is
 `STATUS: UNREADABLE`, never a guess at its contents.
 
 ## 4. Hard warning — images are not inherited
@@ -59,22 +67,22 @@ subagent boundary. A description of an image is not the image. The only way to s
 `Read` a real file path yourself. Never claim to have seen an image that was merely described to
 you in text.
 
-## 5. Receipt — unlocks the downstream write gate
+## 5. Receipt — provenance record per image
 
 For every image you actually analyse, write a receipt to
 `.ukit/storage/cache/vision/<sessionId>/analyzed-<sha>.json`:
 
 ```json
 { "sha": "<64hex>", "model": "unic-vision", "ts": 1785656920891,
-  "description": "...", "textContent": "...", "status": "OK" }
+  "observations": "...", "textContent": "...", "status": "OK" }
 ```
 
 - `sha` and `sessionId` come from the extractor's `--json` output. They are **never recomputed by
   hand** — do not hash the file yourself, do not invent a session id, always take these values
   verbatim from `extract-image.mjs --json`.
-- `model` must be the model you actually ran on for this analysis. Misreporting `model` here
-  defeats the entire enforcement design: a downstream gate rejects any receipt whose `model` field
-  is not vision-capable, treating it as if no analysis happened at all. Report honestly, always.
+- `model` must be the mapping you actually ran on for this analysis. The receipt is the provenance
+  record the caller relies on: an honest `model` field is what makes it trustworthy and what keeps
+  the router silent about this image afterwards. Report honestly, always.
 - Use `Bash` to write the receipt file.
 
 ## 6. Output block
@@ -85,8 +93,9 @@ Always end with:
 STATUS: OK | NO_IMAGE | UNREADABLE | WRONG_MODEL
 MODEL: <actual model>
 IMAGES: <n> (<paths>)
-DESCRIPTION: [what is actually visible]
+OBSERVATIONS: [what is directly visible — layout, elements, colors, structure; facts only]
 TEXT_CONTENT: [verbatim text/code/errors legible in the image, or "none"]
+INFERENCES: [what the observations likely mean — interpretation, clearly separate from facts]
 RELEVANT_TO_TASK: [how it answers the caller's question]
 UNCERTAIN: [anything ambiguous or illegible, or "none"]
 ```
@@ -94,6 +103,8 @@ UNCERTAIN: [anything ambiguous or illegible, or "none"]
 ## 7. Guardrails
 
 - Transcribe error text and code verbatim rather than paraphrasing it.
+- Keep `OBSERVATIONS:` strictly factual; every interpretation goes in `INFERENCES:`. The caller
+  must be able to tell what you saw from what you concluded.
 - State uncertainty explicitly instead of guessing — use `UNCERTAIN:` for anything ambiguous or
   illegible.
 - Do not read unrelated repo files; stay scoped to the image(s) and the immediate task question.