@ngockhoale/ukit 3.4.47 → 3.4.48

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

@@ -2,6 +2,7 @@
 name: bug-debugger
 description: "Debugging specialist for reproducible errors, failing tests, and unexpected behavior. Use proactively when investigation will involve noisy logs, stack traces, or a self-contained reproduce-trace-fix-verify loop. Do not use for trivial obvious fixes or broad architecture ideation."
 model: sonnet  # unic-code
+effort: medium
 color: red
 tools: ["Read", "Grep", "Glob", "Bash", "Edit", "TodoWrite"]
 ---

package/template_project/.claude/agents/code-reviewer.md

@@ -2,6 +2,7 @@
 name: code-reviewer
 description: "Independent reviewer for handoff Phase 3 and for spec/plan documents. For code (default): use after executor reports STATUS: DONE on a handoff task, MUST run with a model different from the executor (configured in .ukit/storage/config.json → handoff.reviewer.model, default unic-smart), produces a verdict: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL. For spec/plan documents (set REVIEW_TARGET_TYPE=spec or plan): reviews a docs/plans/*.md file for completeness/consistency/clarity/scope/YAGNI, produces Status: Approved | Issues Found."
 model: opus  # unic-smart
+effort: medium
 color: yellow
 tools: ["Read", "Grep", "Glob", "Bash"]
 ---

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

@@ -2,6 +2,7 @@
 name: feature-implementer
 description: "Implementation specialist for clear, self-contained coding tasks. Use proactively when the approach is clear and the work can be completed in a bounded pass with a concise summary. Do not use for trivial one-file tweaks or tightly coupled exploratory work."
 model: sonnet  # unic-code
+effort: medium
 color: green
 tools: ["Read", "Edit", "Write", "Grep", "Glob", "Bash", "TodoWrite"]
 ---

package/template_project/.claude/agents/handoff-planner.md

@@ -2,6 +2,7 @@
 name: handoff-planner
 description: "Handoff planning specialist for Phase 1+2. Use when creating a new handoff cycle: writes PLAN.md with full test plan, splits into TASK-xxx.md files with TDD-embedded test cases, and updates INDEX.md. Always use the strongest available model (Opus/unic-smart)."
 model: opus  # unic-smart
+effort: medium
 color: purple
 tools: ["Read", "Edit", "Write", "Glob", "Bash", "TodoWrite"]
 ---

package/template_project/.claude/agents/ukit-small-task-maintainer.md

@@ -2,6 +2,7 @@
 name: ukit-small-task-maintainer
 description: "Internal UKit maintenance subagent for low-risk, reversible UKit decisions. Use proactively when UKit needs to decide or perform safe cleanup such as pruning docs/TASKS.md, classifying queued work, choosing whether compact/summarization is appropriate, summarizing local docs/status, or maintaining small UKit runtime queues. Do not use for product implementation, security, release/publish, data-loss, architecture, or risky/shared code changes."
 model: haiku  # unic-lite
+effort: low
 color: cyan
 tools: ["Read", "Grep", "Glob", "Edit", "Write"]
 ---

package/template_project/.claude/hooks/completion-gate.sh

@@ -85,7 +85,7 @@ fi
 # (coordinator deadline + margin); a forced kill lands on the existing crash-streak
 # path (non-zero STATUS) so the outcome is announced, never silently released.
 __ukit_coord_out="$(mktemp "${TMPDIR:-/tmp}/ukit-coord-out.XXXXXX")"
-printf '%s' "$INPUT" | UKIT_HARNESS=claude-code UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" --evaluate-stop > "$__ukit_coord_out" 2>/dev/null &
+printf '%s' "$INPUT" | UKIT_HARNESS="${UKIT_HARNESS:-claude-code}" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" --evaluate-stop > "$__ukit_coord_out" 2>/dev/null &
 __ukit_coord_pid=$!
 __ukit_coord_ms="${UKIT_HOOK_DEADLINE_MS:-3000}"
 case "$__ukit_coord_ms" in ''|*[!0-9]*) __ukit_coord_ms=3000 ;; esac

package/template_project/.claude/hooks/delegation-gate.mjs

@@ -0,0 +1,343 @@
+// delegation-gate.mjs — PreToolUse chain step (in-proc `runHook(ctx)`, Claude Code).
+//
+// Turns the feature-implementation Playbook's "delegate the coding to Tier 2" requirement from
+// advice into a host-native refusal. It fires ONLY when ALL of these hold:
+//   * the host is Claude Code (UKIT_HARNESS unset/'claude-code') — omp/codex worker identity is
+//     UNVERIFIED, so nothing is enforced there (the acceptance verdict stays UNVERIFIED);
+//   * the live route state is this task's `feature-implementation` run with
+//     `tierLane.delegationRequired === true` (Tier 3 main, Tier 2 executor);
+//   * the call is a source/test mutation (Edit/Write/MultiEdit/NotebookEdit, or a Bash command
+//     whose file write is reliably identifiable) from the MAIN thread — the host stamps
+//     `agent_id` on every subagent tool payload, so main vs worker is read from the host, never
+//     from model text.
+// A main-thread mutation is refused until this task's ledger holds an evidenced native worker
+// handback (the "valid delegation path"). Reads, test runs, docs/bookkeeping writes and every
+// unrelated operation pass untouched.
+//
+// Bounded, never a bypass: each refused attempt is a task-owned `delegation-violation` receipt;
+// the DELEGATION_VIOLATION_LIMIT-th one mints a visible sticky `delegation-required` blocker, so
+// the Stop gate ends the run as BLOCKED. Further attempts stay refused. There is no
+// "second attempt succeeds" path.
+//
+// Worker side: a worker's Bash heredoc/redirect/tee/sed -i/script write has no trustworthy file
+// attribution (the ledger would only see an anonymous workspace delta), so it is refused with a
+// pointer to the supported Edit/Write path.
+//
+// Boundary (documented, not hidden): Bash mutations are detected by a quote-aware scan of the
+// command text. Writes made by a script FILE (`node build.js`), by variables/command
+// substitution, or after a `cd` inside the command are not identifiable here. The Stop-time
+// acceptance backstop still counts any anonymous workspace delta as an inline write
+// (`delegation-required-not-performed`), so such work is never reported as PASS.
+//
+// Fail-open on any internal error (a broken advisory gate must not wedge the session). User
+// overrides: `UKIT_DELEGATION_GATE=off` or `.ukit/storage/config.json` orchestration.delegationGate=false.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const hookFailClosed = false;
+
+const FEATURE_PLAYBOOK_ID = 'feature-implementation';
+const MUTATING_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+const PASS = { code: 0, stdout: '', stderr: '' };
+
+// First path segment under which a write is never "source/test" (tooling, build output, docs, scratch).
+const EXEMPT_ROOTS = new Set([
+  '.git', '.claude', '.ukit', '.omp', '.codex', '.cache', 'node_modules', 'dist', 'build', 'coverage',
+  '.next', '.nuxt', '.turbo', 'tmp', 'docs',
+]);
+const EXEMPT_EXT = /\.(md|mdx|txt|log|tmp|lock)$/i;
+
+const INTERPRETERS = /^(node|nodejs|deno|bun|python|python2|python3|ruby|perl|php)$/;
+const WRAPPERS = new Set(['sudo', 'env', 'command', 'time', 'nice', 'nohup', 'exec', 'builtin']);
+const SHELLS = new Set(['bash', 'sh', 'zsh', 'dash']);
+// File-writing APIs of the interpreters above. `process.stdout.write` / `sys.stdout.write` are not file writes.
+const WRITE_API = /\b(writeFile(?:Sync)?|appendFile(?:Sync)?|createWriteStream|copyFile(?:Sync)?|rename(?:Sync)?|writeFileSync|write_text|write_bytes|File\.write|file_put_contents)\b|\bopen\s*\([^)]*,\s*['"][wax][+b]*['"]/;
+
+// ─── Path classification ────────────────────────────────────────────────────
+
+/** True when `raw` names a project source/test file (i.e. a path this gate protects). */
+export function isSourceTarget(raw, { projectRoot, cwd } = {}) {
+  let text = String(raw ?? '').trim();
+  if (!text) return false;
+  if (/[$`]/.test(text) || text.startsWith('~')) return false; // not statically resolvable
+  if (text.startsWith('/dev/')) return false;
+  const root = path.resolve(projectRoot || '.');
+  const abs = path.isAbsolute(text) ? path.resolve(text) : path.resolve(cwd || root, text);
+  const rel = path.relative(root, abs);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false; // outside the project
+  const parts = rel.split(path.sep);
+  if (EXEMPT_ROOTS.has(parts[0])) return false;
+  if (EXEMPT_EXT.test(parts[parts.length - 1])) return false;
+  return true;
+}
+
+// ─── Bash scan ──────────────────────────────────────────────────────────────
+
+// Splits `command` into heredoc-free text plus the heredoc bodies (bodies may contain `>` etc.).
+function extractHeredocs(command) {
+  const lines = String(command).split('\n');
+  const kept = [];
+  const bodies = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    kept.push(line);
+    const re = /<<(-?)\s*(['"]?)([A-Za-z_][\w-]*)\2/g;
+    const delimiters = [];
+    for (let m = re.exec(line); m; m = re.exec(line)) {
+      if (line[m.index - 1] === '<') continue; // here-string `<<<`
+      delimiters.push({ strip: m[1] === '-', tag: m[3] });
+    }
+    for (const { strip, tag } of delimiters) {
+      const body = [];
+      let closed = false;
+      while (i + 1 < lines.length) {
+        i += 1;
+        const candidate = strip ? lines[i].replace(/^\t+/, '') : lines[i];
+        if (candidate.trim() === tag) { closed = true; break; }
+        body.push(lines[i]);
+      }
+      bodies.push(body.join('\n'));
+      if (!closed) break;
+    }
+  }
+  return { text: kept.join('\n'), bodies };
+}
+
+// Quote-aware pass: returns segments (arrays of words) and file-redirect targets.
+function tokenize(text) {
+  const segments = [[]];
+  const redirects = [];
+  let word = null;
+  const pushWord = () => { if (word !== null) { segments[segments.length - 1].push(word); word = null; } };
+  const newSegment = () => { pushWord(); if (segments[segments.length - 1].length) segments.push([]); };
+  const n = text.length;
+  let i = 0;
+  const readQuoted = (quote) => {
+    let out = '';
+    i += 1;
+    while (i < n && text[i] !== quote) {
+      if (quote === '"' && text[i] === '\\' && i + 1 < n) { out += text[i + 1]; i += 2; continue; }
+      out += text[i]; i += 1;
+    }
+    i += 1;
+    return out;
+  };
+  while (i < n) {
+    const ch = text[i];
+    if (ch === "'" || ch === '"') { word = (word ?? '') + readQuoted(ch); continue; }
+    if (ch === '\\' && i + 1 < n) { word = (word ?? '') + text[i + 1]; i += 2; continue; }
+    if (ch === '#' && word === null) { while (i < n && text[i] !== '\n') i += 1; continue; }
+    if (/\s/.test(ch)) { if (ch === '\n') newSegment(); else pushWord(); i += 1; continue; }
+    if (ch === ';' || ch === '|' || ch === '(' || ch === ')' || ch === '`') { newSegment(); i += 1; if (ch === '|' && text[i] === '|') i += 1; continue; }
+    if (ch === '&' && text[i + 1] === '&') { newSegment(); i += 2; continue; }
+    if (ch === '&' && text[i + 1] !== '>') { newSegment(); i += 1; continue; }
+    if (ch === '&' && text[i + 1] === '>') {
+      pushWord(); i += 2; if (text[i] === '>') i += 1;
+      const target = readRedirectTarget();
+      if (target !== null) redirects.push(target);
+      continue;
+    }
+    if (ch === '>' ) {
+      // `2>file` : the fd digit already landed in `word`; drop it when it is a bare fd number.
+      if (word !== null && /^\d$/.test(word)) word = null; else pushWord();
+      i += 1;
+      if (text[i] === '(') continue; // process substitution
+      if (text[i] === '&') { i += 1; while (i < n && /[\d-]/.test(text[i])) i += 1; continue; } // fd dup
+      if (text[i] === '>' || text[i] === '|') i += 1;
+      const target = readRedirectTarget();
+      if (target !== null) redirects.push(target);
+      continue;
+    }
+    word = (word ?? '') + ch; i += 1;
+  }
+  pushWord();
+  function readRedirectTarget() {
+    while (i < n && (text[i] === ' ' || text[i] === '\t')) i += 1;
+    if (i >= n) return null;
+    if (text[i] === "'" || text[i] === '"') return readQuoted(text[i]);
+    let out = '';
+    while (i < n && !/[\s;|&<>()]/.test(text[i])) { out += text[i]; i += 1; }
+    return out || null;
+  }
+  return { segments: segments.filter((s) => s.length), redirects };
+}
+
+function isFlag(word) { return /^-/.test(word); }
+
+function stripLeading(words) {
+  const out = [...words];
+  while (out.length) {
+    if (/^[A-Za-z_]\w*=/.test(out[0]) || WRAPPERS.has(out[0])) out.shift(); else break;
+  }
+  return out;
+}
+
+function scriptWrites(script, ctx) {
+  if (!WRITE_API.test(script)) return null;
+  const literals = [...script.matchAll(/['"`]([^'"`\n]{1,200})['"`]/g)].map((m) => m[1])
+    .filter((value) => /[\\/]/.test(value) || /\.[A-Za-z0-9]{1,6}$/.test(value));
+  if (literals.length === 0) return { kind: 'script-write', target: null };
+  const hit = literals.find((value) => isSourceTarget(value, ctx));
+  return hit ? { kind: 'script-write', target: hit } : null;
+}
+
+/**
+ * Returns the reliably identifiable source/test file mutations in a Bash command:
+ * [{ kind: 'redirect'|'heredoc'|'tee'|'sed-inplace'|'copy'|'patch'|'script-write', target }].
+ * Reads, test runs and writes to exempt paths yield []. Script FILES are not identifiable (see header).
+ */
+export function scanBashMutations(command, ctx = {}, depth = 0) {
+  const raw = String(command ?? '');
+  if (!raw.trim()) return [];
+  const hits = [];
+  const { text, bodies } = extractHeredocs(raw);
+  const hasHeredoc = bodies.length > 0;
+  const { segments, redirects } = tokenize(text);
+  for (const target of redirects) {
+    if (isSourceTarget(target, ctx)) hits.push({ kind: hasHeredoc ? 'heredoc' : 'redirect', target });
+  }
+  for (const rawWords of segments) {
+    const words = stripLeading(rawWords);
+    if (!words.length) continue;
+    const cmd = path.basename(words[0]);
+    const args = words.slice(1);
+    const plain = args.filter((a) => !isFlag(a));
+    if (cmd === 'tee') {
+      for (const target of plain) if (isSourceTarget(target, ctx)) hits.push({ kind: 'tee', target });
+    } else if (cmd === 'sed' || cmd === 'perl' || cmd === 'ruby') {
+      const inPlace = args.some((a) => (cmd === 'sed' ? /^-[A-Za-z]*i|^--in-place/ : /^-[A-Za-z]*i/).test(a));
+      if (inPlace) {
+        const eIndex = args.findIndex((a) => a === '-e' || a === '-f');
+        const files = args.filter((a, idx) => !isFlag(a) && !(eIndex >= 0 && idx === eIndex + 1));
+        const candidates = cmd === 'sed' && eIndex < 0 ? files.slice(1) : files;
+        for (const target of candidates) if (isSourceTarget(target, ctx)) hits.push({ kind: 'sed-inplace', target });
+      }
+    } else if (cmd === 'cp' || cmd === 'mv' || cmd === 'install') {
+      if (plain.length >= 2 && isSourceTarget(plain[plain.length - 1], ctx)) hits.push({ kind: 'copy', target: plain[plain.length - 1] });
+    } else if (cmd === 'patch' || (cmd === 'git' && /^(apply|am)$/.test(plain[0] || '') && !args.includes('--check') && !args.includes('--stat'))) {
+      hits.push({ kind: 'patch', target: null });
+    } else if (cmd === 'dd') {
+      const of = args.find((a) => a.startsWith('of='));
+      if (of && isSourceTarget(of.slice(3), ctx)) hits.push({ kind: 'copy', target: of.slice(3) });
+    } else if (INTERPRETERS.test(cmd)) {
+      const inline = [];
+      args.forEach((a, idx) => { if (/^-(e|c|p)$/.test(a) && args[idx + 1] !== undefined) inline.push(args[idx + 1]); });
+      const scripts = [...inline, ...(hasHeredoc && (plain.length === 0 || args.includes('-') || args.some((a) => /^-[A-Za-z]*$/.test(a))) ? bodies : [])];
+      for (const script of scripts) {
+        const found = scriptWrites(script, ctx);
+        if (found) hits.push(found);
+      }
+    } else if (SHELLS.has(cmd) && depth < 2) {
+      const cIndex = args.indexOf('-c');
+      if (cIndex >= 0 && args[cIndex + 1] !== undefined) hits.push(...scanBashMutations(args[cIndex + 1], ctx, depth + 1));
+    } else if (cmd === 'eval' && depth < 2) {
+      hits.push(...scanBashMutations(args.join(' '), ctx, depth + 1));
+    }
+  }
+  return hits;
+}
+
+// ─── Gate ───────────────────────────────────────────────────────────────────
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+function userDisabled(projectRoot, env) {
+  if (/^(off|0|false)$/i.test(String(env.UKIT_DELEGATION_GATE || ''))) return true;
+  const config = readJson(path.join(projectRoot, '.ukit', 'storage', 'config.json'));
+  return config?.orchestration?.delegationGate === false;
+}
+
+function deny(reason, env) {
+  const inChain = Boolean(env.UKIT_HOOK_CHAIN_RUNNER);
+  return {
+    code: inChain ? 2 : 0,
+    stdout: `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } })}\n`,
+    stderr: `BLOCKED: ${reason}\n`,
+  };
+}
+
+function describeTarget(mutation, projectRoot) {
+  if (!mutation.target) return 'a source file';
+  const text = String(mutation.target);
+  const rel = path.isAbsolute(text) && projectRoot ? path.relative(projectRoot, text) : text;
+  return `"${(rel && !rel.startsWith('..') ? rel : text).slice(0, 120)}"`;
+}
+
+function mainMessage(attempt, limit, taskId, mutation, projectRoot) {
+  if (attempt >= limit) {
+    return `UKit delegation gate — BLOCKED: this task's feature-implementation Playbook requires the coding to be delegated to the Tier 2 worker, but the orchestrator tried ${attempt} times to write ${describeTarget(mutation, projectRoot)} itself. This run is now recorded as BLOCKED (delegation-required-not-performed). Do not retry the write; report the blocker to the user.`;
+  }
+  return `UKit delegation gate (attempt ${attempt} of ${limit}): this task's feature-implementation Playbook requires Tier 2 coding delegation, and you are the Tier 3 orchestrator — writing ${describeTarget(mutation, projectRoot)} yourself is refused. Dispatch a native worker now with the Agent tool (subagent_type "feature-implementer", the Tier 2 coding model) and start its prompt with "[ukit-task ${taskId}]", naming the files and behaviour to implement; the worker must edit with Edit/Write. When it returns, verify the integrated result yourself with the bare test runner (for example \`npm test\`) — no pipe, tail, grep or compound command — so the runner's own exit status is the evidence. Repeating this write will end the run as BLOCKED.`;
+}
+
+function workerMessage(mutation, projectRoot) {
+  return `UKit delegation gate: a Bash ${mutation.kind} write to ${describeTarget(mutation, projectRoot)} has no trustworthy file attribution, so it is not accepted as worker evidence. Redo this change with the Edit or Write tool (the supported worker edit path), then run the tests with the bare runner command.`;
+}
+
+function targetsOf(toolName, input) {
+  if (toolName === 'Bash') return null;
+  const file = input.file_path ?? input.notebook_path ?? input.path;
+  return typeof file === 'string' && file ? file : null;
+}
+
+async function evaluate(ctx) {
+  const env = ctx.env || {};
+  const payload = ctx.payload || {};
+  const toolName = payload.tool_name;
+  if (toolName !== 'Bash' && !MUTATING_TOOLS.has(toolName)) return PASS;
+  if (env.UKIT_HARNESS && env.UKIT_HARNESS !== 'claude-code') return PASS;
+  const projectRoot = env.CLAUDE_PROJECT_DIR || ctx.projectRoot || process.cwd();
+  if (userDisabled(projectRoot, env)) return PASS;
+
+  const ledgerMod = await import(new URL('../ukit/runtime/execution-ledger.mjs', import.meta.url).href);
+  const playbook = await import(new URL('../ukit/runtime/playbook-execution.mjs', import.meta.url).href);
+  const state = await ledgerMod.readRouteState(projectRoot, payload);
+  const summary = state?.routeSummary;
+  if (!state?.taskInstanceId || summary?.playbookId !== FEATURE_PLAYBOOK_ID || summary.tierLane?.delegationRequired !== true) return PASS;
+
+  const input = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
+  const scanCtx = { projectRoot, cwd: payload.cwd || projectRoot };
+  let mutation = null;
+  if (toolName === 'Bash') {
+    mutation = scanBashMutations(input.command, scanCtx)[0] || null;
+  } else {
+    const file = targetsOf(toolName, input);
+    if (file && isSourceTarget(file, scanCtx)) mutation = { kind: 'edit', target: file };
+  }
+  if (!mutation) return PASS;
+
+  if (payload.agent_id) {
+    // A worker: Edit/Write is the supported path; only anonymous Bash writes are refused.
+    return toolName === 'Bash' ? deny(workerMessage(mutation, projectRoot), env) : PASS;
+  }
+
+  const ledger = await ledgerMod.readExecutionLedger(projectRoot, payload);
+  const owned = ledger && ledger.taskInstanceId === state.taskInstanceId ? ledger : null;
+  const workers = playbook.assessWorkers(owned?.playbookRun || null);
+  if (workers.workers.some((worker) => worker.state === 'evidenced')) return PASS; // valid delegation path exists
+
+  const limit = playbook.DELEGATION_VIOLATION_LIMIT;
+  const prior = Number(owned?.delegationViolations?.count) || 0;
+  const attempt = Math.min(prior + 1, limit);
+  if (prior < limit) {
+    await ledgerMod.recordLedgerEvent({
+      type: 'receipt',
+      receipt: {
+        ts: Date.now(), kind: 'delegation-violation', toolName, toolUseId: payload.tool_use_id || null,
+        success: false, mutation: mutation.kind, target: mutation.target ? String(mutation.target).slice(0, 160) : null,
+      },
+    }, { projectRoot, payload, harness: 'claude-code', routeState: state, deadlineMs: ctx.deadlineMs });
+  }
+  return deny(mainMessage(attempt, limit, state.taskInstanceId, mutation, projectRoot), env);
+}
+
+export async function runHook(ctx) {
+  try {
+    return await evaluate(ctx || {});
+  } catch {
+    return PASS; // advisory gate: an internal fault never wedges the session
+  }
+}