@ngockhoale/ukit 2.3.15 → 2.3.17

package/src/core/taskProgressGuard.js

@@ -0,0 +1,157 @@
+// Pure checker for the executor milestone protocol.
+//
+// A TASK-xxx.md that carries an `## Executor Report` must also carry a `## Progress` section.
+// Each `## Progress` entry uses a fixed format:
+//
+//   - <ISO-8601 timestamp> · milestone: <name> · last-green: <what passed> · files: <paths> · drift: none|<reason>
+//
+// Rules implemented here (canonical wording for the planner/executor contract):
+//
+//   1. A task carrying an Executor Report must have ≥1 `## Progress` entry.
+//      Violation type: 'no-progress'.
+//
+//   2. The newest entry (max parsed timestamp, not last line) must be within
+//      `2 × milestoneIntervalMin` of `now`. The boundary is INCLUSIVE at exactly
+//      `2 × milestoneIntervalMin` old (still OK) and EXCLUSIVE one minute past
+//      (stale). "Strictly beyond" the boundary is stale.
+//      Violation type: 'stale-milestone'.
+//
+//   3. Every `files:` path in an entry must appear under `## Target Files`
+//      unless that entry's `drift:` field carries a non-`none` reason.
+//      Violation type: 'undeclared-drift'.
+//
+//   4. Entries with unparseable timestamps are reported as 'malformed-entry'
+//      and never throw.
+//
+// The module is intentionally tiny and pure: no fs, no Date.now() side effects.
+// `now` defaults to Date.now() so call sites that want determinism (tests,
+// future watchdog integration) can inject a fixed timestamp.
+
+const PROGRESS_HEADING = /^##\s+Progress\s*$/m;
+const REPORT_HEADING = /^##\s+Executor Report\s*$/m;
+const TARGET_HEADING = /^##\s+Target Files\s*$/m;
+const ENTRY_RE = /^-\s+(\S+)\s+·\s+milestone:\s*([^·]*)·\s+last-green:\s*([^·]*)·\s+files:\s*([^·]*)·\s+drift:\s*(.*)$/;
+
+function parseEntry(line) {
+  const m = ENTRY_RE.exec(line);
+  if (!m) return null;
+  const [, ts, milestone, lastGreen, filesField, drift] = m;
+  const files = filesField
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const tsNum = Date.parse(ts);
+  if (Number.isNaN(tsNum)) {
+    return { ok: false, raw: line };
+  }
+  return {
+    ok: true,
+    timestamp: tsNum,
+    milestone: milestone.trim(),
+    lastGreen: lastGreen.trim(),
+    files,
+    drift: drift.trim(),
+  };
+}
+
+function sliceSection(markdown, headingRe) {
+  const match = headingRe.exec(markdown);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  const rest = markdown.slice(start);
+  // Section ends at the next `## ` heading or EOF.
+  const nextHeading = /\n##\s+/.exec(rest);
+  const end = nextHeading ? start + nextHeading.index : markdown.length;
+  return markdown.slice(start, end);
+}
+
+function collectTargetFiles(markdown) {
+  const section = sliceSection(markdown, TARGET_HEADING);
+  if (!section) return new Set();
+  const files = new Set();
+  for (const line of section.split('\n')) {
+    // Lines look like "- `path/to/file.js` — what changes"
+    const m = /^\s*-\s+`?([^`\s]+(?:\.[^`\s]+)?)`?/.exec(line);
+    if (m) files.add(m[1]);
+  }
+  return files;
+}
+
+function collectProgressEntries(progressSection) {
+  const entries = [];
+  for (const line of progressSection.split('\n')) {
+    if (!line.trim().startsWith('- ')) continue;
+    const parsed = parseEntry(line.trim());
+    if (parsed) entries.push(parsed);
+  }
+  return entries;
+}
+
+export function checkMilestoneProgress({
+  markdown,
+  now = Date.now(),
+  milestoneIntervalMin = 5,
+} = {}) {
+  const violations = [];
+
+  if (typeof markdown !== 'string' || markdown.length === 0) {
+    return { ok: false, violations: [{ type: 'no-progress', detail: 'markdown is empty' }] };
+  }
+
+  if (!REPORT_HEADING.test(markdown)) {
+    // No Executor Report — nothing to check.
+    return { ok: true, violations: [] };
+  }
+
+  if (!PROGRESS_HEADING.test(markdown)) {
+    return {
+      ok: false,
+      violations: [{ type: 'no-progress', detail: '## Progress section missing' }],
+    };
+  }
+
+  const progressSection = sliceSection(markdown, PROGRESS_HEADING);
+  const entries = collectProgressEntries(progressSection || '');
+
+  if (entries.length === 0) {
+    violations.push({ type: 'no-progress', detail: '## Progress section has no entries' });
+    return { ok: false, violations };
+  }
+
+  let newestTs = -Infinity;
+  for (const entry of entries) {
+    if (!entry.ok) {
+      violations.push({ type: 'malformed-entry', detail: `unparseable timestamp: ${entry.raw}` });
+      continue;
+    }
+    if (entry.timestamp > newestTs) newestTs = entry.timestamp;
+  }
+
+  if (Number.isFinite(newestTs)) {
+    const limitMs = 2 * milestoneIntervalMin * 60 * 1000;
+    const ageMs = now - newestTs;
+    // Boundary: ageMs === limitMs is still OK; ageMs > limitMs is stale.
+    if (ageMs > limitMs) {
+      violations.push({
+        type: 'stale-milestone',
+        detail: `newest entry is ${Math.round(ageMs / 60000)} min old; threshold is ${2 * milestoneIntervalMin} min`,
+      });
+    }
+  }
+
+  const targetFiles = collectTargetFiles(markdown);
+  for (const entry of entries) {
+    if (!entry.ok) continue;
+    const driftReason = entry.drift && entry.drift !== 'none' ? entry.drift : null;
+    for (const file of entry.files) {
+      if (!targetFiles.has(file) && !driftReason) {
+        violations.push({
+          type: 'undeclared-drift',
+          detail: `file '${file}' not in ## Target Files and entry has no drift reason`,
+        });
+      }
+    }
+  }
+
+  return { ok: violations.length === 0, violations };
+}

package/src/manifest/validateManifest.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 
 const VALID_ITEM_TYPES = new Set(['command', 'skill', 'agent', 'hook', 'config', 'link']);
-const VALID_MERGE_STRATEGIES = new Set(['overwrite_with_backup', 'skip', 'append', 'prepend']);
+const VALID_MERGE_STRATEGIES = new Set(['overwrite_with_backup', 'skip', 'append', 'prepend', 'merge_env_overwrite_with_backup']);
 
 function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);

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

@@ -117,6 +117,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/.claude/agents/handoff-planner.md

@@ -116,6 +116,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/.claude/commands/ukit/handoff-fullstack.md

@@ -262,7 +262,10 @@ TDD — mandatory:
      cd .worktrees/task-xxx && <each verification command>
      Paste full output.
 
-DO NOT run: git add, git commit, git push — leave files as-is in worktree.
+Milestone commits INSIDE your own worktree (e.g. `handoff/task-xxx`) are REQUIRED by the
+milestone protocol — see `## Milestone landing (mandatory)` in the feature-implementer
+contract. Never commit outside your worktree, never push. Use `-m "milestone: <name>"`.
+Copy-back diffs the working tree against base, so milestone commits do not affect it.
 
 Executor Report (append to task file — do NOT touch INDEX.md):
   ## Executor Report

package/templates/.claude/hooks/task-watchdog.sh

@@ -0,0 +1,221 @@
+#!/bin/bash
+# task-watchdog.sh — wall-clock watchdog for handoff tasks.
+#
+# Why this exists:
+#   The Quality Gate lets handoff runs go on for a while, but a wedged task
+#   that never reports a blocker still burns the rest of the pipeline. This
+#   hook measures wall-clock per in_progress task against approved budgets
+#   (S 8/15, M 15/30, L 25/45 minutes by default) and either:
+#     - soft overrun: emits a VISIBLE "checkpoint milestone now + split remainder"
+#                     advisory on Stop (systemMessage), never blocks.
+#     - hard overrun (split policy, default): emits Stop decision=block with a
+#                     visible split instruction naming the follow-up
+#                     TASK-<id>-b; keeps the cycle running instead of letting
+#                     the agent stop silently mid-budget.
+#     - hard overrun (pause policy, selectable in config): emits a pause
+#                     advisory on Stop, never blocks.
+#
+#   PostToolUse NEVER emits decision — that would block the in-flight Edit.
+#   Stop is the only path that can hard-trip; PostToolUse stays advisory only.
+#
+#   Everything fails open and stays inside the 4s hook-chain budget:
+#     - HOOK_DEADLINE_MS=3000 self-kill via setTimeout(...).unref()
+#     - all I/O is async (sync reads on a stalled mount would block the timer)
+#     - process.exit(0) on every path; never throws.
+#
+# Dispatch on hook_event_name:
+#   Stop         → evaluate and may emit decision=block; never emits decision
+#                  unless the trip crosses hardMin AND hardPolicy='split'.
+#   PostToolUse  → advisory only (systemMessage); NEVER emits decision.
+#   anything else → exit 0 silently.
+
+INPUT="$(cat)"
+# Cap the payload before it reaches node's env: oversized stdin would exceed the
+# exec environment limit and node would never start. A truncated payload simply
+# fails JSON.parse inside node → {} → silent degrade exit 0 (documented posture).
+INPUT="${INPUT:0:65536}"
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
+'use strict';
+
+const fsp = require('fs/promises');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+// Wall-clock watchdog. Anything that stalls here must end in clean exit 0 —
+// a stuck hook is indistinguishable from a wedged pipeline to the orchestrator.
+// Every read below is async on purpose: a sync read on a stalled mount would
+// block the loop and the timer below would never fire.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+
+(async () => {
+  const payload = (() => {
+    try {
+      const parsed = JSON.parse(process.env.INPUT || '');
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  })();
+
+  const hookEvent = typeof payload.hook_event_name === 'string' ? payload.hook_event_name : '';
+  const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
+  const projectRoot = process.env.PROJECT_ROOT || process.cwd();
+
+  // Silent degrade for non-relevant events — same posture as every other
+  // UKit advisory hook: only do work when the event type is ours.
+  if (hookEvent !== 'Stop' && hookEvent !== 'PostToolUse') {
+    process.exit(0);
+  }
+
+  const runtimePath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'task-watchdog.mjs');
+  // Async existence check — sync fs here would violate the all-async invariant
+  // (a stalled mount would block the loop and the 3s self-kill could not fire).
+  try {
+    await fsp.access(runtimePath);
+  } catch {
+    process.exit(0);
+  }
+
+  let runtime;
+  try {
+    runtime = await import(pathToFileURL(runtimePath).href);
+  } catch {
+    process.exit(0);
+  }
+
+  const configPath = path.join(projectRoot, '.ukit', 'storage', 'config.json');
+  const config = await runtime.loadConfig(configPath);
+
+  const stateDir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'task-watchdog');
+  const statePath = path.join(stateDir, 'state.json');
+  const state = await runtime.readState(statePath);
+
+  let tasks = [];
+  try {
+    tasks = await runtime.listInProgressTasks(projectRoot);
+  } catch {
+    process.exit(0);
+  }
+
+  // PostToolUse: advisory only. NEVER emit decision — that would block the
+  // in-flight Edit and stall the run. We still re-evaluate so the runtime
+  // state stays warm and the next Stop sees an up-to-date view.
+  if (hookEvent === 'PostToolUse') {
+    const now = Date.now();
+    const evals = runtime.evaluateBudgets({ tasks, state, now, config });
+    const advisories = evals
+      .filter((r) => r.phase !== 'ok')
+      .map((r) => {
+        const task = tasks.find((t) => t.id === r.id);
+        if (!task) return null;
+        if (r.phase === 'hard') {
+          const blocks = Number(state.hardBlocks[r.id] || 0);
+          if (blocks >= (runtime.HARD_BLOCK_CAP || 2)) {
+            return runtime.describeDegraded({ id: r.id, hardBlocks: blocks });
+          }
+          return runtime.describeHardAdvisory(r, r.id);
+        }
+        return runtime.describeSoft(r, r.id);
+      })
+      .filter(Boolean);
+
+    if (advisories.length > 0) {
+      const message = advisories.join('\n');
+      try {
+        process.stdout.write(`${JSON.stringify({ systemMessage: message })}\n`);
+      } catch {}
+    }
+    process.exit(0);
+  }
+
+  // Stop: full evaluation, may emit decision=block under split policy.
+  const now = Date.now();
+  for (const task of tasks) {
+    try {
+      await runtime.ensureFirstSeen(state, task.id, now);
+    } catch {}
+  }
+
+  const evals = runtime.evaluateBudgets({ tasks, state, now, config });
+
+  // First save firstSeen updates so the next Stop sees the same anchored clock.
+  await runtime.writeState(statePath, state);
+
+  const hardResults = evals.filter((r) => r.phase === 'hard');
+  const softResults = evals.filter((r) => r.phase === 'soft');
+
+  if (hardResults.length === 0) {
+    // No hard trips. Emit a soft advisory if anything is in the soft zone,
+    // then exit 0 cleanly. We deliberately do not emit decision here — the
+    // completion gate owns Stop's continuation logic and we never want to
+    // double-block for the same reason.
+    if (softResults.length > 0) {
+      const advisory = softResults
+        .map((r) => runtime.describeSoft(r, r.id))
+        .join('\n');
+      try {
+        process.stdout.write(`${JSON.stringify({ systemMessage: advisory })}\n`);
+      } catch {}
+    }
+    process.exit(0);
+  }
+
+  // At least one hard-trip. Apply policy.
+  const hardPolicy = String(config.taskBudgets?.hardPolicy || 'split');
+  const firstHard = hardResults[0];
+  const blocks = Number(state.hardBlocks[firstHard.id] || 0);
+
+  if (hardPolicy !== 'split') {
+    // pause (or anything non-split) → advisory only, never block.
+    const advisory = hardResults
+      .map((r) => runtime.describePause({ id: r.id, result: r }))
+      .join('\n');
+    try {
+      process.stdout.write(`${JSON.stringify({ systemMessage: advisory })}\n`);
+    } catch {}
+    process.exit(0);
+  }
+
+  // split policy + hard-trip — but the per-task block cap has already been
+  // hit. Degrade to advisory so the orchestrator can hand back to the user.
+  if (blocks >= (runtime.HARD_BLOCK_CAP || 2)) {
+    await runtime.bumpHardBlocks(state, firstHard.id);
+    await runtime.writeState(statePath, state);
+    const advisory = runtime.describeDegraded({ id: firstHard.id, hardBlocks: blocks + 1 });
+    try {
+      process.stdout.write(`${JSON.stringify({ systemMessage: advisory })}\n`);
+    } catch {}
+    process.exit(0);
+  }
+
+  // Hard trip + split policy + under the cap → emit Stop decision=block
+  // with the visible split instruction. This is the "auto-split and continue"
+  // path: blocking the stop IS the continue mechanism — the executor / orchestrator
+  // performs the actual TASK-<id>-b cut on the next turn following the reason.
+  const newBlocks = await runtime.bumpHardBlocks(state, firstHard.id);
+  await runtime.writeState(statePath, state);
+
+  const task = tasks.find((t) => t.id === firstHard.id) || { id: firstHard.id };
+  const lastGreen = runtime.pickLastGreen(task);
+  const reason = runtime.describeSplitReason({
+    id: firstHard.id,
+    result: firstHard,
+    hardBlocks: newBlocks,
+    lastGreen,
+  });
+  try {
+    process.stdout.write(`${JSON.stringify({ decision: 'block', reason })}\n`);
+  } catch {}
+  process.exit(0);
+})().catch(() => {
+  // Fail-open: never let an exception kill the hook.
+  try {
+    process.exit(0);
+  } catch {}
+});
+NODE
+
+exit 0

package/templates/.claude/settings.json

@@ -151,6 +151,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
             "timeout": 4
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\"",
+            "timeout": 4
           }
         ]
       },
@@ -203,6 +208,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\"",
             "timeout": 4
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\"",
+            "timeout": 4
           }
         ]
       }