@ngockhoale/ukit 2.5.1 → 2.6.2

package/templates/.claude/ukit/runtime/stop-coordinator.mjs

@@ -12,9 +12,18 @@
  *     `--evaluate-stop` exactly once (the ledger owns its own counting semantics);
  *   - it evaluates the watchdog policy in-process through task-watchdog.mjs's
  *     exported `evaluateStopWatchdog` exactly once;
- *   - it merges the two evaluator results with a deterministic owner order —
- *     fail-closed completion failure > completion block > watchdog block > merged
- *     advisory > silent release — and emits AT MOST ONE Stop JSON line;
+ *   - it evaluates the handoff-cursor policy in-process: while
+ *     `docs/AI_HANDOFF/RUN.md` carries `Phase:` other than `done`/`blocked`, a
+ *     handoff-fullstack run is still in flight and the stop is bounced back with
+ *     the cursor's `Next:` step — this is what keeps an overnight run moving
+ *     after a recap instead of stalling idle. A stalled-cursor breaker releases
+ *     the stop if the cursor has not advanced across `stopGateMaxStalledBlocks`
+ *     consecutive blocked stops (same liveness shape as the ledger's
+ *     noProgressCount breaker);
+ *   - it merges the three evaluator results with a deterministic owner order —
+ *     fail-closed completion failure > completion block > handoff-cursor block >
+ *     watchdog block > merged advisory > silent release — and emits AT MOST ONE
+ *     Stop JSON line;
  *   - a lock-scoped once-per-stop guard makes a legacy double-registered Stop
  *     (old settings.json still listing both hooks) inert: the second coordinator
  *     invocation for the same session inside the dedupe window emits nothing and
@@ -41,6 +50,7 @@
  *   normalizeEvaluatorStdout    — ledger stdout → { kind, reason?, systemMessage? }.
  *   coordinateStopDecisions     — the pure ordered merge; owns ordering + provenance
  *                                 only (evaluators stay independently testable).
+ *   evaluateHandoffCursor       — in-process RUN.md lane; advisory on any failure.
  *   evaluateCompletionPolicy    — spawns the ledger once, returns the normalized
  *                                 completion evaluator result (throws on failure).
  *   runStopCoordinator          — event guard + dedupe + both evaluators + merge.
@@ -162,6 +172,20 @@ const LOCK_BUDGET_MS = 600;
 
 const WATCHDOG_PROVENANCE_PREFIX = '[ukit-stop-coordinator] task-watchdog also requested a block: ';
 const WATCHDOG_FAILURE_PREFIX = '[ukit-stop-coordinator] task-watchdog evaluator failed (advisory lane, reported verbatim): ';
+const HANDOFF_PROVENANCE_PREFIX = '[ukit-stop-coordinator] handoff-cursor also requested a block: ';
+const HANDOFF_FAILURE_PREFIX = '[ukit-stop-coordinator] handoff-cursor evaluator failed (advisory lane, reported verbatim): ';
+
+// Handoff-cursor lane defaults. Both are overridable through
+// `.ukit/storage/config.json` → `handoff.fullstack.*`; any read/parse error fails
+// OPEN to these values — the lane is advisory and must never wedge a session.
+export const HANDOFF_CURSOR_DEFAULTS = Object.freeze({
+  enabled: true,
+  // A cursor that has not advanced across this many consecutive blocked stops is
+  // a run that can no longer make progress (wedged wave, dead dependency). The
+  // gate releases instead of trapping the session in an unstoppable loop — same
+  // liveness shape as the ledger's noProgressCount breaker.
+  maxStalledBlocks: 12,
+});
 
 // ─── Redaction ────────────────────────────────────────────────────────────
 /**
@@ -223,24 +247,33 @@ export function normalizeEvaluatorStdout(stdout) {
  *   advisory-lane failures travel in the single systemMessage) — one decision, no
  *   duplicate prompts.
  */
-export function coordinateStopDecisions({ completion = null, watchdog = null, failures = {} } = {}) {
+export function coordinateStopDecisions({ completion = null, watchdog = null, handoff = null, failures = {} } = {}) {
   const completionFailed = typeof failures?.completion === 'string' && failures.completion.length > 0;
   const watchdogFailed = typeof failures?.watchdog === 'string' && failures.watchdog.length > 0;
+  const handoffFailed = typeof failures?.handoff === 'string' && failures.handoff.length > 0;
   const watchdogFailureNote = watchdogFailed
     ? `${WATCHDOG_FAILURE_PREFIX}${failures.watchdog}`
     : null;
+  const handoffFailureNote = handoffFailed
+    ? `${HANDOFF_FAILURE_PREFIX}${failures.handoff}`
+    : null;
   const watchdogAdvisory = watchdog?.kind === 'advisory' ? watchdog.systemMessage : null;
+  const handoffAdvisory = handoff?.kind === 'advisory' ? handoff.systemMessage : null;
   const policies = [];
 
   // 1. The fail-closed blocker itself failed → block, redacted, detail on stderr only.
   if (completionFailed) {
     policies.push('completion-gate');
     let reason = redactInfrastructureReason();
+    if (handoff?.kind === 'block') {
+      policies.push('handoff-cursor');
+      reason += `\n${HANDOFF_PROVENANCE_PREFIX}${handoff.reason}`;
+    }
     if (watchdog?.kind === 'block') {
       policies.push('task-watchdog');
       reason += `\n${WATCHDOG_PROVENANCE_PREFIX}${watchdog.reason}`;
     }
-    const notes = [watchdogFailureNote, watchdogAdvisory].filter(Boolean);
+    const notes = [watchdogFailureNote, handoffFailureNote, watchdogAdvisory, handoffAdvisory].filter(Boolean);
     return {
       decision: 'block',
       reason,
@@ -254,11 +287,15 @@ export function coordinateStopDecisions({ completion = null, watchdog = null, fa
   if (completion?.kind === 'block') {
     policies.push('completion-gate');
     let reason = completion.reason;
+    if (handoff?.kind === 'block') {
+      policies.push('handoff-cursor');
+      reason += `\n${HANDOFF_PROVENANCE_PREFIX}${handoff.reason}`;
+    }
     if (watchdog?.kind === 'block') {
       policies.push('task-watchdog');
       reason += `\n${WATCHDOG_PROVENANCE_PREFIX}${watchdog.reason}`;
     }
-    const notes = [watchdogFailureNote, watchdogAdvisory].filter(Boolean);
+    const notes = [watchdogFailureNote, handoffFailureNote, watchdogAdvisory, handoffAdvisory].filter(Boolean);
     return {
       decision: 'block',
       reason,
@@ -268,11 +305,30 @@ export function coordinateStopDecisions({ completion = null, watchdog = null, fa
     };
   }
 
-  // 3. Watchdog block → watchdog owns this stop; completion advisory rides along.
+  // 3. Handoff-cursor block → an unfinished handoff-fullstack run owns this stop.
+  if (handoff?.kind === 'block') {
+    policies.push('handoff-cursor');
+    let reason = handoff.reason;
+    if (watchdog?.kind === 'block') {
+      policies.push('task-watchdog');
+      reason += `\n${WATCHDOG_PROVENANCE_PREFIX}${watchdog.reason}`;
+    }
+    const notes = [completion?.systemMessage, watchdogFailureNote, watchdogAdvisory].filter(Boolean);
+    return {
+      decision: 'block',
+      reason,
+      systemMessage: notes.length > 0 ? notes.join('\n') : undefined,
+      policyOwner: 'handoff-cursor',
+      policies,
+    };
+  }
+
+  // 4. Watchdog block → watchdog owns this stop; other advisories ride along.
   if (watchdog?.kind === 'block') {
     policies.push('task-watchdog');
     if (completion?.kind === 'advisory') policies.push('completion-gate');
-    const notes = [completion?.systemMessage, watchdogFailureNote].filter(Boolean);
+    if (handoff?.kind === 'advisory') policies.push('handoff-cursor');
+    const notes = [completion?.systemMessage, handoffAdvisory, watchdogFailureNote, handoffFailureNote].filter(Boolean);
     return {
       decision: 'block',
       reason: watchdog.reason,
@@ -282,10 +338,11 @@ export function coordinateStopDecisions({ completion = null, watchdog = null, fa
     };
   }
 
-  // 4. No block → merge advisories + verbatim failures into ONE systemMessage, or stay silent.
+  // 5. No block → merge advisories + verbatim failures into ONE systemMessage, or stay silent.
   if (completion?.kind === 'advisory') policies.push('completion-gate');
   if (watchdog?.kind === 'advisory') policies.push('task-watchdog');
-  const notes = [completion?.systemMessage, watchdogAdvisory, watchdogFailureNote].filter(Boolean);
+  if (handoff?.kind === 'advisory') policies.push('handoff-cursor');
+  const notes = [completion?.systemMessage, watchdogAdvisory, handoffAdvisory, watchdogFailureNote, handoffFailureNote].filter(Boolean);
   return {
     decision: null,
     reason: undefined,
@@ -359,6 +416,131 @@ export async function evaluateCompletionPolicy({ projectRoot, rawInput, budgetMs
   return normalizeEvaluatorStdout(stdout);
 }
 
+// ─── Handoff-cursor evaluator (in-process, advisory-on-failure) ───────────
+/**
+ * Read `.ukit/storage/config.json` → `handoff.fullstack.stopGate*` merged over
+ * HANDOFF_CURSOR_DEFAULTS. Any failure returns the defaults — a broken config
+ * must never silence the lane outright NOR wedge it; defaults keep both sane.
+ */
+async function loadHandoffGateConfig(projectRoot) {
+  try {
+    const parsed = JSON.parse(
+      await fs.readFile(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8'),
+    );
+    const gate = parsed?.handoff?.fullstack;
+    return {
+      enabled: typeof gate?.stopGateEnabled === 'boolean' ? gate.stopGateEnabled : HANDOFF_CURSOR_DEFAULTS.enabled,
+      maxStalledBlocks: Number.isFinite(gate?.stopGateMaxStalledBlocks)
+        ? Math.max(1, gate.stopGateMaxStalledBlocks)
+        : HANDOFF_CURSOR_DEFAULTS.maxStalledBlocks,
+    };
+  } catch {
+    return { ...HANDOFF_CURSOR_DEFAULTS };
+  }
+}
+
+function parseRunCursor(text) {
+  const field = (name) => (String(text).match(new RegExp(`^${name}:\\s*(.+)$`, 'm'))?.[1] || '').trim();
+  return {
+    command: field('Command'),
+    goal: field('Goal'),
+    phase: field('Phase'),
+    cursor: field('Cursor'),
+    next: field('Next'),
+  };
+}
+
+/**
+ * Mutate `.ukit/storage/cache/stop-coordinator/state.json`'s `handoff` slot:
+ * { signature, count }. Same signature as last time → count+1; a moved cursor
+ * resets the streak. Returns the committed streak count; a lock-timeout or any
+ * I/O failure returns null (fail-open — never decides the stop).
+ */
+async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs }) {
+  const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'stop-coordinator', 'state.json');
+  try {
+    const outcome = await withAsyncLock(statePath, { deadlineMs: lockBudgetMs }, async () => {
+      let current = {};
+      try {
+        current = JSON.parse(await fs.readFile(statePath, 'utf8')) || {};
+      } catch {}
+      const prev = current.handoff || {};
+      const count = prev.signature === signature ? (Number(prev.count) || 0) + 1 : 1;
+      await fs.mkdir(path.dirname(statePath), { recursive: true });
+      await fs.writeFile(
+        statePath,
+        `${JSON.stringify({ ...current, handoff: { signature, count } }, null, 1)}\n`,
+        'utf8',
+      );
+      return count;
+    });
+    return outcome.ok ? outcome.value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The handoff-cursor policy lane.
+ *
+ * BLOCKS the stop while `docs/AI_HANDOFF/RUN.md` reports an in-flight phase —
+ * the run's own `Next:` line is the continuation instruction, so a recap or a
+ * premature "done" reply gets bounced straight back into the pipeline. Releases
+ * when the cursor says `done` (or `blocked` — a genuinely stuck run is a
+ * legitimate final report), when RUN.md is absent/unreadable, or when the same
+ * un-advancing cursor has already bounced `maxStalledBlocks` stops in a row
+ * (liveness breaker — the gate must never be an unstoppable loop).
+ *
+ * Advisory lane: EVERY failure path returns { kind: 'none' }, never throws.
+ */
+export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS } = {}) {
+  const gate = await loadHandoffGateConfig(projectRoot);
+  if (!gate.enabled) return { kind: 'none' };
+
+  let text;
+  try {
+    text = await fs.readFile(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+  } catch {
+    return { kind: 'none' };
+  }
+  const { goal, phase, cursor, next } = parseRunCursor(text);
+  if (!phase || /^done\b/i.test(phase) || /^blocked\b/i.test(phase)) {
+    return { kind: 'none' };
+  }
+
+  const signature = `${phase}|${cursor}|${next}`;
+  const streak = await bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs });
+  if (streak !== null && streak > gate.maxStalledBlocks) {
+    return {
+      kind: 'advisory',
+      systemMessage:
+        `[ukit-stop-coordinator] handoff-cursor released this stop: the run cursor ` +
+        `("${signature}") has not advanced across ${streak - 1} consecutive blocked stops ` +
+        `(cap ${gate.maxStalledBlocks}), so the gate treats the run as stalled rather than ` +
+        `looping forever. Inspect docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md; ` +
+        `the run can be resumed with /ukit:handoff-fullstack or cleared with /ukit:handoff-clear.`,
+    };
+  }
+
+  const lines = [
+    'UKit handoff run in progress — this stop is refused. A handoff-fullstack cycle is still',
+    'in flight; a recap, wave summary, or "waiting" reply is NOT completion. The only valid',
+    'terminal outputs are "HANDOFF FULLSTACK COMPLETE" (all gates passed, cursor set to',
+    '`Phase: done`) or "HANDOFF FULLSTACK BLOCKED" (every remaining task externally blocked,',
+    'cursor set to `Phase: blocked`).',
+    '',
+    `  Goal:   ${goal || '(not recorded)'}`,
+    `  Phase:  ${phase}`,
+    `  Cursor: ${cursor || '(not recorded)'}`,
+    `  Next:   ${next || '(not recorded)'}`,
+    '',
+    'CONTINUE IMMEDIATELY: read docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md, execute',
+    'the `Next:` step exactly, rewrite the run cursor, and keep working until the completion',
+    'gate in .claude/commands/ukit/handoff-fullstack.md passes.',
+  ];
+  return { kind: 'block', reason: lines.join('\n') };
+}
+
 // ─── Once-per-stop guard ──────────────────────────────────────────────────
 /**
  * Lock-scoped dedupe: persist `{ lastStop: { key, ts } }` and report whether this
@@ -434,7 +616,15 @@ export async function runStopCoordinator({
     process.stderr.write(`[ukit-stop-coordinator] task-watchdog evaluator failed: ${failures.watchdog}\n`);
   }
 
-  return { skip: null, merged: coordinateStopDecisions({ completion, watchdog, failures }) };
+  let handoff = null;
+  try {
+    handoff = await evaluateHandoffCursor({ projectRoot, now, lockBudgetMs });
+  } catch (error) {
+    failures.handoff = error?.message || String(error);
+    process.stderr.write(`[ukit-stop-coordinator] handoff-cursor evaluator failed: ${failures.handoff}\n`);
+  }
+
+  return { skip: null, merged: coordinateStopDecisions({ completion, watchdog, handoff, failures }) };
 }
 
 // ─── CLI ──────────────────────────────────────────────────────────────────

package/templates/.omp/RULES.md

@@ -57,7 +57,15 @@ Prefer unique current-file anchors over line numbers or stale pasted blocks. Nev
 stale spec — re-read current source and confirm before applying. Preserve existing BOM and line
 endings.
 
-## 8. Never end a turn silently
+## 8. Handoff runs never park mid-cycle
+
+While `docs/AI_HANDOFF/RUN.md` `Phase:` is not `done`/`blocked`, a handoff-fullstack run is
+still in flight: a recap or checkpoint is progress output, never a stopping point. Continue
+the cursor's `Next:` step; only `HANDOFF FULLSTACK COMPLETE` or `HANDOFF FULLSTACK BLOCKED`
+ends the run. `handoff-clear` must close the cursor (`Phase: done` or delete) or the gate
+keeps the next session running too.
+
+## 9. Never end a turn silently
 
 Ending a turn with no output is a defect, not a pause. If you stop before the work is finished, the
 last thing you emit is one short line naming what is unfinished and what you need. Silence is never

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

@@ -126,17 +126,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/.omp/agents/feature-implementer.md

@@ -18,8 +18,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/.omp/agents/handoff-planner.md

@@ -54,6 +54,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`:
@@ -100,6 +129,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 |
@@ -159,6 +189,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
 ```
@@ -178,6 +209,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?
@@ -194,7 +227,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">
 ```
@@ -208,6 +241,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/.omp/hooks/pre/ukit-bridge.js

@@ -47,6 +47,7 @@ export const HOOK_EVENT_MAP = {
       'sensitive-data-guard.sh',
       'handoff-model-guard.sh',
       'context-hardcap-gate.sh',
+      'verification-guard.sh',
     ],
   },
   tool_result: {
@@ -102,6 +103,7 @@ export const FAIL_CLOSED_SCRIPTS = new Set([
 
 export const ADVISORY_SCRIPTS = new Set([
   'skill-router.sh',
+  'verification-guard.sh',
   'record-execution.sh',
   'auto-allow-bash.sh',
   'pre-edit-backup.sh',
@@ -331,17 +333,122 @@ export { translateExecResult };
 // 30s cap that silently disagreed with the runner whenever the env knobs were set.
 const chainExecTimeoutMs = resolveChainExecTimeoutMs;
 
-function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic) {
+// BUG-C21-09 (FR-006): hook-errors/ used to append one JSONL row per chain
+// transport error with no byte cap, no rotation, and no sweep — files grew per
+// session forever. Per-file cap mirrors hook-telemetry's <=512KB rotate; the
+// directory sweep is bounded (<= maxEntries stats, <= maxRemovals unlinks) and
+// sampled (~1/16 writes, UKIT_HOOK_ERRORS_SWEEP_PROBABILITY to force/disable).
+const HOOK_ERROR_MAX_BYTES = 512 * 1024;
+const HOOK_ERROR_SWEEP_PROBABILITY_DEFAULT = 1 / 16;
+const HOOK_ERROR_SWEEP_MAX_ENTRIES = 128;
+const HOOK_ERROR_SWEEP_MAX_REMOVALS = 64;
+const HOOK_ERROR_MAX_FILES = 200;
+const HOOK_ERROR_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+
+function hookErrorsDirFor(projectRoot) {
+  return path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-errors');
+}
+
+// Bounded work on THIS session's file only — identical keep-newest-half shape
+// as hook-telemetry's rotateIfNeeded.
+function rotateHookErrorFileIfNeeded(filePath, incomingBytes, maxBytes) {
+  let size = 0;
+  try {
+    size = fs.statSync(filePath).size;
+  } catch {
+    return; // first row for this session
+  }
+  if (size + incomingBytes <= maxBytes) return;
+  try {
+    const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+    if (lines.length && lines[lines.length - 1] === '') lines.pop();
+    const keepBudget = Math.floor(maxBytes / 2);
+    const keep = [];
+    let kept = 0;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const lineBytes = Buffer.byteLength(lines[i], 'utf8') + 1;
+      if (kept + lineBytes > keepBudget) break;
+      keep.unshift(lines[i]);
+      kept += lineBytes;
+    }
+    fs.writeFileSync(filePath, keep.length ? `${keep.join('\n')}\n` : '', 'utf8');
+  } catch {
+    // Rotation failed; drop this row rather than grow past the cap.
+  }
+}
+
+// sweepHookErrorsDir(dir, {now, maxAgeMs, maxFiles, maxEntries, maxRemovals}) ->
+//   { scanned, removed } — bounded: never scans or removes more than the caps,
+// so a pre-existing oversized dir is amortized down across sampled sweeps.
+function sweepHookErrorsDir(dir, {
+  now = Date.now,
+  maxAgeMs = HOOK_ERROR_MAX_AGE_MS,
+  maxFiles = HOOK_ERROR_MAX_FILES,
+  maxEntries = HOOK_ERROR_SWEEP_MAX_ENTRIES,
+  maxRemovals = HOOK_ERROR_SWEEP_MAX_REMOVALS,
+} = {}) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return { scanned: 0, removed: 0 };
+  }
+  const cutoff = now() - maxAgeMs;
+  const entries = [];
+  let scanned = 0;
+  for (const name of names) {
+    if (scanned >= maxEntries) break;
+    scanned += 1;
+    if (!name.endsWith('.jsonl')) continue;
+    try {
+      const stats = fs.statSync(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); // oldest first
+  // 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 {
+        fs.rmSync(path.join(dir, entry.name), { force: true });
+        removed += 1;
+      } catch { /* raced away — fine */ }
+    }
+  }
+  return { scanned, removed };
+}
+
+function hookErrorsSweepProbabilityFromEnv() {
+  const raw = Number(process.env.UKIT_HOOK_ERRORS_SWEEP_PROBABILITY);
+  if (!Number.isFinite(raw)) return HOOK_ERROR_SWEEP_PROBABILITY_DEFAULT;
+  return Math.min(1, Math.max(0, raw));
+}
+
+function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic, { maxBytes = HOOK_ERROR_MAX_BYTES } = {}) {
   try {
-    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-errors');
+    const dir = hookErrorsDirFor(projectRoot);
     fs.mkdirSync(dir, { recursive: true });
     const safeSession = String(sessionId || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
-    fs.appendFileSync(path.join(dir, `${safeSession}.jsonl`), `${JSON.stringify(diagnostic)}\n`, 'utf8');
+    const filePath = path.join(dir, `${safeSession}.jsonl`);
+    const line = `${JSON.stringify(diagnostic)}\n`;
+    rotateHookErrorFileIfNeeded(filePath, Buffer.byteLength(line, 'utf8'), maxBytes);
+    fs.appendFileSync(filePath, line, 'utf8');
+    // Sampled bounded dir sweep — amortizes down any pre-existing oversized dir.
+    if (Math.random() < hookErrorsSweepProbabilityFromEnv()) {
+      sweepHookErrorsDir(dir);
+    }
   } catch {
     // Diagnostics are advisory and must never block or throw.
   }
 }
 
+export { recordHookErrorDiagnostic, sweepHookErrorsDir };
+
 // Cached across the omp process lifetime: resolution below spawns a probe process, and every
 // tool call would otherwise pay that cost again.
 let cachedNodeExecutable = null;

package/templates/AGENTS.md

@@ -288,4 +288,18 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
 - No unrelated changes
 - Verification executed and reported
 - Docs updated when source truth changed
+
+
+## Handoff Fullstack Rules
+
+- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` nghĩa là run còn sống — Stop gate sẽ từ chối stop và trả về `Next:` step.
+- Recap/checkpoint không bao giờ là completion — chỉ `HANDOFF FULLSTACK COMPLETE` (sau khi `Phase: done`) hoặc `HANDOFF FULLSTACK BLOCKED` (sau khi `Phase: blocked`) mới kết thúc run.
+- Resume tự động mọi task chưa xong: current, legacy, pending, interrupted, recovery (`-R<n>` thay `cancelled_superseded`), và task mới được giao.
+- Handoff-create phải viết `docs/AI_HANDOFF/SPEC.md` chi tiết trước khi tạo task; task nào cũng mang `Spec references`.
+- Kết thúc cycle: docs sync → archive `docs/AI_HANDOFF/archive/cycle-NN/` → `Phase: done` → Final Report có marker.
+- `handoff-clear` bắt buộc đóng RUN.md (`Phase: done` hoặc xóa) — cursor sống sẽ giữ Stop gate chặn session sau.
+
+## Compact Instructions
+
+Khi compact giữa một handoff run: giữ lại goal, RUN.md path + phase hiện tại, task inventory, task đang làm, `Next:` step, blockers, verification evidence, commits, worktree/copy-back state, và quy tắc "compact không phải completion". Sau compact: đọc lại RUN.md + INDEX.md rồi chạy tiếp `Next:` ngay.
 {{codegraphSection}}

package/templates/CLAUDE.md

@@ -271,4 +271,18 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
 - No unrelated changes
 - Verification executed and reported
 - Docs updated when source truth changed
+
+
+## Handoff Fullstack Rules
+
+- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` nghĩa là run còn sống — Stop gate sẽ từ chối stop và trả về `Next:` step.
+- Recap/checkpoint không bao giờ là completion — chỉ `HANDOFF FULLSTACK COMPLETE` (sau khi `Phase: done`) hoặc `HANDOFF FULLSTACK BLOCKED` (sau khi `Phase: blocked`) mới kết thúc run.
+- Resume tự động mọi task chưa xong: current, legacy, pending, interrupted, recovery (`-R<n>` thay `cancelled_superseded`), và task mới được giao.
+- Handoff-create phải viết `docs/AI_HANDOFF/SPEC.md` chi tiết trước khi tạo task; task nào cũng mang `Spec references`.
+- Kết thúc cycle: docs sync → archive `docs/AI_HANDOFF/archive/cycle-NN/` → `Phase: done` → Final Report có marker.
+- `handoff-clear` bắt buộc đóng RUN.md (`Phase: done` hoặc xóa) — cursor sống sẽ giữ Stop gate chặn session sau.
+
+## Compact Instructions
+
+Khi compact giữa một handoff run: giữ lại goal, RUN.md path + phase hiện tại, task inventory, task đang làm, `Next:` step, blockers, verification evidence, commits, worktree/copy-back state, và quy tắc "compact không phải completion". Sau compact: đọc lại RUN.md + INDEX.md rồi chạy tiếp `Next:` ngay.
 {{codegraphSection}}