@ngockhoale/ukit 2.2.12 → 2.2.16

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.16 - 2026-09-06
+
+The vision gate is gone — image work is advisory-routed, never blocked. Since TASK-008, a
+pasted image on the UNIC gateway armed `vision-gate.sh`, which refused every Edit/Write until
+`ukit-vision-analyst` had produced receipts for ALL pending images. In practice this
+repeatedly stranded sessions (receipts that never landed, one stale marker blocking
+unrelated writes), so the maintainer retired the hard block: `vision-gate.sh` and its
+manifest entry `hook-vision-gate` are removed from both the live tree and templates, the omp
+bridge and `hook-chain-runner.mjs` no longer list it, and `vision-router.sh` now says "never
+guess at image contents" instead of claiming edits are GATED. Routing to
+`ukit-vision-analyst` still happens — on this gateway the main tier genuinely cannot read
+images — but nothing blocks while it runs. Supersedes the 2.2.15 escape hatch, which patched
+a message on a gate that no longer exists. Verified: vision-hook, route-vision,
+vision-agent, install-wiring, provision-worktree, and ompHookBridge (52/52) all green.
+(An interim 2026-09-05 patch that added an escape hatch to the block message is included
+here and immediately superseded — the gate itself no longer exists.)
+
+## 2.2.14 - 2026-09-05
+
+The context hard-cap gate no longer bricks healthy sessions with a phantom token count. The
+tracker behind `compact.hardCapTokens` accumulates every prompt and tool output across a
+session, and it only reset on the PreCompact hook — which fires for a manual `/compact` but not
+for every harness auto-compact path (SDK/VSCode being the known gap). A session whose live
+context had been compacted down to almost nothing could therefore reach a tracked 528k against
+the 500k cap: Read/Grep stayed open but every Edit/Write/Bash was refused, and the user saw the
+assistant freeze with no error. Every real compaction — manual or automatic — now also leaves a
+`compact_boundary` entry in the session transcript, so `compact-threshold.mjs` rebase the
+counter from that record (`syncCompactPressureStateWithTranscript`, stamped
+`lastCompactBoundaryAt` so each boundary resets exactly once). Both the prompt-time hook and
+`context-hardcap-gate.sh` sync before acting, and the reset is persisted so the gate re-arms
+instead of disabling itself.
+
+When the cap is genuinely reached, the model is now ordered to tell the user instead of going
+quiet. The hard-phase prompt warning and the gate's block message both lead with an explicit
+directive — tell the user "gõ /compact ngay" as the first sentence of the reply, since typing
+"continue" alone hits the same block — and the advisory soft phase tells the model to surface
+`/compact` at the next natural pause. `context-window-guard.sh`'s overflow directive likewise
+demands the compact instruction as the first sentence rather than a buried suggestion.
+
+Vietnamese concrete bug reports route to the debug lane again. Signals such as `lỗi`, `sửa`,
+`đăng nhập`, `đang ở đâu` were written inside `\b(...)\b`, but JavaScript `\b` is ASCII-only and
+those words have diacritic edges, so the patterns could never match — "app bị lỗi khi đăng nhập,
+sửa giúp tôi" fell through to informational lanes while the identical English prompt routed
+correctly. All Vietnamese intent patterns in the router and catalog now use explicit
+`(?<![A-Za-z0-9_])` / `(?![A-Za-z0-9_])` edges; regression tests cover the debug-lane prompt,
+the open-ended status question, and hook-level state.
+
+## 2.2.13 - 2026-09-05
+
+Question-shaped prompts no longer get blocked by the completion gate. "Đây là lỗi gì?",
+"model bạn đang dùng là model gì", or "what is this error?" route to the informational lane and
+answer freely; only prompts that actually ask for a change (fix/sửa/build/…) still owe write and
+verification evidence before claiming done. Two layered causes: the Vietnamese question pattern
+only matched adjacent `là gì` (missing "là model gì" / "là lỗi gì"), and the `\blỗi` veto never
+fired at all — JavaScript `\b` word boundaries don't exist around diacritic characters. A
+`strongQuestion` signal (an explicit `?`, a leading interrogative, or the Vietnamese pattern) now
+overrides error-wording vetoes, while "error when I run tests" and "why is build failing?" still
+route to investigation.
+
+The source-code index understands SQL from the canonical source, not just the installed mirror.
+`CREATE TABLE/VIEW/FUNCTION/PROCEDURE/INDEX/TYPE` and `ALTER TABLE` statements are extracted as
+symbols with schema-qualified names captured by their bare object name (`qas.fn_rpt_billing` →
+`fn_rpt_billing`), and `.sql` files are tracked and code-indexed. The schema bump had previously
+landed only in the runtime mirror; `src/index/` now carries the same v8 schema so the mirror-parity
+test holds and the `scripts/index` lane benefits too.
+
+The handoff model-tier guard closes an under-block found while scenario-testing it. Once a real
+`EXECUTOR_MODEL` or `REVIEWER_MODEL` was on disk, an in-place rewrite could silently demote the
+executor to a lite tier or set executor == reviewer; validation now also fires when an
+already-real model line changes value (same-model rewrites and upward escalation stay free). The
+push-time backstop was unaffected — this moves the rejection to write time, where it belongs.
+
+`handoff.maxParallelAgents` template default is now 2, matching the operator setting; the config
+help prose no longer claims a default of 12 one line above a configured 2.
+
 ## 2.2.12 - 2026-09-04
 
 `ukit install` and `ukit update` now clean up broken Claude Code hook registrations automatically.

package/manifests/platform.full.yaml

@@ -1131,19 +1131,6 @@ items:
     packs:
       - core
 
-  - id: hook-vision-gate
-    type: hook
-    sourceTemplate: .claude/hooks/vision-gate.sh
-    targetPath: .claude/hooks/vision-gate.sh
-    requires:
-      - ukit-index-extract-image-script
-      - ukit-index-unic-gateway-script
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
   - id: hook-context-hardcap-gate
     type: hook
     sourceTemplate: .claude/hooks/context-hardcap-gate.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.12",
+  "version": "2.2.16",
   "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/index/buildIndex.js

@@ -29,11 +29,11 @@ const EXCLUDED_DIR_NAMES = new Set([
   '.venv',
   'venv',
 ]);
-const CODE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue']);
+const CODE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.sql']);
 const STYLE_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
 // `.sh` is tracked but never parsed, like `.md`/`.json`/`.yaml` — it is matched
 // by path only. Without it every shipped hook script was invisible to the index.
-const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.json', '.yaml', '.yml', '.md', '.sh']);
+const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.sql', '.json', '.yaml', '.yml', '.md', '.sh']);
 const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSIONS]);
 export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const INDEX_PARSE_BATCH_SIZE = 8;
@@ -729,6 +729,19 @@ export function extractSymbols(filePath, content) {
     }
   };
 
+  if (filePath.endsWith('.sql')) {
+    // Capture the object name, skipping an optional schema qualifier (qas.fn_rpt_billing → fn_rpt_billing).
+    const sqlIdent = '(?:(?:["`]?[A-Za-z_][A-Za-z0-9_$]*["`]?)\\s*\\.\\s*)?["`]?([A-Za-z_][A-Za-z0-9_$]*)["`]?';
+    addMatches(new RegExp(`CREATE\\s+(?:OR\\s+REPLACE\\s+)?TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${sqlIdent}`, 'gi'), 'table');
+    addMatches(new RegExp(`CREATE\\s+(?:OR\\s+REPLACE\\s+)?VIEW\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${sqlIdent}`, 'gi'), 'view');
+    addMatches(new RegExp(`CREATE\\s+(?:OR\\s+REPLACE\\s+)?FUNCTION\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${sqlIdent}`, 'gi'), 'function');
+    addMatches(new RegExp(`CREATE\\s+(?:OR\\s+REPLACE\\s+)?PROCEDURE\\s+${sqlIdent}`, 'gi'), 'procedure');
+    addMatches(new RegExp(`CREATE\\s+(?:UNIQUE\\s+)?INDEX\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${sqlIdent}`, 'gi'), 'index');
+    addMatches(new RegExp(`CREATE\\s+(?:TYPE|DOMAIN|SEQUENCE|MATERIALIZED\\s+VIEW)\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${sqlIdent}`, 'gi'), 'type');
+    addMatches(new RegExp(`ALTER\\s+TABLE\\s+(?:IF\\s+EXISTS\\s+)?${sqlIdent}`, 'gi'), 'table');
+    return dedupeBy(symbols, (item) => `${item.filePath}:${item.type}:${item.name}`);
+  }
+
   addMatches(/export\s+(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)/g, 'function');
   addMatches(/export\s+class\s+([A-Za-z_$][A-Za-z0-9_$]*)/g, 'class');
   addMatches(/(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s*)?\(/g, 'callable');

package/src/index/paths.js

@@ -13,7 +13,7 @@ export const INDEX_ARTIFACTS = {
   analogs: 'analogs.json',
 };
 
-export const INDEX_SCHEMA_VERSION = 7;
+export const INDEX_SCHEMA_VERSION = 8;
 
 export function getIndexDir(rootDir) {
   return path.join(rootDir, '.cache', 'index');

package/src/index/routeCatalog.js

@@ -234,7 +234,7 @@ export const ROUTE_CATALOG = [
     contextMode: 'standalone',
     signals: [
       { type: 'prompt', regex: /\b(what(?:'s| is)? next|next steps?|project status|current status|where are we|continue(?: from)?(?: last session)?|roadmap|status\.md|task queue|tasks\.md|next queued task|pick next task|work from tasks)\b/i, score: 7 },
-      { type: 'prompt', regex: /\b(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)\b/i, score: 7 },
+      { type: 'prompt', regex: /(?<![A-Za-z0-9_])(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)(?![A-Za-z0-9_])/i, score: 7 },
     ],
   },
   {

package/src/index/taskRouting.js

@@ -960,7 +960,7 @@ function hasHandoffSignal(lower, raw) {
     || /\b(ai handoff|handoff phase|handoff mode|clear handoff|update handoff|start handoff|handoff clear)\b/.test(lower)
     || /\b(brainstorm|idea dump|ideas?).{0,80}\b(handoff|tasks?|taskify|split|breakdown)\b/.test(lower)
     || /\b(handoff|tasks?|taskify|split|breakdown).{0,80}\b(brainstorm|idea dump|ideas?)\b/.test(lower)
-    || /\b(gom|chia|tach|tách|lên|len|xóa|clear|dọn).{0,80}\b(idea|ý tưởng|y tuong|task|công việc|cong viec|handoff)\b/.test(raw)
+    || /(?<![A-Za-z0-9_])(gom|chia|tach|tách|lên|len|xóa|clear|dọn).{0,80}(?<![A-Za-z0-9_])(idea|ý tưởng|y tuong|task|công việc|cong viec|handoff)(?![A-Za-z0-9_])/.test(raw)
     || /\b(bàn giao|ban giao).{0,80}\b(ai|task|công việc|cong viec)\b/.test(raw);
 }
 
@@ -980,7 +980,7 @@ function hasStatusUpdateSignal(lower, raw) {
 function hasOpenEndedStatusSignal(lower, raw) {
   return /\b(what next|what is next|what's next|next step|next steps|project status|current status|where are we|continue|continue from last session|roadmap|status\.md|task queue|tasks\.md|next queued task|pick next task|work from tasks)\b/.test(lower)
     || /\b(lam gi tiep|buoc tiep theo|tiep theo lam gi|lam tiep|dang o dau|trang thai project|tinh trang project|task tiep theo|viec tiep theo trong tasks)\b/.test(lower)
-    || /\b(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)\b/.test(raw);
+    || /(?<![A-Za-z0-9_])(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)(?![A-Za-z0-9_])/.test(raw);
 }
 
 function hasTaskQueueNextSignal(lower, raw) {
@@ -994,7 +994,7 @@ function hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext = false }
   }
 
   return /\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature|update|change|modify|inject|apply|review|audit|diff|pr feedback|code review|auth|login|api|endpoint|test|spec)\b/.test(lower)
-    || /\b(sửa|fix|lỗi|bug|debug|implement|cài|thêm|review|kiểm tra|soát|đăng nhập)\b/.test(raw);
+    || /(?<![A-Za-z0-9_])(sửa|fix|lỗi|bug|debug|implement|cài|thêm|review|kiểm tra|soát|đăng nhập)(?![A-Za-z0-9_])/.test(raw);
 }
 
 function hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext = false } = {}) {
@@ -1017,11 +1017,11 @@ function hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext = fal
 
     return mentionsTargetDoc(lower, targetName)
       || /\b(edit|write|improve|document|docs?|readme|changelog|worklog|memory|code map|template|wording|copy|grammar|format|structure|heading|section|handoff notes?)\b/.test(lower)
-      || /\b(câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu|ghi chú bàn giao)\b/.test(raw);
+      || /(?<![A-Za-z0-9_])(câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu|ghi chú bàn giao)(?![A-Za-z0-9_])/.test(raw);
   }
 
   return /\b(template|wording|edit|copy|grammar|format|structure|heading|section|docs?)\b/.test(lower)
-    || /\b(mẫu|câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu)\b/.test(raw);
+    || /(?<![A-Za-z0-9_])(mẫu|câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu)(?![A-Za-z0-9_])/.test(raw);
 }
 
 function hasExplicitStatusUpdateSignal(lower, raw) {

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -100,7 +100,21 @@ function readRunCursor() {
   const mod = await import(pathToFileURL(thresholdModulePath).href);
   const pressurePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'compact-pressure.json');
   const rawState = readJsonSafe(pressurePath, null);
-  const state = mod.buildCompactPressureState(rawState, config);
+
+  // A compaction the PreCompact hook missed (SDK/VSCode auto-compact) leaves the tracked
+  // counter counting history that was already summarised away — the exact failure that
+  // bricks a healthy session at this cap. The transcript's own compact_boundary entries
+  // are the reliable record of real compactions, so sync before deciding, and persist the
+  // reset so it re-arms exactly once per boundary instead of disabling the gate.
+  let state = mod.buildCompactPressureState(rawState, config);
+  try {
+    const synced = await mod.syncCompactPressureStateWithTranscript(rawState, config, payload.transcript_path);
+    if (synced.reset) {
+      state = await mod.writeCompactPressureState(projectRoot, synced.state, config);
+    }
+  } catch {
+    state = mod.buildCompactPressureState(rawState, config);
+  }
   const thresholds = mod.buildCompactThresholds(config);
 
   const gracePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hardcap-grace.json');
@@ -140,6 +154,7 @@ function readRunCursor() {
           `An unfinished run is in flight (Phase: ${run.phase}${run.cursor ? `, Cursor: ${run.cursor}` : ''}), so this call is allowed instead of stranding it mid-edit.`,
           'Spend the remaining grace on LANDING, not on new work: finish the current edit, commit, update docs/AI_HANDOFF/RUN.md, push.',
           'Do NOT start a new task, open new files, or spawn agents. When grace runs out the gate blocks hard.',
+          'Tell the user in your reply that context is over the cap and they should run /compact as soon as this run lands.',
           'After the user runs /compact, the SessionStart resume hook replays the cursor and the run continues automatically.',
         ].join('\n') + '\n',
       );
@@ -150,19 +165,20 @@ function readRunCursor() {
 
   const lines = [
     `BLOCKED (context hard cap): estimated context ~${state.estimatedTotalTokens} tokens >= hard cap ${thresholds.hardCapTokens}.`,
+    'FIRST ACTION IN YOUR REPLY — tell the user plainly, do not just stop silently: "Context đã đầy — hãy gõ /compact ngay (run /compact now)".',
+    'Typing "continue" alone will hit this same block; only /compact (or a new session) resets the counter. After compacting, resume the interrupted task.',
     'This is an absolute ceiling (compact.hardCapTokens), separate from the soft/hard advisory phases — those were apparently not followed.',
     `Edit/Write/Bash refused (tool_name=${toolName}) until real compaction happens.`,
     run
       ? 'The unfinished-run grace window (compact.hardCapGraceCalls) is already exhausted — progress should be committed and the cursor written by now.'
       : 'No unfinished run in docs/AI_HANDOFF/RUN.md, so there is no grace window to spend.',
-    'Remedy (any one): run /compact, or start a new session (SessionStart resets the counter), or delete .ukit/storage/cache/compact-pressure.json.',
     'Do not work around this by summarizing inline and continuing, and do not reach for a non-gated write tool.',
   ];
   process.stderr.write(`${lines.join('\n')}\n`);
   process.exit(2);
 })().catch((err) => {
-  // Unlike vision-gate.sh, a logic error here fails OPEN: this is a backstop on top of
-  // advisory nudges, not a correctness gate — a broken gate must not brick every session.
+  // A logic error here fails OPEN: this is a backstop on top of advisory nudges,
+  // not a correctness gate — a broken gate must not brick every session.
   process.stderr.write(`context-hardcap-gate: internal error, failing open: ${err?.message ?? err}\n`);
   process.exit(0);
 });

package/templates/.claude/hooks/context-window-guard.sh

@@ -211,7 +211,7 @@ if (withinCooldown) {
   lines_out.push('ACTION THIS TURN, before starting new investigation/subagents/pipeline phases:');
   lines_out.push('1) Persist current progress now (update docs/STATUS.md, e.g. via the update-status skill) so nothing is lost.');
   lines_out.push('2) If the remaining work still has multiple steps or pipeline phases left, split what remains into bounded docs/AI_HANDOFF tasks instead of continuing in this one thread — smaller phases keep each turn under the cap.');
-  lines_out.push('3) Otherwise, tell the user plainly: run /compact now, or wrap up and start a fresh session — work already committed/persisted to disk is not lost.');
+  lines_out.push('3) Otherwise, make the user\'s next action the FIRST sentence of your reply so it cannot be missed: "Context sắp đầy — gõ /compact ngay (run /compact now)", or wrap up and start a fresh session — work already committed/persisted to disk is not lost. Do not keep working silently until tools start being refused.');
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch — each teammate carries its own context window, and every finished report is injected back here, so running many at once is the fastest way to overflow this session. Avoid spawning more until context drops back under the cap.`);
   }

package/templates/.claude/hooks/handoff-model-guard.sh

@@ -60,6 +60,20 @@ function extractField(text, name) {
   return matches[matches.length - 1][1].trim();
 }
 
+// Phase-section detection and model extraction must run on visible content only:
+// task/plan templates carry `## Executor Report` / `## Reviewer Verdict` inside HTML
+// comments, and matching those made plain task creation fail with reviewer/executor
+// model errors (the Phase 2 misfire).
+function stripHtmlComments(text) {
+  return String(text || '').replace(/<!--[\s\S]*?-->/g, '');
+}
+
+function isPlaceholderValue(value) {
+  const raw = String(value || '').trim();
+  if (!raw || /^[<(]/.test(raw)) return true;
+  return ['-','--','tbd','todo','n/a','na','none','unknown','pending'].includes(raw.toLowerCase());
+}
+
 if (toolName === 'Write' || toolName === 'Edit') {
   const filePath = String(input.file_path || '');
   if (!filePath) process.exit(0);
@@ -84,9 +98,11 @@ if (toolName === 'Write' || toolName === 'Edit') {
       : currentContent.replace(oldStr, newStr);
   }
   const newContent = resultingContent();
+  const newVisible = stripHtmlComments(newContent);
+  const currentVisible = stripHtmlComments(currentContent);
 
-  if (isPlan && /## Planner Report/.test(newContent)) {
-    const plannerModel = extractField(newContent, 'PLANNER_MODEL');
+  if (isPlan && /## Planner Report/.test(newVisible)) {
+    const plannerModel = extractField(newVisible, 'PLANNER_MODEL');
     if (!plannerModel || /^unknown$/i.test(plannerModel)) {
       block('PLANNER_MODEL missing/unknown in PLAN.md. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) and self-report its model.');
     }
@@ -102,42 +118,96 @@ if (toolName === 'Write' || toolName === 'Edit') {
     const taskId = taskMatch[1];
     const planPath = path.join(projectRoot, 'docs/AI_HANDOFF/PLAN.md');
 
-    const isFreshTaskFile = !fileExists && !/## Executor Report|## Reviewer Verdict/.test(newContent);
+    const hasExecutorReport = /## Executor Report/.test(newVisible);
+    const hasReviewerVerdict = /## Reviewer Verdict/.test(newVisible);
+    const isFreshTaskFile = !fileExists;
     if (isFreshTaskFile) {
       const planContent = fs.existsSync(planPath) ? fs.readFileSync(planPath, 'utf8') : '';
-      const plannerModel = extractField(planContent, 'PLANNER_MODEL');
+      const plannerModel = extractField(stripHtmlComments(planContent), 'PLANNER_MODEL');
       if (!plannerModel || tierOf(plannerModel) !== 'smart') {
         block(`Cannot create ${taskId}.md — PLAN.md has no valid smart-tier PLANNER_MODEL yet. Run planning via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) first.`);
       }
     }
 
-    if (/## Executor Report/.test(newContent) && !/## Executor Report/.test(currentContent)) {
-      const executorModel = extractField(newContent, 'EXECUTOR_MODEL');
-      if (!executorModel || /^unknown$/i.test(executorModel)) {
-        block(`${taskId}: EXECUTOR_MODEL missing/unknown. Implementation must run via Agent tool subagent_type: "feature-implementer" (sonnet/unic-code) and self-report its model.`);
+    // A section already on disk only counts as validated when its model is real —
+    // otherwise a placeholder skeleton created at Phase 2 could be silently promoted
+    // to a "real" report without ever passing tier validation.
+    const currentExecutorReal = /## Executor Report/.test(currentVisible)
+      && !isPlaceholderValue(extractField(currentVisible, 'EXECUTOR_MODEL'));
+    if (hasExecutorReport && !currentExecutorReal) {
+      const executorModel = extractField(newVisible, 'EXECUTOR_MODEL');
+      if (isPlaceholderValue(executorModel) || /^unknown$/i.test(executorModel)) {
+        if (!isFreshTaskFile) {
+          block(`${taskId}: EXECUTOR_MODEL missing/placeholder. Implementation must run via Agent tool subagent_type: "feature-implementer" (sonnet/unic-code) and self-report its model.`);
+        }
+        // Else: skeleton sections copied from a task template at creation time — the
+        // real Executor Report is appended in Phase 3 and validated there.
+      } else {
+        if (tierOf(executorModel) === 'vision') {
+          block(`${taskId}: EXECUTOR_MODEL "${executorModel}" ${VISION_LANE_MESSAGE}`);
+        }
+        if (tierOf(executorModel) === 'lite') {
+          block(`${taskId}: EXECUTOR_MODEL "${executorModel}" is lite tier. Implementation must run on at least sonnet/unic-code, never haiku/unic-lite.`);
+        }
       }
-      if (tierOf(executorModel) === 'vision') {
-        block(`${taskId}: EXECUTOR_MODEL "${executorModel}" ${VISION_LANE_MESSAGE}`);
-      }
-      if (tierOf(executorModel) === 'lite') {
-        block(`${taskId}: EXECUTOR_MODEL "${executorModel}" is lite tier. Implementation must run on at least sonnet/unic-code, never haiku/unic-lite.`);
+    } else if (hasExecutorReport && currentExecutorReal) {
+      // An in-place rewrite of an already-real model line must not silently demote the
+      // tier or collide with the reviewer; the push-time check would catch it, but the
+      // violating report should never be accepted onto disk in the first place.
+      const previousExecutorModel = extractField(currentVisible, 'EXECUTOR_MODEL');
+      const executorModel = extractField(newVisible, 'EXECUTOR_MODEL');
+      if (executorModel && previousExecutorModel && executorModel !== previousExecutorModel) {
+        if (tierOf(executorModel) === 'vision') {
+          block(`${taskId}: EXECUTOR_MODEL "${executorModel}" ${VISION_LANE_MESSAGE}`);
+        }
+        if (tierOf(executorModel) === 'lite') {
+          block(`${taskId}: EXECUTOR_MODEL "${executorModel}" is lite tier. Implementation must run on at least sonnet/unic-code, never haiku/unic-lite.`);
+        }
+        const verdictModel = extractField(newVisible, 'REVIEWER_MODEL');
+        if (!isPlaceholderValue(verdictModel) && verdictModel.toLowerCase() === executorModel.toLowerCase()) {
+          block(`${taskId}: EXECUTOR_MODEL ("${executorModel}") matches REVIEWER_MODEL ("${verdictModel}") — reviewer must differ from executor.`);
+        }
       }
     }
 
-    if (/## Reviewer Verdict/.test(newContent) && !/## Reviewer Verdict/.test(currentContent)) {
-      const executorModel = extractField(currentContent, 'EXECUTOR_MODEL') || extractField(newContent, 'EXECUTOR_MODEL');
-      const reviewerModel = extractField(newContent, 'REVIEWER_MODEL');
-      if (!reviewerModel || /^unknown$/i.test(reviewerModel)) {
-        block(`${taskId}: REVIEWER_MODEL missing/unknown. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart) and self-report its model.`);
-      }
-      if (tierOf(reviewerModel) === 'vision') {
-        block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" ${VISION_LANE_MESSAGE}`);
-      }
-      if (tierOf(reviewerModel) !== 'smart') {
-        block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" is not strong/opus tier. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart).`);
+    const currentReviewerReal = /## Reviewer Verdict/.test(currentVisible)
+      && !isPlaceholderValue(extractField(currentVisible, 'REVIEWER_MODEL'));
+    if (hasReviewerVerdict && !currentReviewerReal) {
+      const executorModel = extractField(currentVisible, 'EXECUTOR_MODEL') || extractField(newVisible, 'EXECUTOR_MODEL');
+      const reviewerModel = extractField(newVisible, 'REVIEWER_MODEL');
+      if (isPlaceholderValue(reviewerModel) || /^unknown$/i.test(reviewerModel)) {
+        if (!isFreshTaskFile) {
+          block(`${taskId}: REVIEWER_MODEL missing/placeholder. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart) and self-report its model.`);
+        }
+        // Else: skeleton Reviewer Verdict on a freshly created task file — Phase 4
+        // appends the real verdict and it is validated there.
+      } else {
+        if (tierOf(reviewerModel) === 'vision') {
+          block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" ${VISION_LANE_MESSAGE}`);
+        }
+        if (tierOf(reviewerModel) !== 'smart') {
+          block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" is not strong/opus tier. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart).`);
+        }
+        if (executorModel && reviewerModel && executorModel.toLowerCase() === reviewerModel.toLowerCase()) {
+          block(`${taskId}: REVIEWER_MODEL ("${reviewerModel}") matches EXECUTOR_MODEL — reviewer must differ from executor. Re-run review through a different subagent/model.`);
+        }
       }
-      if (executorModel && reviewerModel && executorModel.toLowerCase() === reviewerModel.toLowerCase()) {
-        block(`${taskId}: REVIEWER_MODEL ("${reviewerModel}") matches EXECUTOR_MODEL — reviewer must differ from executor. Re-run review through a different subagent/model.`);
+    } else if (hasReviewerVerdict && currentReviewerReal) {
+      // Mirror of the executor in-place rule: a real reviewer verdict must not be
+      // rewritten onto a weaker tier or onto the executor's own model.
+      const previousReviewerModel = extractField(currentVisible, 'REVIEWER_MODEL');
+      const reviewerModel = extractField(newVisible, 'REVIEWER_MODEL');
+      if (reviewerModel && previousReviewerModel && reviewerModel !== previousReviewerModel) {
+        if (tierOf(reviewerModel) === 'vision') {
+          block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" ${VISION_LANE_MESSAGE}`);
+        }
+        if (tierOf(reviewerModel) !== 'smart') {
+          block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" is not strong/opus tier. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart).`);
+        }
+        const executorModel = extractField(newVisible, 'EXECUTOR_MODEL');
+        if (!isPlaceholderValue(executorModel) && executorModel.toLowerCase() === reviewerModel.toLowerCase()) {
+          block(`${taskId}: REVIEWER_MODEL ("${reviewerModel}") matches EXECUTOR_MODEL — reviewer must differ from executor. Re-run review through a different subagent/model.`);
+        }
       }
     }
   }
@@ -160,7 +230,7 @@ if (toolName === 'Bash') {
   for (const taskId of taskIds) {
     const taskPath = path.join(projectRoot, `docs/AI_HANDOFF/tasks/${taskId}.md`);
     if (!fs.existsSync(taskPath)) continue;
-    const text = fs.readFileSync(taskPath, 'utf8');
+    const text = stripHtmlComments(fs.readFileSync(taskPath, 'utf8'));
     if (!text.includes('## Reviewer Verdict')) continue; // not yet reviewed, not this push's concern
 
     // A documented, human-approved exception (e.g. an opus-tier executor escalation left no
@@ -172,10 +242,10 @@ if (toolName === 'Bash') {
     const executorModel = extractField(text, 'EXECUTOR_MODEL');
     const reviewerModel = extractField(text, 'REVIEWER_MODEL');
 
-    if (!executorModel || /^unknown$/i.test(executorModel)) problems.push(`${taskId}: EXECUTOR_MODEL missing/unknown`);
+    if (isPlaceholderValue(executorModel) || /^unknown$/i.test(executorModel)) problems.push(`${taskId}: EXECUTOR_MODEL missing/placeholder`);
     else if (tierOf(executorModel) === 'lite') problems.push(`${taskId}: EXECUTOR_MODEL "${executorModel}" is lite tier`);
 
-    if (!reviewerModel || /^unknown$/i.test(reviewerModel)) problems.push(`${taskId}: REVIEWER_MODEL missing/unknown`);
+    if (isPlaceholderValue(reviewerModel) || /^unknown$/i.test(reviewerModel)) problems.push(`${taskId}: REVIEWER_MODEL missing/placeholder`);
     else if (tierOf(reviewerModel) !== 'smart') problems.push(`${taskId}: REVIEWER_MODEL "${reviewerModel}" is not opus/unic-smart tier`);
 
     if (executorModel && reviewerModel && executorModel.toLowerCase() === reviewerModel.toLowerCase()) {

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

@@ -331,7 +331,7 @@ const { pathToFileURL } = require('url');
   function hasOpenEndedStatusSignal(lower, raw) {
     return /\b(what next|what is next|what's next|next step|next steps|project status|current status|where are we|continue|continue from last session|roadmap|status\.md|task queue|tasks\.md|next queued task|pick next task|work from tasks)\b/.test(lower)
       || /\b(lam gi tiep|buoc tiep theo|tiep theo lam gi|lam tiep|dang o dau|trang thai project|tinh trang project|task tiep theo|viec tiep theo trong tasks)\b/.test(lower)
-      || /\b(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)\b/.test(raw);
+      || /(?<![A-Za-z0-9_])(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)(?![A-Za-z0-9_])/.test(raw);
   }
 
   function hasTaskQueueNextSignal(lower, raw) {
@@ -345,7 +345,7 @@ const { pathToFileURL } = require('url');
     }
 
     return /\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature|update|change|modify|inject|apply|review|audit|diff|pr feedback|code review|auth|login|api|endpoint|test|spec)\b/.test(lower)
-      || /\b(sửa|fix|lỗi|bug|debug|implement|cài|thêm|review|kiểm tra|soát|đăng nhập)\b/.test(raw);
+      || /(?<![A-Za-z0-9_])(sửa|fix|lỗi|bug|debug|implement|cài|thêm|review|kiểm tra|soát|đăng nhập)(?![A-Za-z0-9_])/.test(raw);
   }
 
   function hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext = false } = {}) {
@@ -368,11 +368,11 @@ const { pathToFileURL } = require('url');
 
       return mentionsTargetDoc(lower, targetName)
         || /\b(edit|write|improve|document|docs?|readme|changelog|worklog|memory|code map|template|wording|copy|grammar|format|structure|heading|section|handoff notes?)\b/.test(lower)
-        || /\b(câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu|ghi chú bàn giao)\b/.test(raw);
+        || /(?<![A-Za-z0-9_])(câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu|ghi chú bàn giao)(?![A-Za-z0-9_])/.test(raw);
     }
 
     return /\b(template|wording|edit|copy|grammar|format|structure|heading|section|docs?)\b/.test(lower)
-      || /\b(mẫu|câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu)\b/.test(raw);
+      || /(?<![A-Za-z0-9_])(mẫu|câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu)(?![A-Za-z0-9_])/.test(raw);
   }
 
   function hasExplicitStatusUpdateSignal(lower, raw) {
@@ -1473,6 +1473,48 @@ const { pathToFileURL } = require('url');
     };
   }
 
+  function isInformationalPrompt({
+    promptText = '',
+    commandText = '',
+    scores = null,
+  } = {}) {
+    if (String(commandText || '').trim()) return false;
+    const raw = String(promptText || '').toLowerCase().trim();
+    if (!raw) return false;
+    const questionSignal = raw.includes('?')
+      || /\b(what|how|when|which|where|who|is|are|does|do|did|can|could|would|should|will)\b/.test(raw)
+      || /(là\s+(?:[^\s]+\s+){0,2}gì|thế nào|như thế nào|bao nhiêu|khi nào|bao giờ|ở đâu|nghĩa là|được không|không\b)/.test(raw);
+    // '?' or a leading/Vietnamese interrogative — required to overrule error wording.
+    const strongQuestion = raw.includes('?')
+      || /^(what|how|when|which|where|who|is|are|does|do|did|can|could|would|should|will)\b/.test(raw)
+      || /(là\s+(?:[^\s]+\s+){0,2}gì|thế nào|như thế nào|bao nhiêu|khi nào|bao giờ|ở đâu)/.test(raw);
+    if (scores) {
+      if (
+        scores.implementSignal
+        || scores.reviewSignal
+        || scores.debugSignal
+        || scores.impactSignal
+        || scores.smallFixSignal
+        || scores.directTransformSignal
+      ) {
+        return false;
+      }
+      if (scores.failureSignal && !strongQuestion) {
+        return false;
+      }
+    }
+    const implementWords = /(?<![A-Za-z0-9_])(implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|sửa|thêm|tạo|xóa|đổi|thay thế|cập nhật|viết|build|chạy|cài)(?![A-Za-z0-9_])/.test(raw);
+    if (implementWords) return false;
+    const investigationWords = /\b(why|debug|triage|root cause|investigate|tại sao)\b/.test(raw);
+    if (investigationWords) return false;
+    // \b never matches around 'lỗi' (diacritics are not \w), so test it as a plain
+    // substring: an error report is informational only when phrased as a question.
+    if (raw.includes('lỗi') && !strongQuestion) return false;
+    const reviewWords = /\b(review|audit|verify)\b/.test(raw);
+    if (reviewWords) return false;
+    return questionSignal;
+  }
+
   function deriveExecutionMode({
     promptText = '',
     commandText = '',
@@ -1495,6 +1537,10 @@ const { pathToFileURL } = require('url');
       && (scores.impactSignal || /\b(check all affected|map all affected|across all affected)\b/.test(raw));
     const boundedLocalBuildCandidate = scores.buildSignal && scores.boundedEditSignal && scores.explicitTarget && !scores.sharedRisk;
 
+    if (isInformationalPrompt({ promptText, commandText, scores })) {
+      return 'informational';
+    }
+
     if ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal) {
       return 'review-release';
     }
@@ -1778,7 +1824,7 @@ const { pathToFileURL } = require('url');
   }
 
   function buildCompletionState({ executionMode = null, verificationRecommendation = null } = {}) {
-    if (!executionMode) {
+    if (!executionMode || executionMode === 'informational') {
       return null;
     }
 
@@ -2331,8 +2377,9 @@ const { pathToFileURL } = require('url');
   const now = Date.now();
   const debounceMs = 10 * 60 * 1000;
   const previousTs = Number(previous?.ts || 0);
+  const informationalNoTargetPrompt = isInformationalPrompt({ promptText, commandText }) && !filePath;
 
-  if (active.length === 0) {
+  if (active.length === 0 || informationalNoTargetPrompt) {
     const lastExplicitUserPromptText = promptText.trim()
       || previous?.routingContext?.lastExplicitUserPromptText
       || '';
@@ -2343,6 +2390,7 @@ const { pathToFileURL } = require('url');
       targetFile: filePath,
       contextIntent: '',
       taskType: '',
+      ...(informationalNoTargetPrompt ? { executionMode: 'informational' } : {}),
     };
     const previousContext = buildPreviousContextSnapshot({
       projectRoot,