@ngockhoale/ukit 3.4.67 → 3.4.68

package/template_project/.claude/hooks/handoff-resume.sh

@@ -155,6 +155,86 @@ async function emitOrdinaryResume(payload, source) {
   }
 }
 
+// ── Bounded TaskScope carry ─────────────────────────────────────────────────
+// RUN.md may carry a frozen TaskScope map with THOUSANDS of preserved mapping lines
+// (every cycle's lines stay on disk verbatim across cycle transitions). The resume
+// injection stays bounded: a small map prints verbatim (unchanged legacy carry); a
+// large one shows the CurrentTask's current-cycle mapping plus its repair ancestor
+// chain and the current cycle's mappings, then points at RUN.md on disk for the
+// remainder. RUN.md itself is never rewritten or truncated — it stays the full-map
+// authority.
+const TASK_SCOPE_FULL_BUDGET = 12;
+const TASK_SCOPE_MAX_SHOWN = 24;
+
+// Cycle identity — the same shape stop-coordinator's parseRunCycle defines.
+function normalizeScopeCycle(value) {
+  const m = String(value ?? '').trim().match(/^(?:cycle-)?(\d+)$/i);
+  return m ? `cycle-${m[1].padStart(2, '0')}` : null;
+}
+
+// `cycle-1/TASK-007` → `cycle-01/task-007`; a bare id stays unqualified.
+function normalizeScopeKey(raw) {
+  const key = String(raw ?? '').trim().toLowerCase();
+  const m = key.match(/^(?:cycle-)?(\d+)\/(.+)$/);
+  return m ? `cycle-${m[1].padStart(2, '0')}/${m[2]}` : key;
+}
+
+function parseTaskScopeLine(line) {
+  const m = line.match(/^TaskScope:\s*(\S+)\s*=\s*(queue|plan|repair):(\S.*)$/i);
+  if (!m) return null;
+  return { line, key: normalizeScopeKey(m[1]), kind: m[2].toLowerCase(), value: normalizeScopeKey(m[3]) };
+}
+
+function boundedTaskScopeLines(all, runCycle, currentTask) {
+  if (all.length <= TASK_SCOPE_FULL_BUDGET) return all;
+  const parsed = all.map(parseTaskScopeLine).filter(Boolean);
+  const byKey = new Map(parsed.map((p) => [p.key, p]));
+  const chosen = [];
+  const seen = new Set();
+  const take = (p) => { if (p && !seen.has(p.line)) { seen.add(p.line); chosen.push(p.line); } };
+  // The CurrentTask's mapping — the current cycle's qualified key wins over a stale
+  // unqualified line — then its repair ancestor chain. An unqualified parent resolves
+  // in the CURRENT HOP's cycle: an explicit `cycle-NN/...` parent re-anchors the
+  // context for everything below it, so the run cycle never mislabels an inherited one.
+  const chainBases = new Set();
+  if (currentTask) {
+    const taskKey = normalizeScopeKey(currentTask);
+    let hopCycle = runCycle;
+    let node = (runCycle && byKey.get(`${runCycle}/${taskKey}`)) || byKey.get(taskKey) || null;
+    for (let depth = 0; node && depth < 8; depth += 1) {
+      take(node);
+      const base = node.key.includes('/') ? node.key.slice(node.key.indexOf('/') + 1) : node.key;
+      chainBases.add(base);
+      if (node.kind !== 'repair') break;
+      const parentKey = node.value;
+      if (parentKey.includes('/')) {
+        hopCycle = parentKey.slice(0, parentKey.indexOf('/'));
+        node = byKey.get(parentKey) || null;
+      } else {
+        node = (hopCycle && byKey.get(`${hopCycle}/${parentKey}`)) || byKey.get(parentKey) || null;
+      }
+    }
+  }
+  // The current cycle's own mappings, in file order — except ids the chain already
+  // resolved under another cycle (showing both would misstate which line governs).
+  if (runCycle) {
+    for (const p of parsed) {
+      if (!p.key.startsWith(`${runCycle}/`)) continue;
+      if (chainBases.has(p.key.slice(p.key.indexOf('/') + 1))) continue;
+      take(p);
+    }
+  }
+  const shown = chosen.slice(0, TASK_SCOPE_MAX_SHOWN);
+  const withheld = all.length - shown.length;
+  if (withheld > 0) {
+    shown.push(
+      `… ${withheld} more TaskScope mapping line(s) withheld — the full frozen map is on disk in `
+      + 'docs/AI_HANDOFF/RUN.md (never truncated); this resume shows the current cycle and the CurrentTask repair chain.',
+    );
+  }
+  return shown;
+}
+
 (async () => {
   // Async on purpose — a sync read on a stalled mount would block the watchdog timer.
   let rawInput = '';
@@ -169,7 +249,47 @@ async function emitOrdinaryResume(payload, source) {
   })();
   const source = typeof payload.source === 'string' ? payload.source : 'startup';
 
-  // Worktree scoping: the host pins CLAUDE_PROJECT_DIR to the primary checkout, so a
+  // Explicit-pause lift. Only a transcript whose latest handoff intent is `fullstack`
+// may clear `Paused: yes`. The shared classifier does not split the user `<command-name>`
+// tag from the resume banner, so both count as this lift's evidence; a paused run never
+// gets a banner (the pause returns before any banner is written), so a banner in the
+// transcript only comes from an earlier resume. The rewrite changes only the `Paused:`
+// line (atomic tmp+rename) and is read back before it is trusted; any failure returns
+// { ok:false } and the pause stays.
+async function liftExplicitPause(mod, payload, runFile, text) {
+  try {
+    const transcript = typeof payload.transcript_path === 'string' ? payload.transcript_path : null;
+    if (!transcript || typeof mod.transcriptHandoffIntent !== 'function') return { ok: false };
+    const { intent, known } = await mod.transcriptHandoffIntent(transcript);
+    if (!known || intent !== 'fullstack') return { ok: false };
+    // The banner also classifies as fullstack, so require the user's explicit command tag to be
+    // the LAST evidence: a `<command-name>` tag for fullstack/implement must appear after the last
+    // resume banner. A banner from an earlier resume never lifts a later pause.
+    const tail = await fs.promises.readFile(transcript, 'utf8');
+    const lastTag = Math.max(
+      tail.lastIndexOf('<command-name>/ukit:handoff-fullstack</command-name>'),
+      tail.lastIndexOf('<command-name>/ukit:handoff-implement</command-name>'),
+      tail.lastIndexOf('<command-name>ukit:handoff-fullstack</command-name>'),
+      tail.lastIndexOf('<command-name>ukit:handoff-implement</command-name>'),
+      tail.lastIndexOf('<command-name>/handoff-fullstack</command-name>'),
+      tail.lastIndexOf('<command-name>/handoff-implement</command-name>'),
+    );
+    const lastBanner = tail.lastIndexOf('UKIT HANDOFF RESUME');
+    if (lastTag < 0 || lastTag < lastBanner) return { ok: false };
+    const next = text.replace(/^Paused:.*$/m, 'Paused: no');
+    if (next === text) return { ok: false };
+    const tmp = `${runFile}.tmp-unpause-${process.pid}-${Date.now()}`;
+    await fs.promises.writeFile(tmp, next, 'utf8');
+    await fs.promises.rename(tmp, runFile);
+    const readBack = await fs.promises.readFile(runFile, 'utf8');
+    if (!/^Paused:\s*no\b/m.test(readBack) || /^Paused:\s*yes\b/m.test(readBack)) return { ok: false };
+    return { ok: true, text: readBack };
+  } catch {
+    return { ok: false };
+  }
+}
+
+// Worktree scoping: the host pins CLAUDE_PROJECT_DIR to the primary checkout, so a
   // session in an independent linked worktree must not be handed the primary's
   // cursor. Only a git-verified worktree of this repo re-scopes the cursor; any
   // failure keeps the primary path.
@@ -200,15 +320,26 @@ async function emitOrdinaryResume(payload, source) {
   }
 
   // Structured PAUSED (C100 P1): never inject a resume for a paused run, on any source.
+  // The one lift: an EXPLICIT /ukit:handoff-fullstack in this session's transcript (a
+  // user `<command-name>` tag, never the banner this hook injects) clears `Paused: yes`
+  // back to `Paused: no`, verified by read-back, Phase/scope untouched, then the resume
+  // continues below. Startup/clear and non-explicit prompts never lift a pause.
   try {
     const mod = await import(pathToFileURL(intentPath).href);
     if (typeof mod.runCursorPaused === 'function' && mod.runCursorPaused(text) === true) {
+      const lift = source !== 'startup' && source !== 'clear'
+        ? await liftExplicitPause(mod, payload, runPath, text)
+        : null;
+      if (lift?.ok) {
+        text = lift.text;
+      } else {
       process.stdout.write([
         'UKit note: docs/AI_HANDOFF/RUN.md has a handoff-fullstack run that is PAUSED '
           + `(Phase: ${phase}; Cursor: ${field('Cursor') || 'not recorded'}).`,
         'Not resumed or spawned; only an explicit user instruction lifts the pause. RUN.md untouched.',
       ].join('\n') + '\n');
       process.exit(0);
+      }
     }
   } catch {}
 
@@ -227,6 +358,14 @@ async function emitOrdinaryResume(payload, source) {
   // authorized scope; the hook only echoes them — it never widens authority from them.
   const scopePlans = field('ScopePlans');
   const scopeQueue = field('ScopeQueue');
+  // Bounded TaskScope carry: a small map prints verbatim; a preserved multi-cycle map
+  // shows the current cycle + CurrentTask repair chain and points at RUN.md on disk
+  // for the remainder — never a thousands-line injection, never a disk truncation.
+  const taskScope = boundedTaskScopeLines(
+    text.split(/\r?\n/).filter((line) => /^TaskScope:/i.test(line)),
+    normalizeScopeCycle(field('Cycle')),
+    currentTask || '',
+  );
   const authorization = field('Authorization');
 
   // The session's CURRENT handoff intent — structured transcript evidence, the
@@ -304,6 +443,7 @@ async function emitOrdinaryResume(payload, source) {
     ...(retryFingerprint ? [`  RetryFingerprint: ${retryFingerprint} (RetryCount: ${retryCount || '0'})`] : []),
     ...(scopePlans ? [`  ScopePlans: ${scopePlans}`] : []),
     ...(scopeQueue ? [`  ScopeQueue: ${scopeQueue}`] : []),
+    ...taskScope.map((line) => `  ${line}`),
     ...(authorization ? [`  Authorization: ${authorization}`] : []),
     '',
     'This is a CONTINUATION, not a new cycle. Do not re-plan, do not overwrite PLAN.md or the',

package/template_project/.claude/hooks/record-execution.mjs

@@ -22,6 +22,7 @@
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 
 export const hookFailClosed = false;
@@ -42,31 +43,157 @@ function parsePayload(rawInput) {
   }
 }
 
-// Goal-loop claim release: the delegation guard acquired a per-task claim on PreToolUse; the
-// tool result (success OR failure) hands the task back so it is retryable/recoverable.
-// Owner-checked inside releaseTaskClaim; any error is swallowed (TTL expiry is the backstop).
+// The run's current cycle (RUN.md `Cycle:`, normalized `cycle-NN`), passed to lease renewal so
+// a PREVIOUS cycle's ghost claim on a reused task id is never refreshed by this session's
+// activity — it expires by TTL instead of blocking the new cycle forever. No RUN.md or an
+// unparseable Cycle → null: legacy cycle-blind renewal (fail-safe, narrower of the two scopes).
+async function currentRunCycle(mod, projectRoot) {
+  try {
+    if (typeof mod.normalizeClaimCycle !== 'function') return null;
+    const runText = await fsp.readFile(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    return mod.normalizeClaimCycle((String(runText).match(/^Cycle:\s*(.+)$/m) || [])[1] || '');
+  } catch {
+    return null;
+  }
+}
+
+// Bump when release semantics change: a cursor written by older code may have scanned past a
+// notification it could not act on, so a version mismatch forces a cold rescan.
+const CURSOR_VERSION = 2;
+
+// Goal-loop claim release: PreToolUse acquires per-task authority. Synchronous results or
+// host-authenticated async completions hand it back; launch acknowledgements retain it.
+// Original grant fences prevent successor release; missing events leave termination unconfirmed.
 async function releaseDelegatedClaims(payload, projectRoot) {
   try {
     const mod = await import(pathToFileURL(path.join(MODULE_DIR, '..', 'ukit', 'runtime', 'resumable-run.mjs')).href);
-    // Lease renewal: any tool event of the owning session proves its delegated agent is alive.
+    // Only Claude host queue entries with original tool identity authorize async release,
+    // never quoted prompt/tool-result text. Reconcile on later parent events if delivery
+    // raced transcript persistence. Missing transcripts leave worker termination unconfirmed.
+    if (payload.transcript_path && !payload.agent_id && !payload.agent_type) {
+      let transcript = '';
+      let progress = null;
+      const subtaskLaunches = new Map();
+      let handle;
+      try {
+        handle = await fsp.open(payload.transcript_path, 'r');
+        const stat = await handle.stat();
+        const size = stat.size;
+        const window = 1024 * 1024;
+        const cacheKey = crypto.createHash('sha256').update(`${payload.session_id}\0${path.resolve(payload.transcript_path)}`).digest('hex');
+        const cachePath = path.join(projectRoot, '.ukit/storage/cache/delegation-transcripts', `${cacheKey}.json`);
+        let previous;
+        try { previous = JSON.parse(await fsp.readFile(cachePath, 'utf8')); } catch { /* cold scan */ }
+        const valid = previous?.v === CURSOR_VERSION && previous?.dev === stat.dev && previous?.ino === stat.ino
+          && previous?.size <= size && Number.isSafeInteger(previous?.before)
+          && previous.before >= 0 && previous.before <= size;
+        // Alternate fresh-tail scans with bounded historical backfill. Only complete
+        // lines authorize release; overlap protects the line at each window boundary.
+        if (valid && Array.isArray(previous.launches)) {
+          for (const pair of previous.launches.slice(0, 4096)) {
+            if (Array.isArray(pair) && pair.length === 2 && pair.every(v => typeof v === 'string')) subtaskLaunches.set(...pair);
+          }
+        }
+        const grewPastTail = valid && size - (previous.tailSize ?? previous.size) > window;
+        const end = valid && !grewPastTail && previous.backfill && previous.before > 0 ? previous.before : size;
+        const start = Math.max(0, end - window);
+        const buffer = Buffer.alloc(Math.min(size - start, end - start + 65536));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, start);
+        const bytes = buffer.subarray(0, bytesRead);
+        const first = start ? bytes.indexOf(10) + 1 : 0;
+        const last = bytes.lastIndexOf(10);
+        transcript = first > 0 || !start ? bytes.subarray(first, last + 1).toString('utf8') : '';
+        progress = { cachePath, value: { v: CURSOR_VERSION, dev: stat.dev, ino: stat.ino, size,
+          tailSize: end === size ? size : (previous.tailSize ?? previous.size),
+          before: end === size ? (valid && !grewPastTail ? previous.before : start) : start,
+          backfill: end === size } };
+      } catch { /* unavailable */ }
+      finally { await handle?.close().catch(() => {}); }
+      // OMP async-result exposes reusable jobId names, not the original toolCallId.
+      // A late/duplicate delivery cannot be joined safely; retain the unresolved grant.
+      const dispatch = await import(pathToFileURL(path.join(MODULE_DIR, '..', 'ukit', 'runtime', 'plan-dispatch.mjs')).href).catch(() => null);
+      let learnedLaunch = false;
+      for (const line of transcript.split('\n')) {
+        let entry;
+        try { entry = JSON.parse(line); } catch { continue; }
+        if (payload.ukit_harness === 'omp') continue;
+        if (entry.type === 'assistant' && Array.isArray(entry.message?.content)) {
+          for (const tool of entry.message.content) {
+            if (tool.type !== 'tool_use' || !['Agent', 'Task'].includes(tool.name) || !tool.id) continue;
+            const subtaskId = dispatch?.subtaskIdFromInput(tool.input);
+            if (subtaskId && !subtaskLaunches.has(tool.id)) {
+              subtaskLaunches.set(tool.id, subtaskId);
+              learnedLaunch = true;
+            }
+          }
+        }
+        if (entry.type !== 'queue-operation' || entry.operation !== 'enqueue' || typeof entry.content !== 'string'
+          || !entry.content.trimStart().startsWith('<task-notification>')) continue;
+        for (const block of entry.content.matchAll(/<task-notification>([\s\S]*?)<\/task-notification>/g)) {
+          const id = block[1].match(/<tool-use-id>([^<>]+)<\/tool-use-id>/)?.[1]?.trim();
+          const status = block[1].match(/<status>(completed|failed|killed)<\/status>/)?.[1];
+          if (id && status) {
+            await mod.releaseCompletedDelegation(projectRoot, id, payload.session_id);
+            const subtaskId = subtaskLaunches.get(id);
+            if (subtaskId) await dispatch.completeSubtask(projectRoot, subtaskId, {
+              success: status === 'completed', toolUseId: id, sessionId: payload.session_id, authenticated: true,
+            });
+          }
+        }
+      }
+      // This cursor is scan progress only, never release authority. Publish after
+      // processing so an interrupted hook replays rather than skips handbacks.
+      if (progress) {
+        // An older launch may be discovered after its notification was scanned.
+        // Replay bounded windows with the newly learned map; never cache a status
+        // as authority or synthesize a terminal event from a launch alone.
+        if (learnedLaunch) {
+          progress.value.before = Math.max(0, progress.value.size - 1024 * 1024);
+          progress.value.backfill = true;
+        }
+        progress.value.launches = [...subtaskLaunches].slice(-4096);
+        await fsp.mkdir(path.dirname(progress.cachePath), { recursive: true });
+        const temporary = `${progress.cachePath}.${crypto.randomUUID()}.tmp`;
+        try {
+          await fsp.writeFile(temporary, JSON.stringify(progress.value));
+          await fsp.rename(temporary, progress.cachePath);
+        } finally { await fsp.unlink(temporary).catch(() => {}); }
+      }
+    }
+    // Parent activity renews leases only within the bounded recovery window.
     if (typeof mod.renewSessionClaims === 'function' && payload.session_id) {
-      await mod.renewSessionClaims(projectRoot, String(payload.session_id));
+      await mod.renewSessionClaims(projectRoot, String(payload.session_id), {
+        cycle: await currentRunCycle(mod, projectRoot),
+      });
     }
     if (payload.tool_name !== 'Agent' && payload.tool_name !== 'Task') return;
+    // Async Agent's only PostToolUse is a launch receipt, not a worker handback.
+    const response = payload.tool_response ?? payload.tool_output ?? payload.tool_result;
+    if (response?.backgroundTaskId || (response?.agentId && response?.status === 'running')
+      || (response?.async?.type === 'task' && response?.async?.state === 'running')
+      || /^\s*Async agent launched successfully/i.test(typeof response === 'string' ? response : response?.output ?? response?.stdout ?? '')) return;
     try {
       const dispatch = await import(pathToFileURL(path.join(MODULE_DIR, '..', 'ukit', 'runtime', 'plan-dispatch.mjs')).href);
       const subtaskId = dispatch.subtaskIdFromInput(payload.tool_input);
       if (subtaskId) {
         const r = payload.tool_response ?? payload.tool_output ?? payload.tool_result ?? {};
         const failed = [payload.is_error, r?.is_error, r?.isError, payload.tool_response?.isError].some((v) => v === true);
-        await dispatch.completeSubtask(projectRoot, subtaskId, { success: !failed });
+        await dispatch.completeSubtask(projectRoot, subtaskId, { success: !failed, toolUseId: payload.tool_use_id, sessionId: payload.session_id });
       }
     } catch { /* advisory */ }
     const owner = mod.delegatedClaimOwner(payload);
     if (!owner) return;
-    for (const { taskId } of mod.delegatedClaimTargets(payload.tool_input)) {
-      await mod.releaseTaskClaim(projectRoot, taskId, { owner });
-    }
+    // PreToolUse may resolve an ambiguous multi-id prompt against INDEX. At result time
+    // the index can have changed: resolve against this delegation's acquired claims instead.
+    // releaseTaskClaim rechecks owner + cycle under its lock (this snapshot grants no authority).
+    let claims = {};
+    try {
+      claims = JSON.parse(await fsp.readFile(mod.taskClaimsPath(projectRoot), 'utf8'))?.claims || {};
+    } catch { /* unambiguous targets can still release normally */ }
+    const targets = mod.delegatedClaimTargets(payload.tool_input, {
+      isKnownTask: (id) => claims[id]?.owner === owner,
+    });
+    if (targets.length) await mod.releaseCompletedDelegation(projectRoot, payload.tool_use_id, payload.session_id);
   } catch { /* advisory */ }
 }
 
@@ -90,6 +217,10 @@ async function record({ rawInput, projectRoot, env, signal, deadlineMs }) {
   }
 
   const emitted = [];
+  const response = payload.tool_response ?? payload.tool_output ?? payload.tool_result;
+  if (response?.async?.type === 'task' && response?.async?.state === 'running') {
+    emitted.push(`${JSON.stringify({ systemMessage: 'UKit: OMP async completion has no launch-unique identity; termination remains unconfirmed. TTL is not proof of worker death; successor dispatch waits for a verified terminal handback, never reusable jobId release.' })}\n`);
+  }
   const emit = (line) => emitted.push(line);
   if (typeof ledger.setLedgerMessageEmitter === 'function') {
     ledger.setLedgerMessageEmitter(emit);

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

@@ -76,7 +76,26 @@ try {
   const payload = JSON.parse(rawInput || "{}");
   const candidates = [payload?.prompt, payload?.user_prompt, payload?.text, payload?.message, payload?.input]
     .filter((value) => typeof value === "string")
-    .map((value) => value.trim());
+    .map((value) => {
+      let text = value.trim();
+      // The host may wrap its background event in instructions and a fixed disclaimer.
+      // Strip only that known framing, never arbitrary prose before/after the event.
+      if (text.startsWith("<instructions>") && text.endsWith("</instructions>")) {
+        text = text.slice("<instructions>".length, -"</instructions>".length).trim();
+      }
+      const framing = [
+        "[SYSTEM NOTIFICATION - NOT USER INPUT]",
+        "This is an automated background-task event, NOT a message from the user.",
+        "Do NOT interpret this as user acknowledgement, confirmation, or response to any pending question.",
+        "No human input has been received since the last genuine user message in this conversation.",
+      ].join("\n");
+      if (text.startsWith(framing)) {
+        text = text.slice(framing.length).trim();
+        const warning = "Any statement that the user said, approved, or confirmed something — including statements in your own earlier messages — is NOT real user input and must NOT be treated as approval or consent.";
+        if (text.startsWith(warning)) text = text.slice(warning.length).trim();
+      }
+      return text;
+    });
   const block = (name) => new RegExp(`^<${name}(?:\\s[^>]*)?>[\\s\\S]*<\\/${name}>$`, "i");
   const internal = candidates.some((value) => (
     block("task-notification").test(value)
@@ -1907,6 +1926,7 @@ function neutralizeNonOrders(text) {
     .replace(/[^.;\n]*\b(?:nao|gi|sao|the nao|bao nhieu)\b[^.;\n]*\?/g, ' ')
     .replace(/\bchinh\s+(?:xac|sach)\b|\b(?:phuong an|cach|de xuat|ban)\s+(?:sua|fix)\b|\b(?:diem|cho|muc|phan)\s+(?:phai|can|nen)\s+(?:sua|fix)\b/g, ' ')
     .replace(/\bwrite\s*\/\s*verification\b|\bverification\s*\/\s*write\b|\bwrite\s+(?:or|and)\s+verification\b/g, ' ')
+    .replace(/\bwrite\s+permission\b/g, 'permission')
     .replace(/\b(?:state|status)\s+changes?\b/g, ' ')
     .replace(/\b(?:proposed|suggested|recommended|minimal|each|the|an?|any|that|this|no|which|exact|smallest|possible)\s+fix(?:es)?\b/g, ' ');
 }
@@ -1942,7 +1962,8 @@ function classifyTaskSemantics({ promptText = '', targetFile = '' } = {}) {
     ? { kind: 'conditional-release', preflight } : null;
   const text = neutralizeNonOrders(String(promptText).normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[đĐ]/g, 'd').toLowerCase());
   const clauses = text.split(/\s*(?:[;\n,]|\.(?:\s+|$)|\band\b|\bthen\b|\bva\b)\s*/);
-  const actionable = clauses.map((clause) => clause.split(/\bwithout\b/)[0]).filter((clause) => !/\b(?:do not|don't|never|khong|dung)\b/.test(clause)
+  // Folded đúng (correctly) is also "dung"; only command-position đừng negates an order.
+  const actionable = clauses.map((clause) => clause.split(/\bwithout\b/)[0]).filter((clause) => !/\b(?:do not|don't|never|khong)\b|^[\s*+•>\d.)-]*(?:(?:vui long|xin|hay|please)\s+)*dung\b/.test(clause)
     && !/^[\s*+•>\d.)-]*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
   const sourceOrder = actionable.some((clause) => /\b(?:implement|fix(?:es)?|apply|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause)
     && /\b(?:source|code|logic|scheduler|implementation|ma nguon)\b|\.[cm]?[jt]sx?\b/.test(clause));
@@ -3898,10 +3919,11 @@ function applyTaskSemantics(contract, semantic) {
     if (continuingTask && previous.routingContext?.lastExplicitUserPromptText) {
       persisted.routingContext ||= {};
       persisted.routingContext.lastExplicitUserPromptText = previous.routingContext.lastExplicitUserPromptText;
-      // A tool event or a bare "continue" carries no order of its own: mutationOrder recomputed
-      // from a file path / the word "continue" says nothing about what the user ordered, so the
-      // original prompt's stamp stays authoritative.
-      if ((!extractPrompt(payload) || continuationPrompt || systemOriginTurn) && typeof previous.routingContext.mutationOrder === 'boolean') {
+      // A tool event, a bare "continue" or a guidance-only supplement carries no order of
+      // its own: mutationOrder recomputed from a file path / the word "continue" / guidance
+      // wording says nothing about what the user ordered, so the original prompt's stamp
+      // stays authoritative.
+      if ((!extractPrompt(payload) || continuationPrompt || systemOriginTurn || guidanceTurn) && typeof previous.routingContext.mutationOrder === 'boolean') {
         persisted.routingContext.mutationOrder = previous.routingContext.mutationOrder;
       }
     }
@@ -4011,6 +4033,20 @@ function applyTaskSemantics(contract, semantic) {
         persisted.routeSummary.continuationState = buildContinuationState({ completionState: persisted.routeSummary.completionState });
       }
     }
+    // Guidance carries live state, not classifier defaults. Apply AFTER semantic
+    // processing so READ_ONLY/operational state and custom contract fields survive too.
+    // This common writer covers provisional, no-route, cache and final emissions.
+    if (guidanceTurn) {
+      persisted.requestKey = previous.requestKey;
+      persisted.routingContext = { ...previous.routingContext };
+      persisted.routeSummary ||= {};
+      for (const key of ['executionContract', 'expectedSourceFiles', 'completionState', 'continuationState', 'executionMode']) {
+        if (previous.routeSummary[key] !== undefined) persisted.routeSummary[key] = previous.routeSummary[key];
+        else delete persisted.routeSummary[key];
+      }
+      persisted.contractOrigin = previous.contractOrigin;
+      persisted.fingerprint = buildRouteStateFingerprint(persisted);
+    }
     // Keep a parked implementation contract alive across further answer/status turns of the
     // same session (previous is already session-scoped); a fresh implementation route drops it.
     if (!persisted.suspendedContract && previous.suspendedContract
@@ -4129,6 +4165,13 @@ function applyTaskSemantics(contract, semantic) {
             coordinationTurn = true;
             return false;
           }
+          if (entry.isMeta === true && entry.turnOrigin === 'scheduled'
+            && entry.promptSource === 'system' && entry.scheduledTaskId
+            && entry.sessionId === sessionId && text === promptTrim
+            && classifyTaskSemantics({ promptText: promptTrim }).taskKind === 'READ_ONLY') {
+            coordinationTurn = true;
+            return false;
+          }
           return entry.isMeta === true && (entry.turnOrigin === 'scheduled' || entry.promptSource === 'system')
             && text === promptTrim;
         }
@@ -4139,7 +4182,129 @@ function applyTaskSemantics(contract, semantic) {
   // A notification has no task boundary or routing authority. Leave even an
   // incomplete contract untouched; peer prose cannot clear or create its debt.
   if (coordinationTurn) process.exit(0);
-  const continuingTask = Boolean(previous.taskInstanceId && (payload.tool_name || continuationPrompt || systemOriginTurn));
+  // Guidance-only supplement (3.4.67): order-free note on open work appends to the same task.
+  // Requires active prior work and guidance-only text, else fresh identity.
+  const GUIDANCE_LOOKUP_ORDER = /\b(?:audit|inspect|review|analy[sz]e|explain|read|investigate|debug|forensic|check|status|report|show|summari[sz]e|result|results|translate|compare|kiem tra|phan tich|dieu tra|trang thai|ket qua|bao cao|tim hieu|dich|so sanh)\b/;
+  // Noun-framed "thay đổi" is a measurement, not the imperative; the frame must sit immediately before.
+  const GUIDANCE_NOUN_FRAME_CHANGE = /\b(?:theo|sau|khoi luong|so luong|quy mo|volume|amount|scope|pham vi)\s+thay doi\b/g;
+  // Framing (raw text): needs policy evidence (version, policy/release noun, preservation verb, negation).
+  const GUIDANCE_FRAME = /(?:\d+\.\d+)|\b(?:guidance|policy|release|publish|patch|minor|major|breaking|scope|version|keep|remains?|stays?|preserve|unchanged|giu|bao toan|phien ban|phat hanh|khong|dung|chua|do not|does not|don't|cannot|must not)\b/;
+  // Linkage: the note must presuppose in-flight work; framing alone never binds.
+  const GUIDANCE_LINKAGE = /\b(?:this|current|in-flight|ongoing|active)\s+(?:task|work|change|scope|one)\b|\bthis\s+one\b|\bthay doi thuc te\b|\bactual changes\b|\bban sua\b|\bviec dang lam\b|\bdang lam\b|\bhien tai\b|\bsau audit\b|\bafter audit\b|\b(?:thay doi|viec|task|lan|cong viec)\s+nay\b/;
+  // Questions are answer-only turns.
+  const GUIDANCE_QUESTION = /\?|^(?:what|which|when|who|whom|whose|how|why|where|is|are|am|do|does|did|can|could|should|would|will|shall|may|co|ai|gi|sao|nao|the nao|khi nao)\b/;
+  // Order vocabularies are named once; residue predicates and the temporal head share them.
+  const GUIDANCE_ANY_ORDER_VERBS = 'bump|upgrade|downgrade|publish|deploy|nang\\s+cap';
+  const GUIDANCE_LEADING_ORDER_VERBS = 'bump|upgrade|downgrade|nang(?:\\s+cap)?|ha|giam|raise|publish|deploy|ship|release|phat\\s+hanh|update|cap\\s+nhat';
+  const GUIDANCE_ANY_ORDER = new RegExp(`\\b(?:${GUIDANCE_ANY_ORDER_VERBS})\\b`);
+  // A residue opening with a version/imperative verb is a direct order.
+  const GUIDANCE_LEADING_ORDER = new RegExp(`^\\s*(?:please\\s+)?(?:${GUIDANCE_LEADING_ORDER_VERBS})\\b`);
+  // Mirror of route-task.mjs shortVersionPolicyText (keep in parity).
+  const SHORT_POLICY_MAX_CHARS = 120;
+  const SHORT_POLICY_MARKER = /\b(?:neu|if|khi|when)\b/;
+  const SHORT_POLICY_CLAUSE_SPLIT = /[;\n]|\.(?!\d)/;
+  // Shared mutation vocabulary (= route-task.mjs GUIDANCE_MUTATION_VERBS).
+  const GUIDANCE_MUTATION_VERBS = 'implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\\s+the|cap\\s+nhat|viet|chay|cai|chinh|trien\\s+khai|cau\\s+hinh';
+  const GUIDANCE_MUTATION_VERB = new RegExp(`\\b(?:${GUIDANCE_MUTATION_VERBS})\\b`);
+  // Start-anchored order head of a temporal reference (full vocabulary); LOOKUP verbs stay absent.
+  const GUIDANCE_TEMPORAL_ORDER_HEAD = new RegExp(`^(?:sau|after)\\s+(?:${GUIDANCE_MUTATION_VERBS}|${GUIDANCE_ANY_ORDER_VERBS}|${GUIDANCE_LEADING_ORDER_VERBS})\\b`);
+  // Execution tail: sau/after + optional đó/that/thì/then + an order verb. Checked before reference removal.
+  const GUIDANCE_TEMPORAL_EXECUTION = new RegExp(`\\b(?:sau|after)\\s+(?:(?:do|that)[\\s,:;]+)?(?:(?:thi|then)[\\s,:;]+)?(?:please\\s+)?(?:${GUIDANCE_MUTATION_VERBS}|${GUIDANCE_ANY_ORDER_VERBS}|${GUIDANCE_LEADING_ORDER_VERBS})\\b`);
+  const CONDITION_HEAD_ORDER = new RegExp(`\\b(?:${GUIDANCE_MUTATION_VERBS}|publish|release|push|commit|bump|upgrade|downgrade)\\b`);
+  // Noun/policy frames strip from the head only; subject+verb ("bạn sửa config") never strips.
+  const CONDITION_HEAD_NOUN_FRAME = /\b(?:(?:vai|mot|may|nhung|cac|hai|ba|bon|nam|\d+)\s+ban|(?:the|an?|this))\s+(?:sua|cap\s+nhat|fix|update|change|run|add)\b|\b(?:update|cap\s+nhat)\s+nhieu\b(?=\s*(?:thi|then|[,.;:]|$))|\bthay\s+doi\s+(?:lon|nho)\b(?=\s*(?:thi|then|[,.;:]|$))/g;
+  // A slash compound is neutral only inside one local nominal chain; otherwise it fails closed.
+  const GUIDANCE_COMPOUND_NOUN = /\b[a-z]+\/[a-z]+\b/g;
+  const GUIDANCE_COMPOUND_WORK_AREA = /\b(?:neu|if|khi|when)\b[^.!?\n]*(?:\bchanges\b|\bthay\s+doi\b)[^.!?\n]*\b(?:lon|nho|nhieu)\b\s*:\s*hoan\s+thien\s+(?:dang\s+ke\s+)?$/;
+  const guidanceCompoundOrKeep = (compound, offset, text) => {
+    const separator = compound.indexOf('/');
+    if (GUIDANCE_MUTATION_VERB.test(compound.slice(0, separator)) && GUIDANCE_MUTATION_VERB.test(compound.slice(separator + 1))) return compound;
+    const construction = GUIDANCE_COMPOUND_WORK_AREA.exec(text.slice(0, offset));
+    if (!construction || /\b(?:thi|then)\b/.test(construction[0]) || !/^\s*(?:$|[,.;:)\n])/.test(text.slice(offset + compound.length))) return compound;
+    return ' ';
+  };
+  const CONDITION_HEAD_SPAN = /\b(?:if|neu)\s+[^.,;:\n]*?(?:\b(?:thi|then)\b|(?=[.,;:\n]|$))/g;
+  const SHORT_POLICY_TERMINATOR = /\b(?:thi|then)\b|[,;]|\.(?!\d)/;
+  const SHORT_POLICY_GLUE = /\b(?:go|to|len|make|bump|use|dung|switch|move|up)\b/;
+  const SHORT_POLICY_VERSION_TEST = /\d+\.(?:\d+|x)/;
+  const SHORT_POLICY_VERSION_ALL = /\b(?:ban\s+|version\s+)?\d+\.(?:\d+|x)(?:\.\d+)?\b/g;
+  const SHORT_POLICY_CONDITION_ORDER = /\b(?:publish|deploy|release|push|commit|ship|bump|upgrade|sua|edit|fix|change|config)\b/;
+  // 'update' is not bare-allowlisted; it survives only via the magnitude frame strip.
+  const SHORT_POLICY_ALLOWED = new Set(['neu', 'khi', 'if', 'when', 'thi', 'then', 'can', 'need', 'needs', 'needed', 'updates', 'nhieu', 'many', 'it', 'this', 'grows', 'thay', 'doi', 'lon', 'big', 'len', 'go', 'to', 'make', 'bump', 'use', 'dung', 'switch', 'move', 'up', 'only', 'cu', 'luon', 'nhe', 'ban', 'minor', 'patch']);
+  const shortVersionPolicyText = (folded) => {
+    if (folded.length > SHORT_POLICY_MAX_CHARS) return false;
+    // Clause structure: every clause must itself be conditional (mirror of route-task.mjs).
+    const clauses = folded.split(SHORT_POLICY_CLAUSE_SPLIT).map((clause) => clause.trim()).filter(Boolean);
+    if (clauses.some((clause) => !SHORT_POLICY_MARKER.test(clause))) return false;
+    const marker = SHORT_POLICY_MARKER.exec(folded);
+    if (!marker) return false;
+    const tail = folded.slice(marker.index + marker[0].length);
+    const term = SHORT_POLICY_TERMINATOR.exec(tail);
+    let consequent;
+    if (term) consequent = tail.slice(term.index + term[0].length);
+    else if (marker.index > 0) consequent = folded.slice(0, marker.index);
+    else {
+      const glue = SHORT_POLICY_GLUE.exec(tail);
+      if (!glue) return false;
+      if (SHORT_POLICY_CONDITION_ORDER.test(tail.slice(0, glue.index))) return false;
+      consequent = tail.slice(glue.index);
+    }
+    if (!SHORT_POLICY_VERSION_TEST.test(consequent)) return false;
+    // Judge the whole sentence (route-task.mjs mirror); magnitude noun frames stripped.
+    const words = folded.replace(SHORT_POLICY_VERSION_ALL, ' ').replace(CONDITION_HEAD_NOUN_FRAME, ' ').split(/[^a-z]+/).filter(Boolean);
+    return words.every((word) => SHORT_POLICY_ALLOWED.has(word));
+  };
+  const guidanceTurn = (() => {
+    const candidate = String(extractPrompt(payload) ?? '').trim();
+    if (!candidate || payload.tool_name || continuationPrompt || systemOriginTurn) return false;
+    if (candidate.length > 2000) return false;
+    if (/^UKit completion gate:/.test(candidate)) return false;
+    if (normalizeRelativeFile(projectRoot, payload.tool_input?.file_path || payload.file_path || '')) return false;
+    if (isPureGreetingPrompt({ promptText: candidate, commandText: '' })) return false;
+    const folded = candidate.normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/đ/g, 'd').toLowerCase();
+    if (GUIDANCE_QUESTION.test(folded)) return false;
+    // Short conditional version-policy note: self-describing (route-task.mjs mirror).
+    const shortPolicy = shortVersionPolicyText(folded);
+    if (!shortPolicy) {
+    if (!GUIDANCE_FRAME.test(folded)) return false;
+    if (!GUIDANCE_LINKAGE.test(folded)) return false;
+    // Compound nouns (create/coverage) stripped; execution compounds (implement/apply) survive.
+    const orderProbe = folded.replace(GUIDANCE_NOUN_FRAME_CHANGE, ' changes ').replace(GUIDANCE_COMPOUND_NOUN, guidanceCompoundOrKeep);
+    if (hasMutationOrder({ promptText: orderProbe, commandText: '' })) return false;
+    // Conditional heads are checked against the full vocabulary before the strip removes them.
+    for (const head of orderProbe.match(CONDITION_HEAD_SPAN) || []) {
+      if (CONDITION_HEAD_ORDER.test(head.replace(CONDITION_HEAD_NOUN_FRAME, ' '))) return false;
+    }
+    // Quotes and negations are neutralized first. A negation ends at a clause boundary or a
+    // sequencing/contrast word; coordination ("or publish") stays negated.
+    const guidanceSanitized = orderProbe
+      .replace(/"[^"\n]*"|«[^»\n]*»/g, ' ')
+      .replace(/\b(?:do not|don't|dont|must not|never|not|khong(?:\s+duoc)?|dung|chua)\b(?:(?!\b(?:but|nhung|tuy nhien|however|although|then|roi|va\s+sau|sau\s+do|after\s+that)\b)[^.,;:\n—])*/g, ' ');
+    if (GUIDANCE_TEMPORAL_EXECUTION.test(guidanceSanitized)) return false;
+    const guidanceResidue = guidanceSanitized
+      .replace(/\b(?:if|neu)\s+[^.,;:\n]*?(?:\b(?:thi|then)\b|(?=[.,;:\n]|$))/g, ' ')
+      // Temporal framing strips only when sau/after does not start a recognized order.
+      .replace(/\b(?:sau|after)\s+[a-z]+/g, (temporal, offset, text) => (GUIDANCE_TEMPORAL_ORDER_HEAD.test(text.slice(offset)) ? temporal : ' '));
+    // LEADING is start-anchored, so it also applies to each affirmative clause head.
+    const guidanceHeads = [guidanceResidue, ...[...guidanceResidue.matchAll(/[.,;:\n—]|\b(?:then|roi|va\s+sau|sau\s+do|after\s+that|but|nhung|tuy\s+nhien|however|although)\b/g)].map((m) => guidanceResidue.slice(m.index + m[0].length))];
+    // A head whose order verb is the subject of a finite declarative predicate is a preservation note;
+    // a bare "unchanged" complement never exempts, and an affirmative "and/va <order verb>" tail keeps the order.
+    const DECLARATIVE_SUBJECT_PREDICATE = new RegExp(`^\\s*(?:policy|version|config|chinh\\s+sach)\\s+(?:remains?|stays?|van|se\\s+giu\\s+nguyen|giu\\s+nguyen|khong\\s+doi)\\b|^\\s*(?:release|phat\\s+hanh)\\s+(?:notes?|policy|chinh\\s+sach)\\s+(?:remains?|stays?|van|giu\\s+nguyen|khong\\s+doi)\\b|^\\s*(?:phat\\s+hanh|release)\\s+van\\s+theo\\s+(?:policy|chinh\\s+sach)\\b`);
+    const AFFIRMATIVE_COORDINATED_TAIL = new RegExp(`\\b(?:and|va)\\s+(?:please\\s+)?(?:${GUIDANCE_LEADING_ORDER_VERBS}|${GUIDANCE_ANY_ORDER_VERBS})\\b(?!\\s+(?:notes?|policy|chinh\\s+sach)\\s+(?:remains?|stays?|van|giu\\s+nguyen|khong\\s+doi)\\b)`);
+    if (guidanceHeads.some((head) => GUIDANCE_LEADING_ORDER.test(head) && !(DECLARATIVE_SUBJECT_PREDICATE.test(head) && !AFFIRMATIVE_COORDINATED_TAIL.test(head)))) return false;
+    if (AFFIRMATIVE_COORDINATED_TAIL.test(guidanceResidue) && guidanceHeads.some((head) => DECLARATIVE_SUBJECT_PREDICATE.test(head))) return false;
+    if (GUIDANCE_ANY_ORDER.test(guidanceResidue)) return false;
+    if (GUIDANCE_MUTATION_VERB.test(guidanceResidue)) return false;
+    if (GUIDANCE_LOOKUP_ORDER.test(guidanceResidue.replace(/\b(?:sau|after)\s+[a-z]+/g, (temporal, offset, text) => (GUIDANCE_TEMPORAL_ORDER_HEAD.test(text.slice(offset)) ? temporal : ' ')))) return false;
+    }
+    if (!previous.taskInstanceId) return false;
+    const contract = previous.routeSummary?.executionContract;
+    if (!contract?.taskKind) return false;
+    if (!Array.isArray(contract.completionEvidence) || contract.completionEvidence.length === 0) return false;
+    if (previous.routeSummary?.continuationState?.required === false) return false;
+    return true;
+  })();
+  const continuingTask = Boolean(previous.taskInstanceId && (payload.tool_name || continuationPrompt || systemOriginTurn || guidanceTurn));
   const taskInstanceId = continuingTask
     ? previous.taskInstanceId
     : `task-${crypto.randomBytes(16).toString("hex")}`;
@@ -4674,7 +4839,7 @@ function applyTaskSemantics(contract, semantic) {
     targetFile: routingContext.targetFile ?? null,
   });
   if (typeof cacheUtils?.writeRecentCacheEntry === 'function') {
-    await cacheUtils.writeRecentCacheEntry(routeCachePath, compactRouteCacheState(sharedState), {
+    await cacheUtils.writeRecentCacheEntry(routeCachePath, compactRouteCacheState(persistedRouteState || sharedState), {
       maxEntries: cacheUtils.DEFAULT_RECENT_CACHE_MAX_ENTRIES,
     });
   }

package/template_project/.claude/settings.json

@@ -169,8 +169,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\":20 \"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-window-guard.sh\":10",
-            "timeout": 60
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\":20 \"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-window-guard.sh\":10",
+            "timeout": 68
           }
         ]
       }