@ngockhoale/ukit 2.5.1 → 2.6.2

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable changes to UKit are documented here.
 
+## 2.6.2 - 2026-09-18
+
+Stability release — 17 confirmed hang / silent-idle / silent-hook defects fixed with
+root causes (full register: `docs/AI_HANDOFF/BUGS-2.6.2.md`), focused on the "system
+goes quiet and does nothing" failure class.
+
+- **No more silent degraded input (§8 contract, BUG-C21-01/02/03)**: every hook that
+  stages stdin now *announces* when staging fails, stalls, or refuses — fail-closed
+  hooks (`block-dangerous`, `protect-files`, `context-hardcap-gate`,
+  `sensitive-data-guard`) emit an `ask`/`systemMessage` JSON + stderr `BLOCKED` +
+  `exit 2`; advisory hooks emit a `systemMessage` + `exit 0`. The old bounded-cut
+  silently truncated and proceeded. `sensitive-data-guard` now also fails closed
+  (exit 2) on any non-refusal staging failure and mirrors its deadline block to
+  stderr so the reason survives `process.exit` truncation.
+- **Sync-fs defeats inside self-deadlines removed (BUG-C21-04)**: the
+  deadline-guarded node blocks in `context-window-guard.sh` and
+  `context-hardcap-gate.sh` no longer call synchronous `fs.*Sync` inside the kill
+  window — a stalled `.ukit` mount can no longer freeze the gate so the unref'd
+  deadline can never fire. (Residual call-frame past the grant boundary recorded
+  as BUG-C21-R1/R2 for the next cycle.)
+- **Host timeouts now cover internal budgets (BUG-C21-05)**: every hook registered
+  in `settings.json` gets `timeout ≥ stage bound + node deadline + margin`; the
+  regression test iterates *all* registered hooks instead of a hand-picked list,
+  and four under-budgeted hooks (`auto-allow-bash`, `vision-router`,
+  `auto-prune-bash`, `reset-compact-pressure`) were raised to 12s.
+- **Missing `await` in skill-router (review major)**: an un-awaited async context
+  snapshot could leave the router writing a stale/partial decision silently.
+- **CLI hangs eliminated (BUG-C21-12/13)**: `ukit update`/`install` `spawnSync`
+  calls now carry timeouts with `killSignal: 'SIGKILL'` (SIGTERM alone keeps
+  waiting on signal-resistant children); a wedged `npm root -g` now reports
+  `global-root-query-timeout` instead of hanging forever. `promptYesNo` resolves
+  on stdin EOF / `ERR_USE_AFTER_CLOSE` instead of hanging or crashing.
+- **Unbounded growth bounded (BUG-C21-07/09/10/11)**: `tee/` cache, hook-errors
+  jsonl, hook-latency and exec-ledger session files now have count caps; the
+  ledger protects receipt files (`.journal`, `.quarantine`, gate crash counter)
+  from count-cap eviction, and the overflow basis uses `entries.length`
+  (post-filter) everywhere.
+- **Handoff machinery (BUG-C21-15)**: all four `RUN.md` `Phase:` consumers treat
+  `done`/`blocked` as terminal — dead runs no longer nag forever.
+- **Wiring/parity (BUG-C21-06/08/14/16/17)**: stale-spec-guard deadline exits
+  distinguish "stall" from "match"; `provision-worktree` spawnSync calls carry
+  timeouts; `task-budget-validator.mjs` is manifest-covered so the documented
+  command works on fresh installs; `verification-guard.sh` is actually registered
+  on PreToolUse Bash; shipped `config.json` regained `codex-context-budget` and a
+  parity test now guards every array field under `subagents`.
+
+
+## 2.6.0 - 2026-09-18
+
+handoff-fullstack v2 — autonomous create→implement→review loop that runs to 100%
+completion of all unfinished work, with a mandatory detailed SPEC gate.
+
+- **Never-stall Stop gate**: `stop-coordinator.mjs` gained a `handoff-cursor` lane that
+  reads `docs/AI_HANDOFF/RUN.md` and blocks stop while `Phase:` is not `done`/`blocked`,
+  carrying the cursor's `Next:` step. Liveness breaker releases after
+  `handoff.fullstack.stopGateMaxStalledBlocks` (default 12) un-advancing blocks; the lane
+  is advisory-on-failure and `stopGateEnabled` disables it. This fixes the observed
+  stall where runs went idle after a recap.
+- **Mandatory SPEC.md**: `handoff-create` now writes `docs/AI_HANDOFF/SPEC.md` — a
+  15-section template (FRs with Given/When/Then, fullstack scope, data model, API
+  contract, test matrix, acceptance criteria, migration, chosen defaults) — before task
+  files. Tasks carry `Spec references`; `handoff-model-guard.sh` hard-blocks fresh task
+  creation without a filled SPEC (`handoff.fullstack.specRequired=false` bypasses).
+- **Autonomous loop contract**: only `HANDOFF FULLSTACK COMPLETE` / `HANDOFF FULLSTACK
+  BLOCKED` may end a run; `CHECKPOINT — WORK CONTINUING` replaces bare recaps. Phase 0
+  sweeps INDEX, task files, HISTORY/archive, `docs/TASKS.md` Ready-for-AI, and
+  uncommitted WIP. Stuck tasks recover via `cancelled_superseded` + `TASK-xxx-R<n>`
+  replacement tasks. `idleWatchdogMin` (default 5) scheduled wakeups keep the loop
+  alive off-Claude-Code; `quietScansRequired` (default 2) guards completion; Phase F
+  runs docs sync → `archive/cycle-NN/` → `Phase: done` → marker report.
+- **Agent + command wiring**: `handoff-planner` gained legacy-sweep and SPEC-authoring
+  phases; `code-reviewer` reviews SPEC+PLAN against a 7-point spec quality gate;
+  `feature-implementer` treats `Spec references` as outranking task-file wording;
+  `handoff-implement`/`handoff-review` codify spec-is-the-contract and `-R<n>`
+  recovery. `handoff-clear` archives SPEC and must close RUN.md; `handoff-status`
+  reports run phase + spec presence.
+- **Config**: `handoff.fullstack.*` keys (`stopGateEnabled`, `stopGateMaxStalledBlocks`,
+  `quietScansRequired`, `idleWatchdogMin`, `autoArchive`, `specRequired`) with `_help`
+  notes, in both config trees.
+
 ## 2.5.1 - 2026-09-18
 
 Post-release fixes from C20 reviewer advisories.

package/manifests/platform.full.yaml

@@ -1548,6 +1548,22 @@ items:
     packs:
       - core
 
+  # BUG-C21-14: this file shipped in templates/ but was never manifest-listed, so
+  # autoDiscoverTemplates:false silently skipped it and the agent-documented
+  # `node .claude/ukit/index/task-budget-validator.mjs` command 404'd on installs.
+  # tests/manifest/settingsHookCoverage.test.js now asserts every file under
+  # templates/.claude/ukit/index/ is covered, which immunizes the next added module.
+  - id: ukit-index-task-budget-validator-script
+    type: config
+    sourceTemplate: .claude/ukit/index/task-budget-validator.mjs
+    targetPath: .claude/ukit/index/task-budget-validator.mjs
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: gitignore-root
     type: config
     sourceTemplate: .gitignore

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.5.1",
+  "version": "2.6.2",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/install.js

@@ -81,9 +81,46 @@ async function loadTrackedManagedPathSet(projectRoot) {
   );
 }
 
+// BUG-C21-13: `readline/promises` `question()` does not settle when the input
+// stream hits EOF without a pending newline — the promise stays pending after
+// the interface `close` event, so an unattended Ctrl+D / piped stdin froze
+// `runInstall` forever. Race every question against the interface's `close`
+// event; on EOF treat it as the default answer (decline → retain) and stop.
+// A post-EOF `question()` also throws ERR_USE_AFTER_CLOSE — same treatment.
+function onceInterfaceClosed(line) {
+  return new Promise((resolve) => {
+    if (typeof line.once === 'function') {
+      line.once('close', resolve);
+    }
+  });
+}
+
+async function askWithEofGuard(line, question) {
+  if (line.closed === true) {
+    return null;
+  }
+  try {
+    const answer = await Promise.race([line.question(question), onceInterfaceClosed(line)]);
+    return typeof answer === 'string' ? answer : null;
+  } catch (error) {
+    if (error?.code === 'ERR_USE_AFTER_CLOSE') {
+      return null;
+    }
+    throw error;
+  }
+}
+
 async function promptYesNo(line, question) {
   while (true) {
-    const answer = (await line.question(question)).trim().toLowerCase();
+    const raw = await askWithEofGuard(line, question);
+
+    if (raw === null) {
+      // EOF / interface closed: default answer (No) — never re-prompt a dead stream.
+      console.log('[UKit] Input ended (EOF) — keeping existing files.');
+      return false;
+    }
+
+    const answer = raw.trim().toLowerCase();
 
     if (answer === '') {
       return false;
@@ -97,6 +134,12 @@ async function promptYesNo(line, question) {
       return false;
     }
 
+    // A real terminal stays open after a bad answer, so re-prompting is safe —
+    // but if the stream just closed mid-loop, bail out as EOF.
+    if (line.closed === true) {
+      console.log('[UKit] Input ended (EOF) — keeping existing files.');
+      return false;
+    }
     console.log('[UKit] Please answer y/yes or n/no.');
   }
 }
@@ -191,7 +234,11 @@ export async function pruneDeselectedAdapters({
       console.log(`[UKit] Removed ${removedCount} ${adapter.label} path(s).`);
     }
   } finally {
-    line.close();
+    try {
+      line.close();
+    } catch {
+      // close() is best-effort cleanup — never let it mask the real result.
+    }
   }
 
   return { retainedManagedPaths: [...new Set(retainedManagedPaths)] };

package/src/cli/commands/update.js

@@ -44,6 +44,11 @@ export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd()
     console.log('[UKit] Run `ukit install` inside a project to set it up.');
     return;
   }
+  if (reason === 'global-root-query-timeout') {
+    console.log('[UKit] Update complete, but locating the upgraded CLI timed out.');
+    console.log('[UKit] `npm root -g` did not answer within 15s — check for a wedged npm/network, then run `ukit install` to refresh this project.');
+    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.');

package/src/core/output/index.js

@@ -353,6 +353,81 @@ function buildRecoveryHintSummary(summary, rawPath, { tokensBefore = 0 } = {}) {
   return null;
 }
 
+// --- tee/ cache bound (BUG-C21-07, FR-006) -----------------------------------
+// Mirror of the bound in templates/.claude/ukit/runtime/output-compression.mjs —
+// keep the two implementations identical. persistRawOutput wrote one preserved
+// file per compression and nothing ever deleted from tee/. Sweeps are SAMPLED
+// (~1/16 writes, UKIT_TEE_SWEEP_PROBABILITY to force/disable) and BOUNDED
+// (<= maxEntries stats, <= maxRemovals unlinks per sweep).
+const TEE_SWEEP_PROBABILITY_DEFAULT = 1 / 16;
+const TEE_SWEEP_MAX_ENTRIES = 128;
+const TEE_SWEEP_MAX_REMOVALS = 64;
+const TEE_MAX_FILES = 500;
+const TEE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+function teeSweepProbabilityFromEnv() {
+  const raw = Number(process.env.UKIT_TEE_SWEEP_PROBABILITY);
+  if (!Number.isFinite(raw)) return TEE_SWEEP_PROBABILITY_DEFAULT;
+  return Math.min(1, Math.max(0, raw));
+}
+
+// See the runtime mirror for the contract: removes entries older than maxAgeMs,
+// then the oldest scanned entries while the dir count exceeds maxFiles — all
+// bounded by maxEntries/maxRemovals so an oversized dir is amortized down.
+export async function sweepTeeCache(dir, {
+  now = Date.now,
+  maxAgeMs = TEE_MAX_AGE_MS,
+  maxFiles = TEE_MAX_FILES,
+  maxEntries = TEE_SWEEP_MAX_ENTRIES,
+  maxRemovals = TEE_SWEEP_MAX_REMOVALS,
+} = {}) {
+  let names;
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return { sampled: true, scanned: 0, removed: 0 };
+  }
+  const cutoff = now() - maxAgeMs;
+  const entries = [];
+  let scanned = 0;
+  for (const name of names) {
+    if (scanned >= maxEntries) break;
+    scanned += 1;
+    try {
+      const stats = await fs.stat(path.join(dir, name));
+      if (stats.isFile()) entries.push({ name, mtimeMs: stats.mtimeMs });
+    } catch { /* raced away — fine */ }
+  }
+  entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+  // Overflow counts eligible FILES only — foreign entries (non-matching names,
+  // dirs) inflate `names.length` and would evict real entries while the dir is
+  // actually under the cap.
+  const overflow = Math.max(0, entries.length - maxFiles);
+  let removed = 0;
+  for (const entry of entries) {
+    if (removed >= maxRemovals) break;
+    if (removed < overflow || entry.mtimeMs < cutoff) {
+      try {
+        await fs.rm(path.join(dir, entry.name), { force: true });
+        removed += 1;
+      } catch { /* raced away — fine */ }
+    }
+  }
+  return { sampled: true, scanned, removed };
+}
+
+export async function maybeSweepTeeCache(dir, {
+  probability,
+  random = Math.random,
+  ...options
+} = {}) {
+  const p = Number.isFinite(probability)
+    ? Math.min(1, Math.max(0, probability))
+    : teeSweepProbabilityFromEnv();
+  if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
+  return sweepTeeCache(dir, options);
+}
+
 async function persistRawOutput(projectRoot, {
   command = '',
   summary = '',
@@ -379,6 +454,8 @@ async function persistRawOutput(projectRoot, {
 
   await fs.mkdir(teeCacheDir, { recursive: true });
   await fs.writeFile(absolutePath, rawOutputText, 'utf8');
+  // Bounded, sampled tee/ prune (BUG-C21-07): advisory only.
+  await maybeSweepTeeCache(teeCacheDir).catch(() => {});
 
   return {
     rawSaved: true,

package/src/core/update.js

@@ -10,6 +10,22 @@ export const UKIT_PACKAGE_NAME = '@ngockhoale/ukit';
 // CLAUDE.md and edits .gitignore — an unwanted surprise in, say, a home directory).
 const INSTALLED_MARKERS = ['.ukit', '.claude', 'CLAUDE.md', 'AGENTS.md', '.codex'];
 
+// BUG-C21-12 (SPEC FR-005): spawnSync defaults to NO timeout, so a wedged npm
+// (network partition, hung credential helper) would block the CLI forever.
+// Per-operation CLI budgets: a pure `npm root -g` resolution is cheap (~15s);
+// `npm install -g` and the post-update reinstall child get a generous 10-minute
+// bound so slow-but-alive installs still finish.
+// killSignal SIGKILL, not the default SIGTERM: a wedged child that ignores
+// SIGTERM (npm's signal-exit cleanup handler can itself wedge) would keep
+// spawnSync waiting past the timeout — verified on Node v22: SIGTERM on a
+// signal-ignoring child blocks indefinitely, SIGKILL returns ~immediately with
+// ETIMEDOUT. Direct-child kill only (no process-group tree kill): these are
+// short-lived CLI one-shots; the detached-group TERM→KILL posture stays in
+// templates/.claude/ukit/runtime/hook-process.mjs where hooks need it.
+export const NPM_QUERY_TIMEOUT_MS = 15_000;
+export const NPM_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+const KILL_ON_TIMEOUT = 'SIGKILL';
+
 export function hasUkitInstalled(projectRoot) {
   return INSTALLED_MARKERS.some((marker) => fs.existsSync(path.join(projectRoot, marker)));
 }
@@ -23,12 +39,23 @@ export function hasUkitInstalled(projectRoot) {
  * Only a fresh child process picks up the newly written package.
  */
 export function resolveGlobalUkitBin({ spawnSync = defaultSpawnSync } = {}) {
-  const result = spawnSync('npm', ['root', '-g'], { encoding: 'utf8' });
+  return resolveGlobalUkitBinDetailed({ spawnSync }).binPath;
+}
+
+// Detailed variant: also reports WHY resolution failed, so callers can surface
+// a timeout as actionable ("npm query timed out — is the network/proxy wedged?")
+// instead of misattributing it to a missing file.
+function resolveGlobalUkitBinDetailed({ spawnSync = defaultSpawnSync } = {}) {
+  const result = spawnSync('npm', ['root', '-g'], {
+    encoding: 'utf8',
+    timeout: NPM_QUERY_TIMEOUT_MS,
+    killSignal: KILL_ON_TIMEOUT,
+  });
   if (result.error || result.status !== 0 || typeof result.stdout !== 'string') {
-    return null;
+    return { binPath: null, timedOut: result.error?.code === 'ETIMEDOUT' };
   }
   const binPath = path.join(result.stdout.trim(), ...UKIT_PACKAGE_NAME.split('/'), 'bin', 'ukit');
-  return fs.existsSync(binPath) ? binPath : null;
+  return { binPath: fs.existsSync(binPath) ? binPath : null, timedOut: false };
 }
 
 /**
@@ -45,14 +72,16 @@ export function runInstallAfterUpdate({
     return { ran: false, reason: 'not-a-ukit-project' };
   }
 
-  const binPath = resolveGlobalUkitBin({ spawnSync });
+  const { binPath, timedOut } = resolveGlobalUkitBinDetailed({ spawnSync });
   if (!binPath) {
-    return { ran: false, reason: 'global-bin-not-found' };
+    return { ran: false, reason: timedOut ? 'global-root-query-timeout' : 'global-bin-not-found' };
   }
 
   const result = spawnSync(execPath, [binPath, 'install'], {
     cwd: projectRoot,
     stdio: 'inherit',
+    timeout: NPM_INSTALL_TIMEOUT_MS,
+    killSignal: KILL_ON_TIMEOUT,
   });
   if (result.error) {
     return { ran: false, reason: `install-failed: ${result.error.message}` };
@@ -66,6 +95,8 @@ export function runInstallAfterUpdate({
 export function updateUkit({ spawnSync = defaultSpawnSync } = {}) {
   const result = spawnSync('npm', ['install', '-g', UKIT_PACKAGE_NAME], {
     stdio: 'inherit',
+    timeout: NPM_INSTALL_TIMEOUT_MS,
+    killSignal: KILL_ON_TIMEOUT,
   });
 
   if (result.error) {

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

@@ -127,17 +127,28 @@ Same model is the most common silent failure. Do not skip this check.
 ### Inputs you expect
 
 - Path to the spec/plan document (e.g. `docs/plans/*.md`). No diff, no task file, no executor report — review the document itself.
+- When invoked from the handoff pipeline you get BOTH `docs/AI_HANDOFF/SPEC.md` and `docs/AI_HANDOFF/PLAN.md`. Review them as one unit: the spec is the contract, the plan is the decomposition. Verdicts still append to PLAN.md's `## Plan Review Log`.
 
 ### Review order
 
 | Category | What to look for |
 |---|---|
 | Completeness | TODO/TBD/placeholders, incomplete sections |
-| Consistency | internal contradictions, conflicting requirements |
+| Consistency | internal contradictions, conflicting requirements; SPEC and PLAN contradicting each other |
 | Clarity | requirements ambiguous enough to cause a wrong build |
 | Scope | focused enough for one plan, not silently covering multiple subsystems |
 | YAGNI | unrequested features, over-engineering |
 
+**Handoff spec quality gate** (only when reviewing `docs/AI_HANDOFF/SPEC.md`):
+
+1. Every functional requirement is testable — Given/When/Then or a command, never "should work".
+2. Every applicable fullstack layer is covered or explicitly `N/A` with a reason.
+3. Every FR traces forward to plan scope; nothing in the plan is unbacked by the spec.
+4. Dependencies between parts are explicit.
+5. Legacy/unfinished work discovered by the Phase 0 sweep is either planned or recorded out-of-scope.
+6. Rollback/migration impact is addressed when data or schema changes.
+7. No vague instruction survives — "improve UI", "faster", "better UX" without defined behavior fails Clarity.
+
 Only flag issues that would cause real problems during implementation planning. Approve unless there are serious gaps that would lead to a flawed plan.
 
 ### Output

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

@@ -19,8 +19,10 @@ reasoning to the parent agent so it can decide whether to re-route.
 **In Handoff mode you are running unattended — ask nothing.** You were spawned by an
 orchestrator driving a pipeline; there is no human in your conversation to answer, and a
 question there is silently dropped while the run stalls. Resolve ambiguity in this order:
-the task file → `PLAN.md` → the surrounding code's existing patterns → the choice you would
-recommend. Record what you chose and why in the task's `## Discussion` thread. Only a blocker
+the task file → the `Spec references` sections of `SPEC.md` → `PLAN.md` → the surrounding
+code's existing patterns → the choice you would recommend. The spec is the contract; if the
+task file and spec disagree, implement the spec and note it in the task's `## Discussion`
+thread. Record what you chose and why in that thread. Only a blocker
 outside the repo (missing credential, unreachable service) justifies reporting `FAIL` early —
 and even then, report it, don't ask about it.
 

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

@@ -55,6 +55,35 @@ Before writing any path or command into `PLAN.md` or a task file, verify it:
 If something cannot be verified, say so in the task's `## Discussion` rather than guessing.
 A stated unknown costs the executor one read; a wrong path costs it a round.
 
+## Phase 0 — Legacy sweep (before writing anything)
+
+The plan owns ALL unfinished work, not only the new request. Scan and fold in:
+
+- `INDEX.md` rows that are not `done`/`cancelled_superseded`.
+- Task files in stale `in_progress` / `blocked` / `changes_requested` /
+  `needs_executor_report` / `needs_breakdown` from dead sessions.
+- `docs/AI_HANDOFF/HISTORY.md` + `archive/` — cycles closed with leftovers.
+- `docs/TASKS.md` — `Ready for AI` items are newly-assigned work.
+- `git status` — uncommitted work-in-progress (finish or checkpoint, never drop silently).
+
+Every discovered item becomes either a task row in the new plan or an explicitly recorded
+out-of-scope line in PLAN.md §2. Silent omission is a plan defect.
+
+**Recovery:** a stuck task record that cannot be cleanly resumed (orphaned worktree,
+contradicting reports, invalid state) is marked `cancelled_superseded` and replaced by
+`TASK-xxx-R1` (`-R2`, …) carrying the same spec references, acceptance criteria and
+verification — link both files' `## Discussion` threads.
+
+## Phase 0.5 — Write SPEC.md
+
+Write `docs/AI_HANDOFF/SPEC.md` from the template at `templates/docs/AI_HANDOFF/SPEC.md`
+(15 sections). The spec is the contract executors implement against — concrete enough that
+nothing is guessed: exact paths, module and API names, schemas, validation rules,
+permissions, empty/error states, migration behavior, test expectations. Every section is
+filled or marked `N/A — <reason>`; every open question is resolved to a chosen default
+recorded in §14. A vague line ("improve UI", "make it faster" with no number) is a spec
+defect — fix it before writing tasks.
+
 ## Phase 1 — Write PLAN.md
 
 Write all 7 sections to `docs/AI_HANDOFF/PLAN.md`:
@@ -101,6 +130,7 @@ Use `_TEMPLATE.md` structure (from pre-read context or file).
 
 | Field | Rule |
 |-------|------|
+| Spec references | SPEC.md section/FR IDs this task implements — every task traces to the spec |
 | Target Files | Exact paths — no two tasks in same wave share a 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 |
@@ -160,6 +190,7 @@ most chains are ordering preferences that a wide wave 1 would satisfy just as we
 ```
 Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <current HEAD branch>
 Goal: <1 sentence>
+Spec: docs/AI_HANDOFF/SPEC.md
 Tasks: <N> total
 Status: planning_done — ready for executor
 ```
@@ -179,6 +210,8 @@ catches it:
 2. Does every task trace back to something in §1/§6? A task nothing asks for is scope creep — cut it.
 3. Do the tasks together actually deliver §1's success definition, or only the easy part of it? State the gap if there is one.
 4. Is the *unhappy* path planned — errors, empty input, permissions, migration of existing data — or only the feature?
+4b. Does every task carry `Spec references` into SPEC.md, and does every SPEC.md FR trace to at least one task? A spec section no task implements is a silent hole.
+4c. Did the Phase 0 sweep leave anything unplanned — stale tasks, legacy leftovers, Ready-for-AI items, uncommitted WIP — without a §2 out-of-scope line?
 
 **Correctness — is anything wrong?**
 5. Every `Target Files` path verified per Grounding? Any `(new)` file marked as such?
@@ -195,7 +228,7 @@ catches it:
 Append the result to `PLAN.md`:
 ```
 ## Planner Self-Audit
-Checklist: 12/12 pass
+Checklist: 14/14 pass
 Fixed during audit: <what you changed, or "nothing">
 Known gaps: <what you deliberately left out and why, or "none">
 ```
@@ -209,6 +242,8 @@ Keep the returned message under 25 lines — the caller may be an orchestrator w
 budget is the constraint on the whole run. Detail belongs in `PLAN.md`, not in the reply.
 
 - Task count + IDs
+- Spec path + one-line coverage statement (`SPEC.md §5 FR-001→TASK-003`, …)
+- Recovery/superseded pairs (`TASK-007 → TASK-007-R1`) | none
 - Dependency graph (text form: TASK-001 → TASK-003, TASK-002 independent)
 - Wave plan: `wave 1: N tasks | wave 2: M tasks` — flag it if the graph is mostly a chain
 - Self-audit result + any `Known gaps`

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

@@ -37,6 +37,7 @@ Write `docs/AI_HANDOFF/archive/cycle-NNN.md` (if there is anything worth archivi
 ```
 # Cycle NNN — <YYYY-MM-DD> — ABORTED
 ## Summary: cycle was cleared before completion
+## Spec: <copy SPEC.md — or note its path if archived separately>
 ## Tasks: <copy INDEX.md table as-is>
 ```
 If `archive/` has > 3 files → delete oldest, append 1-line summary to `HISTORY.md`.
@@ -45,8 +46,11 @@ If `archive/` has > 3 files → delete oldest, append 1-line summary to `HISTORY
 
 ```
 PLAN.md  → "# PLAN\n_(empty)_"
+SPEC.md  → restore the untouched template (keep section headings, clear content)
 INDEX.md → empty table header only
 ACTIVE.md → "# ACTIVE\n_(no active cycle)_"
+RUN.md   → set `Phase: done` (or delete) — a live cursor that is neither `done` nor `blocked`
+           makes the Stop gate refuse the next session's stops; clearing a cycle MUST close the cursor.
 tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
 ```
 

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

@@ -69,7 +69,21 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    BASE=$(git symbolic-ref --short HEAD)
    ```
 
-3. Write `docs/AI_HANDOFF/PLAN.md` — all 6 sections mandatory:
+3. Write `docs/AI_HANDOFF/SPEC.md` — the detailed implementation spec (BẮT BUỘC before tasks).
+   Follow `docs/AI_HANDOFF/SPEC.md`'s template sections (or `templates/docs/AI_HANDOFF/SPEC.md`
+   on a fresh tree): problem/context, goals, non-goals, user journeys, functional requirements
+   with Given/When/Then + error cases, fullstack scope (backend, schema/migrations, API
+   contract, UI+state, integration, security, performance, observability, deploy/rollback),
+   data model, edge cases, test matrix, acceptance criteria, migration steps, open questions
+   with chosen defaults, review checklist.
+
+   The spec must be concrete enough that an executor implements it WITHOUT guessing: exact
+   file paths, module names, API methods, statuses, schemas, validation rules, permissions,
+   empty/error states, migration behavior, and test expectations. Open questions are
+   resolved to a chosen default recorded inline — the plan phase is the only question
+   window, so anything left "TBD" becomes a guess downstream.
+
+4. Write `docs/AI_HANDOFF/PLAN.md` — all 6 sections mandatory:
    - §1 Intent — problem + success definition
    - §2 Scope — in / out of scope. **Add a constraint**: same-wave tasks must not modify the same file (prevents merge conflicts). If two tasks need the same file, make one depend on the other.
    - §3 Approach — solution, trade-offs, alternatives rejected
@@ -83,8 +97,9 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    PLANNER_MODEL: <your exact model ID>
    ```
 
-4. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
+5. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
    Every task MUST have:
+   - Spec references (SPEC.md section IDs this task implements)
    - Target Files (exact paths — no two tasks in same wave share a file)
    - Dependencies (`TASK-xxx` or `none` — wave structure inferred from this, not stored separately)
    - Test Cases (Type | Name | Expected — ≥1 happy + ≥2 edge cases of different kinds)
@@ -93,18 +108,19 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    - Acceptance Criteria (verifiable checklist)
    Missing any field → status: `needs_breakdown`, never `ready`
 
-5. Update `INDEX.md` — one row per task, `status=ready`
+6. Update `INDEX.md` — one row per task, `status=ready`
 
-6. Update `ACTIVE.md`:
+7. Update `ACTIVE.md`:
    ```
    Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <BASE>
    Goal: <1 sentence>
+   Spec: docs/AI_HANDOFF/SPEC.md
    Tasks: <N> total
    Status: planning_done — ready for executor
    ```
    Note: wave structure is inferred from task Dependencies fields — not stored here.
 
-7. Report: task IDs, dependency graph, any `needs_breakdown` + reason
+8. Report: task IDs, dependency graph, any `needs_breakdown` + reason
 
 > **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** manually switch to the strong model, execute steps 1–7 above yourself.
 
@@ -121,9 +137,9 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 Two independent strong-model passes shape the plan before any code is written — that gate is
 intact. What it no longer does is hand a stalled plan back and wait.
 
-**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`), passing `REVIEW_TARGET_TYPE=plan` and the path to `docs/AI_HANDOFF/PLAN.md`. This MUST be a separate agent invocation from Step 2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
+**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`), passing `REVIEW_TARGET_TYPE=plan` and the paths to `docs/AI_HANDOFF/PLAN.md` AND `docs/AI_HANDOFF/SPEC.md`. This MUST be a separate agent invocation from Step 2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
 
-1. Reviewer reads `PLAN.md` only (no diff, no task files, no executor report), checks Completeness / Consistency / Clarity / Scope / YAGNI — see `.claude/agents/code-reviewer.md` → Spec/Plan Review — and appends its verdict to PLAN.md's `## Plan Review Log` (new round entry, prior rounds kept).
+1. Reviewer reads `SPEC.md` + `PLAN.md` (no diff, no task files, no executor report), checks Completeness / Consistency / Clarity / Scope / YAGNI plus the spec quality gate — every requirement testable, every fullstack layer covered, dependencies explicit, no vague instruction left — see `.claude/agents/code-reviewer.md` → Spec/Plan Review — and appends its verdict to PLAN.md's `## Plan Review Log` (new round entry, prior rounds kept).
 2. `Issues Found` → route back to Step 2: planner revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for another Step 2.5 review (this becomes the next round). Do NOT commit or hand off to executor on `Issues Found`.
 3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer, then proceed.