@ngockhoale/ukit 3.4.64 → 3.4.66

package/template_project/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 **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.
+- If a state file exceeds the working context budget, read bounded sections and checkpoint/split work without discarding records. Context pressure never authorizes `clear handoff`, archive, or loss of requirements.
 
 ## How Human Submits Ideas
 
@@ -24,8 +24,9 @@ Mọi giao tiếp giữa các AI trong handoff CHỈ qua file dưới `docs/AI_H
 - `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.
-- `RUN.md` — run cursor của `/ukit:handoff-fullstack`; `Phase:` ≠ `done`/`blocked` khiến Stop gate từ chối stop → run tự chạy tiếp.
-- `archive/` — cycle cũ.
+- `RUN.md` — run cursor của `/ukit:handoff-fullstack`; `Phase:` ≠ `done`/`blocked` với `Paused: no` và session thuộc ownership khiến Stop gate từ chối stop → run tự chạy tiếp. `Paused: yes` giải phóng continuation (stop được phép) nhưng không mint completion.
+- `ARCHIVE/` — completed-only history; active scans exclude this and legacy lowercase `archive/`.
+- `SOURCE.md` / `NOTES.md` / `LEDGER.md` — durable owner source, classified decisions/rationale and requirement coverage; `queued/` holds preserved plans, not permission to execute them.
 
 **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.
 
@@ -51,13 +52,13 @@ 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 |
+| Plan review còn `Issues Found` sau 2 vòng | repair/replan rồi fresh independent escalation review; không tự Approved, affected tasks chưa ready |
 | 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 |
+| Working tree bẩn | KHÔNG blanket-commit và KHÔNG unstage/revert thay đổi không thuộc run. Chỉ commit checkpoint cho file thuộc scope đang chạy; file không liên quan giữ nguyên, ghi vào RUN/Discussion, 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** |
+| Task vẫn fail sau 2 vòng fix | đổi strategy, investigate/replan và tiếp tục independent tasks; local failure không phải external blocked |
 
-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.
+Chỉ cần user-only action khi thật sự thiếu quyền/credential, service/network ngoài repo không hoạt động, hoặc requirement conflict thật cần owner quyết định. Test/lint/review/plan failures đi vào FIX (bounded strategies), không giả external blocker; vẫn hoàn tất independent in-scope work trước khi 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.
 
@@ -74,7 +75,7 @@ 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.
+`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`) chỉ inject lệnh chạy tiếp khi `Phase:` ≠ `done`/`blocked`, `Paused: no` và session thuộc ownership (resume marker sau compact/resume, hoặc `/ukit:handoff-fullstack` tường minh). Session startup/clear mới chỉ nhận ghi chú, không bị inject. Compact giữa run không làm mất cursor vì RUN.md nằm trên đĩa.
 
 ### Context: không bao giờ dừng giữa nhiệm vụ
 
@@ -113,7 +114,7 @@ Mỗi tool/subagent đọc cùng `INDEX.md` + `tasks/TASK-xxx.md` → chọn tas
 ```
 brainstorm ──[plan approved]──▶ ready ──[executor pick]──▶ in_progress
                                                               ├─[PASS]──▶ pending_review
-                                                              └─[FAIL]──▶ blocked
+                                                              └─[FAIL]──▶ in_progress (fix/replan, tối đa 2 strategy; `blocked` chỉ cho external blocker hoặc requirement conflict cần owner)
 pending_review ──[reviewer]──▶ approved | approved_minor ──▶ done
                             ├▶ changes_requested ──[fix]──▶ in_progress
                             └▶ critical_block      ──[fix]──▶ in_progress
@@ -136,13 +137,11 @@ chạy **đến khi không còn gì để làm**:
 - Chỉ 2 output kết thúc hợp lệ: `HANDOFF FULLSTACK COMPLETE` hoặc
   `HANDOFF FULLSTACK BLOCKED`. Recap/checkpoint không phải điểm dừng — dùng form
   `CHECKPOINT — WORK CONTINUING` rồi làm tiếp ngay.
-- Phase 0 sweep gom mọi unfinished work: INDEX, task files, cycle cũ (HISTORY/archive),
-  `docs/TASKS.md` `Ready for AI`, blueprint ngủ đông trong `docs/AI_HANDOFF/queued/*/`,
-  uncommitted WIP.
-- Quiet-period: chỉ đóng run khi backlog rỗng + `handoff.fullstack.quietScansRequired`
-  (mặc định 2) scan liên tiếp không thấy việc mới.
-- Stop gate (Claude Code): `RUN.md` `Phase:` ≠ `done`/`blocked` → Stop hook từ chối
-  stop kèm `Next:` step. Breaker `stopGateMaxStalledBlocks` (mặc định 12) thả ra nếu
+- Phase 0 chỉ nhận unfinished work trong scope owner giao, ghi ScopePlans/ScopeQueue và Authorization vào RUN. Không tự nhập HISTORY/ARCHIVE, `docs/TASKS.md`, plan ngoài scope hay unrelated WIP. Late independent creates nằm ngoài frozen scope; repair/replan cần để hoàn tất scope vẫn tiếp tục.
+- Quiet-period: chỉ đóng run khi **frozen scope** (ScopePlans/ScopeQueue trong RUN) rỗng + `handoff.fullstack.quietScansRequired`
+  (mặc định 2) scan liên tiếp trong scope đó không thấy việc mới. Lịch sử HISTORY/ARCHIVE và backlog ngoài scope không nằm trong quiet scan.
+- Stop gate (Claude Code): `RUN.md` `Phase:` ≠ `done`/`blocked` với `Paused: no` và session thuộc ownership → Stop hook từ chối
+  stop kèm `Next:` step. `Paused: yes` cho phép stop (ghi lý do + recovery action), không phải completion. Breaker `stopGateMaxStalledBlocks` (mặc định 12) thả ra nếu
   cursor không nhích — lối thoát, không phải đường thường.
 - Gate theo session (`stopGateScope: session`, mặc định): chỉ ép session đã chạy `/ukit:handoff-fullstack`
   hoặc nhận resume marker (compact/resume). Session mới (startup/clear) chỉ nhận ghi chú, không bị ép;
@@ -163,15 +162,14 @@ chạy **đến khi không còn gì để làm**:
   `tasks/TASK-*.md` — kể cả khi mọi task canonical đang `ready` (luật "re-run allowed" không áp dụng).
   Thay vào đó ghi plan mới vào **queued path** `docs/AI_HANDOFF/queued/<slug>/` (SPEC/PLAN/INDEX/HANDOFF
   + tasks/) như một blueprint ngủ đông, rồi báo đường dẫn. Chỉ khi human **tường minh** ra lệnh bỏ run
-  (`/ukit:handoff-clear` → `Phase: done`/xóa RUN.md) mới được plan thẳng vào canonical. Executor không
+  mới được thay scope; `/ukit:handoff-clear` chỉ pause và giữ unfinished records, không cấp quyền ghi đè canonical. Executor không
   bao giờ được kích hoạt ở phase này; planner chỉ ghi dưới đúng một output root được chỉ định.
 - **Không drop việc đã queue**: `/ukit:handoff-fullstack` P2 sweep các blueprint `queued/*/` — cycle mới
   kéo chúng vào `tasks/TASK-xxx.md` như mọi việc khác, hoặc ghi rõ lý do out-of-scope trong `PLAN.md §1/§2`.
   Resume (RUN.md đang sống) giữ nguyên blueprint cho cycle sau, không ghi đè.
-- `handoff-clear` PHẢI đặt `Phase: done` (hoặc xóa RUN.md) — cursor sống sẽ giữ gate
-  chặn stop của session sau.
+- `handoff-clear` khi còn việc mở đặt `Paused: yes`, giữ actual phase/scope và recovery action; pause giải phóng continuation nhưng không mint completion.
 - Phase F: docs sync (WORKLOG luôn; PROJECT/CODE_MAP/CHANGELOG khi đổi surface) →
-  archive cycle vào `archive/cycle-NN/` (khi `autoArchive=true`) → `Phase: done` →
+  chỉ archive completed cycle vào `ARCHIVE/cycle-NN/` (khi `autoArchive=true`, không còn review/integration/release debt) → `Phase: done` →
   Final Report với marker.
 
 ### 4 Phases
@@ -236,13 +234,12 @@ Missing any → `needs_breakdown`, `blocked`, or `needs_human`.
 
 ## Clear Handoff
 
-1. Archive current cycle → `archive/cycle-NNN.md` hoặc `archive/cycle-NN/` (gồm PLAN + SPEC + task files).
-2. If archive > 3 entries → delete oldest, append 1-line summary to `HISTORY.md`.
-3. Reset `ACTIVE.md` to empty template.
-4. Clear `INDEX.md`.
-5. Delete all files in `tasks/` (keep `_TEMPLATE.md`).
-6. Clear `PLAN.md`; restore `SPEC.md` về template.
-7. **`RUN.md` → `Phase: done` hoặc xóa** — bắt buộc, không thì Stop gate chặn session sau.
+1. Clear là pause/cancel, không phải completion. Giữ nguyên unfinished work, source, decisions và evidence dưới `docs/AI_HANDOFF/`.
+2. Khi còn pending/blocked/pending-review/pending-release hoặc integration chưa pass: giữ INDEX/tasks/PLAN/SPEC/LEDGER, đặt `Paused: yes` trong RUN và ghi lý do + next recovery action. Không giả `Phase: done` hay xóa cursor.
+3. Chỉ cycle hoàn tất có independent review + verification + delivery evidence mới vào `ARCHIVE/cycle-NN/`. Move task records trước, chạy `archive-cycle` snapshot trước khi reset INDEX; kiểm tra snapshot và giữ đầy đủ source/requirements/reviews.
+4. Không prune/delete lịch sử. Legacy `archive/` và `cycle-NNN.md` chỉ là provenance read-only; không tự chạy lại hay coi summary là completion proof.
+5. Chỉ reset active templates sau khi completed archive được kiểm chứng; giữ mọi queued plan, amendment và record chưa nằm trong archive đó. Cleanup worktree dùng receipt gate, không force-remove.
+6. Không unstage/revert unrelated owner changes. Verify mỗi state-file write trước khi báo kết quả.
 
 ## Docs Sync
 

package/template_project/docs/AI_HANDOFF/queued/README.md

@@ -0,0 +1,52 @@
+# docs/AI_HANDOFF/queued/ — queued blueprints
+
+A queued blueprint is a plan written while a live run owns the canonical lane, or a plan
+whose tasks exceed the 10-task active threshold. It is a draft: it carries no runnable
+admission until `/ukit:handoff-fullstack` folds it into the canonical lane.
+
+```
+queued/<slug>/
+├── SPEC.md      — spec of record for this blueprint
+├── PLAN.md      — plan with §1-§6 and the Planner Report footer
+├── INDEX.md     — draft index: rows are status=queued_blueprint, never ready
+├── HANDOFF.md   — activation notes (what it depends on, when to start) + queue header
+└── tasks/       — TASK-<id>.md blueprints, Status: queued_blueprint
+```
+
+`queued_blueprint` marks a spec-of-record, never a runnable task. The queued `INDEX.md` and
+`tasks/` are not canonical admission; the canonical `docs/AI_HANDOFF/INDEX.md` and
+`tasks/` are the only runnable lane.
+
+## Mandatory overflow (consumable)
+
+When `/ukit:handoff-create` plans more than 10 tasks, the overflow of `feasible`/`adapted`
+LEDGER rows is queued here WITHOUT any `QueueIntent` / `Queue*` header line. It is consumable
+work: `/ukit:handoff-fullstack` folds it into the cycle like any legacy blueprint.
+
+## Deliberate-future queue (backlog)
+
+A blueprint that is planned work for a LATER cycle — `deferred` LEDGER rows only — carries
+these header lines at the top of its `HANDOFF.md`:
+
+```
+QueueIntent: deliberate-future
+QueueOrder: <int>              # drain order, lowest first
+QueueDrain: separate-backlog
+QueueSource: <R-IDs/epics>     # ledger rows / epics this blueprint covers
+```
+
+Semantics:
+
+- `/ukit:handoff-fullstack` does **not** fold these blueprints into the current cycle.
+  It reports each one as `Backlog: <slug>` and leaves it untouched; Backlog items never
+  count toward `index:all-done` / `ExitPredicate`.
+- An explicit slug in the invocation overrides this: the named blueprint is drained,
+  one blueprint per invocation.
+- No new INDEX status exists for this. The metadata lives in the blueprint header only;
+  the status vocabulary in `RULES.md` is unchanged.
+- Blueprints WITHOUT `QueueIntent` keep the legacy fold-in behaviour.
+
+## Naming
+
+Use a unique `<slug>`. If `queued/<slug>/` already exists, append `-2`, `-3`, … and never
+overwrite an existing blueprint.

package/template_project/instructions/core.md

@@ -107,7 +107,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
 <!-- RULE: UNATTENDED-02 -->
 - `maxAttemptsPerFailure: 2`, `maxRecoveryStrategies: 2` distinct fix strategies before reassessing — retry the same edit, then fix the cause differently; never loop one strategy.
 <!-- RULE: UNATTENDED-03 -->
-- BLOCKED only on true external blockers: missing credentials, dead service, unreachable network/API. Test failures, lint errors, review findings, ambiguity are NOT blockers — feed FIX.
+- BLOCKED only on true external blockers: missing credentials/permissions, dead service, unreachable network/API, or a genuine requirement conflict that needs an owner decision. Test failures, lint errors, review findings, plan findings, ambiguity within scope are NOT blockers — feed FIX (bounded strategies, then investigate/replan) and continue independent scope tasks.
 <!-- RULE: UNATTENDED-04 -->
 - A deny (hook/gate/permission) never becomes a question: pick the next safer alternative satisfying the intent, record the substitution. Never emit "do you want me to…" — decide and proceed.
 
@@ -141,7 +141,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 tự động mọi task chưa xong. Kết thúc cycle: docs sync → archive `archive/cycle-NN/` → `Phase: done`; `handoff-clear` bắt buộc đóng RUN.md. 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`.
 
 ## 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:`.