@ngockhoale/ukit 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to UKit are documented here.
 
+## 2.0.5 - 2026-08-11
+
+### Changed
+
+- **Model IDs refreshed to the Claude 5 family**: `claude-sonnet-4-6` → `claude-sonnet-5`, `claude-opus-4-6` → `claude-opus-5`, across the `code`/`smart` tiers, `orchestration.modelTiers.vision.fallbackModel`, `handoff.defaultModel`/`advisorModel`/`orchestratorModel`, the Codex adapter settings, the `handoff-planner` agent example, and the config's own Vietnamese documentation strings. `claude-haiku-4-5` is unchanged — Haiku 4.5 is still current, so the `lite` tier was already correct. 54 references in live config, source and tests; historical records (`docs/AI_HANDOFF/archive/`, `docs/plans/`, `docs/WORKLOG.md`, `.ukit/storage/backups/`) are deliberately left alone, since rewriting what a past cycle actually ran on would be falsifying the record.
+
+## 2.0.4 - 2026-08-11
+
+### Added
+
+- **`context-window-guard.sh`** (UserPromptSubmit) — measures the session's real context by reading the transcript, and warns at 80% of `compact.hardCapTokens` / raises an ALERT at 100%. It counts only the messages *after* the last `compact_boundary`, so it tracks live context rather than the file's lifetime size (on a real 5.8 MB transcript: 1,444,439 tokens whole-file vs 145,510 measured — the whole-file number is off by 10x and useless). Subagent entries (`isSidechain`) are counted separately, since each carries its own window. **Advisory only — it always exits 0.** A hook that blocked here would strand the user at exactly the moment they can no longer type their way out.
+- **`handoff.maxParallelAgents`** (default `3`) — caps how many implementer agents a handoff wave spawns at once. `handoff-implement` and `handoff-fullstack` now batch each wave against it instead of launching every independent task simultaneously.
+- **`ukit update` now refreshes the current project**, replacing the `ukit update && ukit install` two-step. `--no-install` keeps the old CLI-only behaviour. The refresh is spawned as a **child process** running the newly installed global `bin/ukit`: after `npm install -g`, the running process still holds the old module graph, so an in-process install would redeploy the *old* templates and silently defeat the update. It also refuses to scaffold a directory with no UKit markers (install writes `.claude/`, `CLAUDE.md` and edits `.gitignore` — an unwelcome surprise in a home directory), and never reports an install that did not actually happen.
+
+### Changed
+
+- **`compact.hardCapTokens` default lowered from `220000` to `160000`.** The old default sat *above* a 200k model window, so the gate it guards could never fire in the one situation it exists to prevent — it was dead code shipped as a safety feature. Measured live on a real session, the new guard read 157,952 tokens against this 160k cap, matching the point where the API actually starts rejecting input. The separate 50k/80k advisory phases are unchanged.
+- **The index now covers the whole project instead of a fixed list of directory names.** Discovery scanned `src`/`tests`/`test`/`specs`/`spec`/`__tests__`/`manifests` and fell back to the project root only when *none* of them existed. A partial match was the trap: a repo with a top-level `tests/` but its code in `packages/` or `app/` indexed `tests/` and silently nothing else. Scope now comes from the project's own ignore rules — git's tracked plus untracked-not-ignored files — which is self-tuning per layout and needs no configuration. Non-git projects fall back to walking the root. This also removes noise the old name-based walk could not see: build output a project gitignores, and `.claude/`/`.ukit/`, which `ukit install` writes into every project.
+- **Shell scripts are indexed.** `.sh` joins `.md`/`.json`/`.yaml` as tracked-but-not-parsed, matched by path. Every hook UKit ships was previously invisible to its own index.
+
+### Fixed
+
+- **One pasted screenshot could brick `Edit`/`Write` for an entire session on every non-UNIC project.** The vision gate hard-blocks edits until a `ukit-vision-analyst` receipt exists, and it accepted a receipt only if the reported model matched a hardcoded, by-then-stale model ID. That acceptance path is unsatisfiable in practice: an honest agent reports the model it *actually* ran on, so the gate could never be cleared and the only escape was deleting a gitignored marker file by hand. The gate now stands down entirely when the session is off the UNIC gateway — where Claude reads images natively and there is nothing to enforce — and matches `unic-vision` by capability instead of by a pinned version string. Detection failure (`null`) still enforces, so breaking one gitignored file is not a bypass. `tests/handoff/cycle4/vision-gate.test.mjs` gains cases 21b/21c pinning "off-gateway + no receipt is allowed, never a deadlock" and "no fallback model needs to be configured"; the UNIC enforcement cases are untouched and still pass.
+- **The v2.0.2 hard cap could not stop what it was built to stop.** `context-hardcap-gate.sh` is `PreToolUse`, but a context-window rejection happens when the request is *sent* — before any tool call exists to gate. `UserPromptSubmit` is the only event that runs early enough, hence the new guard above. Related: only three modules ever advance `estimatedTotalTokens`, and none of them observe `Read` results, images, or returned subagent reports, so the tracked figure drifts far below reality on exactly the sessions that overflow.
+- **UKit's index could not see what UKit ships — the root cause of three releases' worth of dead features.** Because `src`, `tests` and `manifests` all exist in this repo, `templates/` was never scanned: 0 of 303 shipped files indexed, while the hand-maintained `.claude/` dev mirror sat in plain view. CLAUDE.md mandates an index-first loop, so the AI was routed to `src/` and the mirror, and never learned that `templates/.claude/` is the copy that reaches users. Querying a shipped skill by its own name returned only `src/` files, with no signal that anything was out of scope. Coverage in this repo goes from 136 files to 442, including the 185 `templates/.claude` files and all 17 shipped hooks; the three assets behind the 2.0.0 and 2.0.2 bugs now rank first for their own names.
+- `tests/index/scanScope.test.js` guards the class: code outside the old allowlist is indexed even when a listed directory exists, ignore rules define scope, the non-git fallback still covers the whole project, and the shipped `index-core.mjs` bundle must carry the same discovery logic as `src/` — that bundle is what installed projects actually run, so a fix landing only in `src/` reaches nobody.
+
 ## 2.0.3 - 2026-08-11
 
 ### Added

package/manifests/platform.full.yaml

@@ -1110,6 +1110,17 @@ items:
     packs:
       - core
 
+  - id: hook-context-window-guard
+    type: hook
+    sourceTemplate: .claude/hooks/context-window-guard.sh
+    targetPath: .claude/hooks/context-window-guard.sh
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-reset-compact-pressure
     type: hook
     sourceTemplate: .claude/hooks/reset-compact-pressure.sh

package/package.json

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

package/src/cli/commands/update.js

@@ -1,13 +1,15 @@
-import { updateUkit, UKIT_PACKAGE_NAME } from '../../core/update.js';
+import { updateUkit, runInstallAfterUpdate, UKIT_PACKAGE_NAME } from '../../core/update.js';
 
-const KNOWN_UPDATE_FLAGS = new Set(['--help', '-h']);
+const KNOWN_UPDATE_FLAGS = new Set(['--help', '-h', '--no-install']);
 
-export async function runUpdate({ packageVersion, argv = [] }) {
+export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd() }) {
   if (argv.includes('--help') || argv.includes('-h')) {
-    console.log('Usage: ukit update');
+    console.log('Usage: ukit update [--no-install]');
     console.log('');
-    console.log('Upgrade the globally installed UKit CLI to the latest published version.');
-    console.log(`Equivalent to: npm install -g ${UKIT_PACKAGE_NAME}`);
+    console.log('Upgrade the globally installed UKit CLI, then refresh the current project.');
+    console.log(`Equivalent to: npm install -g ${UKIT_PACKAGE_NAME} && ukit install`);
+    console.log('');
+    console.log('  --no-install   Only upgrade the CLI; do not refresh the current project.');
     return;
   }
 
@@ -23,5 +25,30 @@ export async function runUpdate({ packageVersion, argv = [] }) {
 
   updateUkit();
 
-  console.log('[UKit] Update complete. Run `ukit --version` to confirm the new version.');
+  if (argv.includes('--no-install')) {
+    console.log('[UKit] Update complete. Skipped project refresh (--no-install).');
+    return;
+  }
+
+  console.log('[UKit] Refreshing this project: ukit install');
+  const { ran, reason } = runInstallAfterUpdate({ projectRoot: cwd });
+
+  if (ran) {
+    console.log('[UKit] Update complete — CLI upgraded and project refreshed.');
+    return;
+  }
+
+  // Never report an install that did not happen. Each case gets the actionable next step.
+  if (reason === 'not-a-ukit-project') {
+    console.log('[UKit] Update complete. No UKit files here, so nothing was refreshed.');
+    console.log('[UKit] Run `ukit install` inside a project to set it up.');
+    return;
+  }
+  if (reason === 'global-bin-not-found') {
+    console.log('[UKit] Update complete, but the upgraded CLI could not be located.');
+    console.log('[UKit] Run `ukit install` to refresh this project.');
+    return;
+  }
+  console.log(`[UKit] CLI upgraded, but the project refresh did not finish (${reason}).`);
+  console.log('[UKit] Run `ukit install` to retry.');
 }

package/src/core/runtimeConfig.js

@@ -117,14 +117,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     },
     router: {
       enabled: true,
-      defaultModel: 'claude-sonnet-4-6',
-      advisorModel: 'claude-opus-4-6',
+      defaultModel: 'claude-sonnet-5',
+      advisorModel: 'claude-opus-5',
       advisorEnabled: true,
       maxAdvisorCalls: 3,
     },
     orchestration: {
       enabled: true,
-      orchestratorModel: 'claude-sonnet-4-6',
+      orchestratorModel: 'claude-sonnet-5',
       advisorEnabled: true,
       contracts: {
         'tiny-fix': {
@@ -176,12 +176,12 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       },
       modelTiers: {
         lite: { claudeModel: 'claude-haiku-4-5', genericModel: 'unic-lite' },
-        code: { claudeModel: 'claude-sonnet-4-6', genericModel: 'unic-code' },
-        smart: { claudeModel: 'claude-opus-4-6', genericModel: 'unic-smart' },
+        code: { claudeModel: 'claude-sonnet-5', genericModel: 'unic-code' },
+        smart: { claudeModel: 'claude-opus-5', genericModel: 'unic-smart' },
         vision: {
           claudeModel: 'unic-vision',
           genericModel: 'unic-vision',
-          fallbackModel: 'claude-sonnet-4-6',
+          fallbackModel: 'claude-sonnet-5',
           capabilityTier: true,
           note: 'Capability tier, not a cost tier. Orthogonal to lite/code/smart — never insert into escalation.tierOrder. fallbackModel is used when unicMode is off.',
         },

package/src/core/update.js

@@ -1,7 +1,68 @@
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 
 export const UKIT_PACKAGE_NAME = '@ngockhoale/ukit';
 
+// Markers that a directory is a project someone has already run `ukit install` in.
+// `ukit update` refreshes such a project automatically; it must never scaffold a
+// directory that merely happens to be the shell's cwd (install writes .claude/,
+// CLAUDE.md and edits .gitignore — an unwanted surprise in, say, a home directory).
+const INSTALLED_MARKERS = ['.ukit', '.claude', 'CLAUDE.md', 'AGENTS.md', '.codex'];
+
+export function hasUkitInstalled(projectRoot) {
+  return INSTALLED_MARKERS.some((marker) => fs.existsSync(path.join(projectRoot, marker)));
+}
+
+/**
+ * Absolute path to the globally installed `bin/ukit`, or null if it cannot be resolved.
+ *
+ * Resolving this matters for correctness, not tidiness: after `npm install -g` the
+ * CURRENT process is still running the OLD code off the old module graph. Calling the
+ * in-process install would reinstall the OLD templates and silently defeat the update.
+ * Only a fresh child process picks up the newly written package.
+ */
+export function resolveGlobalUkitBin({ spawnSync = defaultSpawnSync } = {}) {
+  const result = spawnSync('npm', ['root', '-g'], { encoding: 'utf8' });
+  if (result.error || result.status !== 0 || typeof result.stdout !== 'string') {
+    return null;
+  }
+  const binPath = path.join(result.stdout.trim(), ...UKIT_PACKAGE_NAME.split('/'), 'bin', 'ukit');
+  return fs.existsSync(binPath) ? binPath : null;
+}
+
+/**
+ * Run `ukit install` in `projectRoot` using the freshly installed global package.
+ * Returns { ran, reason } so the caller can report accurately rather than claim an
+ * install that never happened.
+ */
+export function runInstallAfterUpdate({
+  projectRoot,
+  spawnSync = defaultSpawnSync,
+  execPath = process.execPath,
+} = {}) {
+  if (!hasUkitInstalled(projectRoot)) {
+    return { ran: false, reason: 'not-a-ukit-project' };
+  }
+
+  const binPath = resolveGlobalUkitBin({ spawnSync });
+  if (!binPath) {
+    return { ran: false, reason: 'global-bin-not-found' };
+  }
+
+  const result = spawnSync(execPath, [binPath, 'install'], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+  });
+  if (result.error) {
+    return { ran: false, reason: `install-failed: ${result.error.message}` };
+  }
+  if (result.status !== 0) {
+    return { ran: false, reason: `install-exited-${result.status}` };
+  }
+  return { ran: true, reason: null };
+}
+
 export function updateUkit({ spawnSync = defaultSpawnSync } = {}) {
   const result = spawnSync('npm', ['install', '-g', UKIT_PACKAGE_NAME], {
     stdio: 'inherit',

package/src/index/buildIndex.js

@@ -1,13 +1,14 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 
 import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, isLikelyTestFilePath, normalizeRelative } from './paths.js';
 import { importsNeedAliasContext, loadImportAliasContextState, resolveImportSpecifier } from './importResolution.js';
 import { clearIndexArtifactCache } from './queryIndex.js';
 import { clearRelatedTestArtifactCache } from './relatedTests.js';
 
-const SOURCE_DIRS = ['src', 'tests', 'test', 'specs', 'spec', '__tests__', 'manifests'];
+const GIT_ENUMERATION_TIMEOUT_MS = 15_000;
 const EXCLUDED_DIR_NAMES = new Set([
   'node_modules',
   '.git',
@@ -30,7 +31,9 @@ const EXCLUDED_DIR_NAMES = new Set([
 ]);
 const CODE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue']);
 const STYLE_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
-const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.json', '.yaml', '.yml', '.md']);
+// `.sh` is tracked but never parsed, like `.md`/`.json`/`.yaml` — it is matched
+// by path only. Without it every shipped hook script was invisible to the index.
+const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.json', '.yaml', '.yml', '.md', '.sh']);
 const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSIONS]);
 export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const INDEX_PARSE_BATCH_SIZE = 8;
@@ -52,7 +55,7 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
     previousCodeFileRecords.map((item) => [item.filePath, { mtimeMs: Number(item.mtimeMs ?? -1), size: Number(item.size ?? -1) }]),
   );
 
-  const discoveredFiles = await collectFiles(await resolveScanRoots(absoluteRoot));
+  const discoveredFiles = await discoverProjectFiles(absoluteRoot);
   const sourceFingerprint = createSourceFingerprint(absoluteRoot, discoveredFiles);
   const styleFilePaths = discoveredFiles
     .map((entry) => {
@@ -942,22 +945,106 @@ function areBugIndexSnapshotsEqual(previousSnapshot, nextSnapshot) {
     && previousSnapshot.size === nextSnapshot.size;
 }
 
-async function resolveScanRoots(rootDir) {
-  const concreteRoots = [];
+/*
+ * File discovery is the whole project, always — never a fixed list of "source"
+ * directory names.
+ *
+ * The old rule scanned `src|tests|test|specs|spec|__tests__|manifests` and only
+ * fell back to the project root when NONE of them existed. Partial matches were
+ * the trap: a repo with a top-level `tests/` but its code in `packages/` indexed
+ * `tests/` and silently nothing else. UKit's own repo hit exactly that — `src`,
+ * `tests` and `manifests` all exist, so `templates/` (the entire shipped payload)
+ * was never indexed, and three releases shipped features that were dead on
+ * arrival because the index kept pointing at `src/` and the hand-maintained
+ * `.claude/` dev mirror instead.
+ *
+ * Scope now comes from the project's OWN ignore rules rather than a guess about
+ * its layout: git lists tracked files plus untracked-not-ignored ones. That is
+ * self-tuning per project and needs no configuration — end users still only run
+ * `ukit install`. It also removes noise the name-based walk cannot see: build
+ * output a project gitignores, and `.claude/`/`.ukit/`, which `ensureGitignore`
+ * writes into every installed project, so UKit's own scaffolding stops competing
+ * with the user's real code in query results.
+ *
+ * Non-git projects fall back to walking the root with the same exclusion rules.
+ */
+async function discoverProjectFiles(rootDir) {
+  const gitFiles = await collectGitTrackedFiles(rootDir);
+  if (gitFiles) {
+    return gitFiles;
+  }
+
+  return collectFiles([rootDir]);
+}
+
+function runGit(rootDir, args) {
+  const result = spawnSync('git', args, {
+    cwd: rootDir,
+    encoding: 'utf8',
+    maxBuffer: 256 * 1024 * 1024,
+    timeout: GIT_ENUMERATION_TIMEOUT_MS,
+    windowsHide: true,
+  });
+
+  if (result.error || result.status !== 0 || typeof result.stdout !== 'string') {
+    return null;
+  }
+
+  return result.stdout;
+}
+
+/**
+ * @returns {Promise<Array<{absolutePath: string, mtimeMs: number, size: number}>|null>}
+ *   `null` when this is not a usable git worktree, so the caller can fall back.
+ */
+async function collectGitTrackedFiles(rootDir) {
+  // `-z` matters beyond separators: it also disables git's path quoting, which
+  // would otherwise mangle non-ASCII filenames.
+  const tracked = runGit(rootDir, ['ls-files', '-z']);
+  if (tracked === null) {
+    return null;
+  }
+  const untracked = runGit(rootDir, ['ls-files', '-z', '--others', '--exclude-standard']) ?? '';
+
+  const relativePaths = new Set();
+  for (const entry of `${tracked}${untracked}`.split('\0')) {
+    if (entry) {
+      relativePaths.add(entry);
+    }
+  }
+  if (relativePaths.size === 0) {
+    return null;
+  }
+
+  const candidates = [...relativePaths].filter((relativePath) => {
+    if (!DISCOVERED_EXTENSIONS.has(path.extname(relativePath).toLowerCase())) {
+      return false;
+    }
+    // Git already applied the project's own ignore rules, so dot-directories it
+    // still lists are deliberate (UKit's `templates/.claude/**` is force-added).
+    // All that is left to defend against is a build directory someone committed.
+    return !relativePath.split('/').some((segment) => EXCLUDED_DIR_NAMES.has(segment));
+  });
 
-  for (const relativeDir of SOURCE_DIRS) {
-    const dirPath = path.join(rootDir, relativeDir);
+  const entries = await Promise.all(candidates.map(async (relativePath) => {
+    const absolutePath = path.join(rootDir, relativePath);
     try {
-      const stat = await fs.stat(dirPath);
-      if (stat.isDirectory()) {
-        concreteRoots.push(dirPath);
+      const stat = await fs.stat(absolutePath);
+      if (!stat.isFile()) {
+        return null;
       }
+      return {
+        absolutePath,
+        mtimeMs: Math.floor(stat.mtimeMs),
+        size: stat.size,
+      };
     } catch {
-      // ignore
+      // staged deletion, or a symlink pointing outside the worktree
+      return null;
     }
-  }
+  }));
 
-  return concreteRoots.length > 0 ? concreteRoots : [rootDir];
+  return entries.filter(Boolean);
 }
 
 function shouldSkipDirectory(name) {
@@ -965,7 +1052,12 @@ function shouldSkipDirectory(name) {
     return true;
   }
 
-  return name.startsWith('.') && name !== '.claude' && name !== '.codex' && name !== '.antigravity';
+  // Dot-directories are tool scaffolding, not project source. `.claude/`,
+  // `.codex/` and `.ukit/` matter most: `ukit install` writes them into every
+  // project AND gitignores them, so the git path never lists them either.
+  // Skipping them here keeps both discovery paths agreeing, and stops UKit's own
+  // ~450 scaffolding files from crowding out the user's code in query results.
+  return name.startsWith('.');
 }
 
 function createSourceFingerprint(rootDir, discoveredFiles) {
@@ -1640,7 +1732,7 @@ export async function isIndexStale({
 
   const currentSourceFingerprint = createSourceFingerprint(
     absoluteRoot,
-    await collectFiles(await resolveScanRoots(absoluteRoot)),
+    await discoverProjectFiles(absoluteRoot),
   );
   return !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, currentSourceFingerprint);
 }

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

@@ -52,7 +52,7 @@ If zero testable behavior → write `N/A` + explicit justification in each task'
 Append this footer to `PLAN.md` — mandatory, checked by a hook before the write is allowed:
 ```
 ## Planner Report
-PLANNER_MODEL: <your exact model ID — e.g. claude-opus-4-6>
+PLANNER_MODEL: <your exact model ID — e.g. claude-opus-5>
 ```
 
 ## Phase 2 — Split into TASK-xxx.md

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

@@ -52,7 +52,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    - §5 Verification — exact shell commands executor will run
    - §6 Acceptance — done checklist (prefer verifiable criteria with commands)
 
-   Append a footer — **mandatory, a hook blocks the write without it**:
+   Append a footer — **mandatory**. The PLAN.md write itself goes through, but a hook then blocks task-file creation and the final push until this footer is present:
    ```
    ## Planner Report
    PLANNER_MODEL: <your exact model ID>

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

@@ -61,7 +61,7 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    - §5 Verification — exact shell commands executor will run
    - §6 Acceptance — done checklist (prefer verifiable criteria with commands)
 
-   Append a footer — **mandatory, a hook blocks the write without it**:
+   Append a footer — **mandatory**. The PLAN.md write itself goes through, but a hook then blocks task-file creation and the final push until this footer is present:
    ```
    ## Planner Report
    PLANNER_MODEL: <your exact model ID>
@@ -127,9 +127,19 @@ Read each `docs/AI_HANDOFF/tasks/TASK-xxx.md` for `Dependencies` field:
 - Chain A→B→C = 3 waves of 1 task each (sequential)
 - Independent A, B, C = 1 wave of 3 tasks (parallel)
 
+**Batch each wave — mandatory.** Read `handoff.maxParallelAgents` from
+`.ukit/storage/config.json` (default **3**). 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.
+
+Never spawn a whole wide wave at once. Every background agent carries its own context
+window, and each finished report is injected back into this session — a wave of 20+ is
+the fastest way to blow the orchestrator's own context window, which kills the run and
+leaves worktrees behind. Batching only ever narrows a wave, never reorders across waves.
+
 ### 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 parallel), 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` — default 3), 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:
 
@@ -139,7 +149,7 @@ git worktree add -b handoff/task-xxx .worktrees/task-xxx $BASE
 # (omit -b if branch already exists)
 ```
 
-**3b — Run tasks in parallel** — one code-model agent per task, each in its own worktree. Each agent:
+**3b — Run the batch in parallel** — one code-model agent per task in the batch (at most `handoff.maxParallelAgents`), each in its own worktree. Each agent:
 ```
 Read docs/AI_HANDOFF/tasks/TASK-xxx.md
 

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

@@ -33,9 +33,22 @@ Read each `tasks/TASK-xxx.md` for `Dependencies` field:
 - Chain A→B→C = 3 waves of 1 task each (sequential, no parallel)
 - Independent A, B, C = 1 wave of 3 tasks (parallel)
 
+### Batch each wave — mandatory
+
+Read `handoff.maxParallelAgents` from `.ukit/storage/config.json` (default **3**). 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.
+
+Never spawn a whole wide wave at once. Every background agent carries its own context
+window, and each finished report is injected back into this session — a wave of 20+ is
+the fastest way to blow the orchestrator's own context window, which kills the run and
+leaves worktrees behind. Dependencies still take priority: batching only ever narrows a
+wave, never reorders it across waves.
+
 ## Step 3 — Execute wave by wave
 
-For each wave:
+For each wave (and for each batch within it):
 
 ### 3a — Create worktrees (from `$BASE`, no extra branch)
 ```bash
@@ -45,7 +58,7 @@ git worktree add -b handoff/task-xxx .worktrees/task-xxx $BASE
 
 ### 3b — Run tasks in parallel (one agent/session per task)
 
-**Claude Code — MANDATORY, do this before anything else in this wave:** call the Agent tool once per task in the wave (in parallel), 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 this 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.
 
 Each spawned agent works independently in its own worktree — **NO git commit, NO git add**:
 

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 220000), separate from the soft/hard advisory pressure phases in
+# default 160000 — must stay below the model's real context window), separate from the
+# soft/hard advisory pressure phases in
 # compact-threshold.mjs (default soft=50000/hard=80000, which only print a suggestion).
 #
 # Those advisory phases are just injected text — nothing stops the agent from ignoring

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

@@ -0,0 +1,158 @@
+#!/bin/bash
+# UserPromptSubmit hook: warn BEFORE the request is sent when the live context is close
+# to the model's real window.
+#
+# Why this exists, and why context-hardcap-gate.sh could not do it:
+#   "Your input exceeds the context window of this model" is an API-level rejection. It
+#   happens when the request is SENT, before the model emits any tool call. A PreToolUse
+#   hook only runs when a tool call is already about to execute, so it is structurally
+#   incapable of preventing that error — it can only ever block the next Edit/Write AFTER
+#   the context is already oversized. UserPromptSubmit is the one event that runs before
+#   the turn, which makes it the only place this check can do any good.
+#
+# Why it measures the transcript instead of compact-pressure.json:
+#   estimatedTotalTokens is UKit's own running approximation, advanced only by a couple of
+#   runtime modules. Nothing feeds it file Reads, tool results, images, or subagent
+#   reports — i.e. the largest contributors — so it can read ~30k while the real context
+#   is nearly full. transcript_path is the actual conversation on disk.
+#
+# ADVISORY ONLY — always exit 0, never exit 2. Blocking the prompt would not prevent the
+# overflow (the context is already accumulated) and would strand the user with no way
+# forward, since /compact itself has to send the transcript and fails the same way. A
+# loud early warning is the thing that actually helps: it arrives while compacting or
+# starting a fresh session still works.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
+const fs = require('fs');
+const path = require('path');
+
+// Reading more than this per prompt is not worth the latency. Reading only the TAIL is
+// also the safe direction: if the last compact boundary is older than the tail, we count
+// the whole tail as live context, which over-estimates and warns earlier.
+const MAX_READ_BYTES = 24 * 1024 * 1024;
+
+// Chars-per-token. Calibrated against a real 2843-line transcript: whole-file bytes read
+// ~1.44M "tokens" (constant false alarms), while message content after the last compact
+// boundary read ~145k for a session that did in fact need compacting right after.
+const CHARS_PER_TOKEN = 4;
+
+const payload = (() => {
+  try {
+    const parsed = JSON.parse(process.env.INPUT || '');
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+})();
+
+const projectRoot = process.env.PROJECT_ROOT;
+const transcriptPath = typeof payload.transcript_path === 'string' ? payload.transcript_path.trim() : '';
+if (!transcriptPath) process.exit(0);
+
+function readTail(filePath) {
+  const stat = fs.statSync(filePath);
+  if (stat.size <= MAX_READ_BYTES) {
+    return { text: fs.readFileSync(filePath, 'utf8'), truncated: false };
+  }
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const buf = Buffer.allocUnsafe(MAX_READ_BYTES);
+    fs.readSync(fd, buf, 0, MAX_READ_BYTES, stat.size - MAX_READ_BYTES);
+    return { text: buf.toString('utf8'), truncated: true };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// The cap the rest of UKit already agrees on, so one config key tunes both this warning
+// and context-hardcap-gate.sh. Default mirrors compact-threshold.mjs.
+function loadHardCap() {
+  try {
+    const raw = fs.readFileSync(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8');
+    const value = JSON.parse(raw)?.compact?.hardCapTokens;
+    if (Number.isFinite(value) && value > 0) return value;
+  } catch { /* fall through to the default */ }
+  return 160_000;
+}
+
+let text;
+let truncated;
+try {
+  ({ text, truncated } = readTail(transcriptPath));
+} catch {
+  // Transcript unreadable (first prompt of a session, permissions, races). Nothing to
+  // measure and nothing worth reporting.
+  process.exit(0);
+}
+
+const lines = text.split('\n').filter(Boolean);
+if (truncated) lines.shift(); // a tail read almost certainly split the first line
+
+// Everything before the last compact boundary is already summarised away and is NOT in
+// the live context. Counting it is what makes naive file-size estimates useless.
+let start = 0;
+for (let i = lines.length - 1; i >= 0; i -= 1) {
+  if (!lines[i].includes('compact_boundary')) continue;
+  try {
+    const entry = JSON.parse(lines[i]);
+    if (entry?.type === 'system' && entry?.subtype === 'compact_boundary') {
+      start = i + 1;
+      break;
+    }
+  } catch { /* not a usable boundary line */ }
+}
+
+let contentChars = 0;
+let sidechainEntries = 0;
+for (let i = start; i < lines.length; i += 1) {
+  let entry;
+  try {
+    entry = JSON.parse(lines[i]);
+  } catch {
+    continue;
+  }
+  // Subagent traffic lives in its own context window, not the main one. Count it
+  // separately: it is a leading indicator of the "many teammates at once" blow-up, but
+  // adding it to the main estimate would overstate the main window.
+  if (entry?.isSidechain) {
+    sidechainEntries += 1;
+    continue;
+  }
+  if (entry?.type !== 'user' && entry?.type !== 'assistant' && entry?.type !== 'attachment') continue;
+  try {
+    contentChars += JSON.stringify(entry.message ?? entry.attachment ?? '').length;
+  } catch { /* unserialisable entry */ }
+}
+
+const estimatedTokens = Math.round(contentChars / CHARS_PER_TOKEN);
+const hardCap = loadHardCap();
+const ratio = estimatedTokens / hardCap;
+
+if (ratio < 0.8) process.exit(0);
+
+const pct = Math.round(ratio * 100);
+const lines_out = [];
+if (ratio >= 1) {
+  lines_out.push(`UKIT CONTEXT ALERT — live context ~${estimatedTokens.toLocaleString()} tokens, at/over the ${hardCap.toLocaleString()} cap (${pct}%).`);
+  lines_out.push('The next few turns risk "Your input exceeds the context window of this model".');
+  lines_out.push('Act now: /compact, or finish this thread and start a fresh session.');
+  lines_out.push('If /compact itself already failed, the context is too large to summarise —');
+  lines_out.push('a new session is the only way out. Work committed to disk is not lost.');
+} else {
+  lines_out.push(`UKIT CONTEXT WARNING — live context ~${estimatedTokens.toLocaleString()} tokens (${pct}% of the ${hardCap.toLocaleString()} cap).`);
+  lines_out.push('Wrap up or /compact soon, while compacting still works.');
+}
+if (sidechainEntries > 0) {
+  lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch. Each teammate carries its own`);
+  lines_out.push('context window, and every finished report is injected back here — running many at');
+  lines_out.push('once is the fastest way to overflow this session.');
+}
+
+process.stdout.write(`${lines_out.join('\n')}\n`);
+process.exit(0);
+NODE
+
+exit 0

package/templates/.claude/hooks/vision-gate.sh

@@ -82,19 +82,6 @@ function readJsonSafe(filePath) {
   }
 }
 
-// Best-effort: a receipt whose model equals modelTiers.vision.fallbackModel counts as
-// vision-capable ONLY when unic-gateway.mjs reports unicMode:false (no real UNIC
-// routing, so the analyst actually ran on the fallback model instead of unic-vision).
-// In-process dynamic import — never a subprocess spawn — and never fatal: any failure
-// just means the fallback exception is unavailable and only the literal "unic-vision"
-// model name is accepted, which is the stricter/safer default.
-function loadFallbackModel() {
-  const configPath = path.join(projectRoot, '.ukit', 'storage', 'config.json');
-  const config = readJsonSafe(configPath);
-  const fallback = config?.orchestration?.modelTiers?.vision?.fallbackModel;
-  return typeof fallback === 'string' && fallback.trim() ? fallback.trim() : null;
-}
-
 // Tri-state on purpose: true | false | null(unknown). Returning false on a detection
 // FAILURE would be read as "unicMode is off", which GRANTS the fallback-model exception
 // below — i.e. deleting or breaking one gitignored file would make the gate accept a
@@ -114,14 +101,11 @@ async function detectUnicModeSafe() {
 
 // Anchored, not a substring match: "unic-vision-mini" and "not-unic-vision" are different
 // models and must not inherit the real one's capability by sharing a substring.
-// ukit-vision-analyst's frontmatter pins the exact name `unic-vision`; anything else goes
-// through the fallbackModel path, which requires a positive unicMode:false detection.
-function isVisionCapable(model, fallbackModel, unicModeIsOff) {
+// Only reached when unicMode is true or unknown — off-gateway sessions already exited
+// above — so `unic-vision` is the only model that can legitimately clear the gate here.
+function isVisionCapable(model) {
   if (typeof model !== 'string' || !model.trim()) return false;
-  const trimmed = model.trim();
-  if (/^unic-vision$/i.test(trimmed)) return true;
-  if (unicModeIsOff && fallbackModel && trimmed === fallbackModel) return true;
-  return false;
+  return /^unic-vision$/i.test(model.trim());
 }
 
 const VALID_STATUSES = new Set(['OK', 'NO_IMAGE', 'UNREADABLE']);
@@ -153,7 +137,7 @@ function findReceipt(sha) {
   return null;
 }
 
-function checkReceipt(receiptPath, fallbackModel, unicModeIsOff) {
+function checkReceipt(receiptPath) {
   if (!receiptPath || !fs.existsSync(receiptPath)) {
     return { ok: false, reason: 'no analysis receipt found' };
   }
@@ -161,7 +145,7 @@ function checkReceipt(receiptPath, fallbackModel, unicModeIsOff) {
   if (!receipt) {
     return { ok: false, reason: 'receipt is not valid JSON' };
   }
-  if (!isVisionCapable(receipt.model, fallbackModel, unicModeIsOff)) {
+  if (!isVisionCapable(receipt.model)) {
     const modelLabel = typeof receipt.model === 'string' && receipt.model.trim() ? receipt.model.trim() : '(missing)';
     return { ok: false, reason: `receipt model "${modelLabel}" is not vision-capable — treated as absent` };
   }
@@ -174,9 +158,25 @@ function checkReceipt(receiptPath, fallbackModel, unicModeIsOff) {
 
 (async () => {
   const now = Date.now();
-  const fallbackModel = loadFallbackModel();
   const unicMode = await detectUnicModeSafe();
 
+  // The gate exists because the UNIC gateway BLINDS the model: unic-code/unic-smart
+  // cannot see images there, so an unanalysed image means guessing. Off the gateway
+  // Claude reads images natively and there is nothing left to enforce.
+  //
+  // This early exit is what makes the gate satisfiable at all off-gateway. The previous
+  // design tried to cover this case by accepting a receipt whose model string equalled
+  // modelTiers.vision.fallbackModel — but the analyst's frontmatter pins `unic-vision`,
+  // so off-gateway it runs on whatever model is actually available and self-reports THAT.
+  // A hardcoded fallback ID could never match it, so no valid receipt was reachable and
+  // one pasted screenshot hard-blocked Edit/Write for the rest of the session.
+  //
+  // Only a POSITIVE false stands the gate down. null (detection failed) still enforces:
+  // breaking one gitignored file must not be a bypass.
+  if (unicMode === false) {
+    process.exit(0);
+  }
+
   const unsatisfied = [];
   for (const markerName of markerNames) {
     const sha = markerName.replace(/^pending-/, '').replace(/\.json$/, '');
@@ -198,7 +198,7 @@ function checkReceipt(receiptPath, fallbackModel, unicModeIsOff) {
     if (now - markerTs > MARKER_MAX_AGE_MS) continue;
 
     const receiptPath = findReceipt(sha);
-    const result = checkReceipt(receiptPath, fallbackModel, unicMode === false);
+    const result = checkReceipt(receiptPath);
     if (!result.ok) {
       unsatisfied.push({ sha, reason: result.reason });
     }

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

@@ -44,6 +44,33 @@ const { pathToFileURL } = require('url');
 
   const promptText = extractPromptText(payload);
 
+  // Tri-state, same contract as vision-gate.sh: true | false | null(unknown).
+  async function detectUnicModeSafe() {
+    try {
+      const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
+      if (!fs.existsSync(gatewayPath)) return null;
+      const mod = await import(pathToFileURL(gatewayPath).href);
+      if (typeof mod.detectUnicGateway !== 'function') return null;
+      return !!mod.detectUnicGateway({ rootDir: projectRoot })?.unicMode;
+    } catch {
+      return null;
+    }
+  }
+
+  const unicMode = await detectUnicModeSafe();
+
+  // Off the UNIC gateway Claude reads images natively, so there is nothing to route and
+  // nothing to gate. Exit before marking anything: an armed marker that the gate will
+  // stand down on anyway is pure noise, and the advice text used to demand an analyst run
+  // whose receipt could never be accepted. Only a POSITIVE false short-circuits; null
+  // (detection failed) still routes, matching the gate's fail-safe direction.
+  //
+  // Cheaper than the old order, too: this replaces an execFileSync node spawn per prompt
+  // with one local import on the overwhelmingly common off-gateway path.
+  if (unicMode === false) {
+    process.exit(0);
+  }
+
   // URL images are checked first and stripped out so the local-path regex never
   // re-matches the tail of a URL (case c is a hint-only lane — no download here).
   const URL_IMAGE_RE = /https?:\/\/\S+\.(?:png|jpe?g|gif|webp)\b/gi;
@@ -105,56 +132,29 @@ const { pathToFileURL } = require('url');
     return;
   }
 
-  // TASK-008: branch the remedy on whether unic-vision is actually invokable for THIS
-  // session. `remedyMode` is tri-state and defaults to the strict/fail-safe variant:
-  //   'gateway'  — unicMode true: today's `unic-vision` text (unchanged).
-  //   'fallback' — unicMode false + a readable orchestration.modelTiers.vision.fallbackModel
-  //                (same config path vision-gate.sh reads, so the advertised model and the
-  //                accepted model never drift): tell the caller to override the model.
-  //   'strict'   — gateway module missing/broken, or unicMode false but fallbackModel is
-  //                unreadable: today's `unic-vision` text (fail-safe default).
-  // Never fatal — any error in this block falls back to 'strict' and no note.
-  let remedyMode = 'strict';
-  let fallbackModel = null;
+  // Only unicMode true or null reach here; off-gateway already exited. Both remaining
+  // cases get the same strict `unic-vision` remedy, so there is no fallback-model branch
+  // to advertise. There must never be one: the analyst self-reports the model it really
+  // ran on, so telling it to claim some other ID is asking it to falsify the receipt —
+  // which the gate is entitled to reject, and which defeats the point of having a gate.
   let unicNote = '';
-  try {
-    const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
-    if (fs.existsSync(gatewayPath)) {
+  if (unicMode === true) {
+    try {
+      const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
       const mod = await import(pathToFileURL(gatewayPath).href);
-      if (typeof mod.detectUnicGateway === 'function') {
-        const result = mod.detectUnicGateway({ rootDir: projectRoot });
-        if (result?.unicMode) {
-          remedyMode = 'gateway';
-          unicNote = `  (UNIC gateway active — ${result.visionModel} routes through it.)`;
-        } else {
-          const configPath = path.join(projectRoot, '.ukit', 'storage', 'config.json');
-          const configRaw = fs.readFileSync(configPath, 'utf8');
-          const config = JSON.parse(configRaw);
-          const candidate = config?.orchestration?.modelTiers?.vision?.fallbackModel;
-          if (typeof candidate === 'string' && candidate.trim()) {
-            fallbackModel = candidate.trim();
-            remedyMode = 'fallback';
-          }
-        }
+      const result = mod.detectUnicGateway({ rootDir: projectRoot });
+      if (result?.visionModel) {
+        unicNote = `  (UNIC gateway active — ${result.visionModel} routes through it.)`;
       }
+    } catch {
+      unicNote = '';
     }
-  } catch {
-    remedyMode = 'strict';
-    fallbackModel = null;
-    unicNote = '';
   }
 
-  const isFallback = remedyMode === 'fallback';
-  const reasonLine = isFallback
-    ? (armed > 0
-        ? 'Edit/Write is now GATED until a vision analysis exists. Do this before anything else:'
-        : 'Do this before anything else:')
-    : (armed > 0
-        ? 'unic-code / unic-smart cannot read images on this gateway, and Edit/Write is now GATED\nuntil a vision analysis exists. Do this before anything else:'
-        : 'unic-code / unic-smart cannot read images on this gateway. Do this before anything else:');
-  const agentLine = isFallback
-    ? `  2. Agent(subagent_type: "ukit-vision-analyst", model: "${fallbackModel}")`
-    : '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]';
+  const reasonLine = armed > 0
+    ? 'unic-code / unic-smart cannot read images on this gateway, and Edit/Write is now GATED\nuntil a vision analysis exists. Do this before anything else:'
+    : 'unic-code / unic-smart cannot read images on this gateway. Do this before anything else:';
+  const agentLine = '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]';
 
   const lines = [
     `UKIT VISION ROUTE — image input detected (${cases.join(', ')}).`,
@@ -164,10 +164,6 @@ const { pathToFileURL } = require('url');
     '     Pass the ABSOLUTE paths from images[].path as text — a subagent does NOT',
     '     inherit image blocks; it can only Read files.',
   ];
-  if (isFallback) {
-    lines.push(`     The analyst must self-report "model": "${fallbackModel}" in its receipt —`);
-    lines.push('     otherwise the gate will reject it.');
-  }
   lines.push('  3. Continue the real task using the returned description.');
   if (markedUrl > 0) {
     lines.push('  Image URL detected: ukit-vision-analyst downloads it with Bash into');

package/templates/.claude/settings.json

@@ -165,6 +165,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-window-guard.sh\"",
+            "timeout": 10
           }
         ]
       }

package/templates/.claude/ukit/index/lib/index-core.mjs

@@ -1,8 +1,9 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 
-const SOURCE_DIRS = ['src', 'tests', 'test', 'specs', 'spec', '__tests__', 'manifests'];
+const GIT_ENUMERATION_TIMEOUT_MS = 15_000;
 const EXCLUDED_DIR_NAMES = new Set([
   'node_modules',
   '.git',
@@ -25,7 +26,7 @@ const EXCLUDED_DIR_NAMES = new Set([
 ]);
 const CODE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue']);
 const STYLE_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
-const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.json', '.yaml', '.yml', '.md']);
+const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.json', '.yaml', '.yml', '.md', '.sh']);
 const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSIONS]);
 const INDEX_SCHEMA_VERSION = 6;
 export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
@@ -131,7 +132,7 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
     previousCodeFileRecords.map((item) => [item.filePath, { mtimeMs: Number(item.mtimeMs ?? -1), size: Number(item.size ?? -1) }]),
   );
 
-  const discoveredFiles = await collectFiles(await resolveScanRoots(absoluteRoot));
+  const discoveredFiles = await discoverProjectFiles(absoluteRoot);
   const sourceFingerprint = createSourceFingerprint(absoluteRoot, discoveredFiles);
   const styleFilePaths = discoveredFiles
     .map((entry) => {
@@ -2699,23 +2700,69 @@ function normalizeTestStem(testBase) {
     .toLowerCase();
 }
 
-async function resolveScanRoots(rootDir) {
-  const concreteRoots = [];
-  for (const relativeDir of SOURCE_DIRS) {
-    const dirPath = path.join(rootDir, relativeDir);
+/*
+ * File discovery is the whole project, always — never a fixed list of "source"
+ * directory names. Scope comes from the project's own ignore rules (git), which
+ * is self-tuning per layout and needs no configuration. Non-git projects fall
+ * back to walking the root with the same exclusion rules.
+ */
+async function discoverProjectFiles(rootDir) {
+  const gitFiles = await collectGitTrackedFiles(rootDir);
+  if (gitFiles) return gitFiles;
+  return collectFiles([rootDir]);
+}
+
+function runGit(rootDir, args) {
+  const result = spawnSync('git', args, {
+    cwd: rootDir,
+    encoding: 'utf8',
+    maxBuffer: 256 * 1024 * 1024,
+    timeout: GIT_ENUMERATION_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0 || typeof result.stdout !== 'string') return null;
+  return result.stdout;
+}
+
+async function collectGitTrackedFiles(rootDir) {
+  // `-z` also disables git path quoting, which would mangle non-ASCII filenames.
+  const tracked = runGit(rootDir, ['ls-files', '-z']);
+  if (tracked === null) return null;
+  const untracked = runGit(rootDir, ['ls-files', '-z', '--others', '--exclude-standard']) ?? '';
+
+  const relativePaths = new Set();
+  for (const entry of `${tracked}${untracked}`.split('\0')) {
+    if (entry) relativePaths.add(entry);
+  }
+  if (relativePaths.size === 0) return null;
+
+  const candidates = [...relativePaths].filter((relativePath) => {
+    if (!DISCOVERED_EXTENSIONS.has(path.extname(relativePath).toLowerCase())) return false;
+    // Git already applied the project's own ignore rules, so dot-directories it
+    // still lists are deliberate. Only committed build dirs are left to reject.
+    return !relativePath.split('/').some((segment) => EXCLUDED_DIR_NAMES.has(segment));
+  });
+
+  const entries = await Promise.all(candidates.map(async (relativePath) => {
+    const absolutePath = path.join(rootDir, relativePath);
     try {
-      const stat = await fs.stat(dirPath);
-      if (stat.isDirectory()) concreteRoots.push(dirPath);
+      const stat = await fs.stat(absolutePath);
+      if (!stat.isFile()) return null;
+      return { absolutePath, mtimeMs: Math.floor(stat.mtimeMs), size: stat.size };
     } catch {
-      // ignore
+      return null;
     }
-  }
-  return concreteRoots.length > 0 ? concreteRoots : [rootDir];
+  }));
+
+  return entries.filter(Boolean);
 }
 
 function shouldSkipDirectory(name) {
   if (EXCLUDED_DIR_NAMES.has(name)) return true;
-  return name.startsWith('.') && name !== '.claude' && name !== '.codex' && name !== '.antigravity';
+  // Dot-directories are tool scaffolding, not project source. `ukit install`
+  // writes AND gitignores `.claude/`, `.codex/`, `.ukit/`, so the git path never
+  // lists them either -- skipping them keeps both discovery paths agreeing.
+  return name.startsWith('.');
 }
 
 function isLikelyTestFile(filePath) {
@@ -3147,7 +3194,7 @@ export async function isIndexStale({
   if (!metaArtifact?.sourceFingerprint) return true;
   const currentSourceFingerprint = createSourceFingerprint(
     absoluteRoot,
-    await collectFiles(await resolveScanRoots(absoluteRoot)),
+    await discoverProjectFiles(absoluteRoot),
   );
   return !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, currentSourceFingerprint);
 }

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

@@ -439,7 +439,14 @@ export function buildCompactThresholds(config = {}) {
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
   // Deliberately NOT coupled to hardThreshold: this is an absolute ceiling, so raising
   // the advisory tokenThreshold must never silently raise the cap along with it.
-  const hardCapTokens = Math.max(1, finiteNumber(config?.compact?.hardCapTokens, 220_000));
+  //
+  // 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));
 
   return {
     softThreshold,

package/templates/.codex/settings.json

@@ -264,7 +264,7 @@
       "configPath": ".ukit/storage/config.json",
       "modelField": "orchestration.orchestratorModel",
       "advisorField": "orchestration.advisorEnabled",
-      "defaultModel": "claude-sonnet-4-6",
+      "defaultModel": "claude-sonnet-5",
       "internalOnly": true,
       "qualityFirst": true,
       "safeUpwardBias": true,

package/templates/ukit/storage/config.json

@@ -9,7 +9,7 @@
   "compact": {
     "enabled": true,
     "tokenThreshold": 50000,
-    "hardCapTokens": 220000,
+    "hardCapTokens": 160000,
     "hardCapBlock": true,
     "contextRotDetection": true,
     "askBeforeDrop": true,
@@ -73,14 +73,14 @@
   },
   "router": {
     "enabled": true,
-    "defaultModel": "claude-sonnet-4-6",
-    "advisorModel": "claude-opus-4-6",
+    "defaultModel": "claude-sonnet-5",
+    "advisorModel": "claude-opus-5",
     "advisorEnabled": true,
     "maxAdvisorCalls": 3
   },
   "orchestration": {
     "enabled": true,
-    "orchestratorModel": "claude-sonnet-4-6",
+    "orchestratorModel": "claude-sonnet-5",
     "advisorEnabled": true,
     "contracts": {
       "tiny-fix": {
@@ -139,12 +139,12 @@
     },
     "modelTiers": {
       "lite": { "claudeModel": "claude-haiku-4-5", "genericModel": "unic-lite" },
-      "code": { "claudeModel": "claude-sonnet-4-6", "genericModel": "unic-code" },
-      "smart": { "claudeModel": "claude-opus-4-6", "genericModel": "unic-smart" },
+      "code": { "claudeModel": "claude-sonnet-5", "genericModel": "unic-code" },
+      "smart": { "claudeModel": "claude-opus-5", "genericModel": "unic-smart" },
       "vision": {
         "claudeModel": "unic-vision",
         "genericModel": "unic-vision",
-        "fallbackModel": "claude-sonnet-4-6",
+        "fallbackModel": "claude-sonnet-5",
         "capabilityTier": true,
         "note": "Capability tier, not a cost tier. Orthogonal to lite/code/smart — never insert into escalation.tierOrder. fallbackModel is used when unicMode is off."
       }
@@ -186,12 +186,13 @@
   "handoff": {
     "enabled": true,
     "crossTool": true,
+    "maxParallelAgents": 3,
     "plan": {
       "requireTestPlan": true,
       "minTestsHappyPath": 1,
       "minTestsEdgeCase": 1,
       "regressionTestRequiredForBugfix": true,
-      "smartModelHint": "claude-opus-4-6"
+      "smartModelHint": "claude-opus-5"
     },
     "executor": {
       "testFirstRequired": true,
@@ -337,8 +338,8 @@
       "doi_reviewer_model": {
         "field": "handoff.reviewer.model",
         "mac_dinh": "unic-smart",
-        "y_nghia": "Model dùng cho reviewer agent ở Phase 3. BẮT BUỘC khác model executor để bắt được lỗi mà executor miss. Có thể dùng claude-opus-4-6, unic-smart, hoặc bất kỳ model reasoning mạnh nào.",
-        "vi_du": "Nếu executor là unic-code (Kilo Code), set reviewer.model=unic-smart hoặc claude-opus-4-6. Nếu executor là claude-sonnet, set reviewer thành claude-opus."
+        "y_nghia": "Model dùng cho reviewer agent ở Phase 3. BẮT BUỘC khác model executor để bắt được lỗi mà executor miss. Có thể dùng claude-opus-5, unic-smart, hoặc bất kỳ model reasoning mạnh nào.",
+        "vi_du": "Nếu executor là unic-code (Kilo Code), set reviewer.model=unic-smart hoặc claude-opus-5. Nếu executor là claude-sonnet, set reviewer thành claude-opus."
       },
       "tat_reviewer_phase": {
         "field": "handoff.reviewer.enabled",
@@ -369,7 +370,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 220000 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.",
+      "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.",
       "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. Không có ngoại lệ.",
       "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.",
       "askBeforeDrop": "Giữ thái độ thận trọng trước khi bỏ context quan trọng. Nếu rủi ro thì hand back cho main model.",
@@ -478,12 +479,13 @@
     "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 3). 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. Lý do: 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 là cách nhanh nhất làm session chính vượt context window. Hạ xuống 2 nếu task nặng; không nên vượt 3.",
       "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.",
         "minTestsEdgeCase": "Tối thiểu test cho edge case (null/empty/boundary/concurrent…).",
         "regressionTestRequiredForBugfix": "Bug fix phải có regression test fail-trước-fix.",
-        "smartModelHint": "Gợi ý model mạnh nhất cho phase plan (ví dụ claude-opus-4-6). UKit không tự ép, chỉ ghi hint vào task."
+        "smartModelHint": "Gợi ý model mạnh nhất cho phase plan (ví dụ claude-opus-5). UKit không tự ép, chỉ ghi hint vào task."
       },
       "executor": {
         "testFirstRequired": "Executor phải viết test trước khi implement (RED → GREEN).",
@@ -494,7 +496,7 @@
       },
       "reviewer": {
         "enabled": "Bật Phase 3 review độc lập. Tắt = bỏ lưới an toàn cuối cùng, không khuyến nghị.",
-        "model": "Model reviewer. BẮT BUỘC khác executor model. Mặc định unic-smart; có thể dùng claude-opus-4-6 hoặc bất kỳ model reasoning mạnh nào.",
+        "model": "Model reviewer. BẮT BUỘC khác executor model. Mặc định unic-smart; có thể dùng claude-opus-5 hoặc bất kỳ model reasoning mạnh nào.",
         "agent": "Tên reviewer agent (xem .claude/agents/code-reviewer.md).",
         "mustDifferFromExecutor": "Nếu true, reviewer tự refuse khi phát hiện cùng model với executor.",
         "blockOnCritical": "CRITICAL → block handoff cứng. Set false chỉ khi muốn warning mềm.",