@ngockhoale/ukit 3.4.67 → 3.4.69

package/template_project/AGENTS.md

@@ -152,7 +152,11 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
 
 ## Handoff Fullstack Rules
 <!-- RULE: HAND-02 -->
-- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` = run còn sống — Stop gate từ chối stop, trả về `Next:`. Chỉ `HANDOFF FULLSTACK COMPLETE`/`BLOCKED` kết thúc run — recap/checkpoint không phải completion; resume chỉ tiếp tục frozen scope khi `Paused: no` và session thuộc ownership (resume marker hoặc `/ukit:handoff-fullstack` tường minh), không tự inject ở startup/clear mới. Kết thúc cycle: docs sync → archive completed-only `ARCHIVE/cycle-NN/` → `Phase: done`; `handoff-clear` khi còn việc mở đặt `Paused: yes` (giữ phase/scope/recovery, không mint completion, không xóa cursor). Full rules: `docs/AI_HANDOFF/RULES.md`.
+- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` = run còn sống — Stop gate từ chối stop, trả về `Next:`. Chỉ `HANDOFF FULLSTACK COMPLETE`/`BLOCKED` kết thúc run — recap/checkpoint không phải completion; resume chỉ tiếp tục frozen scope khi `Paused: no` và session thuộc ownership (resume marker hoặc `/ukit:handoff-fullstack` tường minh), không tự inject ở startup/clear mới. Kết thúc cycle: docs sync → archive completed-only `ARCHIVE/cycle-NN/` → `Phase: done`; `handoff-clear` khi còn việc mở đặt `Paused: yes` (giữ phase/scope/recovery, không mint completion, không xóa cursor). Full rules: `docs/AI_HANDOFF/RULES.md`. Trước khi stop: reconcile task/AC/findings/jobs/independent work/integration/release/consumer/pause/blocker; Stop gate chỉ là backstop. Turn wait ≠ run done; blocker chỉ release khi không còn READY independent work.
+
+## Handoff Planning Gates
+<!-- RULE: HAND-03 -->
+- Tasks born `needs_breakdown`; flip to `ready` only after the validator's `VERDICT: ok` recorded on disk (`node .claude/ukit/index/task-budget-validator.mjs --record <task.md>`) AND `PLAN_REVIEW: Approved` in PLAN.md — and `node .claude/ukit/index/ready-gate.mjs <root>` prints `READY_GATE: ok` before any flip. Owner documents: `node .claude/ukit/index/source-snapshot.mjs <original> docs/AI_HANDOFF/SOURCE.md` before planning reads them (`source snapshot MISSING` when it cannot run). Implementation lands via `node .claude/ukit/index/land-worktree.mjs` (receipt-backed); overwriting PLAN/SPEC/LEDGER needs an `amendments/rev-<NN>/` copy (`node .claude/ukit/index/amend-guard.mjs`). All bare single `node` commands — no `cd`, no `$()`, no compounds.
 
 ## Compact Instructions
 Compact giữa handoff run: giữ goal, RUN.md path + phase, task inventory + task đang làm, `Next:` step, blockers, verification evidence, commits, worktree/copy-back state, "compact không phải completion". Sau compact: đọc lại RUN.md + INDEX.md rồi chạy `Next:`.

package/template_project/CLAUDE.md

@@ -144,7 +144,7 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
 
 ## Handoff Fullstack Rules
 <!-- RULE: HAND-02 -->
-- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` = run còn sống — Stop gate từ chối stop, trả về `Next:`. Chỉ `HANDOFF FULLSTACK COMPLETE`/`BLOCKED` kết thúc run — recap/checkpoint không phải completion; resume chỉ tiếp tục frozen scope khi `Paused: no` và session thuộc ownership (resume marker hoặc `/ukit:handoff-fullstack` tường minh), không tự inject ở startup/clear mới. Kết thúc cycle: docs sync → archive completed-only `ARCHIVE/cycle-NN/` → `Phase: done`; `handoff-clear` khi còn việc mở đặt `Paused: yes` (giữ phase/scope/recovery, không mint completion, không xóa cursor). Full rules: `docs/AI_HANDOFF/RULES.md`.
+- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` = run còn sống — Stop gate từ chối stop, trả về `Next:`. Chỉ `HANDOFF FULLSTACK COMPLETE`/`BLOCKED` kết thúc run — recap/checkpoint không phải completion; resume chỉ tiếp tục frozen scope khi `Paused: no` và session thuộc ownership (resume marker hoặc `/ukit:handoff-fullstack` tường minh), không tự inject ở startup/clear mới. Kết thúc cycle: docs sync → archive completed-only `ARCHIVE/cycle-NN/` → `Phase: done`; `handoff-clear` khi còn việc mở đặt `Paused: yes` (giữ phase/scope/recovery, không mint completion, không xóa cursor). Full rules: `docs/AI_HANDOFF/RULES.md`. Trước khi stop: reconcile task/AC/findings/jobs/independent work/integration/release/consumer/pause/blocker; Stop gate chỉ là backstop. Turn wait ≠ run done; blocker chỉ release khi không còn READY independent work.
 
 ## Compact Instructions
 Compact giữa handoff run: giữ goal, RUN.md path + phase, task inventory + task đang làm, `Next:` step, blockers, verification evidence, commits, worktree/copy-back state, "compact không phải completion". Sau compact: đọc lại RUN.md + INDEX.md rồi chạy `Next:`.

package/template_project/docs/AI_HANDOFF/RULES.md

@@ -231,6 +231,14 @@ A task is `ready` only when it has:
 
 Missing any → `needs_breakdown`, `blocked`, or `needs_human`.
 
+**`ready` là verdict, không phải default:** planner viết task với `needs_breakdown`; task chỉ
+được chuyển `ready` khi CẢ hai gate đã pass — (1) `node .claude/ukit/index/task-budget-validator.mjs
+docs/AI_HANDOFF/tasks/TASK-xxx.md` (một lệnh đơn giản mỗi file, đường dẫn literal, không `cd`/loop/
+biến shell/pipe) in `VERDICT: ok` (hoặc dismissal được ghi trong `## Discussion`), và (2) plan review
+độc lập kết thúc `Approved`. Budget cạn / lệnh bị denial / gián đoạn trước khi đủ gate → task vẫn
+`needs_breakdown`, và `INDEX.md` + `ACTIVE.md` phải ghi rõ gate nào còn thiếu — executor chỉ bao giờ
+pick `ready`.
+
 
 ## Clear Handoff
 

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

@@ -6,7 +6,7 @@ File này BẮT BUỘC giữ structure: Goal + Test Cases + Test Files + Verific
 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 | cancelled_superseded -->
+- Status: `needs_breakdown`  <!-- ready | needs_breakdown | in_progress | pending_review | changes_requested | critical_block | approved | approved_minor | blocked | done | cancelled_superseded. A planner writes tasks `needs_breakdown`; they flip to `ready` only after the task-budget validator verdict is ok (or a documented dismissal) AND the independent plan review is Approved -->
 - Size: `M`        <!-- S | M | L — runtime budgets key off this field; defaults to M when missing -->
 - Owner: `-`       <!-- tool đang giữ task -->
 - Reviewer: `-`    <!-- model name reviewer dùng, set ở Phase 4 -->
@@ -91,6 +91,13 @@ Format mỗi comment:
 <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ể.
+
+Planner persist verdict NGAY khi nó tồn tại: ngay sau mỗi lượt chạy task-budget validator,
+append một dòng vào thread này — `### <date> · planner · Validator: ok <YYYY-MM-DD>`
+(hoặc `### <date> · planner · Validator: dismissed <YYYY-MM-DD> — <reason>`). Bước
+flip-to-ready (sau khi plan review `Approved`) đọc các dòng đã ghi trên disk này để quyết
+định — task không có dòng `Validator:` được ghi thì giữ `needs_breakdown`, dù session còn
+nhớ verdict cũ (compaction-safe).
 -->
 
 (chưa có comment)

package/template_project/instructions/core.md

@@ -141,7 +141,11 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
 
 ## Handoff Fullstack Rules
 <!-- RULE: HAND-02 -->
-- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` = run còn sống — Stop gate từ chối stop, trả về `Next:`. Chỉ `HANDOFF FULLSTACK COMPLETE`/`BLOCKED` kết thúc run — recap/checkpoint không phải completion; resume chỉ tiếp tục frozen scope khi `Paused: no` và session thuộc ownership (resume marker hoặc `/ukit:handoff-fullstack` tường minh), không tự inject ở startup/clear mới. Kết thúc cycle: docs sync → archive completed-only `ARCHIVE/cycle-NN/` → `Phase: done`; `handoff-clear` khi còn việc mở đặt `Paused: yes` (giữ phase/scope/recovery, không mint completion, không xóa cursor). Full rules: `docs/AI_HANDOFF/RULES.md`.
+- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` = run còn sống — Stop gate từ chối stop, trả về `Next:`. Chỉ `HANDOFF FULLSTACK COMPLETE`/`BLOCKED` kết thúc run — recap/checkpoint không phải completion; resume chỉ tiếp tục frozen scope khi `Paused: no` và session thuộc ownership (resume marker hoặc `/ukit:handoff-fullstack` tường minh), không tự inject ở startup/clear mới. Kết thúc cycle: docs sync → archive completed-only `ARCHIVE/cycle-NN/` → `Phase: done`; `handoff-clear` khi còn việc mở đặt `Paused: yes` (giữ phase/scope/recovery, không mint completion, không xóa cursor). Full rules: `docs/AI_HANDOFF/RULES.md`. Trước khi stop: reconcile task/AC/findings/jobs/independent work/integration/release/consumer/pause/blocker; Stop gate chỉ là backstop. Turn wait ≠ run done; blocker chỉ release khi không còn READY independent work.
+
+## Handoff Planning Gates
+<!-- RULE: HAND-03 -->
+- Tasks born `needs_breakdown`; flip to `ready` only after the validator's `VERDICT: ok` recorded on disk (`node .claude/ukit/index/task-budget-validator.mjs --record <task.md>`) AND `PLAN_REVIEW: Approved` in PLAN.md — and `node .claude/ukit/index/ready-gate.mjs <root>` prints `READY_GATE: ok` before any flip. Owner documents: `node .claude/ukit/index/source-snapshot.mjs <original> docs/AI_HANDOFF/SOURCE.md` before planning reads them (`source snapshot MISSING` when it cannot run). Implementation lands via `node .claude/ukit/index/land-worktree.mjs` (receipt-backed); overwriting PLAN/SPEC/LEDGER needs an `amendments/rev-<NN>/` copy (`node .claude/ukit/index/amend-guard.mjs`). All bare single `node` commands — no `cd`, no `$()`, no compounds.
 
 ## Compact Instructions
 Compact giữa handoff run: giữ goal, RUN.md path + phase, task inventory + task đang làm, `Next:` step, blockers, verification evidence, commits, worktree/copy-back state, "compact không phải completion". Sau compact: đọc lại RUN.md + INDEX.md rồi chạy `Next:`.

package/template_project/instructions/layout.yaml

@@ -69,6 +69,7 @@ outputs:
       - { from: core, heading: DuraOne Skill — Conditional Activation }
       - { from: core, heading: Completion Checklist }
       - { from: core, heading: Handoff Fullstack Rules }
+      - { from: core, heading: Handoff Planning Gates }
       - { from: core, heading: Compact Instructions }
     trailer: '{{codegraphSection}}'
   - target: template_project/.omp/RULES.md
@@ -143,5 +144,6 @@ outputs:
       - { from: core, heading: DuraOne Skill — Conditional Activation }
       - { from: core, heading: Completion Checklist }
       - { from: core, heading: Handoff Fullstack Rules }
+      - { from: core, heading: Handoff Planning Gates }
       - { from: core, heading: Compact Instructions }
     trailer: '{{codegraphSection}}'

package/template_project/instructions/overlays/omp-rules.md

@@ -9,8 +9,7 @@ nothing else is loaded. Keep this short: every line here is a per-turn tax.
 - **Non-trivial / risky** (auth, migration, shared runtime, data-loss, flaky) — index-first, then
   activate the matching skill, then verify.
 
-Pick the lane before the first tool call. Skipping this is what turns a direct chat into a
-scattershot one.
+Pick the lane before the first tool call — skipping this is what turns a direct chat into a scattershot one.
 
 ## 2. Execution Contract
 
@@ -30,9 +29,9 @@ files before widening further. These node scripts work unchanged under omp.
 
 ## 5. Auto-activate skills
 
-Skills live in `.claude/skills/` and omp reads them through its `claude` discovery provider — no
-mirror under `.omp/`. On any non-trivial task, and again after the first tool calls reveal what the
-work really is, read the matching `SKILL.md` without being asked. Users never name skills.
+Skills live in `.claude/skills/`, read by omp through its `claude` discovery provider — no mirror under
+`.omp/`. On any non-trivial task — and again after the first tool calls reveal the real work — read the
+matching `SKILL.md` without being asked. Users never name skills.
 
 ## 6. Delegate to bind a model tier
 
@@ -40,36 +39,37 @@ Your own model does not change mid-turn. A tier only applies when work is handed
 `.omp/agents/`, whose `model:` field (`@smol` / `@default` / `@slow` / `@vision`) resolves through
 `modelRoles` in `.omp/config.yml`.
 
-- `tiny-fix` → `@smol` · `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` →
-  `@default` · `review-release` → `@slow`
-- Images: `@vision` only. `@default`/`@slow` cannot see images on the UNIC gateway and must never
-  guess at their contents — hand every image to `ukit-vision-analyst` first.
+- `tiny-fix` → `@smol` · `local-fix`/`local-build`/`shared-edit`/`find-cause`/`map-impact` → `@default` · `review-release` → `@slow`
+- Images: `@vision` only — `@default`/`@slow` cannot see images on the UNIC gateway; hand every image to `ukit-vision-analyst` first.
 
 Doing everything inline is what makes UKit look like it only has one model. Keep direct execution
 for trivial/simple work; delegate when the tier differs or a noisy lane would flood this context.
 
 ## 7. Safe Patch
 
-Prefer unique current-file anchors over line numbers or stale pasted blocks. Never silently merge a
-stale spec — re-read current source and confirm before applying. Preserve existing BOM and line
-endings.
+Prefer unique current-file anchors over line numbers or stale pasted blocks; never silently merge a
+stale spec — re-read current source and confirm before applying. Preserve existing BOM and line endings.
 
 ## 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.
+ends the run; `handoff-clear` must close the cursor or the gate keeps the next session running.
+Before any stop, reconcile task/AC/findings/jobs/independent work/integration/release/consumer/
+pause/blocker; the Stop gate is the backstop; a turn wait is not run done; a blocker releases only
+with no READY independent work. Planning gates are mechanical, disk-read: `needs_breakdown`
+tasks flip `ready` only on a recorded validator `VERDICT: ok` + `PLAN_REVIEW: Approved`, with
+`node .claude/ukit/index/ready-gate.mjs docs/AI_HANDOFF` printing `READY_GATE: ok` before the
+flip; owner docs persist via `source-snapshot.mjs`, work lands via `land-worktree.mjs` — all bare
+single `node` commands.
 
 ## 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
-a status — the user cannot distinguish it from a crash.
-
-> Maintainer note, not a per-turn rule: `modelRoles` in `.omp/config.yml` ships UNIC gateway names.
-> On a non-UNIC provider, edit only the cost tiers `smol`/`default`/`slow` — never `vision`
-> (`unic-vision`) or `decision` (`unic-decision`, the LOCAL JEV/Lava typed-decision model —
-> `docs/pstack/UNIC_DECISION_GUIDE.md`); both are capability lanes. Aliases `lite`/`code`/`smart`
-> map smol↔lite, default↔code, slow↔smart — edit each alongside its tier.
+last line you emit names what is unfinished and what you need. Silence is never a status.
+
+> Maintainer note, not a per-turn rule: `modelRoles` ships UNIC gateway names; on a non-UNIC
+> provider edit only cost tiers `smol`/`default`/`slow` — never `vision` (`unic-vision`) or
+> `decision` (`unic-decision`, LOCAL JEV/Lava typed-decision — `docs/pstack/UNIC_DECISION_GUIDE.md`);
+> both capability lanes. Aliases lite/code/smart = smol/default/slow — edit alongside its tier.

package/template_project/ukit/storage/config.json

@@ -831,7 +831,7 @@
         "blockOnCritical": "CRITICAL \u2192 block handoff c\u1ee9ng. Set false ch\u1ec9 khi mu\u1ed1n warning m\u1ec1m.",
         "blockOnChangesRequested": "CHANGES-REQUESTED \u2192 block handoff \u0111\u1ebfn khi fix. Set false s\u1ebd cho ph\u00e9p done v\u1edbi issue Important.",
         "rerunVerificationCommands": "Reviewer ph\u1ea3i t\u1ef1 ch\u1ea1y l\u1ea1i Verification Commands, kh\u00f4ng tin output executor.",
-        "appendVerdictToTaskFile": "Reviewer append `## Reviewer Verdict` v\u00e0o task file \u0111\u1ec3 kh\u00e9p v\u00f2ng handoff."
+        "appendVerdictToTaskFile": "Persist the reviewer's complete `## Reviewer Verdict` in the task file: the read-only reviewer returns the block; the orchestrator appends it serially with Edit before aggregation/status updates. The legacy key names persistence, not reviewer write authority."
       },
       "statusFlow": "Danh s\u00e1ch status h\u1ee3p l\u1ec7 trong INDEX.md. \u0110\u1ed5i t\u00ean trong n\u00e0y = \u0111\u1ed5i state machine handoff.",
       "fullstack": {