@ngockhoale/ukit 2.7.6 → 2.7.8

package/src/core/taskBudgetValidator.js

@@ -8,8 +8,10 @@
 //   DEFAULT_CRITERIA              — frozen thresholds used by `validateTaskFile` by default.
 //   VERIFICATION_MINUTE_TABLE     — frozen literal table for `yarn test:release-core` and
 //                                   `node scripts/release/verify-release.mjs`. `yarn vitest run`
-//                                   is NOT in the table — its cost is computed dynamically
-//                                   (0.5 per file argument), see `estimateVerificationMinutes`.
+//                                   and the `yarn test` alias (`package.json`:
+//                                   `"test": "vitest run"`) are NOT in the table — their cost
+//                                   is computed dynamically (0.5 per file argument), see
+//                                   `estimateVerificationMinutes`.
 //   estimateVerificationMinutes   — sums per-command minutes over a verification list.
 //   validateTaskFile              — parses a TASK-xxx.md and returns
 //                                   `{ verdict, reasons: [{ criterion, detail }] }`.
@@ -39,8 +41,9 @@ export const VERIFICATION_MINUTE_TABLE = Object.freeze({
   'node scripts/release/verify-release.mjs': 2,
 });
 
-// Per-command minute estimate. `yarn vitest run` → 0.5 per FILE argument
-// (i.e. per non-flag token after `run`); anything else falls back to 1 flat.
+// Per-command minute estimate. `yarn vitest [run]` and the `yarn test` alias (the repo's
+// dominant verification form) → 0.5 per FILE argument (per non-flag token after the runner
+// word); anything else falls back to 1 flat.
 export function estimateVerificationMinutes(commands) {
   if (!Array.isArray(commands)) return 0;
   let total = 0;
@@ -51,8 +54,8 @@ export function estimateVerificationMinutes(commands) {
       total += VERIFICATION_MINUTE_TABLE[cmd];
       continue;
     }
-    if (/^yarn\s+vitest(\s+run)?\b/.test(cmd)) {
-      // 0.5 minutes per non-flag argument after `run` (or after `yarn vitest`).
+    if (/^yarn\s+(?:vitest(\s+run)?|test)(?=\s|$)/.test(cmd)) {
+      // 0.5 minutes per non-flag argument after the runner word (`run`, or `yarn test` itself).
       const tokens = cmd.split(/\s+/);
       const runIdx = tokens.indexOf('run');
       const tail = runIdx >= 0 ? tokens.slice(runIdx + 1) : tokens.slice(2);

package/src/core/unattendedDoctor.js

@@ -16,6 +16,13 @@ const INSTALL_REPAIR = 'Run ukit install';
 const OMP_CONFIG_TIMEOUT_MS = 5000;
 const COMPLETION_LOOP_HEADER = '## Unattended Completion Loop';
 
+// B3 / FR-003 — the shipped template carries `{{token}}` placeholders that `ukit install`
+// renders. `parse()` must not see them raw: `{{compact.autoCompactWindow}}` reads as a flow
+// mapping in KEY position, and the `yaml` lib then warns "Keys with collection values will be
+// stringified" on every doctor run. Same neutralization `tests/consistency/ompAgentParity.test.js`
+// already applies; deliberately generic (no key-specific case) so a new placeholder is covered.
+const TEMPLATE_PLACEHOLDER_PATTERN = /\{\{[^}]+\}\}/g;
+
 async function readOmpConfig(projectRoot) {
   const configPath = path.join(projectRoot, '.omp', 'config.yml');
   try {
@@ -51,7 +58,7 @@ function execOmpConfigGet(projectRoot, ompPath) {
 async function readTemplateDenyMatches() {
   try {
     const text = await fs.readFile(path.join(PACKAGE_ROOT, 'templates', '.omp', 'config.yml'), 'utf8');
-    const parsed = parse(text);
+    const parsed = parse(text.replace(TEMPLATE_PLACEHOLDER_PATTERN, '0'));
     const patterns = parsed?.bash?.patterns;
     if (!Array.isArray(patterns)) return [];
     return patterns

package/src/render/buildVariables.js

@@ -39,6 +39,16 @@ export function buildTemplateVariables({ projectContext, stackContext, packageVe
       os: projectContext.runtime.os,
       nodeVersion: projectContext.runtime.nodeVersion,
     },
+    verification: {
+      // CX-10: render only commands whose scripts exist in the target
+      // package.json — a hardcoded lint/typecheck list produced a permanently
+      // failing verification contract on projects without those scripts.
+      requiredBeforeCompletion: JSON.stringify(
+        ['test', 'lint', 'typecheck']
+          .filter((name) => projectContext?.scripts?.[name])
+          .map((name) => `${projectContext.runtime.packageManager} ${name}`),
+      ),
+    },
     stack: {
       // original flags
       frontend: stackContext.flags.frontend,

package/templates/.claude/agents/bug-debugger.md

@@ -50,7 +50,7 @@ Systematic debugging — understand before fixing.
 
 ```
 STATUS: DONE | BLOCKED | PARTIAL
-EXECUTOR_TOOL: [claude-code | kilo-code | codex | other]
+EXECUTOR_TOOL: [claude-code | codex | omp | other]
 EXECUTOR_MODEL: [exact model name you are running as. "unknown" if you cannot tell.]
 EXECUTOR_SUBAGENT: [subagent name within your host, if any, else "-"]
 SUMMARY: [1-2 sentences — root cause and fix]

package/templates/.claude/agents/feature-implementer.md

@@ -72,9 +72,9 @@ and even then, report it, don't ask about it.
 
 ```
 STATUS: DONE | BLOCKED | PARTIAL
-EXECUTOR_TOOL: [claude-code | kilo-code | codex | other]
+EXECUTOR_TOOL: [claude-code | codex | omp | other]
 EXECUTOR_MODEL: [exact model name you are running as — e.g. unic-code, claude-sonnet-4-5, gpt-5-mini. If you truly cannot tell, write "unknown" — reviewer treats unknown as suspicious and asks the human to confirm.]
-EXECUTOR_SUBAGENT: [name of the subagent you are, if your host has multiple — e.g. "Kilo:code", "Claude:feature-implementer". Otherwise "-".]
+EXECUTOR_SUBAGENT: [name of the subagent you are, if your host has multiple — e.g. "Claude:feature-implementer", "omp:task". Otherwise "-".]
 SUMMARY: [1-2 sentences of what was implemented]
 TEST_PLAN_FOLLOWED: [task §4 / inline / N/A — reason]
 FILES_CHANGED:

package/templates/.claude/commands/ukit/handoff-create.md

@@ -1,7 +1,7 @@
 # /ukit:handoff-create — Phase 1 + 2: Plan
 
 **Role: PLANNER**
-**Tool: any** (Claude Code / Codex / omp / Kilo — your choice)
+**Tool: any** (Claude Code / Codex / omp — your choice)
 **Model split:**
 - Read/understand → lite model (haiku · unic-lite · cheapest available)
 - Write plan + tasks → strong model (Opus · unic-smart · strongest available)

package/templates/.claude/commands/ukit/handoff-fullstack.md

@@ -1,7 +1,7 @@
 # /ukit:handoff-fullstack — Full Pipeline: Plan → Implement → Review
 
 **Role: ORCHESTRATOR**
-**Tool: any** (Claude Code / Codex / omp / Kilo — your choice)
+**Tool: any** (Claude Code / Codex / omp — your choice)
 
 ## Model Split
 

package/templates/.claude/commands/ukit/handoff-implement.md

@@ -1,7 +1,7 @@
 # /ukit:handoff-implement — Phase 3: Execute
 
 **Role: EXECUTOR (orchestrated)**
-**Tool: any** (Claude Code / Codex / omp / Kilo — your choice)
+**Tool: any** (Claude Code / Codex / omp — your choice)
 **Model: code model** (Sonnet · unic-code · cheap-smart)
 
 > **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@smol` / `@default` / `@slow`.

package/templates/.claude/commands/ukit/handoff-review.md

@@ -1,7 +1,7 @@
 # /ukit:handoff-review — Phase 4: Review
 
 **Role: REVIEWER**
-**Tool: any** (Claude Code / Codex / omp / Kilo — your choice)
+**Tool: any** (Claude Code / Codex / omp — your choice)
 **Model: strong model, MUST differ from executor** (Opus · unic-smart · strongest available)
 
 > **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@smol` / `@default` / `@slow`.

package/templates/.claude/hooks/auto-prune-bash.sh

@@ -11,6 +11,25 @@ if [ ! -f "$SETTINGS_LOCAL" ] || [ ! -f "$USAGE_FILE" ]; then
   exit 0
 fi
 
+# O1 (TASK-009): armed AFTER the missing-state short-circuit above, so the
+# nothing-to-prune path stays as free as it is today and only real work is measured.
+# This hook stages no stdin (SPEC §14), so it owns its own EXIT trap: the trap
+# returns the status it captured and the always-exit-0 posture is unchanged.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
+if [ "${UKIT_TEL_ARMED:-}" = "1" ]; then
+  ukit_hook_telemetry_arm
+  __ukit_tel_finish() {
+    local __ukit_tel_rc=$?
+    if [ "${UKIT_TEL_ARMED:-}" = "1" ] && command -v ukit_hook_telemetry_finish >/dev/null 2>&1; then
+      UKIT_TEL_RC="$__ukit_tel_rc" UKIT_TEL_EVENT="SessionStart" ukit_hook_telemetry_finish
+    fi
+    return "$__ukit_tel_rc"
+  }
+  trap __ukit_tel_finish EXIT
+fi
+
 NOW_UTC=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
 node -e '

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

@@ -238,7 +238,10 @@ async function readRunCursor() {
     if (synced.reset || synced.probed) {
       // Persist a clean probe too: hook processes are ephemeral, so otherwise every
       // mutation would reopen and parse the same 4MB transcript tail.
-      state = await mod.writeCompactPressureState(projectRoot, synced.state, sessionConfig);
+      // TASK-004: withFileLock is fail-closed — a contended pressure lock skips the
+      // write and resolves undefined (journaled). Keep the synced in-memory state;
+      // the gate still decides on correct data, the persist just lands next run.
+      state = (await mod.writeCompactPressureState(projectRoot, synced.state, sessionConfig)) ?? synced.state;
     }
   } catch {
     state = await mod.buildCompactPressureState(rawState, sessionConfig);

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

@@ -187,16 +187,24 @@ if (toolName === 'Write' || toolName === 'Edit') {
   const newVisible = stripHtmlComments(newContent);
   const currentVisible = stripHtmlComments(currentContent);
 
+  // A documented, human-approved override closes the tier contract for this
+  // cycle — e.g. a gateway with no smart-tier model where the human approved
+  // planning on the available tier. Same semantics as the push-time check.
+  const planHasHumanOverride = (text) =>
+    /## Model-Tier Guard Override/.test(text) && /OVERRIDE_APPROVED_BY:\s*human/i.test(text);
+
   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.');
-    }
-    if (tierOf(plannerModel) === 'vision') {
-      block(`PLANNER_MODEL "${plannerModel}" ${VISION_LANE_MESSAGE}`);
-    }
-    if (tierOf(plannerModel) !== 'smart') {
-      block(`PLANNER_MODEL "${plannerModel}" is not strong/opus tier. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart).`);
+    if (!planHasHumanOverride(newVisible)) {
+      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.');
+      }
+      if (tierOf(plannerModel) === 'vision') {
+        block(`PLANNER_MODEL "${plannerModel}" ${VISION_LANE_MESSAGE}`);
+      }
+      if (tierOf(plannerModel) !== 'smart') {
+        block(`PLANNER_MODEL "${plannerModel}" is not strong/opus tier. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart).`);
+      }
     }
   }
 
@@ -209,8 +217,9 @@ if (toolName === 'Write' || toolName === 'Edit') {
     const isFreshTaskFile = !fileExists;
     if (isFreshTaskFile) {
       const planContent = (await pathExists(planPath)) ? await readTextSafe(planPath) : '';
-      const plannerModel = extractField(stripHtmlComments(planContent), 'PLANNER_MODEL');
-      if (!plannerModel || tierOf(plannerModel) !== 'smart') {
+      const planVisible = stripHtmlComments(planContent);
+      const plannerModel = extractField(planVisible, 'PLANNER_MODEL');
+      if (!planHasHumanOverride(planVisible) && (!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.`);
       }
 
@@ -285,13 +294,15 @@ if (toolName === 'Write' || toolName === 'Edit') {
     if (hasReviewerVerdict && !currentReviewerReal) {
       const executorModel = extractField(currentVisible, 'EXECUTOR_MODEL') || extractField(newVisible, 'EXECUTOR_MODEL');
       const reviewerModel = extractField(newVisible, 'REVIEWER_MODEL');
+      const planContentForReview = (await pathExists(planPath)) ? await readTextSafe(planPath) : '';
+      const reviewOverride = planHasHumanOverride(stripHtmlComments(planContentForReview));
       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 {
+      } else if (!reviewOverride) {
         if (tierOf(reviewerModel) === 'vision') {
           block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" ${VISION_LANE_MESSAGE}`);
         }

package/templates/.claude/hooks/reinject-context.sh

@@ -9,6 +9,28 @@ fi
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 SCRIPT_PATH="$HOOK_DIR/../ukit/runtime/reinject-context.mjs"
 
+# O1 (TASK-009): this hook stages no stdin (SPEC §14), so the shared cleanup path in
+# hook-input.sh never runs for it and nothing here would ever be measured. Arm the
+# no-staging start marker and finish it from this hook's own EXIT trap: arming costs
+# one mktemp and reads no clock, and the single bounded `--finish` child is the
+# telemetry process rather than a hook work step. A missing runtime (pre-install
+# tree) leaves the flag unset — exactly as unmeasured as today — and the trap returns
+# the status it captured, so the `exit $?` below still reaches the host unchanged.
+# shellcheck source=/dev/null
+source "$HOOK_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
+if [ "${UKIT_TEL_ARMED:-}" = "1" ]; then
+  ukit_hook_telemetry_arm
+  __ukit_tel_finish() {
+    local __ukit_tel_rc=$?
+    if [ "${UKIT_TEL_ARMED:-}" = "1" ] && command -v ukit_hook_telemetry_finish >/dev/null 2>&1; then
+      # The event travels per call — no staged envelope exists to carry it.
+      UKIT_TEL_RC="$__ukit_tel_rc" UKIT_TEL_EVENT="PreCompact" ukit_hook_telemetry_finish
+    fi
+    return "$__ukit_tel_rc"
+  }
+  trap __ukit_tel_finish EXIT
+fi
+
 if [ -f "$SCRIPT_PATH" ]; then
   UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT_PATH"
   exit $?

package/templates/.claude/hooks/reset-compact-pressure.sh

@@ -24,6 +24,25 @@ if [ ! -f "$PRESSURE_FILE" ]; then
   exit 0
 fi
 
+# O1 (TASK-009): armed AFTER the no-pressure-file short-circuit above, so the common
+# "nothing to reset" start stays unmeasured while real resets get timed. This hook
+# stages no stdin (SPEC §14), so it owns its EXIT trap; the trap restores the captured
+# status and the always-exit-0 posture below is unchanged.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
+if [ "${UKIT_TEL_ARMED:-}" = "1" ]; then
+  ukit_hook_telemetry_arm
+  __ukit_tel_finish() {
+    local __ukit_tel_rc=$?
+    if [ "${UKIT_TEL_ARMED:-}" = "1" ] && command -v ukit_hook_telemetry_finish >/dev/null 2>&1; then
+      UKIT_TEL_RC="$__ukit_tel_rc" UKIT_TEL_EVENT="SessionStart" ukit_hook_telemetry_finish
+    fi
+    return "$__ukit_tel_rc"
+  }
+  trap __ukit_tel_finish EXIT
+fi
+
 # The lock directory lives beside the state file; its parent exists because the file does.
 node -e '
 // Deadline must exceed the bounded lock wait in this block (maxWaitMs = 5000) so the
@@ -132,6 +151,13 @@ process.stdin.on("end", () => {
     }
   })();
   const sessionId = typeof payload.session_id === "string" ? payload.session_id.trim() : "";
+  // TASK-008 fix round: the pressure writer keys records by payload.session_id,
+  // and hosts that omit session_id on prompt/tool events (omp) now send the
+  // transcript path as the session key. When session_start DOES carry a real id
+  // but the writers did not, the record lives under the transcript key — delete
+  // both so the targeted reset cannot silently miss. Transcript paths are
+  // unique per session, so this can never touch a sibling record.
+  const transcriptKey = typeof payload.transcript_path === "string" ? payload.transcript_path.trim() : "";
   const pressurePath = process.argv[1];
 
   withLock(`${pressurePath}.lock`, async () => {
@@ -160,6 +186,9 @@ process.stdin.on("end", () => {
 
     const sessions = { ...raw.sessions };
     delete sessions[sessionId];
+    if (transcriptKey && transcriptKey !== sessionId) {
+      delete sessions[transcriptKey];
+    }
     const newest = Object.entries(sessions)
       .sort(([, a], [, b]) => (b?.updatedAt ?? 0) - (a?.updatedAt ?? 0))[0]?.[1] ?? null;
     const tempPath = `${pressurePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;

package/templates/.claude/hooks/session-episode.sh

@@ -37,6 +37,26 @@ if [ "$__ukit_ep_gate" != "1" ]; then
 fi
 unset __ukit_ep_gate
 
+# O1 (TASK-009): armed only past the gate above, so a gate-off SessionEnd stays a pure
+# fast exit. This hook stages no stdin (SPEC §14) and owns its EXIT trap; the trap
+# returns the captured status, so the always-exit-0 contract is unchanged. The row is
+# not session-attributed: the staged payload is reaped below before this trap runs, and
+# re-deriving the id in shell would mean another spawn on the teardown path.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
+if [ "${UKIT_TEL_ARMED:-}" = "1" ]; then
+  ukit_hook_telemetry_arm
+  __ukit_tel_finish() {
+    local __ukit_tel_rc=$?
+    if [ "${UKIT_TEL_ARMED:-}" = "1" ] && command -v ukit_hook_telemetry_finish >/dev/null 2>&1; then
+      UKIT_TEL_RC="$__ukit_tel_rc" UKIT_TEL_EVENT="SessionEnd" ukit_hook_telemetry_finish
+    fi
+    return "$__ukit_tel_rc"
+  }
+  trap __ukit_tel_finish EXIT
+fi
+
 # Bounded stdin read (existing hook style): cap +1 byte in background so a
 # producer that never closes the pipe cannot park the session teardown.
 UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-episode-in.XXXXXX")" || exit 0

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

@@ -2523,6 +2523,10 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     if (!entry || typeof entry !== 'object') {
       return;
     }
+    // The sandbox starts without .ukit/storage/cache. Create it before the
+    // sidecar append and lock acquisition; otherwise both operations fail with
+    // ENOENT and withStateLock falls through to an unlocked read-modify-write.
+    await ensureDir(filePath);
 
     // BUG-C23-15: the entry is STAGED to an append-only sidecar before the lock is
     // attempted (small appendFile is atomic — no read-modify-write, so no lost
@@ -2605,14 +2609,17 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
           if (!error || error.code !== 'EEXIST') return;
           try {
             const stat = fsSync.statSync(lockPath);
-            if (Date.now() - stat.mtimeMs > 10000) {
-              try {
-                const owner = JSON.parse(fsSync.readFileSync(path.join(lockPath, 'owner'), 'utf8'));
-                if (!owner || !Number.isInteger(owner.pid) || !isPidAlive(owner.pid)) {
-                  fsSync.rmSync(lockPath, { recursive: true, force: true });
-                  continue;
-                }
-              } catch {
+            let owner = null;
+            try {
+              owner = JSON.parse(fsSync.readFileSync(path.join(lockPath, 'owner'), 'utf8'));
+            } catch {}
+            // The watchdog may call process.exit while this process is in the
+            // async merge. Its finally block cannot run after that synchronous
+            // exit, so the exit fold must reclaim its own abandoned lock before
+            // folding the staged sidecar. A live foreign owner remains protected.
+            const ownInterruptedLock = owner?.pid === process.pid;
+            if (ownInterruptedLock || Date.now() - stat.mtimeMs > 10000) {
+              if (ownInterruptedLock || !owner || !isPidAlive(owner.pid)) {
                 fsSync.rmSync(lockPath, { recursive: true, force: true });
                 continue;
               }

package/templates/.claude/hooks/verification-guard.sh

@@ -215,6 +215,9 @@ function isVerificationCommand(command) {
   ].some((pattern) => pattern.test(command));
 }
 
+// F-15: execution-ledger.mjs mirrors this list in its own
+// isExplicitBroadVerificationRequest — the completion gate honors the same
+// explicit-broad signal when classifying a scope='broad' receipt. Keep both in sync.
 function isExplicitBroadVerificationRequest(promptText) {
   const text = String(promptText || '').toLowerCase();
   return [