@ngockhoale/ukit 2.2.16 → 2.3.0

package/templates/.claude/hooks/sensitive-data-guard.sh

@@ -0,0 +1,269 @@
+#!/bin/bash
+# PreToolUse (Read|Grep|Bash) + UserPromptSubmit hook: sensitive-data gate.
+#
+# Blocks sensitive data — API keys, private keys, credentials, secret files —
+# from being sent to the AI. Strict by design ("cảnh cực gắt"): mere suspicion
+# of private data blocks the call so the USER decides. Detection covers three
+# egress channels into model context:
+#   1. Read/Grep of secret files (.env*, *.pem, id_rsa, credentials.json, ...)
+#   2. Bash commands that dump secrets (cat .env, bare `env`, curl -u user:pass,
+#      URL-embedded credentials, any high-confidence token in the command text)
+#   3. UserPromptSubmit prompt text containing high-confidence secret patterns
+#
+# FAIL-CLOSED on detection (exit 2). Never echoes the detected value — only a
+# redacted preview plus a truncated sha256 (12 hex chars: enough for the human
+# to verify, not enough for the model to forge an allowlist entry).
+#
+# User escape hatches (explicit human action only):
+#   - security.sensitiveDataGate=false in .ukit/storage/config.json disables the gate
+#   - .ukit/storage/security/allowlist.json { values: [sha256...], paths: [...] }
+#     approves exact secrets / file paths (protect-files.sh blocks model edits there)
+#
+# Fails open only when there is nothing to scan (malformed stdin, no channel):
+# a broken gate must not brick every session, but every real detection blocks.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const { createHash } = require('crypto');
+
+const payload = (() => {
+  try {
+    const parsed = JSON.parse(process.env.INPUT || '');
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+})();
+
+const projectRoot = process.env.PROJECT_ROOT || process.cwd();
+
+function readJsonSafe(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+const config = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), null);
+if (config && config.security && config.security.sensitiveDataGate === false) {
+  process.exit(0);
+}
+
+const allowlist = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'security', 'allowlist.json'), null) || {};
+const allowedValueHashes = new Set(
+  Array.isArray(allowlist.values) ? allowlist.values.filter((v) => typeof v === 'string') : [],
+);
+const allowedPaths = Array.isArray(allowlist.paths) ? allowlist.paths.filter((p) => typeof p === 'string') : [];
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function pathAllowed(filePath) {
+  const normalized = String(filePath).replace(/\\/g, '/').trim();
+  let relative = normalized;
+  try {
+    relative = path.relative(projectRoot, normalized);
+  } catch {
+    // keep normalized
+  }
+  return allowedPaths.some((allowed) => allowed === normalized || allowed === relative);
+}
+
+// --- high-confidence secret value patterns (shared by prompt + bash scanning) ---
+const TOKEN_PATTERNS = [
+  { label: 'OpenAI/Anthropic-style API key', re: /\bsk-(?:proj-|ant-|svc-|acct-|admin-)?[A-Za-z0-9_-]{20,}/g },
+  { label: 'AWS access key id', re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { label: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{30,}\b/g },
+  { label: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}/g },
+  { label: 'GitLab token', re: /\bglpat-[A-Za-z0-9_-]{20,}/g },
+  { label: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/g },
+  { label: 'Google API key', re: /\bAIza[0-9A-Za-z_-]{20,}/g },
+  { label: 'Stripe live key', re: /\b[srp]k_live_[A-Za-z0-9]{20,}/g },
+  { label: 'JWT', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+  { label: 'private key block', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/g },
+  { label: 'bearer token', re: /\bBearer\s+[A-Za-z0-9._+/=-]{20,}/gi },
+];
+
+const ASSIGNMENT_RE = /(^|[^A-Za-z0-9_])(api[_-]?key|apikey|secret[_-]?key|secret|client[_-]?secret|password|passwd|auth[_-]?token|access[_-]?token|token)\s*[:=]\s*["']?([A-Za-z0-9+/_.~-]{16,})/gi;
+
+function scanSecretText(text) {
+  const found = [];
+  for (const { label, re } of TOKEN_PATTERNS) {
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(text)) !== null) {
+      found.push({ label, value: match[0] });
+    }
+  }
+  ASSIGNMENT_RE.lastIndex = 0;
+  let match;
+  while ((match = ASSIGNMENT_RE.exec(text)) !== null) {
+    found.push({ label: `${match[2].toLowerCase()} assignment`, value: match[3] });
+  }
+  return found;
+}
+
+// --- secret file classification ---
+function classifySecretFile(filePath) {
+  if (typeof filePath !== 'string' || !filePath.trim()) return null;
+  const normalized = filePath.replace(/\\/g, '/').trim();
+  const rawBase = normalized.split('/').pop();
+  if (!rawBase) return null;
+  const base = rawBase.toLowerCase();
+  if (base.endsWith('.env.example')) return null;
+  if (base === '.env' || base.startsWith('.env.')) return 'dotenv/secret env file';
+  if (base.endsWith('.pub') || base.endsWith('.public')) return null;
+  if (/^id_(rsa|dsa|ecdsa|ed25519)(\.|$)/.test(base)) return 'SSH private key';
+  if (/\.(pem|key|p12|pfx|keystore|jks)$/.test(base)) return 'key/certificate file';
+  if (/^credentials\.(json|ya?ml|txt|ini)$/.test(base)) return 'credentials file';
+  if (/^service[_-]?account.*\.json$/.test(base)) return 'service-account key file';
+  if (base === '.npmrc' || base === '.netrc' || base === '.htpasswd') return 'credentials file';
+  if (/^secrets?\.(json|ya?ml|txt|ini|env)$/.test(base)) return 'secrets file';
+  if (/(^|\/)\.aws\/credentials$/i.test(normalized)) return 'AWS credentials file';
+  return null;
+}
+
+// --- bash command shapes that dump secrets ---
+const DUMP_VERBS = new Set([
+  'cat', 'head', 'tail', 'less', 'more', 'zless', 'zcat', 'xxd', 'strings',
+  'base64', 'od', 'hexdump', 'bat', 'grep', 'egrep', 'fgrep', 'rg', 'awk', 'sed',
+]);
+
+function scanBashShapes(command) {
+  const found = [];
+  const segments = command.split(/\|\||&&|;|\||\n/);
+  for (const rawSegment of segments) {
+    const segment = rawSegment.trim();
+    if (!segment) continue;
+    const tokens = segment.split(/\s+/);
+    const head = tokens[0].replace(/^["']+|["']+$/g, '');
+
+    if ((head === 'env' || head === 'printenv' || head === 'history') && tokens.length === 1) {
+      found.push({ label: `bare \`${head}\` dumps environment/history (may contain tokens)`, value: segment });
+      continue;
+    }
+    if (head === 'export' && (tokens[1] === '-p' || tokens[1] === '--print')) {
+      found.push({ label: 'bare `export -p` dumps all environment variables', value: segment });
+      continue;
+    }
+
+    if (DUMP_VERBS.has(head)) {
+      for (const token of tokens.slice(1)) {
+        const cleaned = token.replace(/^["']+|["',:]+$/g, '');
+        const kind = classifySecretFile(cleaned);
+        if (kind && !pathAllowed(cleaned)) {
+          found.push({ label: `${head} reads ${kind}`, value: cleaned, isPath: true });
+        }
+      }
+    }
+
+    if (/(^|\s)(-u|--user)\s+["']?[^\s"':]+:[^\s"']+/.test(segment)) {
+      found.push({ label: 'curl/wget inline credentials (-u user:password)', value: segment });
+    }
+    if (/https?:\/\/[^\s/@'"]+:[^\s/@'"]+@/.test(segment)) {
+      found.push({ label: 'URL with embedded credentials (user:pass@host)', value: segment });
+    }
+  }
+  return found;
+}
+
+// --- channel wiring ---
+const event = String(payload.hook_event_name || '');
+const toolName = String(payload.tool_name || '');
+const toolInput = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
+
+const textChannels = [];
+const filePathChannels = [];
+let bashCommand = null;
+
+if (event === 'UserPromptSubmit') {
+  const prompt = [payload.prompt, payload.user_prompt, payload.text].find(
+    (candidate) => typeof candidate === 'string' && candidate.trim(),
+  );
+  if (prompt) textChannels.push({ channel: 'prompt', text: prompt });
+} else if (event === 'PreToolUse') {
+  if (toolName === 'Read' && typeof toolInput.file_path === 'string') {
+    filePathChannels.push(toolInput.file_path);
+  } else if (toolName === 'Grep') {
+    if (typeof toolInput.path === 'string' && toolInput.path.trim()) filePathChannels.push(toolInput.path);
+    if (typeof toolInput.pattern === 'string') textChannels.push({ channel: 'grep pattern', text: toolInput.pattern });
+  } else if (toolName === 'Bash' && typeof toolInput.command === 'string') {
+    bashCommand = toolInput.command;
+  }
+} else {
+  process.exit(0);
+}
+
+// --- collect findings ---
+const findings = [];
+
+for (const filePath of filePathChannels) {
+  const kind = classifySecretFile(filePath);
+  if (kind && !pathAllowed(filePath)) {
+    findings.push({ label: `Read of ${kind}`, preview: filePath, hashSource: filePath });
+  }
+}
+
+const seenValues = new Set();
+for (const { channel, text } of textChannels) {
+  for (const finding of scanSecretText(text)) {
+    if (allowedValueHashes.has(sha256(finding.value))) continue;
+    const key = `${channel}:${finding.label}:${finding.value}`;
+    if (seenValues.has(key)) continue;
+    seenValues.add(key);
+    findings.push({ label: `${finding.label} in ${channel}`, value: finding.value });
+  }
+}
+
+if (bashCommand) {
+  for (const finding of scanBashShapes(bashCommand)) {
+    if (finding.isPath) {
+      findings.push({ label: `bash command touches ${finding.label}`, preview: finding.value });
+      continue;
+    }
+    if (allowedValueHashes.has(sha256(finding.value))) continue;
+    findings.push({ label: `${finding.label} in bash command`, value: finding.value });
+  }
+  for (const finding of scanSecretText(bashCommand)) {
+    if (allowedValueHashes.has(sha256(finding.value))) continue;
+    const key = `bash:${finding.label}:${finding.value}`;
+    if (seenValues.has(key)) continue;
+    seenValues.add(key);
+    findings.push({ label: `${finding.label} in bash command`, value: finding.value });
+  }
+}
+
+if (findings.length === 0) {
+  process.exit(0);
+}
+
+// --- block message: redacted previews only, never the secret itself ---
+function describeFinding(finding) {
+  const where = finding.preview
+    ? `${finding.preview}`
+    : `${String(finding.value).slice(0, 3)}…(${String(finding.value).length} chars, sha256 ${sha256(String(finding.value)).slice(0, 12)}…)`;
+  return `  - ${finding.label}: ${where}`;
+}
+
+const lines = [
+  `BLOCKED (sensitive data): ${findings.length} potential secret(s) detected. Nothing was sent to the AI.`,
+  ...findings.map(describeFinding),
+  'This gate is intentionally strict — it blocks on suspicion so the USER decides.',
+  'To proceed, the USER must choose one of:',
+  '  1. Redact the secret (placeholder like <API_KEY>) and retry.',
+  '  2. Approve it explicitly: add the full sha256 (shasum -a 256 of the value) or the file path',
+  '     to .ukit/storage/security/allowlist.json — that file is protected from AI edits.',
+  '  3. Disable the gate: security.sensitiveDataGate=false in .ukit/storage/config.json (not recommended).',
+  'Never repeat or guess the detected value in your reply. Ask the user instead.',
+];
+process.stderr.write(`${lines.join('\n')}\n`);
+process.exit(2);
+NODE
+
+exit $?

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

@@ -2415,6 +2415,10 @@ const { pathToFileURL } = require('url');
     }
 
     ensureDir(statePath);
+    // A no-route prompt (short nudge, informational question) must not wipe the last full
+    // route: completion-gate.sh reads routeSummary/requestKey from this state to decide
+    // whether a Stop is premature. Downgrading to a route-less state here silently disarms
+    // the gate mid-task, so carry the previous route forward until a real route replaces it.
     fs.writeFileSync(statePath, JSON.stringify({
       fingerprint,
       ts: now,
@@ -2422,6 +2426,8 @@ const { pathToFileURL } = require('url');
       activeSkills: [],
       routingContext: compactRoutingContext(routingContext),
       ...(previousContext ? { previousContext: compactPreviousContext(previousContext) } : {}),
+      ...(previous?.routeSummary ? { routeSummary: previous.routeSummary } : {}),
+      ...(previous?.requestKey ? { requestKey: previous.requestKey } : {}),
     }));
     process.exit(0);
   }

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

@@ -12,6 +12,12 @@
 #
 # Runs on EVERY prompt, 8s budget: one shell-out to extract-image.mjs
 # --detect --mark-pending --json, no decoding.
+#
+# Hint policy (dedup): the full dispatch hint fires ONLY when the extractor armed
+# NEW pending markers this prompt. Mentions whose markers already carry
+# analyzed-<sha>.json receipts are silent — re-hinting a closed, analyzed image on
+# every unrelated prompt is the false-positive loop this version exists to kill.
+# A named path that does not resolve from the project root gets a short note only.
 
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
@@ -81,12 +87,9 @@ const { pathToFileURL } = require('url');
 
   // Shell out to the single owner of image detection + marker writing. Runs on every
   // prompt (cheap: --detect --mark-pending, never decodes). All three input forms are
-  // armed here, not just pasted images: a path or URL that only produced hint text would
-  // leave Edit/Write ungated, which is exactly the "analyse blind" case this cycle exists
-  // to prevent. --ref hashes a local file's bytes / a URL string inside the extractor.
-  let markedPasted = 0;
-  let markedPath = 0;
-  let markedUrl = 0;
+  // armed here, not just pasted images. --ref hashes a local file's bytes / a URL
+  // string inside the extractor.
+  let extractorJson = null;
   const extractorPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'extract-image.mjs');
   if (fs.existsSync(extractorPath)) {
     const args = [extractorPath, '--detect', '--mark-pending', '--json'];
@@ -105,34 +108,50 @@ const { pathToFileURL } = require('url');
         encoding: 'utf8',
         timeout: 6000,
       });
-      const parsed = JSON.parse(out);
-      const images = Array.isArray(parsed?.images) ? parsed.images : [];
-      // Ref markers carry a `source`; pasted ones do not. Counting this way stays correct
-      // when a named path does not exist on disk and the extractor drops it.
-      markedPasted = images.filter((img) => !img?.source).length;
-      markedPath = images.filter((img) => img?.source === 'path').length;
-      markedUrl = images.filter((img) => img?.source === 'url').length;
+      extractorJson = JSON.parse(out);
     } catch (err) {
       process.stderr.write(`vision-router: extractor call skipped (${err?.message ?? err})\n`);
     }
   }
 
-  // `cases` reflects what the PROMPT mentioned. Named paths that do not resolve from
-  // the project root still get the unresolved-path note below.
+  // Decide from what the EXTRACTOR did, not from prompt-text regex hits: `written`
+  // markers are genuinely new work; `alreadyAnalyzed` entries are closed cases that
+  // must stay silent. Regex mentions alone no longer trigger the full hint.
+  const images = Array.isArray(extractorJson?.images) ? extractorJson.images : [];
+  const analyzed = Array.isArray(extractorJson?.alreadyAnalyzed) ? extractorJson.alreadyAnalyzed : [];
+  const sessionId = typeof extractorJson?.sessionId === 'string' && extractorJson.sessionId
+    ? extractorJson.sessionId
+    : '';
+  const armedCount = images.length;
+  const armedRefs = new Set(images.filter((img) => typeof img?.ref === 'string').map((img) => img.ref));
+  const analyzedRefs = new Set(analyzed.filter((a) => typeof a?.ref === 'string').map((a) => a.ref));
+  const unresolvedLocal = localMatches.filter(
+    (m) => !armedRefs.has(m.trim()) && !analyzedRefs.has(m.trim())
+  );
   const cases = [];
-  if (markedPasted > 0) cases.push('pasted image');
-  if (localMatches.length > 0) cases.push('local file path');
-  if (urlMatches.length > 0) cases.push('image URL');
-
-  if (cases.length === 0) {
+  if (images.some((img) => !img?.source)) cases.push('pasted image');
+  if (images.some((img) => img?.source === 'path')) cases.push('local file path');
+  if (images.some((img) => img?.source === 'url')) cases.push('image URL');
+
+  if (armedCount === 0) {
+    // No NEW markers. Only speak up when a named path never resolved at all —
+    // an already-analyzed mention is a closed case and stays silent.
+    if (unresolvedLocal.length > 0) {
+      const lines = [
+        `UKIT VISION ROUTE — named image path did not resolve from the project root (${unresolvedLocal[0]}).`,
+        'Nothing was armed for analysis. Resolve the real path or drop the reference;',
+        'never guess at the contents of an image you cannot read.',
+      ];
+      process.stdout.write(`${lines.join('\n')}\n`);
+    }
     process.exit(0);
     return;
   }
 
-  // Only unicMode true or null reach here; off-gateway already exited. Both remaining
-  // cases get the same strict `unic-vision` remedy, so there is no fallback-model branch
-  // to advertise. There must never be one: the analyst self-reports the model it really
-  // ran on, so telling it to claim some other ID is asking it to falsify the receipt.
+  // Only unicMode true or null reach here; off-gateway already exited. There is no
+  // fallback-model branch to advertise. There must never be one: the analyst
+  // self-reports the model it really ran on, so telling it to claim some other ID is
+  // asking it to falsify the receipt.
   let unicNote = '';
   if (unicMode === true) {
     try {
@@ -147,26 +166,33 @@ const { pathToFileURL } = require('url');
     }
   }
 
-  const reasonLine = 'unic-code / unic-smart cannot read images on this gateway — never guess at\nimage contents. Do this before relying on them:';
-  const agentLine = '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]';
+  // 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
+  // must hand off to the specialist.
+  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 — image input detected (${cases.join(', ')}).`,
-    reasonLine,
+    `UKIT VISION ROUTE — new image input detected (${cases.join(', ')}).`,
+    ...reasonLines,
     '  1. node .claude/ukit/index/extract-image.mjs --json',
-    agentLine,
-    '     Pass the ABSOLUTE paths from images[].path as text — a subagent does NOT',
-    '     inherit image blocks; it can only Read files.',
+    '  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.',
   ];
-  lines.push('  3. Continue the real task using the returned description.');
-  if (markedUrl > 0) {
+  if (sessionId) {
+    lines.push(`  Markers armed under sessionId: ${sessionId} (receipts: analyzed-<sha>.json).`);
+  }
+  if (images.some((img) => img?.source === 'url')) {
     lines.push('  Image URL detected: ukit-vision-analyst downloads it with Bash into');
     lines.push('  .ukit/storage/cache/vision/, then Reads the downloaded file.');
   }
-  if (localMatches.length > markedPath) {
-    lines.push('  A named image path did not resolve from the project root — resolve it before');
-    lines.push('  analysing, and do not guess at its contents.');
-  }
   if (unicNote) lines.push(unicNote);
 
   process.stdout.write(`${lines.join('\n')}\n`);

package/templates/.claude/settings.json

@@ -54,7 +54,13 @@
     "PreToolUse": [
       {
         "matcher": "Read|Grep|Glob",
-        "hooks": []
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\"",
+            "timeout": 8
+          }
+        ]
       },
       {
         "matcher": "Edit|Write",
@@ -104,6 +110,11 @@
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh\"",
             "timeout": 8
           },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\"",
+            "timeout": 8
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
@@ -162,6 +173,11 @@
     "UserPromptSubmit": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\"",
+            "timeout": 8
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",

package/templates/.claude/ukit/index/extract-image.mjs

@@ -6,9 +6,10 @@
  * blocks, so pasted images are invisible unless this script first decodes them
  * to disk. This is the single home of the sha256 key: `pending-<sha>` markers
  * (written by --mark-pending) and `<sha>.<ext>` image files (written by a normal
- * extract) MUST agree exactly, or the TASK-008 gate deadlocks forever. Both
- * paths call the same hashPayload() function on the exact base64 string as it
- * appears in the transcript — no trimming, no normalising, no decoding first.
+ * extract) MUST agree exactly, or analysis receipts can never be matched back to
+ * their markers. Both paths call the same hashPayload() function on the exact
+ * base64 string as it appears in the transcript — no trimming, no normalising,
+ * no decoding first.
  *
  * Usage:
  *   node extract-image.mjs [options]
@@ -323,14 +324,23 @@ function main() {
   // A sha with an existing analyzed-<sha>.json receipt is a closed, content-addressed case:
   // identical bytes already produced that analysis, so skipping it loses no information.
   const isAlreadyAnalyzed = (sha) => fs.existsSync(path.join(markerDir, `analyzed-${sha}.json`));
-  const selected = selectImages(blocks, opts.limit).filter((img) => !isAlreadyAnalyzed(img.sha));
-  const refs = resolveRefs(opts.refs).filter((ref) => !isAlreadyAnalyzed(ref.sha));
+  const allSelected = selectImages(blocks, opts.limit);
+  const allRefs = resolveRefs(opts.refs);
+  const selected = allSelected.filter((img) => !isAlreadyAnalyzed(img.sha));
+  const refs = allRefs.filter((ref) => !isAlreadyAnalyzed(ref.sha));
+  // Closed cases reported back so callers (vision-router.sh) can stay silent on them:
+  // a sha with an analyzed-<sha>.json receipt needs no new dispatch, and without this
+  // list the caller cannot tell "already analyzed" from "never resolved".
+  const alreadyAnalyzed = [
+    ...allSelected.filter((img) => isAlreadyAnalyzed(img.sha)).map((img) => ({ sha: img.sha, source: 'pasted' })),
+    ...allRefs.filter((ref) => isAlreadyAnalyzed(ref.sha)).map((ref) => ({ sha: ref.sha, source: ref.source, ref: ref.value })),
+  ];
 
   // --detect is report-only, so it must not short-circuit --mark-pending when both are
   // passed together. vision-router.sh combines them; short-circuiting here would arm
-  // nothing and leave the TASK-008 write gate permanently open.
+  // nothing and leave every image unmarked.
   if (opts.detect && !opts.markPending) {
-    printResult(opts, { imageCount: selected.length + refs.length, sessionId, images: [] });
+    printResult(opts, { imageCount: selected.length + refs.length, sessionId, images: [], alreadyAnalyzed });
     return;
   }
 
@@ -374,7 +384,7 @@ function main() {
       }
     }
     pruneMarkerDirs(outDir);
-    printResult(opts, { imageCount: written.length, sessionId, images: written });
+    printResult(opts, { imageCount: written.length, sessionId, images: written, alreadyAnalyzed });
     return;
   }
 

package/templates/.claude/ukit/index/route-task.mjs

@@ -579,6 +579,9 @@ function printRouteState(state) {
   if (state.routeSummary?.executionContract?.modelTier) {
     console.log(`modelTier: ${state.routeSummary.executionContract.modelTier}`);
   }
+  if (state.routeSummary?.tierLane?.instruction) {
+    console.log(`tierLane: ${state.routeSummary.tierLane.instruction}`);
+  }
   if (state.routeSummary?.escalatedTier) {
     console.log(`escalatedTier: ${state.routeSummary.escalatedTier}`);
     if (state.routeSummary.escalationReason) {
@@ -1475,6 +1478,15 @@ function buildRouteSummary({
   const primaryTargets = summarizeCompactList(preview.primaryTargets ?? [], 2);
   const relatedTests = summarizeCompactList(preview.relatedTests ?? [], 2);
   const styleFiles = summarizeCompactList(preview.styleFiles ?? [], 1);
+  // WS-C target-aware evidence: the completion ledger checks impact-evidence against these
+  // files, so carry the full resolver list (target + primaryTargets + relatedTests), bounded
+  // for compact route state. Absent when the route has no indexed context — the ledger then
+  // falls back to its legacy any-read behaviour.
+  const expectedSourceFiles = unique([
+    ...(routingContext.targetFile ? [routingContext.targetFile] : []),
+    ...(preview.primaryTargets ?? []),
+    ...(preview.relatedTests ?? []),
+  ].filter((filePath) => typeof filePath === 'string' && filePath.trim())).slice(0, 8);
   const primaryCommands = unique(verificationRecommendation?.commands ?? []);
   const fallbackCommands = unique(verificationRecommendation?.fallbackCommands ?? []);
   const preferredOrder = unique(
@@ -1497,6 +1509,7 @@ function buildRouteSummary({
     executionCandidates,
   });
   const executionContract = buildExecutionContract(executionMode);
+  const tierLane = buildTierLane({ modelTier: executionContract?.modelTier ?? null });
   const completionState = buildCompletionState({
     executionMode,
     verificationRecommendation,
@@ -1539,8 +1552,10 @@ function buildRouteSummary({
     executionCandidates,
     approachSelector,
     executionContract,
+    tierLane,
     completionState,
     continuationState,
+    ...(expectedSourceFiles.length > 0 ? { expectedSourceFiles } : {}),
     intentMode: routingContext.intentMode ?? null,
     handoffFile,
     delegateHint: delegationRecommendation?.hint ?? null,
@@ -1894,9 +1909,10 @@ function buildExecutionContract(executionMode = null) {
       maxReadPasses: 2,
       maxContextPulls: 1,
       verificationPolicy: 'targeted-if-covered',
-      completionRule: 'require-write',
+      completionRule: 'require-write-and-verification',
       delegationPolicy: 'disallow-by-default',
-      completionEvidence: ['write-evidence'],
+      completionEvidence: ['write-evidence', 'verification-evidence'],
+      postEditReviewPolicy: 'sidecar-non-blocking',
     },
     'find-cause': {
       modelTier: 'code',
@@ -1915,6 +1931,7 @@ function buildExecutionContract(executionMode = null) {
       delegationPolicy: 'allow-qualified-sidecar',
       completionEvidence: ['write-evidence', 'verification-evidence'],
       mirrorConsistencyRequired: true,
+      postEditReviewPolicy: 'sidecar-non-blocking',
     },
     'map-impact': {
       modelTier: 'code',
@@ -2182,10 +2199,36 @@ function applyEscalationToRouteSummary(routeSummary = null, { config = null, tar
     delete routeSummary.escalatedTier;
     delete routeSummary.escalationReason;
   }
+  // Recomputed here (not only in buildRouteSummary) so the lane always reflects the final
+  // tier after escalation, on every path that emits a route summary.
+  routeSummary.tierLane = buildTierLane({
+    modelTier: routeSummary.executionContract?.modelTier ?? null,
+    escalatedTier: escalation?.escalatedTier ?? null,
+  });
 
   return routeSummary;
 }
 
+// WS-E tier-role wiring: a contract tier only takes effect when the executing session hands
+// the work to an agent whose definition binds that tier — otherwise every session behaves as
+// if it only had one model. `code` is the DEFAULT implementation lane, so a code-tier contract
+// produces no instruction (inline execution on a code session is already correct, and silence
+// keeps the hook flow smooth). Labels are stable tier roles (lite/code/smart), never provider
+// or model identity. Vision never appears here — it is a capability lane, not a cost tier.
+function buildTierLane({ modelTier = null, escalatedTier = null } = {}) {
+  const tier = escalatedTier ?? modelTier;
+  if (!tier || tier === 'vision') {
+    return null;
+  }
+  return {
+    tier,
+    defaultLane: tier === 'code',
+    instruction: tier === 'code'
+      ? null
+      : `Hand this task to an agent bound to the ${tier} tier instead of doing it inline, unless this session already runs on the ${tier} tier.`,
+  };
+}
+
 function advanceContinuationState(continuationState = null, previousContinuationState = null, thresholds = null) {
   if (!continuationState || typeof continuationState !== 'object') {
     return continuationState;
@@ -2875,6 +2918,14 @@ function compactRouteSummary(routeSummary = null) {
     completionState: routeSummary.completionState ?? null,
     continuationState: routeSummary.continuationState ?? null,
     delegateHint: routeSummary.delegateHint ?? null,
+    // WS-E tier-role binding: consumers need the hand-off instruction, not just the raw tier.
+    ...(routeSummary.tierLane ? { tierLane: routeSummary.tierLane } : {}),
+    // WS-C target-aware evidence: the completion ledger reads these from the PERSISTED route
+    // state — without this spread the CLI path never delivers them and the gate falls back
+    // to legacy any-read behaviour.
+    ...(Array.isArray(routeSummary.expectedSourceFiles) && routeSummary.expectedSourceFiles.length > 0 ? {
+      expectedSourceFiles: routeSummary.expectedSourceFiles,
+    } : {}),
     nextActionType: routeSummary.nextActionType ?? null,
     nextActionCommand: routeSummary.nextActionCommand ?? null,
     helperHint: routeSummary.helperHint ?? null,