@ngockhoale/ukit 2.0.7 → 2.1.2

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

@@ -8,7 +8,26 @@
 $ARGUMENTS
 _Empty = all `pending_review` tasks. Or: "TASK-001" for a specific task._
 
-> **NO git commit. NO git push.** Reviewer only reads and reports. Human decides when to commit.
+> **The reviewer agents never commit.** The orchestrator does: it checkpoints each fix round
+> and, once the set is approved, pushes. Force-push stays denied.
+
+---
+
+## Autonomy Contract — read before anything else
+
+Review every `pending_review` task and drive the set to a decision in this one invocation.
+The human is not watching.
+
+**Ask nothing after the run starts.** Findings do not end the run — they start the auto-fix
+loop (Step 3). Escalate only for a blocker outside the repo, or a task still failing after
+both fix rounds, and even then finish everything else first.
+
+Never pause mid-review to ask for `/compact`. Reviewer agents return ≤6 lines and write the
+full verdict to disk; a compaction request belongs at the end of the command, never inside it.
+
+Maintain `docs/AI_HANDOFF/RUN.md` (`Command: handoff-review`, `Phase:`, `Cursor:`, `Next:`)
+after every step. If it already exists with `Phase:` not `done`, this is a **continuation**:
+jump to `Next:` instead of restarting, and do not ask whether to continue.
 
 ---
 
@@ -18,13 +37,16 @@ Read `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`.
 Read `docs/AI_HANDOFF/INDEX.md` → collect `pending_review` tasks (or specific task).
 If none → report and stop.
 
-Verify there are uncommitted changes from handoff-implement:
+`/ukit:handoff-implement` commits one commit per wave, so the changes under review are in
+commits since the plan commit, not only in the working tree. Resolve the review range once:
 ```bash
-git status           # should show modified/new files, no handoff branches/worktrees
-git diff --stat      # summary of all changes
+PLAN_COMMIT=$(git log --format=%H --grep='^handoff: plan' -n 1)
+git diff --stat $PLAN_COMMIT   # every handoff change: wave commits + working tree
+git status                     # no handoff branches/worktrees should remain
 ```
 
-If `git diff` is empty and `git status` is clean → handoff-implement was not completed. Stop and re-run it.
+If that diff is empty → handoff-implement was not completed. Report which tasks are still
+`ready` and stop; there is nothing to review yet.
 
 ## Step 2 — Review the diff
 
@@ -51,13 +73,14 @@ Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
 <each command from §Verification Commands across all tasks>
 ```
 
-If any command fails → verdict: `critical_block`. Stop.
+If any command fails → verdict: `critical_block` for this task. That ends **this task's**
+review, not the run — the orchestrator picks it up in Step 3's auto-fix loop.
 
 ### 2c — Review unified diff
 
 ```bash
-git diff             # all uncommitted changes vs $BASE
-git status           # overview of modified/new/deleted files
+git diff $PLAN_COMMIT   # every handoff change: wave commits + working tree
+git status              # overview of modified/new/deleted files
 ```
 
 Review as one unified diff — correctness, regression risk, security, edge cases, maintainability.
@@ -78,43 +101,89 @@ FINDINGS:
 NEXT_STATUS_FOR_INDEX: <status>
 ```
 
+Then return to the orchestrator **at most 6 lines** — the full verdict is already on disk:
+```
+TASK: TASK-xxx
+VERDICT: approved | approved_minor | changes_requested | critical_block
+REVIEWER_MODEL: <exact model ID>
+VERIFICATION_RERUN: PASS | FAIL
+BLOCKING: <one line per critical/important finding, or "none">
+```
+Do not paste the diff, the findings prose, or verification logs back into the orchestrator.
+
 ### 2e — Orchestrator updates INDEX.md
 
 Set `status = NEXT_STATUS_FOR_INDEX`. Orchestrator writes INDEX, not the reviewer.
 
-## Step 3 — After all tasks reviewed
-
-**All `approved` or `approved_minor`:**
-
-Update INDEX.md: all approved tasks → `done`.
-
-**DO NOT commit. DO NOT push.** Leave the working tree as-is for human review.
-
-Report:
-```
-✅ All tasks approved.
-Uncommitted changes are in the working tree — human commits when ready.
-  git diff --stat     ← review summary
-  git add . && git commit -m "..."   ← when ready
+## Step 3 — Auto-fix loop (max 2 rounds)
+
+Any task with `changes_requested` or `critical_block` enters this loop. **Do not report to
+the human and stop** — an unattended review that ends in a to-do list is what stretches a
+cycle across days.
+
+For round in 1..2:
+
+1. Collect every task not yet `approved`/`approved_minor`. If none, exit the loop.
+2. Group them into waves by `Dependencies`, auto-serializing any pair that shares a target
+   file. Spawn one `feature-implementer` per task **in parallel**, at most
+   `handoff.maxParallelAgents`, each in its own worktree. Each agent gets:
+   - the task file path — it reads its own `## Reviewer Verdict` from disk, so do not paste
+     findings into the prompt;
+   - the instruction: fix every `critical` and `important` finding, leave `minor` alone
+     unless trivially safe, keep existing tests green, add a regression test per critical
+     finding, re-run §Verification Commands, and append `## Executor Report (fix round <N>)`
+     to the task file;
+   - a ≤10-line return contract (`TASK` / `STATUS` / `EXECUTOR_MODEL` / `FILES` / `VERIFY` /
+     `NOTE`) — no pasted logs.
+3. Copy changes back, delete worktrees, then checkpoint:
+   ```bash
+   git add -A && git commit -m "handoff: fix round <N> — TASK-00x"
+   ```
+4. Re-review **only the tasks touched this round**, in parallel, per 2a–2e. The reviewer must
+   still differ from the executor model and still re-runs verification itself.
+5. Update `INDEX.md` and `RUN.md`. Exit when everything is approved.
+
+After round 2, a task still failing is genuinely stuck: leave it `blocked`, record why in its
+`## Discussion` thread, and name it in the report. **Every other task still proceeds to Step
+4** — one stubborn task must not hold the rest hostage.
+
+## Step 4 — Commit + push
+
+Update `INDEX.md`: approved tasks → `done`; still-failing tasks → `blocked`.
+
+Commit anything left uncommitted, then push once:
+```bash
+git add -A && git commit -m "handoff: review <goal>"   # skip if nothing left to commit
+git push origin $BASE
 ```
 
-**Any `changes_requested` or `critical_block`:**
+Push without asking — `git push` is in the settings `allow` list precisely so an unattended
+run never stalls at the last step. Force-push stays denied, so this can only fast-forward.
+
+If some tasks are `blocked`, still push: the approved work is reviewed, tested and
+committed, and the per-wave commits make any subset revertible.
 
-Report which files need fixes. Executor re-runs `/ukit:handoff-implement TASK-xxx`.
-Changes from the failed task remain in the working tree — executor fixes them in place (no new worktree needed for simple fixes).
+Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`.
 
-## Step 4 — Report
+## Step 5 — Report
 
 ```
 Review summary:
   TASK-001: approved
-  TASK-002: changes_requested — see §Discussion
-  Working tree: unchanged — human commits when satisfied
+  TASK-002: approved (fix round 1)
+  TASK-003: blocked — <one-line reason>
+Fix rounds used: <0|1|2>
+Git: <K> commits pushed to <BASE>
+Blocked (needs you): <TASK-xxx> | none
 ```
 
-**Next:**
-- All approved → human reviews `git diff` and commits manually.
-- Has fixes → executor re-runs `/ukit:handoff-implement TASK-xxx`
+Then, as the last line:
+
+> Cycle finished. Run `/compact` before starting the next cycle — this session carries the
+> whole review history and the next cycle deserves a clean window.
+
+This is the only place this command may ask for a compaction. All state lives in git,
+`INDEX.md` and `RUN.md`, so a compacted or fresh session resumes with nothing lost.
 
 > Orchestrator (this session) handles Step 1, 2e, and 3 directly — those are not delegated.
 > Other tools without subagent support: manually switch to the strong model, run 2a–2d per task (one session at a time).

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

@@ -16,6 +16,14 @@
 # just brick the session with no way out, since only the user (not the agent) can invoke
 # real compaction.
 #
+# Grace window (compact.hardCapGraceCalls, default 10): blocking the very first tool call
+# past the cap strands a handoff run mid-edit — files half-written, nothing committed, no
+# cursor — which is strictly worse than letting it land. When docs/AI_HANDOFF/RUN.md shows
+# an unfinished run, the gate therefore allows a BOUNDED number of further calls so the run
+# can commit, write its cursor and push; after that it blocks exactly as before. The budget
+# is per over-cap episode, not per wave: it only resets when the estimate actually drops
+# (i.e. a real compaction happened), so a run cannot mint itself fresh grace forever.
+#
 # Config toggle: compact.hardCapBlock (default true). Set to false only to debug this
 # gate itself; it must not become a normal escape hatch.
 
@@ -59,6 +67,22 @@ function readJsonSafe(filePath, fallback = null) {
   }
 }
 
+// An unfinished handoff run — same cursor file the resume hook and the advisory
+// context guard read. `Phase: done` (or no file) means there is nothing in flight.
+function readRunCursor() {
+  try {
+    const text = fs.readFileSync(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    const runPhase = (text.match(/^Phase:\s*(.+)$/m)?.[1] || '').trim();
+    if (!runPhase || /^done$/i.test(runPhase)) return null;
+    return {
+      phase: runPhase,
+      cursor: (text.match(/^Cursor:\s*(.+)$/m)?.[1] || '').trim(),
+    };
+  } catch {
+    return null;
+  }
+}
+
 (async () => {
   const config = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), {}) || {};
   if (config?.compact?.hardCapBlock === false) {
@@ -78,15 +102,58 @@ function readJsonSafe(filePath, fallback = null) {
   const state = mod.buildCompactPressureState(rawState, config);
   const thresholds = mod.buildCompactThresholds(config);
 
+  const gracePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hardcap-grace.json');
+
   if (state.estimatedTotalTokens < thresholds.hardCapTokens) {
+    // Back under the cap — the episode is over, so the next one starts with a full budget.
+    fs.rmSync(gracePath, { force: true });
     process.exit(0);
     return;
   }
 
+  const run = readRunCursor();
+  if (run) {
+    const graceCalls = Number.isFinite(config?.compact?.hardCapGraceCalls)
+      ? config.compact.hardCapGraceCalls
+      : 10;
+    const prior = readJsonSafe(gracePath, null);
+    // Reset only when the estimate actually fell since grace started: that is the signal a
+    // real compaction/shed happened. Advancing the cursor alone must NOT top the budget up,
+    // otherwise a long run gets unlimited grace and the ceiling stops meaning anything.
+    const carried =
+      prior && Number.isFinite(prior.startedAtTokens) && state.estimatedTotalTokens >= prior.startedAtTokens
+        ? prior
+        : { startedAtTokens: state.estimatedTotalTokens, used: 0 };
+
+    if (carried.used < graceCalls) {
+      const used = carried.used + 1;
+      try {
+        fs.mkdirSync(path.dirname(gracePath), { recursive: true });
+        fs.writeFileSync(gracePath, JSON.stringify({ ...carried, used }));
+      } catch {
+        // Losing the counter must not block the run; worst case grace restarts.
+      }
+      process.stderr.write(
+        [
+          `CONTEXT OVER CAP — grace ${used}/${graceCalls} (~${state.estimatedTotalTokens} tokens >= ${thresholds.hardCapTokens}).`,
+          `An unfinished run is in flight (Phase: ${run.phase}${run.cursor ? `, Cursor: ${run.cursor}` : ''}), so this call is allowed instead of stranding it mid-edit.`,
+          'Spend the remaining grace on LANDING, not on new work: finish the current edit, commit, update docs/AI_HANDOFF/RUN.md, push.',
+          'Do NOT start a new task, open new files, or spawn agents. When grace runs out the gate blocks hard.',
+          'After the user runs /compact, the SessionStart resume hook replays the cursor and the run continues automatically.',
+        ].join('\n') + '\n',
+      );
+      process.exit(0);
+      return;
+    }
+  }
+
   const lines = [
     `BLOCKED (context hard cap): estimated context ~${state.estimatedTotalTokens} tokens >= hard cap ${thresholds.hardCapTokens}.`,
     'This is an absolute ceiling (compact.hardCapTokens), separate from the soft/hard advisory phases — those were apparently not followed.',
     `Edit/Write/Bash refused (tool_name=${toolName}) until real compaction happens.`,
+    run
+      ? 'The unfinished-run grace window (compact.hardCapGraceCalls) is already exhausted — progress should be committed and the cursor written by now.'
+      : 'No unfinished run in docs/AI_HANDOFF/RUN.md, so there is no grace window to spend.',
     'Remedy (any one): run /compact, or start a new session (SessionStart resets the counter), or delete .ukit/storage/cache/compact-pressure.json.',
     'Do not work around this by summarizing inline and continuing, and do not reach for a non-gated write tool.',
   ];

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

@@ -164,6 +164,28 @@ const now = Date.now();
 const withinCooldown = guardState.lastPhase === phase
   && (now - Number(guardState.lastActionAt || 0)) < COOLDOWN_MS;
 
+// A one-shot pipeline (handoff-fullstack) is mid-flight when RUN.md exists with a phase
+// other than `done`. Telling the agent to stop and ask for /compact there is actively
+// harmful: the human is deliberately away, the pipeline has a disk cursor that makes it
+// resumable, and a mid-cycle halt is what used to strand a cycle for days. The right
+// directive during a run is "shed context at the next wave boundary and keep going" —
+// compaction is requested once, at the cycle boundary, by the command's Final Report.
+function readRunCursor() {
+  try {
+    const text = fs.readFileSync(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    const runPhase = (text.match(/^Phase:\s*(.+)$/m)?.[1] || '').trim();
+    if (!runPhase || /^done$/i.test(runPhase)) return null;
+    return {
+      phase: runPhase,
+      cursor: (text.match(/^Cursor:\s*(.+)$/m)?.[1] || '').trim(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+const run = readRunCursor();
+
 const lines_out = [];
 if (ratio >= 1) {
   lines_out.push(`UKIT CONTEXT ALERT — live context ~${estimatedTokens.toLocaleString()} tokens, at/over the ${hardCap.toLocaleString()} cap (${pct}%).`);
@@ -174,10 +196,21 @@ if (ratio >= 1) {
 
 if (withinCooldown) {
   lines_out.push('(Directive already issued this phase — act on it now if not already done; this is just a reminder.)');
+} else if (run) {
+  lines_out.push(`A handoff run is mid-flight (RUN.md — Phase: ${run.phase}${run.cursor ? `, Cursor: ${run.cursor}` : ''}). DO NOT stop, DO NOT ask the user to /compact, DO NOT re-scope the remaining work into a new cycle.`);
+  lines_out.push('ACTION THIS TURN — shed context, then keep going:');
+  lines_out.push('1) Finish the step in flight, then update docs/AI_HANDOFF/RUN.md so the cursor is current.');
+  lines_out.push('2) At the next wave boundary, collapse the finished wave to one line per task and stop re-reading task files, executor reports, and earlier diffs — that detail is already on disk.');
+  lines_out.push('3) Make sure spawned agents are returning their short summary form (<=10 lines), not pasted RED/verification logs. Pasted subagent logs are the usual cause of this warning.');
+  lines_out.push('4) Continue to the next wave/phase. The user is asked to /compact once, at the end of the cycle — not now.');
+  if (sidechainEntries > 0) {
+    lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch. Keep concurrency at or below handoff.maxParallelAgents and keep returns short; do not widen the batch while this warning stands.`);
+  }
+  writeGuardState({ lastPhase: phase, lastActionAt: now });
 } else {
   lines_out.push('ACTION THIS TURN, before starting new investigation/subagents/pipeline phases:');
   lines_out.push('1) Persist current progress now (update docs/STATUS.md, e.g. via the update-status skill) so nothing is lost.');
-  lines_out.push('2) If the remaining work still has multiple steps or pipeline phases left (e.g. a handoff-fullstack run with implement/review/deploy still ahead), split what remains into bounded docs/AI_HANDOFF tasks instead of continuing in this one thread — smaller phases keep each turn under the cap.');
+  lines_out.push('2) If the remaining work still has multiple steps or pipeline phases left, split what remains into bounded docs/AI_HANDOFF tasks instead of continuing in this one thread — smaller phases keep each turn under the cap.');
   lines_out.push('3) Otherwise, tell the user plainly: run /compact now, or wrap up and start a fresh session — work already committed/persisted to disk is not lost.');
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch — each teammate carries its own context window, and every finished report is injected back here, so running many at once is the fastest way to overflow this session. Avoid spawning more until context drops back under the cap.`);

package/templates/.claude/hooks/handoff-model-guard.sh

@@ -14,6 +14,18 @@
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 
+# Fast path — skip the node spawn (~70ms) when this hook provably has nothing to say.
+# The two branches below only ever act on (a) Edit/Write under docs/AI_HANDOFF/, or
+# (b) a Bash `git push`. If neither marker appears anywhere in the raw payload, the node
+# program is guaranteed to exit 0, so running it is pure latency — paid on EVERY Bash,
+# Edit and Write in every session and every parallel subagent, which is where a
+# many-agent pipeline quietly loses minutes.
+# Conservative by construction: a payload that merely mentions these strings still falls
+# through to the real check below. This can only skip work, never skip a block.
+if ! printf '%s' "$INPUT" | grep -qE 'AI_HANDOFF|git[[:space:]]+push'; then
+  exit 0
+fi
+
 INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE'
 const fs = require('fs');
 const path = require('path');

package/templates/.claude/hooks/handoff-resume.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# SessionStart hook: resume an interrupted handoff-fullstack run.
+#
+# Why this exists:
+#   A one-shot pipeline is only one-shot if an interruption is recoverable without the human
+#   retyping anything. Compaction, a crash, or closing the terminal all end the session while
+#   the cycle is still mid-flight. docs/AI_HANDOFF/RUN.md is the cursor the command writes
+#   after every step; this hook reads it back at session start and injects the continuation
+#   instruction, so the very next turn picks up where the run stopped.
+#
+#   Pairs with context-window-guard.sh, which stops telling the agent to halt for /compact
+#   while a run is active. Between them: never stop mid-cycle, and if the session ends anyway,
+#   resume automatically.
+#
+# Fires on every SessionStart source (startup / resume / clear / compact). `compact` is the
+# important one — that is the path the command's own Final Report tells the user to take
+# between cycles, and the path an over-full session takes mid-cycle.
+#
+# ADVISORY ONLY — always exit 0. A resume hint must never be able to block a session from
+# starting.
+
+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');
+
+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 runPath = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md');
+
+let text;
+try {
+  text = fs.readFileSync(runPath, 'utf8');
+} catch {
+  // No cursor file: nothing was running, or the last cycle was cleared. Stay silent —
+  // a resume banner on every ordinary session start would be pure noise.
+  process.exit(0);
+}
+
+const field = (name) => (text.match(new RegExp(`^${name}:\\s*(.+)$`, 'm'))?.[1] || '').trim();
+
+const phase = field('Phase');
+// `done` means the last cycle finished cleanly. Anything else means a step was in flight.
+if (!phase || /^done$/i.test(phase)) process.exit(0);
+
+const goal = field('Goal');
+const base = field('Base');
+const cursor = field('Cursor');
+const next = field('Next');
+const source = typeof payload.source === 'string' ? payload.source : 'startup';
+
+const out = [
+  'UKIT HANDOFF RESUME — an unfinished handoff-fullstack run was found on disk.',
+  `  Goal:   ${goal || '(not recorded)'}`,
+  `  Base:   ${base || '(not recorded)'}`,
+  `  Phase:  ${phase}`,
+  `  Cursor: ${cursor || '(not recorded)'}`,
+  `  Next:   ${next || '(not recorded)'}`,
+  '',
+  'This is a CONTINUATION, not a new cycle. Do not re-plan, do not overwrite PLAN.md or the',
+  'task files, and do not ask the user whether to continue — they already asked for a',
+  'one-shot run and the pipeline was interrupted, not cancelled.',
+  '',
+  'Read docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md, then execute the `Next:` step',
+  'above using .claude/commands/ukit/handoff-fullstack.md as the procedure. Skip tasks',
+  'already `done` or `pending_review`; pick up `ready`, `in_progress`, `changes_requested`',
+  'and `blocked` ones. Keep writing the cursor after every step.',
+];
+
+if (source === 'compact') {
+  out.push('');
+  out.push('The session was just compacted, so the window is clean — this is the ideal moment');
+  out.push('to continue. Resume immediately rather than reporting status and waiting.');
+}
+
+process.stdout.write(`${out.join('\n')}\n`);
+process.exit(0);
+NODE
+
+exit 0

package/templates/.claude/settings.json

@@ -26,10 +26,13 @@
       "Bash(git status:*)",
       "Bash(git diff:*)",
       "Bash(git log:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(git worktree:*)",
       "Bash(jq:*)"
     ],
     "ask": [
-      "Bash(git push:*)",
       "Bash(gh pr create:*)",
       "Bash(gh pr comment:*)",
       "Bash(gh issue comment:*)"
@@ -197,6 +200,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\"",
+            "timeout": 8
           }
         ]
       }

package/templates/docs/AI_HANDOFF/RULES.md

@@ -38,6 +38,55 @@ Khi cần hỏi-lại / push-back / gợi ý cho phase khác, AI ghi vào `## Di
 
 Phase kế tiếp PHẢI đọc Discussion trước khi tiếp tục — coi như inbox.
 
+## Autonomy Model — hỏi một lần, chạy tới hết
+
+Handoff được thiết kế để chạy **không cần người ngồi canh**. Config: `.ukit/storage/config.json` → `handoff.autonomy`.
+
+**Cửa sổ hỏi duy nhất là lúc plan.** `/ukit:handoff-create` (và bước P0 của `/ukit:handoff-fullstack`) gom mọi câu hỏi vào **một** lần `AskUserQuestion` rồi đóng cửa sổ. Câu trả lời ghi nguyên văn vào `PLAN.md §1` — các phase sau coi đó là lời của người dùng và không hỏi lại.
+
+Từ sau đó, mọi ngã ba đều có cách giải quyết tự động:
+
+| Tình huống | Xử lý tự động |
+|-----------|---------------|
+| Scope nhiều subsystem | tách module, plan module 1, queue phần còn lại vào `INDEX.md` |
+| Plan review còn `Issues Found` sau 2 vòng | planner áp findings rồi đi tiếp, ghi vào Plan Review Log |
+| 2 task cùng wave đụng 1 file | đẩy task sau xuống wave kế (thêm dependency) |
+| Working tree bẩn | commit checkpoint rồi chạy tiếp |
+| Reviewer trả `changes_requested`/`critical_block` | vào vòng auto-fix, tối đa 2 vòng |
+| Task vẫn fail sau 2 vòng fix | để `blocked`, **các task khác vẫn đi tiếp tới push** |
+
+Chỉ escalate cho người khi: blocker nằm ngoài repo (thiếu credential, service chết), hoặc task còn fail sau cả 2 vòng fix. Kể cả vậy vẫn phải làm xong mọi task khác trước rồi mới báo.
+
+**Quality gate không bị nới.** Bỏ chỗ *hỏi người*, không bỏ chỗ *kiểm tra*: TDD RED→GREEN vẫn bắt buộc, reviewer vẫn phải khác model executor, vẫn re-run Verification Commands, vẫn cấm claim DONE khi chưa có PASS tươi.
+
+### Run cursor — `RUN.md`
+
+Mỗi command ghi lại `docs/AI_HANDOFF/RUN.md` sau **mỗi bước**:
+
+```
+Command: <handoff-fullstack|handoff-implement|handoff-review>
+Goal: <1 câu>
+Base: <branch>
+Phase: <phase hiện tại | done>
+Cursor: wave <N> batch <M> — <vừa xong cái gì>
+Next: <bước kế tiếp chính xác>
+```
+
+`Phase:` khác `done` = có run đang dở. Command được gọi lại sẽ **chạy tiếp từ cursor**, không plan lại, không hỏi. Hook `SessionStart` (`handoff-resume.sh`) đọc file này và tự inject lệnh chạy tiếp — nên compact hay mất session giữa chừng đều không làm mất run.
+
+### Context: không bao giờ dừng giữa nhiệm vụ
+
+- Subagent ghi **full log vào task file trên đĩa**, chỉ trả về orchestrator ≤10 dòng (executor) / ≤6 dòng (reviewer). Paste log ngược lại orchestrator là nguyên nhân số 1 làm run chết vì hết context.
+- Hết mỗi wave: commit, ghi cursor, **collapse** wave đó còn 1 dòng/task trong bộ nhớ làm việc, rồi chạy tiếp.
+- Yêu cầu `/compact` **chỉ** được đặt ở cuối command, giữa 2 cycle. Giữa cycle thì tuyệt đối không — state đã nằm hết ở git + `INDEX.md` + `RUN.md` nên compact ở ranh giới cycle không mất gì.
+- Vượt `compact.hardCapTokens` (mặc định 160k) mà `RUN.md` còn run dở: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit đang dở, commit, ghi cursor, push. Không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
+- Không hook nào gọi được `/compact` — đó là lệnh client-only. Nên đường thoát duy nhất khi context đầy là: hạ cánh trong grace → user `/compact` → `handoff-resume.sh` replay cursor → chạy tiếp. Bật auto-compact trong `/config` của Claude Code để bước `/compact` tự xảy ra.
+
+### Git
+
+- `handoff-implement`: **1 commit / wave**, không push. Mỗi wave revert độc lập được.
+- `handoff-review` / `handoff-fullstack`: commit thêm mỗi vòng auto-fix, rồi **push 1 lần** ở cuối. Push không hỏi (`Bash(git push:*)` nằm trong `allow`); force-push vẫn bị `deny`.
+
 ## Handoff Flow (tool-agnostic, file-based state machine)
 
 UKit handoff hoạt động qua **file state**. Anh tự chọn tool nào cho từng phase — Claude Code / Kilo Code / Codex / OpenCode / tool mới sau này — đều được. UKit chỉ care về **role của model**, không care tool.
@@ -72,7 +121,8 @@ pending_review ──[reviewer]──▶ approved | approved_minor ──▶ don
 **Phase 1 — Idea + Plan** (smart/reasoning model)
 - Human submit ideas (natural language).
 - AI ghi vào `PLAN.md`: §1 Intent, §2 Scope, §3 Approach, **§4 Test Plan (bắt buộc TDD-style)**, §5 Verification Commands, §6 Acceptance Criteria.
-- Output: PLAN.md đầy đủ, chờ human approve.
+- Đây là **cửa sổ hỏi duy nhất** của cả pipeline: gom mọi câu hỏi vào 1 lần `AskUserQuestion` trước khi viết, ghi câu trả lời vào §1.
+- Output: PLAN.md đầy đủ + Planner Self-Audit. Chạy standalone (`/ukit:handoff-create`) thì dừng ở đây chờ human xem; chạy trong `/ukit:handoff-fullstack` thì đi thẳng tiếp sang Phase 2 — plan review độc lập là gate thay cho human.
 
 **Phase 2 — Create Tasks (TDD-embedded, MANDATORY)** (smart/reasoning model, thường cùng phase 1)
 - Human approve plan → AI split `PLAN.md §7` sang nhiều `tasks/TASK-xxx.md`.
@@ -83,7 +133,7 @@ pending_review ──[reviewer]──▶ approved | approved_minor ──▶ don
   - `§ Acceptance Criteria`: checklist.
 - Nếu split mà task nào không kèm được Test Cases + Test Files cụ thể → task đó chưa đủ `ready`, đánh `needs_breakdown`.
 - Update `INDEX.md`: thêm row mỗi task với status `ready`.
-- Đây là **điểm cắt human-approval**: phase này xong, executor được phép pick.
+- Đây là **điểm cắt cuối trước khi code chạy**: phase này xong, executor được phép pick. Trong `/ukit:handoff-fullstack`, gate ở đây là plan review độc lập (model mạnh, context riêng) chứ không phải human — vì người dùng đã chủ động chọn chạy one-shot.
 - Mục tiêu: executor (cheap-smart model) đọc task file là biết NGAY test gì cần viết trước, KHÔNG phải tự suy diễn.
 
 **Phase 3 — Implement + Test** (cheap-smart/code model)

package/templates/ukit/storage/config.json

@@ -11,6 +11,7 @@
     "tokenThreshold": 50000,
     "hardCapTokens": 160000,
     "hardCapBlock": true,
+    "hardCapGraceCalls": 10,
     "contextRotDetection": true,
     "askBeforeDrop": true,
     "codexContext": {
@@ -187,6 +188,18 @@
     "enabled": true,
     "crossTool": true,
     "maxParallelAgents": 10,
+    "autonomy": {
+      "askWindow": "plan-only",
+      "planReviewRounds": 2,
+      "autoFixRounds": 2,
+      "autoSerializeFileConflicts": true,
+      "resumeFromCursor": true,
+      "runCursorFile": "docs/AI_HANDOFF/RUN.md",
+      "commitPerWave": true,
+      "pushOnComplete": true,
+      "compactAtCycleBoundaryOnly": true,
+      "agentReturnMaxLines": 10
+    },
     "plan": {
       "requireTestPlan": true,
       "minTestsHappyPath": 1,
@@ -372,7 +385,8 @@
       "enabled": "Bật/tắt toàn bộ helper compact của UKit.",
       "tokenThreshold": "Ngưỡng token chung cho runtime compact dùng chung.",
       "hardCapTokens": "Ngưỡng cứng tuyệt đối (mặc định 160000 token ước lượng). Chạm/vượt ngưỡng này thì context coi như quá dài — không phải gợi ý nữa, là bắt buộc. PHẢI thấp hơn context window thật của model (200k), nếu không API sẽ báo lỗi vượt context trước khi gate kịp chặn.",
-      "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ệ.",
+      "hardCapBlock": "Nếu true, hook context-hardcap-gate chặn cứng Edit/Write/Bash (exit 2) khi vượt hardCapTokens, cho tới khi có compact thật (PreCompact) reset lại bộ đếm.",
+      "hardCapGraceCalls": "Số tool call được phép chạy tiếp sau khi vượt hardCapTokens KHI docs/AI_HANDOFF/RUN.md còn run dở (mặc định 10). Dùng để run kịp commit + ghi cursor + push rồi mới bị chặn, thay vì chết giữa lúc đang Edit. Hết grace là chặn cứng như cũ. Budget tính theo mỗi đợt vượt cap, chỉ reset khi ước lượng token thật sự giảm (có compact thật) — không reset theo wave.",
       "contextRotDetection": "Phát hiện context quá dài/dễ mục để giữ lại state quan trọng trước khi AI nhớ sai.",
       "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.",
       "agentContext": {