@ngockhoale/ukit 2.1.3 → 2.1.4

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to UKit are documented here.
 
+## 2.1.4 - 2026-08-19
+
+More room before compaction, the handoff hooks stop taxing every call they were meant to speed up, and the shipped handoff instructions stop contradicting the config they tell agents to read.
+
+### Changed
+
+- **`compact.hardCapTokens` 160,000 → 220,000 and `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` 150,000 → 180,000.** 2.1.3 fixed the deadlock but left the pair sized for a 200k window, which meant compacting far more often than necessary on a 256k model. The new pair leaves roughly 40k of working room after auto-compact fires, and the ordering invariant `autoCompactWindow < hardCapTokens` still holds — `tests/core/autoCompactWindow.test.js` fails if either number moves in isolation. **On a 200k model, lower `hardCapTokens` back to 160,000 or below**; the `_help` text in `config.json` says so, and the gate cannot protect you if the cap sits above your real context window.
+- **Config-missing fallbacks follow the default**: `compact-threshold.mjs` and `context-window-guard.sh` now fall back to `220_000` rather than `160_000`, so a corrupt or absent `config.json` behaves like a fresh install instead of silently reverting to the old cap.
+
+### Fixed
+
+- **The shipped handoff instructions no longer restate a config value that had gone stale.** Eight lines across `handoff-fullstack.md`, `handoff-implement.md`, `handoff-review.md` and `handoff-planner.md` told agents `handoff.maxParallelAgents` defaults to **10**, while `config.json` in the same release ships **12** — so an installed project got instructions that contradicted its own runtime config. Every one of those lines already said "read from `.ukit/storage/config.json`", so the restated number was redundant as well as wrong; it is now gone and the value has exactly one home. This was the second occurrence (the first was the `3 → 10` bump), and the cause both times was hand-copying a config value into prose. `tests/consistency/configDocsSync.test.js` now fails the suite if any doc restates a numeric `handoff.*` default that contradicts config, in English or Vietnamese, and if a `templates/.claude` file without `{{ }}` variables drifts from its active copy — the "keep the two mirrors identical" rule was written in two places but had never been enforced by anything except a maintainer running `diff` by hand.
+- **The worktree early-exit guard no longer costs more than it saves.** `skill-router.sh` and `stale-spec-guard.sh` skip routing for tool calls scoped to a disposable `.worktrees/task-*` tree — but the first cut spawned `node -e` on every call to decide that, measured at 53ms → 124ms per call in the main tree, where the skip never applies. A pure-bash `case "$INPUT" in *".worktrees/"*)` pre-check now gates the node spawn; it is a strict superset of what the node guard can match, so the main tree pays nothing. Both hooks still fail **open** — any parse error, missing field or node failure falls through to the normal path.
+
+### Added
+
+- **`.claude/ukit/index/provision-worktree.mjs`** — deterministic worktree provisioning for handoff waves, packaged via `manifests/platform.full.yaml`. It hides the worktree's `node_modules` symlink through the worktree's own `.git/info/exclude` (a symlink never matched `.gitignore`'s `node_modules/`, so an orchestrator `git add -A` would have committed a machine-local absolute path), and skips git-tracked files when copying `.claude/` so it cannot clobber `.claude/commands/ukit/handoff-fullstack.md`. **Shipped but not yet wired into `handoff-implement`** — the wiring is queued for a later release.
+- **Test-selection policy in `docs/AI_HANDOFF/RULES.md`** — per-task related tests are the floor, and a full suite at the wave/cycle boundary is mandatory, not optional. This is the compensating net that makes narrowed per-task scope safe; the agent definitions already cited it before it existed.
+- **`scripts/bench/parallel-agents.mjs`** — harness for measuring concurrent test-process contention at several parallelism levels, recording `slowdownFactor` / `perRunCost` / a `recommended` value plus the load averages the run happened under. It measures test-process contention, not LLM agents.
+- **`handoff.maxParallelAgents`: 10 → 12.** Chosen, not measured — the benchmark above was never run on a quiet enough machine, so this is the middle of the ~10-15 safe band the config's own `_help` has always documented. Lower it to 3-5 if your tasks produce long verification output or you see compaction firing repeatedly.
+
 ## 2.1.3 - 2026-08-16
 
 The reason auto-compact never fired in the terminal was UKit itself. This makes it fire.

package/manifests/platform.full.yaml

@@ -1238,6 +1238,19 @@ items:
     packs:
       - core
 
+  - id: ukit-index-provision-worktree-script
+    type: config
+    sourceTemplate: .claude/ukit/index/provision-worktree.mjs
+    targetPath: .claude/ukit/index/provision-worktree.mjs
+    requires:
+      - ukit-runtime-text-profile-script
+      - ukit-runtime-safe-patch-core-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-stale-spec-check-script
     type: config
     sourceTemplate: .claude/ukit/index/stale-spec-check.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/scripts/bench/parallel-agents.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * parallel-agents.mjs — TASK-004 harness.
+ *
+ * Measures the *machine-contention* component of N parallel agents by spawning N concurrent
+ * child processes (default `yarn test:release-core`) per level and recording wall-clock.
+ * This deliberately does NOT claim to benchmark LLM agent wall-clock (token counts, server
+ * load and retries make that irreproducible) — see TASK-004 planner note #1.
+ *
+ * Usage:
+ *   node scripts/bench/parallel-agents.mjs [--levels 1,3,5,10] [--cmd "<test command>"] [--out <path>]
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const SLOWDOWN_LIMIT = 2.0;
+
+function parseArgs(argv) {
+  const opts = { levels: '1,3,5,10', cmd: 'yarn test:release-core', out: '.cache/bench/parallel-agents.json' };
+  for (let i = 0; i < argv.length; i += 2) {
+    const key = argv[i];
+    const val = argv[i + 1];
+    if ((key === '--levels' || key === '--cmd' || key === '--out') && val !== undefined) {
+      opts[key.slice(2)] = val;
+    }
+  }
+  return opts;
+}
+
+function parseLevels(raw) {
+  if (!/^\d+(,\d+)*$/.test(raw.trim())) {
+    throw new Error(`unparseable --levels value: "${raw}" (expected comma-separated positive integers, e.g. 1,3,5,10)`);
+  }
+  const levels = raw.split(',').map((s) => parseInt(s, 10));
+  if (levels.some((n) => n < 1)) throw new Error(`--levels values must be >= 1, got: ${raw}`);
+  return levels;
+}
+
+function runLevel(n, cmd) {
+  return new Promise((resolve) => {
+    const t0 = Date.now();
+    let live = 0;
+    let highWater = 0;
+    let failures = 0;
+    let settled = 0;
+    const children = [];
+    for (let i = 0; i < n; i += 1) {
+      const child = spawn(cmd, { shell: true, stdio: 'ignore' });
+      live += 1;
+      highWater = Math.max(highWater, live);
+      children.push(child);
+      child.on('error', () => {
+        live -= 1;
+        settled += 1;
+        failures += 1;
+        maybeFinish();
+      });
+      child.on('exit', (code) => {
+        live -= 1;
+        settled += 1;
+        if (code !== 0) failures += 1;
+        maybeFinish();
+      });
+    }
+    function maybeFinish() {
+      if (settled === n) {
+        resolve({ n, wallClockMs: Date.now() - t0, failures, concurrencyHighWaterMark: highWater });
+      }
+    }
+  });
+}
+
+function fail(msg) {
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  let levels;
+  try {
+    levels = parseLevels(opts.levels);
+  } catch (err) {
+    fail(err.message);
+  }
+
+  const cpuCount = os.cpus().length;
+  const loadAvgStart = os.loadavg();
+  const startedAt = new Date().toISOString();
+
+  const rows = [];
+  for (const n of levels) {
+    // eslint-disable-next-line no-await-in-loop -- levels are measured sequentially on purpose
+    rows.push(await runLevel(n, opts.cmd));
+  }
+  const base = rows[0].wallClockMs;
+  for (const row of rows) {
+    row.slowdownFactor = row.wallClockMs / base;
+    row.perRunCost = row.wallClockMs / row.n;
+  }
+
+  const eligible = rows.filter((r) => r.slowdownFactor <= SLOWDOWN_LIMIT);
+  const recommended = eligible.reduce((best, r) => (r.perRunCost < best.perRunCost ? r : best), eligible[0]).n;
+
+  const loadAvgEnd = os.loadavg();
+  const finishedAt = new Date().toISOString();
+
+  const result = {
+    cpuCount,
+    levels: rows.map(({ n, wallClockMs, slowdownFactor, perRunCost, failures, concurrencyHighWaterMark }) => ({
+      n, wallClockMs, slowdownFactor, perRunCost, failures, concurrencyHighWaterMark,
+    })),
+    recommended,
+    measurementConditions: { loadAvgStart, loadAvgEnd, startedAt, finishedAt, cpuCount },
+  };
+
+  // Print the human table first so a failed --out write still shows the numbers.
+  const header = 'n'.padStart(4) + '  ' + 'wallClockMs'.padStart(12) + '  ' + 'slowdownFactor'.padStart(15) + '  ' + 'perRunCost'.padStart(11) + '  ' + 'failures'.padStart(8) + '  ' + 'concurrencyHighWaterMark'.padStart(23);
+  console.log(header);
+  for (const r of result.levels) {
+    console.log(
+      String(r.n).padStart(4)
+      + '  ' + String(r.wallClockMs).padStart(12)
+      + '  ' + r.slowdownFactor.toFixed(2).padStart(15)
+      + '  ' + r.perRunCost.toFixed(1).padStart(11)
+      + '  ' + String(r.failures).padStart(8)
+      + '  ' + String(r.concurrencyHighWaterMark).padStart(23),
+    );
+  }
+  console.log(`recommended: ${recommended} (best perRunCost with slowdownFactor <= ${SLOWDOWN_LIMIT}) on ${cpuCount} CPUs`);
+  console.log(`loadAvgStart: [${loadAvgStart.map((v) => v.toFixed(2)).join(', ')}]  loadAvgEnd: [${loadAvgEnd.map((v) => v.toFixed(2)).join(', ')}]`);
+
+  // Overwrite (never append), and never leave a partial file behind.
+  const outPath = path.resolve(opts.out);
+  try {
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    const body = JSON.stringify(result, null, 2) + '\n';
+    fs.writeFileSync(outPath, body);
+  } catch (err) {
+    fail(`cannot write --out ${outPath}: ${err.message}`);
+  }
+
+  const totalFailures = result.levels.reduce((s, r) => s + r.failures, 0);
+  if (totalFailures > 0) {
+    const perLevel = result.levels.filter((r) => r.failures > 0).map((r) => `n=${r.n}: ${r.failures}/${r.n} failed`).join('; ');
+    fail(`bench command failed: ${perLevel}`);
+  }
+}
+
+main().catch((err) => fail(err && err.message ? err.message : String(err)));

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

@@ -30,7 +30,7 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 0. **Verification package completeness** — Check whether the project has a lint or typecheck script (`package.json` scripts, or the stack's equivalent). If it does and the task's Verification Commands don't run it, that is `CHANGES-REQUESTED`: "verification commands missing lint/typecheck — re-run planner or add the command and re-verify" — do this before anything else below.
 1. **Test Plan adherence** — Were all tests in §4 actually implemented, including the ≥2 edge cases required by `handoff.plan.minTestsEdgeCase`? Check the Executor Report's `RED_OUTPUT` field: it must contain actual failing-test output (assertion failure, stack trace, non-zero exit), not a bare claim like "confirmed" or "yes". Missing or vague `RED_OUTPUT` → `CHANGES-REQUESTED`: "no evidence tests were RED before implementation — re-run TDD cycle and paste real output". Then run the tests yourself: `<task Verification Commands>`. Fresh PASS required, no trusting executor's output blindly.
 2. **Correctness** — Does the diff implement the requested behavior? Any obvious wrong assumptions, stale refs, missing cases?
-3. **Regression risk** — What existing behavior could this break? Are shared paths/tests/contracts still aligned? Run the wider test suite if shared code was touched.
+3. **Regression risk** — What existing behavior could this break? Are shared paths/tests/contracts still aligned? Run the wider suite only when the diff touched shared code; otherwise the task's own targeted commands are the gate and the wave-boundary full `yarn test` (see docs/AI_HANDOFF/RULES.md "Test selection") is the regression net.
 4. **Safety / security / data loss** — Destructive actions, auth/permission, path handling, unsafe shell/DB/file ops.
 5. **Performance / scale** — Accidental N+1, repeated I/O, large scans inside hot paths.
 6. **Maintainability** — Duplicated logic, dead branches, misleading naming, drift between docs/tests/source.

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

@@ -105,7 +105,7 @@ Use `_TEMPLATE.md` structure (from pre-read context or file).
 | Dependencies | `TASK-xxx` or `none` — wave order is inferred from this |
 | Test Cases | Type \| Test Name \| Expected — ≥1 happy + ≥2 edge cases of different kinds |
 | Test Files | Exact test file paths to create/modify |
-| Verification Commands | Runnable shell commands — MUST include the project's lint/typecheck command if one exists (see §5 rule above) |
+| Verification Commands | Runnable shell commands — MUST include the project's lint/typecheck command if one exists (see §5 rule above). Apply the "Test selection" resolution order from docs/AI_HANDOFF/RULES.md: `src/`/`scripts/` targets → the `tests` array in `.cache/index/tests-map.json`; `templates/.claude/**`/`.claude/**` targets → path convention (hooks → `tests/hooks/` + `tests/handoff/cycle*/`; manifest/settings → `tests/manifest/`; runtime `.mjs` mirrors → `tests/core/*Parity*` + `tests/index/`); if both resolve to fewer than one test file the task MUST fall back to `yarn test:release-core` — never the full suite by default, never an empty selection |
 | Acceptance Criteria | Verifiable checklist |
 
 Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
@@ -120,7 +120,7 @@ Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
 
 Wave width is the single biggest lever on how long a cycle takes: a wave of 6 finishes in
 roughly the time of its slowest task, while a chain of 6 takes six times that. Executors run
-up to `handoff.maxParallelAgents` (default 10) at once, so a plan that produces `none`
+up to `handoff.maxParallelAgents` at once, so a plan that produces `none`
 dependencies for most tasks is dramatically faster than one that produces a chain.
 
 **Write `Dependencies: none` unless B genuinely cannot be written without A's output.** A real

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

@@ -223,7 +223,7 @@ must not share a file) in case it slipped through review. Only mark a task `need
 if it is missing required fields — never merely for sharing a file.
 
 **Batch each wave — mandatory.** Read `handoff.maxParallelAgents` from
-`.ukit/storage/config.json` (default **10**). A wave with more tasks than that is split
+`.ukit/storage/config.json`. A wave with more tasks than that is split
 into consecutive batches of at most that many; finish one batch completely (including 3c
 copy-back and worktree deletion) before starting the next.
 
@@ -234,7 +234,7 @@ leaves worktrees behind. Batching only ever narrows a wave, never reorders acros
 
 ### I3 — Execute wave by wave (code model agents)
 
-**Claude Code — MANDATORY, do this before anything else in I3:** for each wave, call the Agent tool once per task **in the current batch** (in parallel, at most `handoff.maxParallelAgents` — default 10), each with `subagent_type: "feature-implementer"`. Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
+**Claude Code — MANDATORY, do this before anything else in I3:** for each wave, call the Agent tool once per task **in the current batch** (in parallel, at most `handoff.maxParallelAgents`), each with `subagent_type: "feature-implementer"`. Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
 
 For each wave:
 
@@ -398,7 +398,7 @@ If that diff is empty → implement was not completed. Do not stop: re-enter Pha
 
 ### R2 — Model isolation check (strong model, always first)
 
-**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json` (default **10**). If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (R2–R4, appended to each task file) before starting the next.
+**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (R2–R4, appended to each task file) before starting the next.
 
 **Claude Code — MANDATORY, do this before anything else in R2–R4:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"`. Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees.
 

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

@@ -94,7 +94,7 @@ when it is missing required fields — never merely for sharing a file.
 
 ### Batch each wave — mandatory
 
-Read `handoff.maxParallelAgents` from `.ukit/storage/config.json` (default **10**). A wave
+Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. A wave
 with more tasks than that is split into consecutive batches of at most that many; finish
 one batch completely (including 3c copy-back and worktree deletion) before starting the
 next.

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

@@ -50,7 +50,7 @@ If that diff is empty → handoff-implement was not completed. Report which task
 
 ## Step 2 — Review the diff
 
-**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json` (default **10**). If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (2a–2d, appended to each task file) before starting the next.
+**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (2a–2d, appended to each task file) before starting the next.
 
 **Claude Code — MANDATORY, do this before anything else:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"`. Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.
 

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

@@ -1,6 +1,7 @@
 #!/bin/bash
 # PreToolUse hook: hard-enforce an absolute context token cap (compact.hardCapTokens,
-# default 160000 — must stay below the model's real context window), separate from the
+# default 220000, sized for a 256k window — must stay below the model's real context
+# window, so lower it on a 200k model), separate from the
 # soft/hard advisory pressure phases in
 # compact-threshold.mjs (default soft=50000/hard=80000, which only print a suggestion).
 #

package/templates/.claude/hooks/context-window-guard.sh

@@ -75,7 +75,7 @@ function loadHardCap() {
     const value = JSON.parse(raw)?.compact?.hardCapTokens;
     if (Number.isFinite(value) && value > 0) return value;
   } catch { /* fall through to the default */ }
-  return 160_000;
+  return 220_000;
 }
 
 let text;

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

@@ -4,6 +4,39 @@
 
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+# Worktree early-exit: when the tool call is scoped to a disposable .worktrees/task-*
+# tree, there is nothing to route — exit before spawning the router. Reads
+# tool_input.file_path / tool_input.path / tool_input.command (never tool_input.pattern).
+# Skips only when ".worktrees/" starts a path component. Fails OPEN: any parse
+# problem, missing field, or node error falls through to the normal hook path below.
+# Pure-bash pre-check first: the node guard can only ever match when the literal
+# ".worktrees/" substring is present, so this case is a strict superset and avoids
+# paying the node spawn cost on the far more common non-worktree call.
+case "$INPUT" in
+  *".worktrees/"*)
+    if printf '%s' "$INPUT" | node -e '
+const chunks = [];
+process.stdin.on("data", (c) => chunks.push(c));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    const toolInput = (payload && typeof payload === "object" && payload.tool_input
+      && typeof payload.tool_input === "object") ? payload.tool_input : {};
+    const candidates = [toolInput.file_path, toolInput.path, toolInput.command];
+    const QMARKS = String.fromCharCode(34, 39, 96);
+    const worktreeComponent = new RegExp("(^|[\\/\\s=" + QMARKS + "])\\.worktrees/");
+    process.exit(candidates.some((v) => typeof v === "string" && worktreeComponent.test(v)) ? 0 : 1);
+  } catch {
+    process.exit(1);
+  }
+});
+' >/dev/null 2>&1; then
+      exit 0
+    fi
+    ;;
+esac
+
 STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 THRESHOLD_SCRIPT="$HOOK_DIR/../ukit/runtime/compact-threshold.mjs"

package/templates/.claude/hooks/stale-spec-guard.sh

@@ -10,4 +10,36 @@ if [ ! -f "$SCRIPT" ]; then
   exit 0
 fi
 
+# Worktree early-exit: when the tool call is scoped to a disposable .worktrees/task-*
+# tree, skip the stale-spec check entirely. Reads tool_input.file_path /
+# tool_input.path / tool_input.command (never tool_input.pattern). Skips only when
+# ".worktrees/" starts a path component. Fails OPEN: any parse problem, missing field,
+# or node error falls through to the normal check below.
+# Pure-bash pre-check first: the node guard can only ever match when the literal
+# ".worktrees/" substring is present, so this case is a strict superset and avoids
+# paying the node spawn cost on the far more common non-worktree call.
+case "$INPUT" in
+  *".worktrees/"*)
+    if printf '%s' "$INPUT" | node -e '
+const chunks = [];
+process.stdin.on("data", (c) => chunks.push(c));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    const toolInput = (payload && typeof payload === "object" && payload.tool_input
+      && typeof payload.tool_input === "object") ? payload.tool_input : {};
+    const candidates = [toolInput.file_path, toolInput.path, toolInput.command];
+    const QMARKS = String.fromCharCode(34, 39, 96);
+    const worktreeComponent = new RegExp("(^|[\\/\\s=" + QMARKS + "])\\.worktrees/");
+    process.exit(candidates.some((v) => typeof v === "string" && worktreeComponent.test(v)) ? 0 : 1);
+  } catch {
+    process.exit(1);
+  }
+});
+' >/dev/null 2>&1; then
+      exit 0
+    fi
+    ;;
+esac
+
 printf '%s' "$INPUT" | node "$SCRIPT"

package/templates/.claude/settings.json

@@ -11,7 +11,7 @@
   "defaultView": "chat",
   "autoCompactEnabled": true,
   "env": {
-    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "150000"
+    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "180000"
   },
   "permissions": {
     "defaultMode": "bypassPermissions",

package/templates/.claude/ukit/index/provision-worktree.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * provision-worktree.mjs — deterministic worktree provisioner (TASK-002).
+ *
+ * Provisions what `git worktree add` cannot bring across (all four are gitignored):
+ *   - node_modules  -> SYMLINK to the main tree (28M; avoids N concurrent installs)
+ *   - .claude/      -> REAL COPY preserving file modes (never a symlink: a worktree
+ *                      edit must not write through into the live main-tree mirror).
+ *                      Mode preservation matters: every .claude/hooks/*.sh is 755 and
+ *                      tests/handoff/cycle4/vision-gate.test.mjs asserts the exec bit.
+ *   - .ukit/storage/config.json -> copy
+ *   - .cache/index/             -> copy
+ *
+ * CLI: node .claude/ukit/index/provision-worktree.mjs <worktree-path> [--main-root <path>]
+ * exit 0 on success (including a no-op second run); non-zero + one-line stderr otherwise.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+function fail(msg) {
+  process.stderr.write(`provision-worktree: ${msg}\n`);
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+let wtPath = null;
+let mainRoot = null;
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === '--main-root') {
+    if (i + 1 >= args.length) fail('--main-root requires a value');
+    mainRoot = args[(i += 1)];
+  } else if (wtPath === null) {
+    wtPath = args[i];
+  } else {
+    fail(`unexpected argument: ${args[i]}`);
+  }
+}
+if (!wtPath) fail('usage: provision-worktree.mjs <worktree-path> [--main-root <path>]');
+wtPath = path.resolve(wtPath);
+mainRoot = path.resolve(mainRoot ?? process.cwd());
+
+// --- validate before mutating anything -------------------------------------
+
+if (!fs.existsSync(wtPath) || !fs.statSync(wtPath).isDirectory()) {
+  fail(`worktree path is not an existing directory: ${wtPath}`);
+}
+try {
+  fs.accessSync(wtPath, fs.constants.W_OK);
+} catch {
+  fail(`worktree dir is not writable: ${wtPath}`);
+}
+
+const mainModules = path.join(mainRoot, 'node_modules');
+if (!fs.existsSync(mainModules)) {
+  fail(`main tree has no node_modules at ${mainModules}; run the install in the main tree first`);
+}
+
+function readPkg(p) {
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (err) {
+    fail(`cannot parse ${p}: ${err.message}`);
+    return null; // unreachable — fail() exits the process
+  }
+}
+const mainPkg = readPkg(path.join(mainRoot, 'package.json'));
+const wtPkg = readPkg(path.join(wtPath, 'package.json'));
+if (mainPkg && wtPkg) {
+  const depsOf = (o) => JSON.stringify({ d: o.dependencies ?? {}, dd: o.devDependencies ?? {} });
+  if (depsOf(mainPkg) !== depsOf(wtPkg)) {
+    fail('package.json dependencies/devDependencies differ from the main tree; run a real install in this worktree instead of symlinking node_modules');
+  }
+}
+
+// --- helpers -----------------------------------------------------------------
+
+// The symlinked node_modules must stay invisible to `git status`/`git add -A`
+// in this worktree: .gitignore's `node_modules/` (trailing slash) matches a
+// real directory but NOT a symlink, so without this a handoff pipeline that
+// runs `git add -A` would stage a symlink whose target is an absolute,
+// machine-local path. `info/exclude` resolves to the shared git common dir
+// (verified: worktrees do not get a private copy), so this is a one-time,
+// idempotent, untracked local-metadata change — never part of any commit.
+function excludeNodeModulesFromGit(root) {
+  try {
+    const common = spawnSync('git', ['-C', root, 'rev-parse', '--git-common-dir'], { encoding: 'utf8' });
+    if (common.status !== 0) return false; // not a git repo (e.g. unit-test fixture) — best effort
+    const gitCommonDir = path.resolve(root, common.stdout.trim());
+    const excludePath = path.join(gitCommonDir, 'info', 'exclude');
+    fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+    const existing = fs.existsSync(excludePath) ? fs.readFileSync(excludePath, 'utf8') : '';
+    if (existing.split('\n').some((l) => l.trim() === 'node_modules')) return false; // already present
+    const sep = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    fs.appendFileSync(excludePath, `${sep}node_modules\n`);
+    return true;
+  } catch {
+    return false; // best effort — a missing/unwritable git dir must not fail provisioning
+  }
+}
+
+// The `.claude` copy must never clobber a git-TRACKED file (today exactly
+// `.claude/commands/ukit/handoff-fullstack.md` — owned by TASK-005). A fresh
+// worktree already has that file checked out by `git worktree add`; if the
+// gitignored dev mirror in mainRoot has locally drifted from the committed
+// copy, an unconditional recursive copy would silently overwrite the
+// worktree's tracked file with main's unreviewed local state.
+function trackedClaudeFiles(root) {
+  try {
+    const res = spawnSync('git', ['-C', root, 'ls-files', '--', '.claude'], { encoding: 'utf8' });
+    if (res.status !== 0 || !res.stdout) return new Set();
+    return new Set(res.stdout.split('\n').map((s) => s.trim()).filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
+// --- provision -------------------------------------------------------------
+
+// 1. node_modules symlink
+const wtModules = path.join(wtPath, 'node_modules');
+let modulesSt = null;
+try {
+  modulesSt = fs.lstatSync(wtModules);
+} catch {
+  /* absent */
+}
+if (modulesSt === null) {
+  try {
+    fs.symlinkSync(mainModules, wtModules, 'dir');
+  } catch (err) {
+    fail(`cannot create node_modules symlink: ${err.message}`);
+  }
+  console.log(`provisioned node_modules -> symlink ${mainModules}`);
+} else if (modulesSt.isSymbolicLink()) {
+  const target = fs.readlinkSync(wtModules);
+  if (path.resolve(wtPath, target) !== path.resolve(mainModules)) {
+    fail(`node_modules symlink already exists but points at ${target}, not ${mainModules}`);
+  }
+  console.log(`node_modules symlink already correct -> ${target}`);
+} else {
+  fail(`${wtModules} already exists and is not a symlink`);
+}
+if (excludeNodeModulesFromGit(wtPath)) {
+  console.log('node_modules excluded from git via .git/info/exclude');
+}
+
+// 2. .claude real copy, preserving modes
+const srcClaude = path.join(mainRoot, '.claude');
+const dstClaude = path.join(wtPath, '.claude');
+if (!fs.existsSync(srcClaude)) {
+  fail(`main tree has no .claude directory to copy: ${srcClaude}`);
+} else {
+  // Always (re)copy: a fresh worktree may already carry a partial, git-tracked
+  // .claude/ (e.g. commands), which must not make us skip the hooks/scripts.
+  // Never overwrite a git-tracked file under .claude/ (e.g.
+  // handoff-fullstack.md) — leave whatever `git worktree add` already
+  // checked out for it alone.
+  const trackedInClaude = trackedClaudeFiles(mainRoot);
+  fs.cpSync(srcClaude, dstClaude, {
+    recursive: true,
+    filter: (src) => {
+      const rel = path.relative(mainRoot, src).split(path.sep).join('/');
+      return !trackedInClaude.has(rel);
+    },
+  });
+  console.log(
+    `provisioned .claude -> copy of ${srcClaude}` +
+      (trackedInClaude.size > 0 ? ` (skipped ${trackedInClaude.size} git-tracked file(s))` : ''),
+  );
+}
+
+// 3. .ukit/storage/config.json
+const srcConfig = path.join(mainRoot, '.ukit', 'storage', 'config.json');
+const dstConfig = path.join(wtPath, '.ukit', 'storage', 'config.json');
+if (fs.existsSync(dstConfig)) {
+  console.log('.ukit/storage/config.json already present (skipped copy)');
+} else if (!fs.existsSync(srcConfig)) {
+  fail(`main tree has no .ukit/storage/config.json to copy: ${srcConfig}`);
+} else {
+  fs.mkdirSync(path.dirname(dstConfig), { recursive: true });
+  fs.copyFileSync(srcConfig, dstConfig);
+  console.log('provisioned .ukit/storage/config.json');
+}
+
+// 4. .cache/index
+const srcCache = path.join(mainRoot, '.cache', 'index');
+const dstCache = path.join(wtPath, '.cache', 'index');
+if (fs.existsSync(dstCache)) {
+  console.log('.cache/index already present in worktree (skipped copy)');
+} else if (!fs.existsSync(srcCache)) {
+  fail(`main tree has no .cache/index directory to copy: ${srcCache}`);
+} else {
+  fs.cpSync(srcCache, dstCache, { recursive: true });
+  console.log('provisioned .cache/index');
+}
+
+process.exit(0);

package/templates/.claude/ukit/runtime/compact-threshold.mjs

@@ -442,11 +442,13 @@ export function buildCompactThresholds(config = {}) {
   //
   // Must stay BELOW the model's real context window or the cap is unreachable: the API
   // rejects the request with "input exceeds the context window" long before an estimate
-  // climbing toward a higher number ever trips this. The previous 220_000 default sat
-  // above a 200k window, so the gate could never fire on a standard model — it was dead
-  // code in exactly the situation it existed to prevent. 160_000 leaves real headroom on
-  // a 200k window for the response plus the estimator's own undercount.
-  const hardCapTokens = Math.max(1, finiteNumber(config?.compact?.hardCapTokens, 160_000));
+  // climbing toward a higher number ever trips this. 220_000 is sized for a 256k window
+  // and leaves headroom for the response plus the estimator's own undercount. On a 200k
+  // model this default sits ABOVE the window, so the gate can never fire and is dead code
+  // in exactly the situation it exists to prevent — set compact.hardCapTokens to 160_000
+  // or lower for those. Pair it with env.CLAUDE_CODE_AUTO_COMPACT_WINDOW, which must stay
+  // strictly below this cap so the client auto-compacts before the gate blocks tools.
+  const hardCapTokens = Math.max(1, finiteNumber(config?.compact?.hardCapTokens, 220_000));
 
   return {
     softThreshold,

package/templates/docs/AI_HANDOFF/RULES.md

@@ -79,8 +79,8 @@ Next: <bước kế tiếp chính xác>
 - Subagent ghi **full log vào task file trên đĩa**, chỉ trả về orchestrator ≤10 dòng (executor) / ≤6 dòng (reviewer). Paste log ngược lại orchestrator là nguyên nhân số 1 làm run chết vì hết context.
 - Hết mỗi wave: commit, ghi cursor, **collapse** wave đó còn 1 dòng/task trong bộ nhớ làm việc, rồi chạy tiếp.
 - Yêu cầu `/compact` **chỉ** được đặt ở cuối command, giữa 2 cycle. Giữa cycle thì tuyệt đối không — state đã nằm hết ở git + `INDEX.md` + `RUN.md` nên compact ở ranh giới cycle không mất gì.
-- Vượt `compact.hardCapTokens` (mặc định 160k) mà `RUN.md` còn run dở: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit đang dở, commit, ghi cursor, push. Không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
-- Không hook nào gọi được `/compact` — đó là lệnh client-only. Nhưng từ 2.1.3, settings mặc định đặt `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 150000` < `hardCapTokens` (160k), nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor → chạy tiếp, không cần người gõ gì. Grace window ở trên chỉ còn là lưới an toàn.
+- Vượt `compact.hardCapTokens` (mặc định 220k, cỡ cho context window 256k) mà `RUN.md` còn run dở: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit đang dở, commit, ghi cursor, push. Không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
+- Không hook nào gọi được `/compact` — đó là lệnh client-only. Nhưng từ 2.1.3, settings mặc định đặt `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 180000` < `hardCapTokens` (220k), nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor → chạy tiếp, không cần người gõ gì. Grace window ở trên chỉ còn là lưới an toàn.
 - Sửa một trong hai số đó thì phải giữ `autoCompactWindow < hardCapTokens`. Đảo thứ tự là deadlock: gate chặn tool trước → transcript ngừng lớn → ngưỡng auto-compact không bao giờ tới. `tests/core/autoCompactWindow.test.js` khóa bất biến này.
 
 ### Git
@@ -132,6 +132,17 @@ pending_review ──[reviewer]──▶ approved | approved_minor ──▶ don
   - `§ Test Files`: đường dẫn cụ thể file test sẽ tạo/sửa (ví dụ `tests/auth/login.test.js`).
   - `§ Verification Commands`: lệnh executor sẽ chạy để xác nhận PASS. Nếu project có sẵn lint/typecheck script → BẮT BUỘC liệt kê ở đây, không chỉ lệnh test. Project không có thì ghi rõ N/A, không được bỏ qua im lặng.
   - `§ Acceptance Criteria`: checklist.
+
+#### Test selection (which tests the Verification Commands run)
+
+Resolution order — exactly three steps, in this order. A task's Verification Commands MUST NOT default to the full suite:
+
+1. Target File under `src/` or `scripts/` → read `.cache/index/tests-map.json` and take the `tests` array for that `sourceFile`.
+2. Target File under `templates/.claude/**` or `.claude/**` → `tests-map.json` has no coverage of these paths, so use the path convention: hooks → `tests/hooks/` + `tests/handoff/cycle*/`; manifest/settings → `tests/manifest/`; runtime `.mjs` mirrors → `tests/core/*Parity*` + `tests/index/`.
+3. **Mandatory non-empty floor** — if steps 1–2 resolve to fewer than one test file, the task MUST fall back to `yarn test:release-core`. An empty selection is never permitted. This floor is a fallback for a single task's narrowed selection, not a default — most tasks resolve via steps 1–2 and never reach it.
+
+**Wave/cycle boundary regression net** — the three steps above narrow one task's Verification Commands only; they are not a substitute for full-suite coverage. A full `yarn test` run at each wave/cycle boundary MUST happen and is the regression net for every per-task narrowed selection made under this policy. `code-reviewer.md`'s "wave-boundary full `yarn test` ... is the regression net" sentence refers to this paragraph.
+
 - Nếu split mà task nào không kèm được Test Cases + Test Files cụ thể → task đó chưa đủ `ready`, đánh `needs_breakdown`.
 - Update `INDEX.md`: thêm row mỗi task với status `ready`.
 - Đây là **điểm cắt cuối trước khi code chạy**: phase này xong, executor được phép pick. Trong `/ukit:handoff-fullstack`, gate ở đây là plan review độc lập (model mạnh, context riêng) chứ không phải human — vì người dùng đã chủ động chọn chạy one-shot.

package/templates/ukit/storage/config.json

@@ -9,7 +9,7 @@
   "compact": {
     "enabled": true,
     "tokenThreshold": 50000,
-    "hardCapTokens": 160000,
+    "hardCapTokens": 220000,
     "hardCapBlock": true,
     "hardCapGraceCalls": 10,
     "contextRotDetection": true,
@@ -187,7 +187,7 @@
   "handoff": {
     "enabled": true,
     "crossTool": true,
-    "maxParallelAgents": 10,
+    "maxParallelAgents": 12,
     "autonomy": {
       "askWindow": "plan-only",
       "planReviewRounds": 2,
@@ -384,7 +384,7 @@
     "compact": {
       "enabled": "Bật/tắt toàn bộ helper compact của UKit.",
       "tokenThreshold": "Ngưỡng token chung cho runtime compact dùng chung.",
-      "hardCapTokens": "Ngưỡng cứng tuyệt đối (mặc định 160000 token ước lượng). Chạm/vượt ngưỡng này thì context coi như quá dài — không phải gợi ý nữa, là bắt buộc. PHẢI thấp hơn context window thật của model (200k), nếu không API sẽ báo lỗi vượt context trước khi gate kịp chặn.",
+      "hardCapTokens": "Ngưỡng cứng tuyệt đối (mặc định 220000 token ước lượng, cỡ cho context window 256k). Chạm/vượt ngưỡng này thì context coi như quá dài — không phải gợi ý nữa, là bắt buộc. PHẢI thấp hơn context window thật của model, nếu không API sẽ báo lỗi vượt context trước khi gate kịp chặn — model 200k thì hạ xuống 160000 hoặc thấp hơn. Đi kèm env.CLAUDE_CODE_AUTO_COMPACT_WINDOW trong .claude/settings.json (mặc định 180000), số đó phải nhỏ hơn ngưỡng này để client tự auto-compact trước khi gate chặn tool.",
       "hardCapBlock": "Nếu true, hook context-hardcap-gate chặn cứng Edit/Write/Bash (exit 2) khi vượt hardCapTokens, cho tới khi có compact thật (PreCompact) reset lại bộ đếm.",
       "hardCapGraceCalls": "Số tool call được phép chạy tiếp sau khi vượt hardCapTokens KHI docs/AI_HANDOFF/RUN.md còn run dở (mặc định 10). Dùng để run kịp commit + ghi cursor + push rồi mới bị chặn, thay vì chết giữa lúc đang Edit. Hết grace là chặn cứng như cũ. Budget tính theo mỗi đợt vượt cap, chỉ reset khi ước lượng token thật sự giảm (có compact thật) — không reset theo wave.",
       "contextRotDetection": "Phát hiện context quá dài/dễ mục để giữ lại state quan trọng trước khi AI nhớ sai.",
@@ -494,7 +494,7 @@
     "handoff": {
       "enabled": "Bật Quality Gate cho handoff: plan có Test Plan, executor test-first, reviewer model khác. Tắt = quay về flow cũ (dễ lọt lỗi vặt).",
       "crossTool": "true nghĩa là handoff truyền qua file (PLAN/INDEX/tasks) chứ không qua in-process subagent — cho phép plan ở Claude Code, execute ở Kilo Code, review ở Claude Code khác model.",
-      "maxParallelAgents": "Số agent chạy song song TỐI ĐA trong một wave (mặc định 10, tăng từ 3 để giảm thời gian chờ khi có nhiều task độc lập). Một wave có nhiều task hơn số này sẽ được chia thành nhiều batch chạy lần lượt — áp dụng cho cả Phase 3 Implement và Phase 4 Review. Lý do giới hạn vẫn còn: mỗi agent nền có context window riêng, và report của agent khi xong sẽ được inject ngược vào session chính — chạy quá nhiều cùng lúc (vd 20+) vẫn có thể làm session chính vượt context window và bỏ lại worktree rác. Hạ xuống 3-5 nếu task nặng (verification output dài) hoặc thấy compact bị trigger liên tục; tránh vượt quá ~10-15.",
+      "maxParallelAgents": "Số agent chạy song song TỐI ĐA trong một wave (mặc định 12, tăng từ 3 để giảm thời gian chờ khi có nhiều task độc lập; 12 là số chọn theo dải an toàn ~10-15 dưới đây, không phải số đo được). Một wave có nhiều task hơn số này sẽ được chia thành nhiều batch chạy lần lượt — áp dụng cho cả Phase 3 Implement và Phase 4 Review. Lý do giới hạn vẫn còn: mỗi agent nền có context window riêng, và report của agent khi xong sẽ được inject ngược vào session chính — chạy quá nhiều cùng lúc (vd 20+) vẫn có thể làm session chính vượt context window và bỏ lại worktree rác. Hạ xuống 3-5 nếu task nặng (verification output dài) hoặc thấy compact bị trigger liên tục; tránh vượt quá ~10-15.",
       "plan": {
         "requireTestPlan": "Bắt buộc PLAN.md §4 phải có Test Plan trước khi task chuyển ready.",
         "minTestsHappyPath": "Tối thiểu test cho happy path.",