@ngockhoale/ukit 1.5.4 → 1.5.6

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to UKit are documented here.
 
+## 1.5.5 - 2026-05-30
+
+### Added
+
+- **Handoff Quality Gate** — opt-in, tool-agnostic, file-based, 4-phase pipeline (Idea+Plan → Create Tasks → Implement+Test → Review+Test) for tasks routed through `docs/AI_HANDOFF/`. Daily ad-hoc prompts are NOT affected and continue with the existing lightweight workflow.
+- New agent `templates/.claude/agents/code-reviewer.md`: independent reviewer with a model-isolation check. Refuses to review when `EXECUTOR_MODEL` equals reviewer's own model, when either is missing/unknown, or when re-run of Verification Commands fails. Emits a structured `## Reviewer Verdict` block.
+- New config block `handoff.*` in `templates/ukit/storage/config.json` with Vietnamese `_help` entries: `handoff.plan.requireTestPlan`, `handoff.executor.testFirstRequired`, `handoff.reviewer.model` (default `unic-smart`), `handoff.reviewer.blockOnCritical`, etc. The `*.modelHint` fields are explicitly documented as *labels for humans, not enforced selectors* — model enforcement happens via executor self-report + reviewer refusal.
+- New `## 4. Test Plan (REQUIRED — TDD-style)` section in `templates/docs/AI_HANDOFF/PLAN.md`.
+- New `templates/docs/AI_HANDOFF/tasks/_TEMPLATE.md`: every task file MUST embed its own `## Test Cases` (table with happy + ≥1 edge case + regression for bug fixes) + `## Test Files` + `## Verification Commands` + `## Acceptance Criteria`. Tasks without these are `needs_breakdown`, not `ready`.
+- `## Discussion` section pattern on task files: structured AI-to-AI comment thread (date · role · tool/model) so planner/executor/reviewer can talk back to each other through files — no out-of-band channels.
+- New task status states in `INDEX.md`: `pending_review`, `changes_requested`, `critical_block`, `approved`, `approved_minor`, plus Owner/Reviewer columns.
+
+### Changed
+
+- `templates/.claude/agents/feature-implementer.md`: now operates in two explicit modes. **Daily mode** (DEFAULT): unchanged lightweight flow — tests only when touched code has coverage, no reviewer trigger. **Handoff mode** (when task lives under `docs/AI_HANDOFF/tasks/`): test-first → green → reviewer; cannot claim `STATUS: DONE` without fresh PASS in turn. Report format now includes `EXECUTOR_TOOL`, `EXECUTOR_MODEL`, `EXECUTOR_SUBAGENT` self-report.
+- `templates/.claude/agents/bug-debugger.md`: same two-mode split. Handoff mode requires regression-test-first (RED before fix, GREEN after); Daily mode unchanged.
+- `templates/docs/AI_HANDOFF/RULES.md`: rewritten around the 4-phase model. Added `## Hard rule — All work stays in docs/AI_HANDOFF/` (no out-of-band AI communication). Added Phase 2 TDD-embedded requirement. Auto-compact 80-line rule scoped to state files (ACTIVE/INDEX/tasks); PLAN.md and RULES.md exempt.
+- `templates/CLAUDE.md` + `templates/AGENTS.md`: added scoped `## Handoff Quality Gate` section with explicit OPT-IN scope language so adapter targets (Claude Code, Kilo Code, Codex, OpenCode, future tools) only apply Quality Gate to handoff work, not daily prompts.
+
+### Fixed
+
+- Fixed output-history deduplication for `promptCache: false` — the second call with semantically equivalent (but noisy) output now returns the cached first summary instead of recomputing. Root cause: `normalizeOutputSummaryForDedupe` wasn't stripping `FAIL`/`PASS`/`Test Files`/`Tests`/`Duration`/`Start at` lines from the dedup key, so slight token-budget differences between two similar payloads produced different keys and broke cache hits. Added `findOutputHistoryEntry` lookup in `main()` to serve cached summaries without prompt-cache.
+
+### Why
+
+User had two real concerns: (1) cheap-model executors (e.g. Kilo Code) miss small things — fixed by mandatory test-first + independent reviewer with different model; (2) UKit cannot dictate which model any external tool uses — fixed by making the contract self-report-based (executor writes `EXECUTOR_MODEL`, reviewer compares and refuses on match/unknown). The Quality Gate is opt-in via the `docs/AI_HANDOFF/` folder so daily ad-hoc work is unaffected.
+
 ## 1.5.4 - 2026-05-28
 
 ### Fixed

package/package.json

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

package/src/cli/commands/diff.js

@@ -18,6 +18,7 @@ export async function runDiff({ packageRoot, projectRoot, packageVersion, argv =
   const toolsArg = parseToolsArg(argv);
   const selectedOptionalTools = resolveOptionalToolKeys(toolsArg);
   const selectedAdapterItemIds = toSelectedAdapterItemIds(selectedOptionalTools);
+  const withCodegraph = argv.includes('--with-codegraph');
 
   const pathConfig = buildPathConfig({ packageRoot, projectRoot });
 
@@ -26,6 +27,7 @@ export async function runDiff({ packageRoot, projectRoot, packageVersion, argv =
     pathConfig,
     dryRun: true,
     selectedAdapterItemIds,
+    withCodegraph,
   });
 
   console.log('[UKit] Diff preview:');

package/src/cli/commands/install.js

@@ -198,6 +198,7 @@ export async function pruneDeselectedAdapters({
 export async function runInstall({ packageRoot, projectRoot, packageVersion, argv = [] }) {
   const toolsArg = parseToolsArg(argv);
   const selectedOptionalTools = resolveOptionalToolKeys(toolsArg);
+  const withCodegraph = argv.includes('--with-codegraph');
 
   const pruneResult = await pruneDeselectedAdapters({
     projectRoot,
@@ -213,6 +214,7 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
     dryRun: false,
     selectedAdapterItemIds,
     retainedManagedRelativePaths: pruneResult?.retainedManagedPaths ?? [],
+    withCodegraph,
   });
 
   const { create, update, unchanged, skip } = result.summary;

package/src/cli/index.js

@@ -92,6 +92,10 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('                     Values: claude, antigravity, codex, opencode');
     console.log('                     Example: ukit install --tools=claude,codex,opencode');
     console.log('                     Use --tools=none to disable all optional adapters');
+    console.log('  --with-codegraph   Enable CodeGraph MCP integration in CLAUDE.md');
+    console.log('                     Adds routing rules that prefer codegraph_* tools for');
+    console.log('                     symbol search, context building, and impact analysis.');
+    console.log('                     Omit this flag to remove the section on reinstall.');
     console.log('');
     console.log('Maintainer / debug examples:');
     console.log('  ukit index build');

package/src/core/runInstallPipeline.js

@@ -217,6 +217,7 @@ export async function runInstallPipeline({
   dryRun,
   selectedAdapterItemIds,
   retainedManagedRelativePaths = [],
+  withCodegraph = false,
 }) {
   // Check for an existing install before making any changes.
   // cleanupLegacyPaths() is only safe to run on reinstalls: on a fresh install
@@ -239,6 +240,7 @@ export async function runInstallPipeline({
     stackContext,
     packageVersion,
     providerContext,
+    withCodegraph,
   });
 
   const plan = await buildInstallPlan({

package/src/render/buildVariables.js

@@ -1,4 +1,17 @@
-export function buildTemplateVariables({ projectContext, stackContext, packageVersion, providerContext }) {
+const CODEGRAPH_SECTION = `
+## CodeGraph Integration (active)
+
+CodeGraph MCP is enabled for this project. When \`codegraph_*\` tools appear in your tool list:
+- **Symbol search** → \`codegraph_search\` (replaces \`node .claude/ukit/index/query-index.mjs\`)
+- **Context building** → \`codegraph_context\` (replaces \`resolve-context.mjs\`)
+- **Impact analysis** → \`codegraph_impact\` (replaces \`impact-context.mjs\`)
+- **Call graph** → \`codegraph_trace\`, \`codegraph_callers\`, \`codegraph_callees\` (new capability, no UKit equivalent)
+
+UKit routing, memory, and skill activation remain primary. CodeGraph is the index query layer only.
+To disable: rerun \`ukit install\` without \`--with-codegraph\`.
+`;
+
+export function buildTemplateVariables({ projectContext, stackContext, packageVersion, providerContext, withCodegraph = false }) {
   return {
     project: {
       name: projectContext.project.name,
@@ -35,5 +48,6 @@ export function buildTemplateVariables({ projectContext, stackContext, packageVe
     user: {
       profile: 'default',
     },
+    codegraphSection: withCodegraph ? CODEGRAPH_SECTION : '',
   };
 }

package/templates/.claude/agents/bug-debugger.md

@@ -8,50 +8,79 @@ tools: ["Read", "Grep", "Glob", "Bash", "Edit", "TodoWrite"]
 
 Systematic debugging — understand before fixing.
 
+**Two modes:**
+- **Daily/ad-hoc** (DEFAULT): bug not coming from `docs/AI_HANDOFF/` → reproduce → fix → verify (no mandatory regression test if no pre-existing coverage; original lightweight flow).
+- **Handoff mode**: bug task lives in `docs/AI_HANDOFF/tasks/TASK-xxx.md` → activate Quality Gate: regression-test-first → green → reviewer.
+
 ## Workflow
 
 ### 1. Reproduce (required)
 
-- Run the failing command/action
-- Capture exact error message and stack trace
-- If not reproducible → document conditions and ask user
+- Run the failing command/action.
+- Capture exact error message and stack trace.
+- If not reproducible → document conditions and ask user.
 
 ### 2. Trace Root Cause
 
-- Read error location and surrounding code
-- Trace data flow: input → processing → failure point
-- Identify: is this a logic error, state error, or integration error?
+- Read error location and surrounding code.
+- Trace data flow: input → processing → failure point.
+- Identify: logic / state / integration error?
+
+### 3. Regression Test First (RED) — Handoff mode
+
+- Write a regression test that reproduces the bug as a failing test.
+- Run it: must FAIL with the original error/signature.
+- If you truly cannot write a regression test (pure UI glitch, env-only issue), document why and attach a manual repro script.
+- **Daily mode**: write a regression test only if the file already has tests; otherwise rely on the original repro command for verification.
 
-### 3. Fix
+### 4. Fix (GREEN)
 
-- Apply smallest reliable fix at the root cause
-- Do NOT patch symptoms — fix the cause
+- Apply smallest reliable fix at the root cause.
+- Do NOT patch symptoms — fix the cause.
+- Re-run the regression test: must PASS.
 
-### 4. Verify
+### 5. Verify
 
-- Re-run the original failing command → must pass
-- Run related tests: `yarn test [relevant-file]`
-- Check no regression in adjacent functionality
+- Re-run the original failing command → must pass.
+- Run related tests: `yarn test [relevant-file]`.
+- If shared code touched, run wider suite.
+- Check no regression in adjacent functionality.
 
-### 5. Report
+### 6. Report
 
 ```
 STATUS: DONE | BLOCKED | PARTIAL
+EXECUTOR_TOOL: [claude-code | kilo-code | codex | opencode | other]
+EXECUTOR_MODEL: [exact model name you are running as. "unknown" if you cannot tell.]
+EXECUTOR_SUBAGENT: [subagent name within your host, if any, else "-"]
 SUMMARY: [1-2 sentences — root cause and fix]
 ROOT_CAUSE: [what caused the bug]
+REGRESSION_TEST:
+  file: [path]
+  red_before: [exact error captured]
+  green_after: [pass output line]
 FILES_CHANGED:
   - [file path]: [what changed]
-VERIFIED: [original failing command now passes + test output]
+VERIFICATION:
+  command: [exact command]
+  result: [N pass / M fail / exit code]
 ISSUES: [any remaining risks or edge cases, or "none"]
-NEXT: [follow-up needed, or "nothing — bug fixed"]
+HANDOFF_TO_REVIEWER: yes | no — reason
+NEXT: [follow-up needed, or "ready for review"]
 ```
 
+### 7. Trigger Reviewer — Handoff mode ONLY
+
+Daily mode: skip. Handoff mode: set task status `pending_review` in `INDEX.md`; a reviewer session (model from `handoff.reviewer.model`, MUST differ from this debugger's model) will pick it up.
+
 ## Rules
 
-- Don't patch blindly — confirm root cause with evidence
+- **Iron law (Handoff mode):** no `DONE` without (a) regression test passing and (b) original failing command passing, both in this turn.
+- **Daily mode:** original — original failing command must pass; regression test optional unless prior coverage exists.
+- Don't patch blindly — confirm root cause with evidence.
 - For bug triage, use graduated doc budget:
   - obvious/simple bug: `docs/MEMORY.md` only
   - non-trivial bug: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
   - read `docs/WORKLOG.md` only recent relevant entries
-- Keep fix scope minimal — no drive-by refactors
-- If root cause is unclear after 5 minutes of tracing → ask user for more context
+- Keep fix scope minimal — no drive-by refactors.
+- If root cause is unclear after 5 minutes of tracing → ask user for more context.

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

@@ -0,0 +1,86 @@
+---
+name: code-reviewer
+description: "Independent reviewer for handoff Phase 3. Use after executor reports STATUS: DONE on a handoff task. MUST run with a model different from the executor (configured in .ukit/storage/config.json → handoff.reviewer.model, default unic-smart). Produces a verdict: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL."
+model: inherit
+color: yellow
+tools: ["Read", "Grep", "Glob", "Bash"]
+---
+
+You are the independent reviewer for UKit's handoff Quality Gate. Your model is configured in `.ukit/storage/config.json` → `handoff.reviewer.model` and MUST differ from the executor's model. If the host can bind a model from config, use it; otherwise note in the verdict which model you are running as.
+
+**Do not invent issues. Do not rubber-stamp.** Every finding must point at a specific file + line + concrete failure mode.
+
+## Inputs you expect
+
+- Path to task file: `docs/AI_HANDOFF/tasks/TASK-xxx.md` (has Test Plan §4 + Verification Commands + Executor Report at bottom).
+- The executor's `STATUS: DONE` report with FILES_CHANGED + VERIFICATION block.
+- The diff (use `git diff` or read FILES_CHANGED directly).
+
+If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete handoff package".
+
+## Review order
+
+1. **Test Plan adherence** — Were all tests in §4 actually implemented? Run them yourself: `<task Verification Commands>`. Fresh PASS required, no trusting executor's output blindly.
+2. **Correctness** — Does the diff implement the requested behavior? Any obvious wrong assumptions, stale refs, missing cases?
+3. **Regression risk** — What existing behavior could this break? Are shared paths/tests/contracts still aligned? Run the wider test suite if shared code was touched.
+4. **Safety / security / data loss** — Destructive actions, auth/permission, path handling, unsafe shell/DB/file ops.
+5. **Performance / scale** — Accidental N+1, repeated I/O, large scans inside hot paths.
+6. **Maintainability** — Duplicated logic, dead branches, misleading naming, drift between docs/tests/source.
+
+## Severity ladder
+
+- **CRITICAL** — security hole, data loss risk, broken core behavior, test was faked (no real assertion), or verification command does NOT actually pass when you re-run it. Blocks handoff cứng.
+- **CHANGES-REQUESTED** — Important issues: missing edge-case test, regression risk in shared code, wrong abstraction at scope boundary. Executor must fix and re-submit.
+- **APPROVED-WITH-MINOR** — Minor naming / doc / style issues. Logged on task file but handoff allowed.
+- **APPROVED** — Clean.
+
+## Output (append to task file as `## Reviewer Verdict`)
+
+```
+## Reviewer Verdict
+
+VERDICT: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL
+REVIEWER_MODEL: [model name actually used]
+EXECUTOR_MODEL: [from executor report]
+VERIFICATION_RERUN:
+  command: [exact command]
+  result: [N pass / M fail]
+TEST_PLAN_COVERAGE: [all-followed | partial — list gaps | missing — list]
+FINDINGS:
+  critical:
+    - file: <path:line> — <what fails, how>
+  important:
+    - file: <path:line> — <what risk, evidence>
+  minor:
+    - file: <path:line> — <what to clean up>
+NEXT_STATUS_FOR_INDEX: approved | approved_minor | changes_requested | critical_block
+NOTES: [1-2 sentences for human reviewer if needed]
+```
+
+After writing the verdict, update `docs/AI_HANDOFF/INDEX.md` row for this task: set Status = NEXT_STATUS_FOR_INDEX, set Reviewer = your model name.
+
+## Model isolation check (FIRST thing you do)
+
+UKit cannot force any tool to use a specific model. The contract is enforced HERE, by you, via self-report comparison.
+
+1. Read `EXECUTOR_MODEL` and `EXECUTOR_TOOL` and `EXECUTOR_SUBAGENT` from the Executor Report at the bottom of the task file.
+2. Identify your own model. Your model SHOULD match `handoff.reviewer.model` in `.ukit/storage/config.json`. State both in the verdict.
+3. Apply this table:
+
+| Executor model        | Your model            | Action                                                                                     |
+|-----------------------|-----------------------|--------------------------------------------------------------------------------------------|
+| named, != yours       | named                 | proceed with review                                                                        |
+| named, == yours       | named                 | REFUSE -> VERDICT = CHANGES-REQUESTED, reason "reviewer model must differ from executor"   |
+| "unknown"             | named                 | proceed but mark `NOTES: executor model unverified - human, please confirm before merge`   |
+| named                 | "unknown"             | REFUSE -> VERDICT = CHANGES-REQUESTED, reason "reviewer cannot verify own model"           |
+| missing field         | any                   | REFUSE -> VERDICT = CHANGES-REQUESTED, reason "executor did not self-report model - re-run with v1.5.5+ contract" |
+
+Same model is the most common silent failure. Do not skip this check.
+
+## Rules
+
+- **Always re-run** the task's Verification Commands. If they fail, VERDICT = CRITICAL regardless of executor claims.
+- If executor said `TEST_PLAN_FOLLOWED: N/A` without a real justification, downgrade to at minimum CHANGES-REQUESTED.
+- Never approve when test file has no real `expect`/`assert` - that is a fake test -> CRITICAL.
+- Keep the verdict block <= 30 lines. Findings are bullet points, not essays.
+- The same-model refusal above is non-negotiable: bypassing it defeats the entire Quality Gate.

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

@@ -8,48 +8,89 @@ tools: ["Read", "Edit", "Write", "Grep", "Glob", "Bash", "TodoWrite"]
 
 Implement requested behavior with minimal scope drift.
 
+**Two modes — auto-detect at start:**
+- **Daily/ad-hoc mode** (DEFAULT): task didn't come from `docs/AI_HANDOFF/` → use the original lightweight workflow. Tests only when touched code already has coverage. No reviewer trigger.
+- **Handoff mode**: task file is `docs/AI_HANDOFF/tasks/TASK-xxx.md` OR user explicitly invokes handoff (e.g. "execute task TASK-001") → activate full Quality Gate: test-first → green → reviewer.
+
+If unsure, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
+
 ## Workflow
 
 ### 1. Understand (< 30 seconds)
 
-- Infer intent directly from user request (build/test/docs flow)
+- Infer intent directly from user request (build/test/docs flow).
 - Apply graduated doc budget:
   - trivial: no docs
   - simple: `docs/MEMORY.md` only
   - non-trivial: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
-- Identify target files and existing patterns
-- If confidence is low or risk is high, ask one short clarifying question before deeper analysis
+- Identify target files and existing patterns.
+- If task came from handoff, read `tasks/TASK-xxx.md` and locate its **Test Plan** + **Verification Commands**.
+- If confidence is low or risk is high, ask one short clarifying question before deeper analysis.
 
 ### 2. Plan Approach (< 1 minute)
 
-- List files to create/modify (max diff)
-- Implement directly
+- List files to create/modify (max diff).
+- **Handoff mode only:** if no Test Plan exists in the task file and task is not `trivial`, write one inline before implementing (happy + ≥1 edge case; regression test if fixing a bug). In daily mode, skip this step.
+
+### 3. Test First (RED) — Handoff mode
+
+- Write the test(s) from §2 / from task Test Plan.
+- Run them: must FAIL for the expected reason. Capture output.
+- If test passes immediately → test is wrong or behavior already exists. Fix the test or stop and report.
+- **Daily mode**: skip this step unless touched code already has tests (then follow original rule).
 
-### 3. Implement
 
-- Smallest correct change set
-- Reuse existing code before creating new
-- No unrelated changes or speculative refactors
-- Follow project conventions (check `.claude/skills/` for patterns)
+### 4. Implement (GREEN)
 
-### 4. Verify
+- Smallest correct change set to make the test pass.
+- Reuse existing code before creating new.
+- No unrelated changes or speculative refactors.
+- Follow project conventions (check `.claude/skills/` for patterns).
 
-- Run existing tests if touched behavior has coverage: `yarn test` or project-specific
-- For SQL changes: verify with `EXPLAIN ANALYZE` on non-trivial queries
-- Check no lint errors introduced
+### 5. Verify (REQUIRED before DONE in Handoff mode; targeted in Daily mode)
 
-### 5. Report
+- **Handoff mode**: run the task's Verification Commands fresh in this turn. Capture full output. If ANY test fails → status is `PARTIAL` or `BLOCKED`, never `DONE`.
+- **Daily mode**: run existing tests if touched behavior has coverage; lint clean; targeted verification only.
+- For SQL changes: verify with `EXPLAIN ANALYZE` on non-trivial queries.
+- Check no lint errors introduced.
+
+### 6. Report
 
 ```
 STATUS: DONE | BLOCKED | PARTIAL
+EXECUTOR_TOOL: [claude-code | kilo-code | codex | opencode | other]
+EXECUTOR_MODEL: [exact model name you are running as — e.g. unic-code, claude-sonnet-4-5, gpt-5-mini. If you truly cannot tell, write "unknown" — reviewer treats unknown as suspicious and asks the human to confirm.]
+EXECUTOR_SUBAGENT: [name of the subagent you are, if your host has multiple — e.g. "Kilo:code", "Claude:feature-implementer". Otherwise "-".]
 SUMMARY: [1-2 sentences of what was implemented]
+TEST_PLAN_FOLLOWED: [task §4 / inline / N/A — reason]
 FILES_CHANGED:
   - [file path]: [what changed]
-VERIFIED: [test output / manual check result]
+TESTS_ADDED:
+  - [test file]: [test names]
+VERIFICATION:
+  command: [exact command run]
+  result: [N pass / M fail / exit code]
+  output_excerpt: |
+    [last 5-10 lines of test output]
 ISSUES: [any problems or edge cases, or "none"]
-NEXT: [follow-up needed, or "nothing — task complete"]
+HANDOFF_TO_REVIEWER: yes | no — reason
+NEXT: [follow-up needed, or "ready for review"]
 ```
 
+> **Self-report rule:** UKit cannot force any tool/host to use a specific model. Your self-reported `EXECUTOR_MODEL` is how the reviewer (in another tool or subagent) knows what to compare against its own model. Misreporting → reviewer refuses and asks the human to confirm.
+
+### 7. Trigger Reviewer — Handoff mode ONLY
+
+- Daily mode: skip this step entirely. Just report and stop.
+- Handoff mode + `STATUS: DONE` + `handoff.reviewer.enabled=true`:
+  - Set task status to `pending_review` in `docs/AI_HANDOFF/INDEX.md`.
+  - The next AI session (any tool, model from `handoff.reviewer.model`, MUST differ from executor) will pick `pending_review` task and run review.
+  - Do NOT dispatch reviewer in-process unless your host explicitly supports it AND can guarantee a different model — file-based handoff is the default.
+
 ## Rules
 
-- Add/update tests only when touched behavior already has coverage
+- **Iron law (Handoff mode):** no `DONE` without fresh PASS output in the current turn.
+- **Daily mode:** original rule — add tests only when touched behavior already has coverage.
+- If Handoff Test Plan says `N/A`, document why in the report and ensure manual verification ran.
+- Never silently skip reviewer phase in Handoff mode; if disabled, say so explicitly in NEXT.
+- Detection rule: if the task came from `docs/AI_HANDOFF/tasks/`, you are in Handoff mode. Otherwise Daily mode.

package/templates/.claude/ukit/runtime/output-compression.mjs

@@ -1082,7 +1082,11 @@ function normalizeOutputSummaryForDedupe(summary) {
   return String(summary ?? '')
     .split(/\r?\n/)
     .map((line) => String(line ?? '').trim())
-    .filter((line) => line && !/^- Full output:\s+/i.test(line))
+    .filter((line) => line
+      && !/^- Full output:\s+/i.test(line)
+      && !/^-\s*FAIL(?:ED)?\b/i.test(line)
+      && !/^-\s*PASS\b/i.test(line)
+      && !/^-\s*(?:Test Files|Tests|Duration|Start at)\b/i.test(line))
     .join('\n');
 }
 
@@ -1131,6 +1135,16 @@ async function appendOutputHistory(projectRoot, entry) {
   return nextDocument;
 }
 
+async function findOutputHistoryEntry(projectRoot, command, summary) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const current = normalizeOutputHistoryDocument(await readJson(runtimePaths.outputHistoryPath, { entries: [] }));
+  const lookupKey = [
+    String(command ?? '').trim(),
+    normalizeOutputSummaryForDedupe(summary),
+  ].join('\n').trim().toLowerCase();
+  return current.entries.find((candidate) => buildOutputHistoryDedupeKey(candidate) === lookupKey) ?? null;
+}
+
 function shouldCompress(config) {
   return Boolean(config?.tokenPipeline?.outputCompression);
 }
@@ -1244,6 +1258,28 @@ async function main() {
     exitCode,
     projectRoot,
   });
+
+  const historyMatch = await findOutputHistoryEntry(projectRoot, result.command, result.summary);
+  if (historyMatch?.summary) {
+    await appendOutputHistory(projectRoot, {
+      timestamp: Date.now(),
+      command: historyMatch.command,
+      profile: historyMatch.profile,
+      summary: historyMatch.summary,
+      tokensBefore: historyMatch.tokensBefore,
+      tokensAfter: historyMatch.tokensAfter,
+      savedTokens: historyMatch.savedTokens,
+      exitCode,
+      rawSaved: historyMatch.rawSaved,
+      rawPath: historyMatch.rawPath,
+      rawBytes: historyMatch.rawBytes,
+      recoveryReason: historyMatch.recoveryReason,
+      truncated: historyMatch.truncated,
+    });
+    process.stdout.write(String(historyMatch.summary));
+    return;
+  }
+
   const recoveryReason = buildRawOutputRecoveryReason({
     exitCode,
     tokensBefore: result.tokensBefore,

package/templates/AGENTS.md

@@ -83,6 +83,13 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - Threshold-based compact pressure is internal orchestration; do not expose it to users.
 - For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
 
+## Handoff Quality Gate — OPT-IN
+
+Activates ONLY when work goes through `docs/AI_HANDOFF/` (user says "execute task TASK-xxx" or target is `docs/AI_HANDOFF/tasks/*.md`). Daily prompts → unchanged lightweight flow, no test-first/reviewer overhead.
+
+In Handoff mode: read `docs/AI_HANDOFF/RULES.md` for the 4-phase spec (Idea+Plan → Create Tasks → Implement+Test → Review+Test), state machine, comment thread, and self-reported model contract. Config: `.ukit/storage/config.json` → `handoff.*`.
+
+
 ## Context + Verification Budget
 
 - **Trivial**: no docs, no index query unless the file target is unclear.

package/templates/CLAUDE.md

@@ -89,6 +89,13 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files.
 - Use `node .claude/ukit/index/safe-patch.mjs` internally when normal Edit/Write may normalize bytes or when anchor-based matching is needed.
 
+## Handoff Quality Gate — OPT-IN
+
+CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task TASK-xxx" hoặc target là `docs/AI_HANDOFF/tasks/*.md`). Daily prompt → KHÔNG đụng, flow cũ giữ nguyên.
+
+Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + comment thread + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
+
+
 ## Context + Verification Budget
 
 - **Trivial**: no docs.
@@ -158,3 +165,4 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
   - `.claude/skills/duraone/references/sql.md`
   - `.claude/skills/duraone/references/workflow.md`
 - Khi không active: dùng generic coding standards + project-specific patterns từ index.
+{{codegraphSection}}

package/templates/docs/AI_HANDOFF/INDEX.md

@@ -1,6 +1,13 @@
 # Handoff Task Index
 
-| ID | Title | Priority | Size | Status | File |
-|----|-------|----------|------|--------|------|
+<!--
+Status values (xem RULES.md §Status state machine):
+ready | in_progress | pending_review | changes_requested | critical_block | approved | approved_minor | blocked | done
+
+Owner = tool đang giữ task: claude-code | kilo-code | codex | opencode | -
+-->
+
+| ID | Title | Priority | Size | Status | Owner | Reviewer | File |
+|----|-------|----------|------|--------|-------|----------|------|
 
 Updated:

package/templates/docs/AI_HANDOFF/PLAN.md

@@ -2,4 +2,74 @@
 
 Status: `empty`
 
-<!-- AI ghi ý tưởng + phân tích ở đây. Sau khi tách thành tasks, clear phần dưới. -->
+<!--
+File này CHỈ dùng cho luồng Handoff Quality Gate.
+Daily prompt / quick fix → KHÔNG cần đụng vào đây, UKit vẫn chạy flow cũ bình thường.
+
+Chỉ kích hoạt khi user explicit đẩy việc qua handoff (ví dụ: "đưa vào handoff", "gom ý tưởng X").
+
+QUALITY GATE: mỗi task split ra phải kèm Test Plan (xem mục bên dưới).
+Không có Test Plan → task không được phép chuyển sang status `ready`.
+-->
+
+## 1. Intent / Goal
+
+<!-- 1-2 câu mô tả thứ user muốn đạt. Không paste lại nguyên prompt. -->
+
+## 2. Scope
+
+- In scope:
+- Out of scope:
+- Risk surface (file/module rủi ro share):
+
+## 3. Approach
+
+<!-- Cách làm ngắn gọn. Reuse code có sẵn trước khi tạo mới. -->
+
+## 4. Test Plan (REQUIRED — TDD-style)
+
+Liệt kê test sẽ viết TRƯỚC khi code. Mỗi test phải có:
+
+| # | Loại | Tên test | File | Expect | Pre-state |
+|---|------|----------|------|--------|-----------|
+| 1 | unit / integration / regression / e2e | `<tên test mô tả hành vi>` | `<path/to/file.test.js>` | `<output kỳ vọng cụ thể>` | `<input/fixture>` |
+
+Bắt buộc tối thiểu:
+
+- **Happy path**: hành vi chính chạy đúng.
+- **Edge case**: ít nhất 1 (null/empty/boundary/concurrent…).
+- **Regression** (nếu fix bug): test fail-trước-khi-fix, pass-sau-khi-fix.
+
+Nếu task không thể test (config-only, doc-only, prototype throw-away): ghi `Test plan: N/A — lý do: <…>` và đính kèm phương án verify thủ công.
+
+## 5. Verification Commands
+
+Lệnh chính xác executor sẽ chạy:
+
+```bash
+# ví dụ:
+# yarn test path/to/file.test.js
+# yarn test --run
+# node scripts/smoke.mjs
+```
+
+## 6. Acceptance Criteria
+
+- [ ] Tất cả test ở Test Plan PASS (kèm output trong report).
+- [ ] Không có regression ở suite liên quan.
+- [ ] Reviewer (model riêng) báo `APPROVED` hoặc `APPROVED-WITH-MINOR`.
+- [ ] Docs/CHANGELOG cập nhật nếu user-facing.
+
+## 7. Task Split (Phase 2 — TDD-embedded, MANDATORY)
+
+Khi human approve plan, AI tạo từng `tasks/TASK-xxx.md` theo cấu trúc ở `tasks/_TEMPLATE.md`.
+
+**Mỗi TASK file BẮT BUỘC có:**
+- `## Test Cases` — bảng test (loại, tên, expected, fixture) cho slice của task. Tối thiểu happy + 1 edge + regression nếu fix bug.
+- `## Test Files` — đường dẫn cụ thể file test sẽ tạo/sửa.
+- `## Verification Commands` — lệnh executor + reviewer đều chạy fresh.
+- `## Acceptance Criteria`.
+
+Task không kèm Test Cases + Test Files cụ thể → đánh `needs_breakdown`, không cho status `ready`.
+
+Update `INDEX.md`: thêm row cho mỗi task mới với `Status: ready`, `Owner: -`.

package/templates/docs/AI_HANDOFF/RULES.md

@@ -7,7 +7,7 @@
 - Do NOT read `RULES.md` every request — only when you need flow clarification.
 - Do NOT read multiple task files in one request.
 - If ACTIVE.md + INDEX.md + task file would exceed budget, read only the task file.
-- Auto-compact: if any single handoff file exceeds 80 lines, trigger `clear handoff` immediately.
+- Auto-compact: if any **state file** (`ACTIVE.md`, `INDEX.md`, or any single `tasks/TASK-xxx.md`) exceeds 80 lines, trigger `clear handoff` / split task. `PLAN.md` and `RULES.md` are reference/spec — exempt.
 
 ## How Human Submits Ideas
 
@@ -15,12 +15,90 @@
 - If request is already a concrete task (clear file/logic/output, small enough to do now), bypass handoff and execute directly.
 - If request is broad/ambiguous/multi-step, use handoff.
 
-## Handoff Flow
+## Hard rule — All work stays in `docs/AI_HANDOFF/`
 
-1. Human submits ideas → AI writes to `PLAN.md`.
-2. Human approves plan → AI splits into `tasks/TASK-xxx.md` + updates `INDEX.md`.
-3. AI implementer reads `INDEX.md` → picks task → reads `tasks/TASK-xxx.md` → implements.
-4. After implementation → update `INDEX.md` status, archive cycle if done.
+Mọi giao tiếp giữa các AI trong handoff CHỈ qua file dưới `docs/AI_HANDOFF/`:
+
+- `PLAN.md` — brainstorm + Test Plan tổng (Phase 1).
+- `INDEX.md` — bảng task + status (mọi phase đọc/ghi).
+- `tasks/TASK-xxx.md` — nơi sống của từng task: Goal + Test Cases + Verification + Executor Report + Reviewer Verdict + **Discussion thread**.
+- `ACTIVE.md` — snapshot cycle hiện tại.
+- `archive/` — cycle cũ.
+
+**Cấm**: AI gửi câu hỏi/comment qua chat tool khác, qua commit message, hay qua file ngoài thư mục này. Lý do: cross-tool/cross-subagent chỉ đồng bộ được qua file. AI nào không đọc folder này = không tham gia handoff.
+
+### Discussion thread (AI-to-AI comments)
+
+Khi cần hỏi-lại / push-back / gợi ý cho phase khác, AI ghi vào `## Discussion` của task file (template ở `tasks/_TEMPLATE.md`). Format:
+
+```
+### <YYYY-MM-DD> · <role: planner|executor|reviewer> · <tool/model>
+<nội dung — gửi @planner / @executor / @reviewer nếu có người nhận>
+```
+
+Phase kế tiếp PHẢI đọc Discussion trước khi tiếp tục — coi như inbox.
+
+## 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.
+
+3 phase × 3 role model:
+
+- **Plan** — model mạnh nhất anh có (reasoning model). Có thể chạy ở bất kỳ tool nào hỗ trợ planning tốt.
+- **Execute** — model rẻ-mà-vẫn-thông-minh (code model). Có thể là subagent code của Kilo, hay agent build của OpenCode, hay feature-implementer của Claude Code.
+- **Review** — **MODEL KHÁC executor** (reasoning model thường tốt hơn). Có thể là tool khác, hoặc cùng tool nhưng subagent khác model (ví dụ Kilo có subagent code và subagent review riêng).
+
+Hai mô hình triển khai đều hợp lệ:
+- **Cross-tool**: ví dụ Claude (plan) → Kilo (execute) → Claude (review). Bridge qua file.
+- **Same-tool different-subagent**: ví dụ Kilo:plan → Kilo:code → Kilo:review, miễn 3 subagent dùng MODEL khác nhau ở role tương ứng.
+
+Mỗi tool/subagent đọc cùng `INDEX.md` + `tasks/TASK-xxx.md` → chọn task theo `status` → cập nhật status khi xong.
+
+> **Quan trọng — UKit không enforce model:** `handoff.executor.cheapSmartModelHint` và `handoff.reviewer.model` trong `.ukit/storage/config.json` chỉ là **nhãn** để anh biết MUỐN dùng gì. Tool nào dùng model nào là do anh chọn trong settings của tool đó. UKit enforce contract bằng cách bắt executor TỰ KHAI `EXECUTOR_MODEL` trong Executor Report; reviewer so với chính nó và refuse nếu trùng. Vì vậy nếu trong Kilo anh để cả code-subagent và review-subagent đều dùng cùng model → reviewer sẽ tự refuse, không silent-pass.
+
+### Status state machine
+
+```
+brainstorm ──[plan approved]──▶ ready ──[executor pick]──▶ in_progress
+                                                              ├─[PASS]──▶ pending_review
+                                                              └─[FAIL]──▶ blocked
+pending_review ──[reviewer]──▶ approved | approved_minor ──▶ done
+                            ├▶ changes_requested ──[fix]──▶ in_progress
+                            └▶ critical_block      ──[fix]──▶ in_progress
+```
+
+### 4 Phases
+
+**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.
+
+**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`.
+- **Mỗi TASK file BẮT BUỘC có Test Plan của riêng nó**, không chỉ trỏ về PLAN.md. Cụ thể:
+  - `§ Test Cases`: bảng test (loại, tên test, expected) cho phần task này — happy + ≥1 edge case + regression (nếu fix bug).
+  - `§ Test Files`: đường dẫn cụ thể file test sẽ tạo/sửa (ví dụ `tests/auth/login.test.js`).
+  - `§ Verification Commands`: lệnh executor sẽ chạy để xác nhận PASS.
+  - `§ 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.
+- 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)
+- User: "execute next task" / "làm TASK-001" / "implement task 1".
+- Executor đọc `INDEX.md` → pick `ready` task → đổi `in_progress` → **viết test trước → RED → implement → GREEN** → chạy Verification Commands fresh trong turn → append `## Executor Report` (gồm `EXECUTOR_TOOL`/`EXECUTOR_MODEL`/`EXECUTOR_SUBAGENT` + verification output) vào cuối task file → đổi status `pending_review`.
+- KHÔNG được claim DONE nếu chưa có PASS fresh.
+
+**Phase 4 — Review + Test** (reviewer model — KHÁC model executor)
+- User: "review pending tasks" / "review TASK-001".
+- Reviewer đọc INDEX → pick `pending_review` → đọc task file + diff → **so model với `EXECUTOR_MODEL`, refuse nếu trùng/unknown** → **re-run Verification Commands fresh** (không tin executor) → áp `code-review` skill → append `## Reviewer Verdict` vào task file (verdict + findings + reviewer model dùng) → đổi status:
+  - `approved` / `approved_minor` → cho phép `done`.
+  - `changes_requested` → executor phải fix Important → lặp Phase 3-4.
+  - `critical_block` → executor PHẢI fix → lặp Phase 3-4.
+
+Nếu `handoff.reviewer.enabled=false`, Phase 4 skip nhưng phải log lý do vào task — bỏ Phase 4 là bỏ lưới an toàn cuối.
 
 ## Task Gate
 
@@ -28,11 +106,13 @@ A task is `ready` only when it has:
 - Clear target files
 - Clear action
 - Dependencies stated
-- Verification command
+- **Test Plan** (PLAN.md §4) — happy path + ≥1 edge case (+ regression test nếu fix bug); hoặc `N/A` kèm lý do
+- Verification command (lệnh executor sẽ chạy)
 - Acceptance criteria
 
 Missing any → `needs_breakdown`, `blocked`, or `needs_human`.
 
+
 ## Clear Handoff
 
 1. Archive current cycle → `archive/cycle-NNN.md`.

package/templates/docs/AI_HANDOFF/tasks/_TEMPLATE.md

@@ -0,0 +1,72 @@
+# TASK-XXX — <short title>
+
+<!--
+Template cho mỗi task. Planner copy file này khi split PLAN.md sang task riêng.
+File này BẮT BUỘC giữ structure: Goal + Test Cases + Test Files + Verification + Acceptance.
+Mọi AI (planner / executor / reviewer) đọc và ghi vào file NÀY. Không trao đổi ngoài file.
+-->
+
+- Status: `ready`  <!-- ready | in_progress | pending_review | changes_requested | critical_block | approved | approved_minor | blocked | done -->
+- Owner: `-`       <!-- tool đang giữ task -->
+- Reviewer: `-`    <!-- model name reviewer dùng, set ở Phase 4 -->
+- Parent plan: `docs/AI_HANDOFF/PLAN.md` §<section>
+
+## Goal
+
+<!-- 1-2 câu mô tả slice này làm gì. -->
+
+## Target Files
+
+- `<path/to/source.js>` — <what changes>
+
+## Test Cases (REQUIRED — TDD)
+
+| # | Loại | Tên test | Expected | Pre-state / Fixture |
+|---|------|----------|----------|---------------------|
+| 1 | unit | `<describe behavior>` | `<concrete expected>` | `<input>` |
+| 2 | edge | `<null/empty/boundary>` | `<expected>` | `<input>` |
+| 3 | regression (nếu bug fix) | `<reproduces bug>` | RED before fix, GREEN after | `<repro input>` |
+
+## Test Files
+
+- `<tests/path/to/file.test.js>` — chứa các test ở trên.
+
+## Verification Commands
+
+```bash
+yarn test tests/path/to/file.test.js
+```
+
+## Acceptance Criteria
+
+- [ ] Mọi test ở §Test Cases PASS.
+- [ ] Không regression ở suite liên quan.
+- [ ] Reviewer verdict APPROVED hoặc APPROVED-WITH-MINOR.
+- [ ] Docs/CHANGELOG cập nhật nếu user-facing.
+
+## Dependencies
+
+- (none) <!-- hoặc TASK-xxx phải done trước -->
+
+---
+
+## Discussion
+
+<!--
+AI nói chuyện với nhau Ở ĐÂY, không nói qua tool khác.
+Format mỗi comment:
+
+### <date> · <role: planner|executor|reviewer> · <tool/model>
+<nội dung — câu hỏi, lưu ý, đề xuất, đẩy ngược về phase trước>
+
+Reply lùn 1 level (####). Ghi rõ "→ @planner" / "→ @executor" / "→ @reviewer" nếu có người nhận cụ thể.
+-->
+
+(chưa có comment)
+
+---
+
+<!--
+Phase 3 executor append `## Executor Report` BÊN DƯỚI dấu phân cách này.
+Phase 4 reviewer append `## Reviewer Verdict` BÊN DƯỚI Executor Report.
+-->

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.5.4",
+  "version": "1.5.6",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",
@@ -156,6 +156,45 @@
     "deltaMaxHunks": 3,
     "deltaMaxDiffCells": 2000000
   },
+  "handoff": {
+    "enabled": true,
+    "crossTool": true,
+    "plan": {
+      "requireTestPlan": true,
+      "minTestsHappyPath": 1,
+      "minTestsEdgeCase": 1,
+      "regressionTestRequiredForBugfix": true,
+      "smartModelHint": "claude-opus-4-6"
+    },
+    "executor": {
+      "testFirstRequired": true,
+      "mustRunVerificationInTurn": true,
+      "blockDoneWithoutFreshPass": true,
+      "cheapSmartModelHint": "unic-code",
+      "appendReportToTaskFile": true
+    },
+    "reviewer": {
+      "enabled": true,
+      "model": "unic-smart",
+      "agent": "code-reviewer",
+      "mustDifferFromExecutor": true,
+      "blockOnCritical": true,
+      "blockOnChangesRequested": true,
+      "rerunVerificationCommands": true,
+      "appendVerdictToTaskFile": true
+    },
+    "statusFlow": [
+      "ready",
+      "in_progress",
+      "pending_review",
+      "changes_requested",
+      "critical_block",
+      "approved",
+      "approved_minor",
+      "blocked",
+      "done"
+    ]
+  },
   "subagents": {
     "enabled": true,
     "smallTaskModel": "unic-lite",
@@ -259,6 +298,30 @@
         "field": "compact.codexContext.autoCompact",
         "mac_dinh": true,
         "y_nghia": "Chỉ set false khi đang debug hành vi compact của UKit."
+      },
+      "doi_reviewer_model": {
+        "field": "handoff.reviewer.model",
+        "mac_dinh": "unic-smart",
+        "y_nghia": "Model dùng cho reviewer agent ở Phase 3. BẮT BUỘC khác model executor để bắt được lỗi mà executor miss. Có thể dùng claude-opus-4-6, unic-smart, hoặc bất kỳ model reasoning mạnh nào.",
+        "vi_du": "Nếu executor là unic-code (Kilo Code), set reviewer.model=unic-smart hoặc claude-opus-4-6. Nếu executor là claude-sonnet, set reviewer thành claude-opus."
+      },
+      "tat_reviewer_phase": {
+        "field": "handoff.reviewer.enabled",
+        "mac_dinh": true,
+        "y_nghia": "Tắt Phase 3 review nếu muốn chạy nhanh prototype. KHÔNG khuyến nghị cho code production — bỏ review là bỏ lưới an toàn cuối cùng.",
+        "khi_nao_tat": "Chỉ tắt cho throw-away prototype hoặc khi anh tự review thủ công."
+      },
+      "block_handoff_khi_critical": {
+        "field": "handoff.reviewer.blockOnCritical",
+        "mac_dinh": true,
+        "y_nghia": "Nếu reviewer báo CRITICAL → task không được phép done; executor phải fix và review lại. Set false chỉ khi muốn cảnh báo mềm.",
+        "khuyen_nghi": "Giữ true. Đây là rào chắn chống ship lỗi nghiêm trọng."
+      },
+      "bat_test_plan_bat_buoc": {
+        "field": "handoff.plan.requireTestPlan",
+        "mac_dinh": true,
+        "y_nghia": "Planner phải hoàn thành PLAN.md §4 (Test Plan) trước khi task chuyển ready. Tắt sẽ làm UKit cho phép skip TDD — kéo theo executor dễ làm sót.",
+        "khuyen_nghi": "Giữ true."
       }
     },
     "version": "Phiên bản config runtime đi kèm package UKit.",
@@ -374,6 +437,35 @@
       "deltaMaxChangedLines": "Ngân sách dòng đổi mặc định cho kiểm tra delta sau này.",
       "deltaMaxHunks": "Ngân sách hunk đổi mặc định cho kiểm tra delta sau này.",
       "deltaMaxDiffCells": "Giới hạn cell LCS khi tính delta; quá ngưỡng này UKit dùng fallback tuyến tính để tránh chậm trên file rất lớn."
+    },
+    "handoff": {
+      "enabled": "Bật Quality Gate cho handoff: plan có Test Plan, executor test-first, reviewer model khác. Tắt = quay về flow cũ (dễ lọt lỗi vặt).",
+      "crossTool": "true nghĩa là handoff truyền qua file (PLAN/INDEX/tasks) chứ không qua in-process subagent — cho phép plan ở Claude Code, execute ở Kilo Code, review ở Claude Code khác model.",
+      "plan": {
+        "requireTestPlan": "Bắt buộc PLAN.md §4 phải có Test Plan trước khi task chuyển ready.",
+        "minTestsHappyPath": "Tối thiểu test cho happy path.",
+        "minTestsEdgeCase": "Tối thiểu test cho edge case (null/empty/boundary/concurrent…).",
+        "regressionTestRequiredForBugfix": "Bug fix phải có regression test fail-trước-fix.",
+        "smartModelHint": "Gợi ý model mạnh nhất cho phase plan (ví dụ claude-opus-4-6). UKit không tự ép, chỉ ghi hint vào task."
+      },
+      "executor": {
+        "testFirstRequired": "Executor phải viết test trước khi implement (RED → GREEN).",
+        "mustRunVerificationInTurn": "Phải chạy Verification Commands trong cùng turn báo DONE; không tin output cũ.",
+        "blockDoneWithoutFreshPass": "Không cho phép STATUS:DONE nếu chưa có PASS fresh trong turn này.",
+        "cheapSmartModelHint": "Gợi ý model rẻ-mà-vẫn-thông-minh cho executor (ví dụ unic-code). UKit chỉ ghi hint.",
+        "appendReportToTaskFile": "Executor append `## Executor Report` vào cuối task file để reviewer (tool khác) đọc được."
+      },
+      "reviewer": {
+        "enabled": "Bật Phase 3 review độc lập. Tắt = bỏ lưới an toàn cuối cùng, không khuyến nghị.",
+        "model": "Model reviewer. BẮT BUỘC khác executor model. Mặc định unic-smart; có thể dùng claude-opus-4-6 hoặc bất kỳ model reasoning mạnh nào.",
+        "agent": "Tên reviewer agent (xem .claude/agents/code-reviewer.md).",
+        "mustDifferFromExecutor": "Nếu true, reviewer tự refuse khi phát hiện cùng model với executor.",
+        "blockOnCritical": "CRITICAL → block handoff cứng. Set false chỉ khi muốn warning mềm.",
+        "blockOnChangesRequested": "CHANGES-REQUESTED → block handoff đến khi fix. Set false sẽ cho phép done với issue Important.",
+        "rerunVerificationCommands": "Reviewer phải tự chạy lại Verification Commands, không tin output executor.",
+        "appendVerdictToTaskFile": "Reviewer append `## Reviewer Verdict` vào task file để khép vòng handoff."
+      },
+      "statusFlow": "Danh sách status hợp lệ trong INDEX.md. Đổi tên trong này = đổi state machine handoff."
     }
   }
 }