@ngockhoale/ukit 2.3.15 → 2.3.19

package/templates/.claude/ukit/index/task-budget-validator.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+// task-budget-validator.mjs — TASK-014 / Cycle C12 (shipped CLI twin)
+//
+// Self-contained twin of src/core/taskBudgetValidator.js for user installs (no `src/`).
+// The logic below is a literal port — keep the two files behavior-identical when editing.
+//
+// Usage:
+//   node .claude/ukit/index/task-budget-validator.mjs <path-to-TASK-xxx.md> [criteria JSON]
+//
+// Output:
+//   First stdout line: `VERDICT: ok` or `VERDICT: needs_breakdown`
+//   Then one `REASON: <criterion>: <detail>` line per reason.
+//   ALWAYS exits 0 — advisory gate, must never break a pipeline.
+
+import fs from 'node:fs';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+const DEFAULT_CRITERIA = Object.freeze({
+  maxTargetFiles: 3,
+  maxTestCases: 8,
+  maxVerificationMinutes: 10,
+});
+
+const VERIFICATION_MINUTE_TABLE = Object.freeze({
+  'yarn test:release-core': 3,
+  'node scripts/release/verify-release.mjs': 2,
+});
+
+function estimateVerificationMinutes(commands) {
+  if (!Array.isArray(commands)) return 0;
+  let total = 0;
+  for (const raw of commands) {
+    const cmd = String(raw || '').trim();
+    if (!cmd) continue;
+    if (Object.prototype.hasOwnProperty.call(VERIFICATION_MINUTE_TABLE, cmd)) {
+      total += VERIFICATION_MINUTE_TABLE[cmd];
+      continue;
+    }
+    if (/^yarn\s+vitest(\s+run)?\b/.test(cmd)) {
+      const tokens = cmd.split(/\s+/);
+      const runIdx = tokens.indexOf('run');
+      const tail = runIdx >= 0 ? tokens.slice(runIdx + 1) : tokens.slice(2);
+      const fileArgs = tail.filter((t) => !t.startsWith('-') && t.length > 0);
+      total += fileArgs.length * 0.5;
+      continue;
+    }
+    total += 1;
+  }
+  return Math.round(total * 10) / 10;
+}
+
+function splitSections(markdown) {
+  const lines = String(markdown || '').split('\n');
+  const sections = new Map();
+  let currentHeading = null;
+  let buffer = [];
+  for (const line of lines) {
+    const m = /^##\s+(.+?)\s*$/.exec(line);
+    if (m) {
+      if (currentHeading !== null) sections.set(currentHeading, buffer);
+      currentHeading = m[1].trim();
+      buffer = [];
+    } else if (currentHeading !== null) {
+      buffer.push(line);
+    }
+  }
+  if (currentHeading !== null) sections.set(currentHeading, buffer);
+  return sections;
+}
+
+function getSectionBody(sections, name) {
+  if (sections.has(name)) return sections.get(name).join('\n');
+  const normalizedName = name.replace(/\s*\([^)]*\)\s*$/, '');
+  for (const [heading, body] of sections) {
+    if (heading.replace(/\s*\([^)]*\)\s*$/, '') === normalizedName) {
+      return body.join('\n');
+    }
+  }
+  return null;
+}
+
+function countTargetFiles(body) {
+  if (body == null) return 0;
+  let count = 0;
+  for (const line of body.split('\n')) {
+    if (/^-\s+\S/.test(line)) count += 1;
+  }
+  return count;
+}
+
+function countTestCases(body) {
+  if (body == null) return 0;
+  let count = 0;
+  let sawHeader = false;
+  let sawSeparator = false;
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (!sawHeader) {
+      sawHeader = true;
+      continue;
+    }
+    if (!sawSeparator && /^\|[-\s|]+\|\s*$/.test(trimmed)) {
+      sawSeparator = true;
+      continue;
+    }
+    count += 1;
+  }
+  return count;
+}
+
+function extractVerificationCommands(body) {
+  if (body == null) return [];
+  const lines = body.split('\n');
+  const fenceStart = /^```\s*bash\s*$/;
+  const fenceEnd = /^```\s*$/;
+  let inFence = false;
+  const out = [];
+  for (const line of lines) {
+    if (!inFence) {
+      if (fenceStart.test(line.trim())) inFence = true;
+      continue;
+    }
+    if (fenceEnd.test(line.trim())) break;
+    out.push(line);
+  }
+  return out.map((l) => l.trim()).filter(Boolean);
+}
+
+function goalText(body) {
+  if (body == null) return '';
+  return body
+    .split('\n')
+    .map((l) => l.replace(/^#+\s*/, '').trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+export function validateTaskFile(markdown, criteria = DEFAULT_CRITERIA) {
+  const reasons = [];
+  const text = typeof markdown === 'string' ? markdown : '';
+  const sections = splitSections(text);
+
+  const goalBody = getSectionBody(sections, 'Goal');
+  const targetBody = getSectionBody(sections, 'Target Files');
+  const testBody = getSectionBody(sections, 'Test Cases');
+  const verifyBody = getSectionBody(sections, 'Verification Commands');
+
+  const requiredSections = [
+    ['Goal', goalBody],
+    ['Test Cases', testBody],
+    ['Verification Commands', verifyBody],
+  ];
+  for (const [name, body] of requiredSections) {
+    if (body == null || body.trim() === '') {
+      reasons.push({
+        criterion: 'missing-field',
+        detail: `required section \`## ${name}\` is missing or empty`,
+      });
+    }
+  }
+
+  if (targetBody != null) {
+    const n = countTargetFiles(targetBody);
+    if (n > criteria.maxTargetFiles) {
+      reasons.push({
+        criterion: 'target-file-count',
+        detail: `${n} target files exceeds maxTargetFiles=${criteria.maxTargetFiles}`,
+      });
+    }
+  }
+
+  if (testBody != null) {
+    const n = countTestCases(testBody);
+    if (n > criteria.maxTestCases) {
+      reasons.push({
+        criterion: 'test-case-count',
+        detail: `${n} test cases exceeds maxTestCases=${criteria.maxTestCases}`,
+      });
+    }
+  }
+
+  if (verifyBody != null) {
+    const commands = extractVerificationCommands(verifyBody);
+    if (commands.length > 0) {
+      const minutes = estimateVerificationMinutes(commands);
+      if (minutes > criteria.maxVerificationMinutes) {
+        reasons.push({
+          criterion: 'verification-minutes',
+          detail: `estimated ${minutes} verification minutes exceeds maxVerificationMinutes=${criteria.maxVerificationMinutes}`,
+        });
+      }
+    }
+  }
+
+  if (goalBody != null) {
+    const prose = goalText(goalBody);
+    if (/\binvestigate\b/i.test(prose) && /\bfirst\b/i.test(prose)) {
+      reasons.push({
+        criterion: 'investigate-first',
+        detail: 'Goal contains both "investigate" and "first" — split the task into a spike + a build step',
+      });
+    }
+  }
+
+  return {
+    verdict: reasons.length === 0 ? 'ok' : 'needs_breakdown',
+    reasons,
+  };
+}
+
+function main() {
+  const [, , targetPath, criteriaArg] = process.argv;
+  let criteria = DEFAULT_CRITERIA;
+  if (criteriaArg) {
+    try {
+      const overrides = JSON.parse(criteriaArg);
+      criteria = { ...DEFAULT_CRITERIA, ...overrides };
+    } catch {
+      // malformed override — fall back to defaults (advisory, never fail)
+    }
+  }
+  let markdown = '';
+  try {
+    markdown = fs.readFileSync(targetPath, 'utf8');
+  } catch (err) {
+    console.log('VERDICT: needs_breakdown');
+    console.log(`REASON: missing-field: cannot read ${targetPath} (${err && err.code ? err.code : 'error'})`);
+    process.exit(0);
+  }
+  const { verdict, reasons } = validateTaskFile(markdown, criteria);
+  console.log(`VERDICT: ${verdict}`);
+  for (const r of reasons) {
+    console.log(`REASON: ${r.criterion}: ${r.detail}`);
+  }
+  process.exit(0);
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main();
+}

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -938,23 +938,12 @@ async function main() {
       return;
     }
 
-    // Claude Code invokes Stop again after a Stop hook blocks the first stop. Re-blocking
-    // that recovery turn creates a self-sustaining loop, so let it end normally instead.
-    // If work still lacks evidence, surface the recovery reason to the user rather than
-    // silently ending after the automatic continuation.
-    // Vibecode autonomy keeps pushing through the reentrant Stop as well: the recovery turn
-    // after a block is another chance to finish the work, not a release valve. Block again
-    // with the reason; the loop still ends the moment evidence lands or a blocker appears.
-    if (payload.stop_hook_active === true && state?.routeSummary?.autonomyLevel !== 'vibecode') {
-      if (result.continue || result.capped || result.notify) {
-        const recoveryReason = result.reason
-          || 'UKit completion gate reached its continuation limit; unfinished work was not retried again.';
-        process.stdout.write(`${JSON.stringify({
-          systemMessage: `UKit stopped automatic recovery after one continuation: ${recoveryReason}`,
-        })}\n`);
-      }
-      return;
-    }
+    // A reentrant Stop (Claude Code re-fires Stop after this hook already blocked once) is
+    // gated exactly like any other Stop: while evidence is still missing it blocks again
+    // with the actionable reason instead of silently releasing the recovery turn. Loop
+    // termination is guaranteed elsewhere — non-vibecode routes end at the continuation cap
+    // (final-notice block -> capped visible release), and vibecode ends on the visible
+    // verification-loop blocker.
 
     if (result.continue) {
       if (result.finalNotice) await markNotified(projectRoot, payload, ledger);

package/templates/.claude/ukit/runtime/task-watchdog.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * task-watchdog.mjs — wall-clock watchdog runtime for handoff tasks.
+ *
+ * Self-contained runtime module. No imports from `src/`, no sibling imports
+ * beyond `node:` builtins (the `token-utils` file lock is intentionally NOT
+ * used — file-locking watchdog state under a Stop hook with a 4s budget is a
+ * recipe for getting killed mid-write by its own chain).
+ *
+ * Exports:
+ *   DEFAULT_CONFIG                — fail-open defaults; identical to the
+ *                                   `handoff.taskBudgets` / `handoff.milestoneIntervalMin`
+ *                                   keys seeded into templates/ukit/storage/config.json.
+ *   parseTaskFile(markdown)       — minimal twin of src/core/taskProgressGuard's
+ *                                   parser; reads id, status, size, lastProgressIso.
+ *   evaluateBudgets(...)          — per in_progress task returns
+ *                                   { id, phase: 'ok'|'soft'|'hard', elapsedMin, lastGreenMin }.
+ *                                   elapsed = now - state[id].firstSeen; Progress
+ *                                   appends do NOT reset the clock.
+ *   loadConfig(configPath)        — deep-merges .ukit/storage/config.json's
+ *                                   `handoff` key over DEFAULT_CONFIG; any read/parse
+ *                                   error → DEFAULT_CONFIG (fail-open).
+ *   readState(statePath) / writeState(statePath, value) —
+ *                                   `.ukit/storage/cache/task-watchdog/state.json`,
+ *                                   shape { firstSeen, hardBlocks }; any I/O error
+ *                                   → treat as empty, never throw.
+ *
+ * The hard clock does not reset on Progress appends on purpose: trickling entries
+ * every 4 minutes must not buy an unlimited task. The newest Progress timestamp is
+ * used only to name the last-green milestone in user-facing messages.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// ─── Defaults ─────────────────────────────────────────────────────────────
+export const DEFAULT_CONFIG = Object.freeze({
+  taskBudgets: {
+    S: { softMin: 8, hardMin: 15 },
+    M: { softMin: 15, hardMin: 30 },
+    L: { softMin: 25, hardMin: 45 },
+    hardPolicy: 'split',
+  },
+  milestoneIntervalMin: 5,
+});
+
+// Cap on consecutive hard-trip emissions before degrading to advisory —
+// after the third evaluation the hook stops blocking and the run is allowed
+// to end so the orchestrator can hand back to the user. An honest failure of
+// enforcement is better than a wedged pipeline.
+export const HARD_BLOCK_CAP = 2;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function deepFreeze(value) {
+  if (!isPlainObject(value)) return value;
+  for (const key of Object.keys(value)) deepFreeze(value[key]);
+  return Object.freeze(value);
+}
+
+function mergeBudgets(into, from) {
+  if (!isPlainObject(from)) return into;
+  for (const [size, bucket] of Object.entries(from)) {
+    if (!isPlainObject(bucket)) continue;
+    const prev = isPlainObject(into[size]) ? into[size] : {};
+    into[size] = { ...prev, ...bucket };
+  }
+  return into;
+}
+
+// ─── Config ───────────────────────────────────────────────────────────────
+export async function loadConfig(configPath) {
+  const fallback = deepFreeze(JSON.parse(JSON.stringify(DEFAULT_CONFIG)));
+  if (!configPath) return fallback;
+  let raw;
+  try {
+    raw = await fs.readFile(configPath, 'utf8');
+  } catch {
+    return fallback;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+  const handoff = parsed?.handoff;
+  if (!isPlainObject(handoff)) return fallback;
+
+  const merged = {
+    taskBudgets: {},
+    hardPolicy: typeof handoff.taskBudgets?.hardPolicy === 'string'
+      ? handoff.taskBudgets.hardPolicy
+      : DEFAULT_CONFIG.taskBudgets.hardPolicy,
+    milestoneIntervalMin: Number.isFinite(handoff.milestoneIntervalMin)
+      ? handoff.milestoneIntervalMin
+      : DEFAULT_CONFIG.milestoneIntervalMin,
+  };
+  mergeBudgets(merged.taskBudgets, DEFAULT_CONFIG.taskBudgets);
+  mergeBudgets(merged.taskBudgets, handoff.taskBudgets);
+
+  // Keep the legacy key visible (matches the seeded config.json shape).
+  merged.taskBudgets.hardPolicy = merged.hardPolicy;
+  return deepFreeze(merged);
+}
+
+// ─── State ────────────────────────────────────────────────────────────────
+const EMPTY_STATE = Object.freeze({ firstSeen: Object.freeze({}), hardBlocks: Object.freeze({}) });
+
+export async function readState(statePath) {
+  if (!statePath) return { firstSeen: {}, hardBlocks: {} };
+  try {
+    const raw = await fs.readFile(statePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      firstSeen: isPlainObject(parsed?.firstSeen) ? { ...parsed.firstSeen } : {},
+      hardBlocks: isPlainObject(parsed?.hardBlocks) ? { ...parsed.hardBlocks } : {},
+    };
+  } catch {
+    return { firstSeen: {}, hardBlocks: {} };
+  }
+}
+
+export async function writeState(statePath, value) {
+  if (!statePath) return;
+  try {
+    await fs.mkdir(path.dirname(statePath), { recursive: true });
+    // temp + rename to avoid leaving a half-written state file if the hook is killed.
+    const tempPath = `${statePath}.${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`;
+    await fs.writeFile(tempPath, `${JSON.stringify(value, null, 1)}\n`, 'utf8');
+    await fs.rename(tempPath, statePath);
+  } catch {
+    // Fail-open: never throw from state writes.
+  }
+}
+
+// ─── Task parser ──────────────────────────────────────────────────────────
+const TASK_ID_REGEX = /^#\s+TASK-([0-9]+[A-Za-z0-9._-]*)\b/m;
+const STATUS_REGEX = /^-\s*Status:\s*`?([a-z_]+)`?/m;
+const SIZE_REGEX = /^-\s*Size:\s*`?([SML])`?/m;
+
+// Progress entries follow the format fixed by src/core/taskProgressGuard.js:
+//   - <ISO-8601> · milestone: <name> · ...
+const PROGRESS_ENTRY_REGEX = /^-\s+(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?(?:[+-]\d{2}:?\d{2}|Z)?)\s+·/gm;
+
+export function parseTaskFile(markdown) {
+  if (typeof markdown !== 'string') {
+    return { id: null, status: null, size: null, lastProgressIso: null };
+  }
+  const idMatch = markdown.match(TASK_ID_REGEX);
+  const statusMatch = markdown.match(STATUS_REGEX);
+  const sizeMatch = markdown.match(SIZE_REGEX);
+  let lastProgressIso = null;
+  PROGRESS_ENTRY_REGEX.lastIndex = 0;
+  for (const m of markdown.matchAll(PROGRESS_ENTRY_REGEX)) {
+    const candidate = m[1];
+    if (!lastProgressIso || candidate > lastProgressIso) lastProgressIso = candidate;
+  }
+  return {
+    id: idMatch ? `TASK-${idMatch[1]}` : null,
+    status: statusMatch ? statusMatch[1] : null,
+    size: sizeMatch ? sizeMatch[1] : null,
+    lastProgressIso,
+  };
+}
+
+function parseIsoToMs(iso) {
+  if (typeof iso !== 'string') return NaN;
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? ms : NaN;
+}
+
+// ─── Discovery ────────────────────────────────────────────────────────────
+export async function listInProgressTasks(projectRoot) {
+  const tasksDir = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'tasks');
+  let entries;
+  try {
+    entries = await fs.readdir(tasksDir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (!/^TASK-.*\.md$/i.test(entry)) continue;
+    let text;
+    try {
+      text = await fs.readFile(path.join(tasksDir, entry), 'utf8');
+    } catch {
+      continue;
+    }
+    const parsed = parseTaskFile(text);
+    if (!parsed.id) continue;
+    if (parsed.status !== 'in_progress') continue;
+    if (!['S', 'M', 'L'].includes(parsed.size)) parsed.size = 'M';
+    out.push(parsed);
+  }
+  return out;
+}
+
+// ─── Budget evaluation ────────────────────────────────────────────────────
+function bucketFor(size, config) {
+  const key = ['S', 'M', 'L'].includes(size) ? size : 'M';
+  const budgets = config?.taskBudgets || DEFAULT_CONFIG.taskBudgets;
+  return budgets[key] || DEFAULT_CONFIG.taskBudgets[key];
+}
+
+/**
+ * Evaluate every in_progress task against its wall-clock budget.
+ *
+ * `state` carries `firstSeen[id]` (epochMs) and `hardBlocks[id]` (count).
+ * The hard clock does NOT reset on Progress appends — that would let a task
+ * trickle entries every 4 minutes and never trip. Progress is used only to
+ * name the last-green milestone in user-facing messages.
+ */
+export function evaluateBudgets({ tasks = [], state = {}, now, config = DEFAULT_CONFIG } = {}) {
+  const out = [];
+  for (const task of tasks) {
+    const id = task.id;
+    const bucket = bucketFor(task.size, config);
+    const softMin = Number(bucket?.softMin) || 0;
+    const hardMin = Number(bucket?.hardMin) || 0;
+    const firstSeen = Number(state?.firstSeen?.[id]) || now;
+    const elapsedMs = Math.max(0, now - firstSeen);
+    const elapsedMin = elapsedMs / 60_000;
+    let phase = 'ok';
+    if (elapsedMin > hardMin) phase = 'hard';
+    else if (elapsedMin >= softMin) phase = 'soft';
+    let lastGreenMin = null;
+    if (task.lastProgressIso) {
+      const ms = parseIsoToMs(task.lastProgressIso);
+      if (Number.isFinite(ms)) lastGreenMin = Math.max(0, (now - ms) / 60_000);
+    }
+    out.push({ id, phase, elapsedMin, lastGreenMin, size: task.size, softMin, hardMin });
+  }
+  return out;
+}
+
+// ─── Hook-driver helpers ──────────────────────────────────────────────────
+export function describeSoft(result, id) {
+  return [
+    `[ukit-watchdog] ${id} is in its soft overrun window (elapsed ${result.elapsedMin.toFixed(1)}min; budget ${result.softMin}/${result.hardMin}min).`,
+    `Checkpoint a milestone now via \`## Progress\` and split the remaining Acceptance Criteria into ${id}-b before crossing hardMin.`,
+  ].join(' ');
+}
+
+// Hard-phase advisory for advisory-only contexts (PostToolUse, degraded paths):
+// same split instruction as the split-policy Stop block, but never a decision.
+export function describeHardAdvisory(result, id) {
+  return [
+    `[ukit-watchdog] ${id} has crossed its hard budget (elapsed ${result.elapsedMin.toFixed(1)}min > hardMin ${result.hardMin}min).`,
+    `Checkpoint a milestone via \`## Progress\` and split the remaining Acceptance Criteria into ${id}-b now.`,
+  ].join(' ');
+}
+
+export function describeSplitReason({ id, result, hardBlocks, lastGreen }) {
+  const lastGreenLine = lastGreen?.iso
+    ? `last-green: ${lastGreen.iso} (${lastGreen.label || 'milestone'})`
+    : `last-green: none recorded`;
+  return [
+    `UKit watchdog: ${id} crossed its hard budget (elapsed ${result.elapsedMin.toFixed(1)}min > hardMin ${result.hardMin}min).`,
+    `Hard-trip count for this task: ${hardBlocks}/${HARD_BLOCK_CAP}.`,
+    `Action: split the remaining Acceptance Criteria into ${id}-b right now and continue from ${lastGreenLine}.`,
+    `Do not extend or skip — create ${id}-b carrying the unresolved Acceptance Criteria, run TDD there, and report status when both halves are green.`,
+  ].join(' ');
+}
+
+export function describePause({ id, result }) {
+  return [
+    `[ukit-watchdog] ${id} crossed its hard budget (elapsed ${result.elapsedMin.toFixed(1)}min > hardMin ${result.hardMin}min) but hardPolicy="pause".`,
+    `STOP and hand back to the user — do not auto-split.`,
+  ].join(' ');
+}
+
+export function describeDegraded({ id, hardBlocks }) {
+  return [
+    `[ukit-watchdog] ${id} has tripped its hard budget ${hardBlocks} times already; degrading to advisory so the orchestrator is not wedged.`,
+    `Hand back to the user now with the running progress, last green, and a concrete blocker.`,
+  ].join(' ');
+}
+
+// ─── State bookkeeping ────────────────────────────────────────────────────
+export async function ensureFirstSeen(state, id, now) {
+  if (!state.firstSeen[id]) state.firstSeen[id] = now;
+  return state.firstSeen[id];
+}
+
+export async function bumpHardBlocks(state, id) {
+  const next = Number(state.hardBlocks[id] || 0) + 1;
+  state.hardBlocks[id] = next;
+  return next;
+}
+
+export function pickLastGreen(task) {
+  if (!task?.lastProgressIso) return null;
+  return { iso: task.lastProgressIso, label: 'milestone' };
+}

package/templates/.gitignore

@@ -48,10 +48,11 @@ Thumbs.db
 .cache/
 # legacy: Antigravity adapter removed in v2.2.0; leftovers must stay ignored
 .antigravity/
-.claude/
-.codex/
-.omp/
-.ukit/
+# NOTE (C12): runtime dirs (.claude/ .codex/ .omp/ .ukit/) are deliberately NOT
+# ignored here. This file is a per-directory .gitignore for templates/, so an
+# unanchored `.claude/` silently hid NEW template files (it swallowed
+# templates/.claude/ukit/index/task-budget-validator.mjs). The root .gitignore
+# already carries the anchored /.claude/ /.codex/ /.omp/ /.ukit/ exclusions.
 opencode.json
 AGENTS.md
 CLAUDE.md

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

@@ -116,6 +116,36 @@ what lets the cycle reach the end.
   - The next AI session (any tool, model from `handoff.reviewer.model`, MUST differ from executor) will pick `pending_review` task and run review.
   - Do NOT dispatch reviewer in-process unless your host explicitly supports it AND can guarantee a different model — file-based handoff is the default.
 
+## Milestone landing (mandatory — Handoff mode)
+
+Long runs must land work to disk continuously, so a killed turn loses at most one milestone
+and a respawn picks up exactly where the previous executor stopped. This applies in Handoff
+mode only; daily flow does not get a Progress section.
+
+- **Cadence.** Every `handoff.milestoneIntervalMin` (default 5) wall-clock minutes OR at
+  every RED → GREEN → verify milestone (whichever comes first), append a Progress entry to
+  the task file and make a milestone commit on YOUR worktree branch.
+- **Entry format (fixed — `src/core/taskProgressGuard.js` parses it).**
+
+  `- <ISO-8601 local timestamp> · milestone: <name> · last-green: <what passed> · files: <comma-separated paths> · drift: none|<one line why>`
+
+  Re-state every file changed since the previous entry. If a file is not under
+  `## Target Files`, the `drift:` field MUST carry a one-line reason; otherwise the guard
+  reports `undeclared-drift`.
+- **Milestone commit.** The commit lives on your worktree branch only (e.g.
+  `handoff/task-xxx`). Use a `-m "milestone: <name>"` message. Never commit outside your
+  worktree, never push. The orchestrator's copy-back step (`git diff --name-only` against
+  base) diffs the working tree, so intermediate commits on the worktree branch are free —
+  **copy-back is unaffected** by milestone commits.
+- **Resume.** When a previous run aborted, you will be respawned. Read `## Progress`,
+  jump straight to the last entry whose `last-green:` is not `none`, and continue from
+  there. Do NOT re-plan, do NOT restart from RED, do NOT re-write tests that already
+  passed. The progress section is the resume contract.
+- **Staleness.** If your newest entry is older than `2 × handoff.milestoneIntervalMin`,
+  the guard reports `stale-milestone`; the boundary is inclusive at exactly `2 ×` and
+  exclusive one minute beyond. Keep entries fresh — the cadence rule above is what
+  guarantees that.
+
 ## Rules
 
 - **Iron law (Handoff mode):** no `DONE` without fresh PASS output in the current turn.

package/templates/.omp/agents/handoff-planner.md

@@ -115,6 +115,18 @@ Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
 - Chain: A → B → C runs as 3 sequential waves (1 task each, no parallelism)
 - Independent: A, B, C (all `none`) runs as 1 wave, all parallel
 
+### Task-budget validator — gate before any task becomes `ready`
+
+Before marking a task `ready`, run the task-budget validator on the file you just wrote:
+
+```
+node .claude/ukit/index/task-budget-validator.mjs docs/AI_HANDOFF/tasks/TASK-xxx.md
+```
+
+The validator's first stdout line is `VERDICT: ok` or `VERDICT: needs_breakdown`, followed by `REASON:` lines. It always exits 0 (advisory). When the verdict is `needs_breakdown`, either split the task into smaller TASK files until each one passes, or record a one-line dismissal in that task's `## Discussion` thread explaining why the violation is acceptable. A `ready` task whose validator verdict is `needs_breakdown` is not actually ready — Phase 3 (state file write) must follow a `VERDICT: ok` (or a documented dismissal).
+
+Numeric thresholds and the minute table live in `src/core/taskBudgetValidator.js` and the shipped CLI twin. Do not restate them here — `tests/consistency/configDocsSync.test.js` greps this file for stale numbers and will fail if a threshold is hard-coded. Reference the validator / PLAN §3 instead.
+
 ### Maximize wave width — dependencies are expensive
 
 Wave width is the single biggest lever on how long a cycle takes: a wave of 6 finishes in

package/templates/.omp/hooks/pre/ukit-bridge.js

@@ -41,7 +41,7 @@ export const HOOK_EVENT_MAP = {
   },
   tool_result: {
     'Read|Grep|Glob': ['record-execution.sh'],
-    'Edit|Write': ['post-edit-verify.sh', 'record-execution.sh'],
+    'Edit|Write': ['post-edit-verify.sh', 'record-execution.sh', 'task-watchdog.sh'],
     Bash: ['compress-output.sh', 'record-execution.sh'],
   },
   before_agent_start: ['sensitive-data-guard.sh', 'skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
@@ -98,6 +98,7 @@ export const ADVISORY_SCRIPTS = new Set([
   'vision-router.sh',
   'context-window-guard.sh',
   'post-edit-verify.sh',
+  'task-watchdog.sh',
   'compress-output.sh',
   'reinject-context.sh',
   'auto-prune-bash.sh',