@ngockhoale/ukit 3.4.66 → 3.4.68

package/template_project/.claude/commands/ukit/handoff-create.md

@@ -19,8 +19,12 @@ $ARGUMENTS
 `/ukit:handoff-create` produces **SPEC.md, PLAN.md, and decomposed task files under
 `docs/AI_HANDOFF/` — nothing else.** It never edits product code, never launches an
 executor, and never escalates itself into implementation. Long plans are simply
-**queued**: after Step 2.5 the command stops with the tasks in `status=ready`, and
-implementation waits for an explicit human action.
+**queued**: after Step 2.5 the command stops with every task `ready` — which is a
+verdict, not a default: tasks are born `needs_breakdown` and only flip to `ready` after
+the task-budget validator (`VERDICT: ok`) AND the independent plan review (`Approved`)
+both pass (see Step 2.5). If a gate never ran (budget, denial, interruption), the tasks
+stay non-ready and the state files say so, and implementation still waits for an explicit
+human action.
 
 This holds even when `docs/AI_HANDOFF/RUN.md` already carries an unfinished
 handoff-fullstack cursor. Running this command **makes the session's handoff intent
@@ -44,7 +48,7 @@ is **not** `done`/`blocked`, a fullstack run is live and owns the canonical plan
 
 **Explicit abandonment never overwrites an unfinished canonical run.** Only when the human
 explicitly says to abandon/clear the current run, first run `/ukit:handoff-clear`, which
-sets `Paused: yes` in `RUN.md` and keeps its actual phase and scope, recording the
+sets `Paused: yes` in `RUN.md` and keeps its actual phase and scope; a later explicit `/ukit:handoff-fullstack` lifts it (`Paused: no`, read back, Phase/scope untouched). Recording the
 cancellation reason and next recovery action (it never sets `Phase: done` and never erases
 `RUN.md`). The paused canonical files are still unfinished: the new request is written under
 the queued root `docs/AI_HANDOFF/queued/<slug>/` and the canonical task files, INDEX, and
@@ -93,13 +97,35 @@ the document into a LEDGER, a bounded task set and a queue, and never implements
 
 - **Phase A — gather (lite tier):** chunk the document, extract candidate requirements, and
   collect feasibility evidence from the **current source** (index-first) plus `git log`,
-  `git diff` and `git status` of the touched areas. Gatherers decide nothing.
+  `git diff` and `git status` of the touched areas. Gatherers decide nothing. Before
+  chunking, persist the source verbatim with ONE simple command, literal paths (no `cd`, no
+  compound):
+  `node .claude/ukit/index/source-snapshot.mjs <original-path> docs/AI_HANDOFF/SOURCE.md`
+  (under a queued root, pass that root's SOURCE.md path). It records the origin path, the
+  sha256 of the original bytes and a byte-identical copy, and refuses to overwrite an
+  existing snapshot. If it cannot run (denial, budget), `PLAN.md` and `LEDGER.md` must
+  state `source snapshot MISSING` explicitly — never cite only a mutable path as the source.
 - **Phase B — decide (smart tier):** write the LEDGER at `${OUTPUT_ROOT}LEDGER.md` — every
   requirement gets exactly one disposition (`feasible`/`adapted`/`deferred`/`blocker`); the
   footer reads `Coverage: N/N rows dispositioned`; note that
-  disposition coverage is not implementation coverage. Draft 2-3 candidate plans, score them, pick the best and record
+  disposition coverage is not implementation coverage. Material the source itself marks as
+  proposal, example, or rejected (and explicit non-goals) is NOT `deferred` — `deferred`
+  means intentionally-later work with a queue entry. Those items are `NOTES.md` entries
+  with their kind (`proposal`/`example`/`rejected`), per the advisor-plan skill; forcing
+  them into `deferred` queues non-work as backlog. Draft 2-3 candidate plans, score them, pick the best and record
   the rejected ones in `PLAN.md`. Every task carries detailed TDD test cases (happy, edge,
   error with expected results) that prove it works.
+- **Plan count is a deliverable.** When the owner source states a number of plans or
+  separate plans ("at least two plans", "plan A and plan B"), write that many real plan
+  units in the Handoff-supported layout: the first plan under `OUTPUT_ROOT` (canonical
+  SPEC.md/PLAN.md/tasks/, or the queued root when a run is live), each further plan as its
+  own `docs/AI_HANDOFF/queued/<slug>/` blueprint with its own SPEC.md, PLAN.md, INDEX.md
+  (rows `queued_blueprint`), HANDOFF.md and tasks/. Group labels ("group A/B") inside one
+  PLAN.md never satisfy a stated count. Verify the count mechanically before reporting:
+  `node .claude/ukit/index/plan-count.mjs docs/AI_HANDOFF <N>` (the planning root, the
+  stated count) must print `PLAN_COUNT: ok (<found>/<N>)`. If the layout genuinely cannot
+  carry the count, record an explicit owner-decision item (a `NOTES.md` `question` entry
+  naming the decision) instead of silently collapsing it.
 - **Phase C — review:** the independent plan review in Step 2.5.
 - **Phase D — implement (code tier, separate phase):** never in this session; it runs later
   under `/ukit:handoff-fullstack` or `/ukit:handoff-implement`.
@@ -147,10 +173,43 @@ Ending the turn on a question with no plan written is a failed create.
 
 After the batched call, run Steps 1–2.5 to completion without further questions.
 
+## Step 0.5 — Source snapshot (before Step 1, every run)
+
+When the problem statement comes from — or references — an original document on disk,
+persist the source verbatim with ONE simple command, literal paths, BEFORE Step 1 reads
+anything:
+
+```
+node .claude/ukit/index/source-snapshot.mjs <original-path> docs/AI_HANDOFF/SOURCE.md
+```
+
+(under a queued root, pass that root's SOURCE.md path literally). The helper refuses to
+overwrite an existing snapshot (exclusive create), so a re-run never clobbers the recorded
+bytes. If it cannot run (denial, budget, no file), PLAN.md — and LEDGER.md on the advisor
+path — must state `source snapshot MISSING` explicitly — never cite only a mutable path as
+the source. Chat-only input needs no snapshot: the durable verbatim message origin stands in
+for the file (Step 2.5 item 1 reads it).
+
 ---
 
+## Planning dispatch contract
+
+For **all three planning dispatches** (context reader, planner, independent reviewer),
+omit the `isolation` field entirely. Do not set it to `worktree`, `remote`, `null`, or
+an empty string. Planning reads/writes belong to this checkout; it does not authorize
+worktree allocation. This also applies to read-only context agents. On omp, omit the
+corresponding isolation/worktree option; Codex without agents uses its existing
+instruction-mediated path, not a new worktree.
+
+Do not repeat or respawn a refused dispatch, change its writer, or manufacture a
+fallback plan to satisfy Stop. Preserve the exact refusal and incomplete planning
+state. A hook refusal is not a transient network error.
+
 ## Step 1 — Read context (lite model)
 
+Before this first context-agent call, omit the `isolation` field entirely.
+Do not repeat or respawn a refused dispatch.
+
 **Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` (omp: the `task` tool with `agent: "ukit-small-task-maintainer"`). Do NOT read these files yourself in the current session — this step is contracted to the lite tier (haiku/unic-lite), which only the spawned agent's frontmatter model guarantees. Ask the agent to:
 
 1. Read `docs/AI_HANDOFF/INDEX.md` → current tasks + statuses (or "empty")
@@ -183,14 +242,21 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 
 1. Check INDEX.md task statuses (canonical root only — skip when the live-run guard routed
    you to the queued root):
-   - All tasks are `ready` (planning only) → **only an explicit amendment may overwrite**: when the human names the existing plan to refine: first copy every prior file (PLAN.md, SPEC.md, LEDGER.md, NOTES.md, SOURCE.md, tasks/TASK-*.md, when present) to the next unused `amendments/rev-<NN>/` under the same root (scan existing rev dirs and take max+1; never reuse or overwrite an existing rev dir). Then compose the revised PLAN.md in full: carry the existing `## Amendment History` forward and append this amendment's entry (prior review rounds and verdicts; prior requirement, decision and task versions with what changed and why; each change's `invalidated` evidence: tasks, executor reports, verdicts that no longer hold). Write the revised PLAN.md only after that entry is in the composed text, so the overwrite can never drop the history. An **independent new request** (a different goal, even when the old tasks are all `ready`) is NOT an amendment: write it under the queued root `docs/AI_HANDOFF/queued/<slug>/` and never overwrite the existing canonical plan.
+   - **Resume gates — `needs_breakdown` rows and PLAN.md without `PLAN_REVIEW: Approved`:**
+     a previous create run ended before both gates passed. Never re-intake the request,
+     do NOT re-run the advisor chain, and never overwrite the existing SPEC/PLAN/tasks on
+     this path. Run only the missing gates on the existing plan: the per-task validator
+     (`--record`, step 5 below) for every task still lacking its recorded `Validator:` line,
+     and the Step 2.5 independent review. Flip per the ready gate only after both pass; if
+     a gate cannot run, leave the statuses as they are and name the missing gate in
+     INDEX.md and ACTIVE.md.
+   - All tasks are `ready` (planning only) → **only an explicit amendment may overwrite**: when the human names the existing plan to refine: first copy every prior file (PLAN.md, SPEC.md, LEDGER.md, NOTES.md, SOURCE.md, tasks/TASK-*.md, when present) to the next unused `amendments/rev-<NN>/` under the same root (scan existing rev dirs and take max+1; never reuse or overwrite an existing rev dir). Then run the mechanical guard ONCE, naming every file you are about to rewrite — `node .claude/ukit/index/amend-guard.mjs docs/AI_HANDOFF PLAN.md SPEC.md` — and only an `AMEND_GUARD: ok` line lets the rewrite proceed (a queued root passes its own root path). The checker is mechanical — it verifies the `amendments/rev-<NN>` copy exists on disk — but its invocation is prose: no host hook runs it for you, so run it yourself before composing the revision. Then compose the revised PLAN.md in full: carry the existing `## Amendment History` forward and append this amendment's entry (prior review rounds and verdicts; prior requirement, decision and task versions with what changed and why; each change's `invalidated` evidence: tasks, executor reports, verdicts that no longer hold). Write the revised PLAN.md only after that entry is in the composed text, so the overwrite can never drop the history. An **independent new request** (a different goal, even when the old tasks are all `ready`) is NOT an amendment: write it under the queued root `docs/AI_HANDOFF/queued/<slug>/` and never overwrite the existing canonical plan.
    - Any task is `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **do not overwrite** the in-flight cycle: its task files carry executor reports and verdicts. An **independent new request** is still planned and written under the queued root `docs/AI_HANDOFF/queued/<slug>/` (it is never refused for this reason); report which tasks are in flight and point the human at `/ukit:handoff-review` (to finish the cycle) or `/ukit:handoff-clear` (to abandon it). Only an explicit amendment of the in-flight plan is refused, with that pointer.
    - No tasks → fresh cycle, proceed normally.
 
-2. Resolve base branch:
-   ```bash
-   BASE=$(git symbolic-ref --short HEAD)
-   ```
+2. Resolve base branch: run ONE simple command — `git symbolic-ref --short HEAD` — and use
+   the printed branch name as a literal (`<base-branch>`) in ACTIVE.md's `Base:` line and in
+   any later command. No assignment, no command substitution, no compound.
 
 3. Write `${OUTPUT_ROOT}SPEC.md` — the detailed implementation spec (BẮT BUỘC before tasks).
    Follow `docs/AI_HANDOFF/SPEC.md`'s template sections (or `template_project/docs/AI_HANDOFF/SPEC.md`
@@ -224,14 +290,37 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    Every task MUST have:
    - Spec references (SPEC.md section IDs this task implements)
    - Target Files (exact paths — no two tasks in same wave share a file)
-   - Dependencies (`TASK-xxx` or `none` — wave structure inferred from this, not stored separately)
-   - Test Cases (Type | Name | Expected — ≥1 happy + ≥2 edge cases of different kinds)
+   - Dependencies (`TASK-xxx` or `none` — wave structure inferred from this, not stored separately; a source delivery-order qualifier like "after import works" IS a dependency, name its source line)
+   - Test Cases (Type | Name | Expected — ≥1 happy + ≥2 edge cases of different kinds; every Expected is ONE deterministic outcome, never "X or nothing")
    - Test Files (exact paths)
-   - Verification Commands (runnable shell commands)
+   - Verification Commands (runnable shell commands that run the tests — grepping a doc for a literal line such as `Coverage: N/N` is not evidence)
    - Acceptance Criteria (verifiable checklist)
-   Missing any field → status: `needs_breakdown`, never `ready`
-
-6. Update `${OUTPUT_ROOT}INDEX.md` — one row per task. Canonical root: `status=ready`.
+   Missing any field → status: `needs_breakdown`, never `ready`.
+   Write every task file `Status: needs_breakdown` — `ready` is a verdict, not a default —
+   and run the task-budget validator on each file you just wrote as ONE simple command per
+   task, from the project root, literal path, no `cd`, no loop, no shell variables, no
+   pipes, no compound:
+   ```
+   node .claude/ukit/index/task-budget-validator.mjs docs/AI_HANDOFF/tasks/TASK-001.md
+   ```
+   Repeat the command per task file (eight tasks = eight separate calls). `VERDICT:
+   needs_breakdown` → split further, or record a one-line dismissal in the task's
+   `## Discussion`. Nothing is `ready` yet — the review gate in Step 2.5 still applies.
+   Right after each `VERDICT: ok`, record it from the tool itself with ONE simple command
+   per task — `node .claude/ukit/index/task-budget-validator.mjs --record docs/AI_HANDOFF/tasks/TASK-001.md` — which re-validates and appends
+   `Validator: ok <YYYY-MM-DD> <tool-version>` to that task's `## Discussion` thread
+   (atomic temp-file + rename, existing BOM and line endings preserved, idempotent — a
+   second run never duplicates the line — and it refuses a non-ok verdict, so a
+   `needs_breakdown` file is never recorded). A dismissal stays a hand-written one-liner:
+   `Validator: dismissed <YYYY-MM-DD> — <reason>`. Verdicts live on disk, not in session
+   memory: compaction must not erase a gate.
+
+6. Update `${OUTPUT_ROOT}INDEX.md` — one row per task. Canonical root: rows start
+   `status=needs_breakdown`; set `ready` only in Step 2.5, after the validator passed each
+   task (or a documented dismissal) AND the independent plan review returned `Approved`.
+   If the run ends before both gates completed (budget exhausted, command denied,
+   interruption), the rows stay `needs_breakdown`, and INDEX.md and ACTIVE.md must say
+   which gate is missing.
    **Queued root: a draft index with `status=queued_blueprint` rows, never `ready`.** The queued
    blueprint's own `INDEX.md` and `tasks/` are a draft only: they are not canonical runnable
    admission. The "first 10 active" rule applies to the canonical root alone; a blueprint's tasks
@@ -247,6 +336,10 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    Tasks: <N> total
    Status: planning_done — ready for executor
    ```
+   When the gates have not all passed, write the honest state instead:
+   `Status: planning_incomplete — tasks not ready: <validator | plan review>` (a
+   human-readable ACTIVE.md marker only — machine readers parse INDEX.md rows and
+   task-file `- Status:` lines, never write `planning_incomplete` into those).
    Note: wave structure is inferred from task Dependencies fields — not stored here.
 
 8. Report: task IDs, dependency graph, any `needs_breakdown` + reason — and, when queued,
@@ -277,14 +370,16 @@ round gives one more fresh pass on anything still open. A stalled plan is never
 
 1. Reviewer reads `SPEC.md` + `PLAN.md` plus the plan's sources, starting from the original: `SOURCE.md` (the verbatim original bytes; verify the recorded sha256 against them; for chat input, the durable verbatim message origin stands in for the file), then `LEDGER.md` (classification of every requirement), `NOTES.md` (optional source-only notes, when present; a missing note is caught because the chain starts at SOURCE, not at NOTES), the `tasks/TASK-*.md` files of the plan, and the current source the plan's Target Files touch (no executor report, no diff). It compares the chain SOURCE → classification (LEDGER) → tasks (acceptance and verification), and NOTES are checked against the same chain. Each `feasible`/`adapted` row maps to a task with acceptance and a verification command. It checks that every `feasible`/`adapted` row and every requirement not explicitly deferred, blocked, or classified as rejected/proposal/example is covered by a task with acceptance and verification, that no feasible/adapted row lacks evidence, and Completeness / Consistency / Clarity / Scope / YAGNI plus the spec quality gate — every requirement testable, every fullstack layer covered, dependencies explicit, no vague instruction left — see `.claude/agents/code-reviewer.md` → Spec/Plan Review — and appends its verdict to PLAN.md's `## Plan Review Log` (new round entry, prior rounds kept).
 2. `Issues Found` → route back to Step 2: planner revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for another Step 2.5 review (this becomes the next round). Do NOT commit or hand off to executor on `Issues Found`.
-3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer, then proceed.
+3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer. Before any flip, run the mechanical ready gate ONCE on the output root — `node .claude/ukit/index/ready-gate.mjs ${OUTPUT_ROOT}` — and require `READY_GATE: ok` (every task marked `ready` carries a recorded `Validator:` line and PLAN.md carries `PLAN_REVIEW: Approved`; INDEX rows and task files agree). Any `tasks not ready: …` / `index/task mismatch …` line names the exact gap — fix it (re-run the validator with `--record`, finish the review, align the statuses) and re-run the gate; do not flip while it fails. This is the second of the two readiness gates: flip ONLY the tasks whose task file's `## Discussion` records `Validator: ok <date>` (or `Validator: dismissed <date> — <reason>`) to `Status: ready` in that task file and in `INDEX.md` — re-read each task file from disk to decide, never from session memory; a task without the recorded `Validator:` line stays `needs_breakdown` (a verdict held only in the session does not count) — and set ACTIVE.md to `Status: planning_done — ready for executor`.
 
 > **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the strong model in a **separate** chat/session from Step 2, paste PLAN.md, review using the Spec/Plan Review checklist in `.claude/agents/code-reviewer.md`.
 
 ---
 
-**Next:** the plan is complete and every task is `ready` (queued — nothing has been
-implemented). To start implementation, the human runs `/ukit:handoff-implement` for the
+**Next:** the plan is complete; every task is `ready` only when both gates passed (validator
+`VERDICT: ok` per task + review `Approved`) — otherwise the tasks stay `needs_breakdown`
+and INDEX/ACTIVE name the missing gate (nothing has been implemented either way). To start
+implementation once the tasks are `ready`, the human runs `/ukit:handoff-implement` for the
 plan-only flow, or `/ukit:handoff-fullstack` to drive plan → implement → review as one
 one-shot pipeline. This command does not do either on its own.