@ngockhoale/ukit 3.4.12 → 3.4.13

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.13 - 2026-10-04
+
+**`/ukit:handoff-create` is strictly planning-only; the Stop gate follows the session's CURRENT handoff intent.**
+`handoff-create` writes SPEC/PLAN/task files under `docs/AI_HANDOFF/` and stops with tasks
+`ready` (queued) — it never edits product code, launches executors, or escalates itself
+into implementation, even when an unfinished `RUN.md` exists or after compact/resume.
+New shared `handoff-intent.mjs` classifies a transcript by its MOST RECENT structured
+intent (`/ukit:handoff-create` vs `/ukit:handoff-fullstack` command tag, `Skill` call,
+SessionStart resume banner). The Stop gate and `handoff-resume.sh` both use it: a session
+that planned after an earlier fullstack run is no longer bounced into the stale run,
+while a session actually driving `handoff-fullstack` (including create → fullstack
+re-acquire) is still held to completion — the completion gate and ExitPredicate are
+unchanged. Unknown/unreadable/windowed-out transcripts stay fail-closed. Claude Code,
+Codex and omp share the same runtime, with native transcript envelopes normalized.
+Planning alongside a live run preserves its cursor, index and tasks and writes a
+separate queued plan instead. Tests: `handoffIntentSeparation`,
+`handoffResumeIntent`, `handoffCreateQueueing`.
+
 ## 3.4.12 - 2026-10-02
 
 **Handoff Stop gate is session-scoped — a stale `RUN.md` no longer hijacks unrelated sessions.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.12",
+  "version": "3.4.13",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

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

@@ -14,6 +14,52 @@ $ARGUMENTS
 > **Can be run multiple times.** If the plan or tasks aren't satisfactory after the first run, re-run `/ukit:handoff-create` to refine until the plan is good — as long as no task has been implemented yet.
 > **NO git commit. NO git push.** This phase only writes docs files. No code changes.
 
+## Planning-only contract — this command never implements
+
+`/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.
+
+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
+planning**, so the Stop gate and the SessionStart compact/resume hook both keep quiet
+until the human explicitly resumes.
+
+### A live fullstack run is never overwritten — the new plan is QUEUED
+
+Before writing anything, read `docs/AI_HANDOFF/RUN.md`. If it exists and its `Phase:`
+is **not** `done`/`blocked`, a fullstack run is live and owns the canonical plan:
+
+- **Never touch** `RUN.md`, `INDEX.md`, `PLAN.md`, `SPEC.md`, `ACTIVE.md`, or
+  `tasks/TASK-*.md`. Overwriting them — which the "all tasks are `ready`" rule below
+  would otherwise allow — destroys in-flight tasks, executor reports and verdicts.
+- Write the whole new plan under the **queued path** instead:
+  `docs/AI_HANDOFF/queued/<slug>/` — `SPEC.md`, `PLAN.md`, `INDEX.md`, `HANDOFF.md`
+  (activation notes: what it depends on, when to start) and `tasks/`. This is a
+  blueprint, not a runnable cycle: no `tasks/TASK-*.md` row is created and nothing is
+  executed.
+- Report the queued path; the live run continues untouched.
+
+**Explicit abandonment is the only way to replace a live run.** Only when the human
+explicitly says to abandon/clear the current run, first run `/ukit:handoff-clear`
+(sets `Phase: done` / removes `RUN.md`), then plan against the canonical files. A mere
+mention of the new work is not abandonment — absent that explicit instruction, always
+take the queued path.
+
+### Planning-only output root (decided here, passed to the planner)
+
+The planner writes to exactly ONE root, chosen above: the **canonical root**
+`docs/AI_HANDOFF/` when no run is live, else the **queued root**
+`docs/AI_HANDOFF/queued/<slug>/`. Pass it to the planner as its planning-only output
+root; the planner writes nothing outside it and never launches an executor.
+
+- To implement later: `/ukit:handoff-implement` (plan-only flow), or
+  `/ukit:handoff-fullstack` (one-shot pipeline) — that explicit invocation reacquires
+  ownership, resumes a live run, or sweeps a queued blueprint in once the run is closed.
+- To abandon a paused run first: `/ukit:handoff-clear`.
+
 ---
 
 ## Question Policy — this is the one phase that may ask
@@ -47,7 +93,8 @@ After the batched call, run Steps 1–2.5 to completion without further question
 2. Read `docs/AI_HANDOFF/ACTIVE.md` → active cycle info (or "no active cycle")
 3. Read `docs/AI_HANDOFF/RULES.md` → PLAN.md 6-section format + Task Gate required fields
 4. Read `docs/AI_HANDOFF/tasks/_TEMPLATE.md` → task file structure
-5. Return a compact summary. Do NOT write anything yet.
+5. Read `docs/AI_HANDOFF/RUN.md` → its `Phase:` line (or "no run"). This decides the output root.
+6. Return a compact summary. Do NOT write anything yet.
 
 > **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the lite model, run the steps above yourself, keep the summary in context.
 
@@ -55,11 +102,19 @@ After the batched call, run Steps 1–2.5 to completion without further question
 
 ## Step 2 — Write plan + tasks (strong model)
 
-**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "handoff-planner"` (omp: the `task` tool with `agent: "handoff-planner"`), passing it the Step 1 summary and the problem/feature description. Do NOT write PLAN.md or task files yourself in the current session — this step is contracted to the strong tier (opus/unic-smart), which only the spawned agent's frontmatter model guarantees.
+**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "handoff-planner"` (omp: the `task` tool with `agent: "handoff-planner"`), passing it the Step 1 summary, the problem/feature description, and the **planning-only output root** (`docs/AI_HANDOFF/` when no run is live, else `docs/AI_HANDOFF/queued/<slug>/`) decided in the live-run guard below. Do NOT write PLAN.md or task files yourself in the current session — this step is contracted to the strong tier (opus/unic-smart), which only the spawned agent's frontmatter model guarantees. The planner never launches an executor.
 
 The planner agent does the following (use Step 1 summary — do NOT re-read files):
 
-1. Check INDEX.md task statuses:
+0. **Live-run guard — decide OUTPUT_ROOT first (see "A live fullstack run is never
+   overwritten").** If Step 1 reported `RUN.md` with a `Phase:` that is not `done`/`blocked`,
+   a fullstack run is live: set `OUTPUT_ROOT = docs/AI_HANDOFF/queued/<slug>/` (`<slug>` =
+   a short kebab name for this work), write ONLY there, and skip steps 1, 6 and 7 — the
+   canonical `RUN.md`/`INDEX.md`/`PLAN.md`/`SPEC.md`/`ACTIVE.md`/`tasks/` stay untouched.
+   Otherwise `OUTPUT_ROOT = docs/AI_HANDOFF/`. Everything below writes under `OUTPUT_ROOT`.
+
+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) → **re-run allowed**: overwrite PLAN.md and TASK-xxx.md freely — this is iterative refinement.
    - Any task is `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **do not overwrite**: that cycle is mid-flight and its task files carry executor reports and verdicts. 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). Planning is the one phase where stopping is correct — there is nothing safe to do automatically here.
    - No tasks → fresh cycle, proceed normally.
@@ -69,7 +124,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    BASE=$(git symbolic-ref --short HEAD)
    ```
 
-3. Write `docs/AI_HANDOFF/SPEC.md` — the detailed implementation spec (BẮT BUỘC before tasks).
+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`
    on a fresh tree): problem/context, goals, non-goals, user journeys, functional requirements
    with Given/When/Then + error cases, fullstack scope (backend, schema/migrations, API
@@ -83,7 +138,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    resolved to a chosen default recorded inline — the plan phase is the only question
    window, so anything left "TBD" becomes a guess downstream.
 
-4. Write `docs/AI_HANDOFF/PLAN.md` — all 6 sections mandatory:
+4. Write `${OUTPUT_ROOT}PLAN.md` — all 6 sections mandatory:
    - §1 Intent — problem + success definition
    - §2 Scope — in / out of scope. **Add a constraint**: same-wave tasks must not modify the same file (prevents merge conflicts). If two tasks need the same file, make one depend on the other.
    - §3 Approach — solution, trade-offs, alternatives rejected
@@ -97,7 +152,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    PLANNER_MODEL: <your exact model ID>
    ```
 
-5. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
+5. Create `${OUTPUT_ROOT}tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
    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)
@@ -108,9 +163,12 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    - Acceptance Criteria (verifiable checklist)
    Missing any field → status: `needs_breakdown`, never `ready`
 
-6. Update `INDEX.md` — one row per task, `status=ready`
+6. Update `${OUTPUT_ROOT}INDEX.md` — one row per task, `status=ready`. **Skip entirely when
+   the live-run guard routed you to the queued root** — a blueprint carries no runnable
+   `ready` row; its `HANDOFF.md` activation notes are the record instead.
 
-7. Update `ACTIVE.md`:
+7. Update `ACTIVE.md` (canonical root only — **skip when queued**; the queued blueprint's
+   `HANDOFF.md` replaces it):
    ```
    Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <BASE>
    Goal: <1 sentence>
@@ -120,9 +178,10 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    ```
    Note: wave structure is inferred from task Dependencies fields — not stored here.
 
-8. Report: task IDs, dependency graph, any `needs_breakdown` + reason
+8. Report: task IDs, dependency graph, any `needs_breakdown` + reason — and, when queued,
+   the `OUTPUT_ROOT` path plus why it was queued (the live run it must not disturb).
 
-> **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the strong model, execute steps 1–7 above yourself.
+> **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the strong model, execute steps 0–8 above yourself.
 
 ---
 
@@ -137,7 +196,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 Two independent strong-model passes shape the plan before any code is written — that gate is
 intact. What it no longer does is hand a stalled plan back and wait.
 
-**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`), passing `REVIEW_TARGET_TYPE=plan` and the paths to `docs/AI_HANDOFF/PLAN.md` AND `docs/AI_HANDOFF/SPEC.md`. This MUST be a separate agent invocation from Step 2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
+**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`), passing `REVIEW_TARGET_TYPE=plan` and the paths to `${OUTPUT_ROOT}PLAN.md` AND `${OUTPUT_ROOT}SPEC.md` (canonical root, or the queued root when one was chosen). This MUST be a separate agent invocation from Step 2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
 
 1. Reviewer reads `SPEC.md` + `PLAN.md` (no diff, no task files, no executor report), checks 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`.
@@ -147,4 +206,13 @@ intact. What it no longer does is hand a stalled plan back and wait.
 
 ---
 
-**Next:** switch to code model → `/ukit:handoff-implement`
+**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
+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.
+
+When a live fullstack run forced the plan into `docs/AI_HANDOFF/queued/<slug>/`, that
+blueprint is dormant: `/ukit:handoff-fullstack` sweeps it into the canonical plan once the
+current run is closed (or the human explicitly abandons it with `/ukit:handoff-clear`),
+copying the queued tasks into `tasks/` at that point — exactly like any other queued
+blueprint. Nothing is dropped, and nothing is auto-implemented before then.

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

@@ -111,6 +111,23 @@ all treats it as closed. It is *paused*, not abandoned: an explicit `/ukit:hando
 re-invocation resumes it as a continuation; `ukit handoff-clear` abandons it. Only when
 `RUN.md` is absent or `Phase: done` does a new request start a fresh cycle.
 
+### Explicit invocation reacquires ownership
+
+`/ukit:handoff-create` is planning-only and makes a session's handoff intent *planning* — so
+while the human is planning, neither the Stop gate nor the SessionStart compact/resume hook
+forces a paused run back into implementation. This command is the explicit counter-action:
+
+- Invoking `/ukit:handoff-fullstack` (or running the `handoff-fullstack` skill) makes the
+  session's handoff intent *implementation* again — ownership is reacquired, the queued
+  `ready` tasks from the create phase are picked up, and a `Phase:` outside `done`/`blocked`
+  in `RUN.md` is once more held to completion by the Stop gate.
+- Work queued by planning is **not lost**: it waits in `INDEX.md`/`PLAN.md` until this
+  explicit invocation (or `/ukit:handoff-implement`) claims it.
+
+Enforcement is therefore never weakened — it is scoped to *which* command the session
+actually invoked. A session driving this pipeline still cannot stop early; a session that
+only planned never gets bounced into a run it did not ask for.
+
 ---
 
 ## §0 — Completion contract (terminal outputs)
@@ -153,11 +170,23 @@ work, not only the current plan:
 3. Previous cycles — `docs/AI_HANDOFF/HISTORY.md` and `archive/` for cycles closed with
    unfinished tasks; their leftovers join THIS cycle.
 4. `docs/TASKS.md` — `Ready for AI` items are newly-assigned work; fold them into the plan.
-5. `git status` / `git diff` — uncommitted work-in-progress that must be finished or
+5. `docs/AI_HANDOFF/queued/*/` — dormant blueprints. A planning run that could **not**
+   touch the canonical plan (a live run was in flight) queues its SPEC/PLAN/tasks under
+   `docs/AI_HANDOFF/queued/<slug>/` instead of overwriting (see `/ukit:handoff-create`).
+   When this run is planning a fresh cycle (P2), sweep those blueprints in: copy a
+   blueprint's tasks into `tasks/TASK-xxx.md` and schedule them like any other item. Never
+   overwrite a blueprint — a blueprint the run decides to defer stays queued.
+6. `git status` / `git diff` — uncommitted work-in-progress that must be finished or
    checkpointed, never silently dropped.
 
 The inventory feeds P2: the planner either schedules every discovered item or records why
-it is out of scope (§1/§2 of PLAN.md). Silent omission is a plan defect.
+it is out of scope (§1/§2 of PLAN.md). Silent omission is a plan defect — a queued
+blueprint dropped without either scheduling or a recorded reason is exactly that defect.
+
+> **Never overwrite a live run to consume a queued blueprint.** A blueprint is folded in
+> only through P2's normal plan-write path, and only when no run is mid-flight; on a
+> Resume (RUN.md `Phase:` not `done`/`blocked`) the run continues from its own cursor and
+> leaves the queued blueprint untouched for the next cycle.
 
 **Recovery rule — stuck task records.** For every `pending`, stale `in_progress`, or
 `blocked` task whose record cannot be cleanly resumed (invalid state, orphaned worktree

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

@@ -105,8 +105,31 @@ setTimeout(() => {
 const projectRoot = process.env.PROJECT_ROOT;
 const runPath = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md');
 const runtimePath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'execution-ledger.mjs');
+const intentPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'handoff-intent.mjs');
+
+// The session's CURRENT handoff intent, from structured transcript evidence (the
+// shared handoff-intent module the Stop gate uses). `intent === 'create'` means the
+// latest thing the user asked this session to do is plan — so a live RUN.md from an
+// earlier fullstack run must NOT be forced back into implementation here. Unknown
+// (`known` false: no transcript path, unreadable, shared module missing) keeps the
+// existing fail-toward-resume behaviour, exactly as the Stop gate keeps its block.
+async function readHandoffIntent(transcriptPath) {
+  try {
+    const mod = await import(pathToFileURL(intentPath).href);
+    if (typeof mod.transcriptHandoffIntent !== 'function') return { intent: null, known: false };
+    return await mod.transcriptHandoffIntent(transcriptPath);
+  } catch {
+    return { intent: null, known: false };
+  }
+}
 
 async function emitOrdinaryResume(payload, source) {
+  // A session actively driving (or handed) a fullstack run is owned by that run —
+  // the Stop gate holds the stop, not the ordinary routed-task resume lane.
+  const { intent } = await readHandoffIntent(
+    typeof payload.transcript_path === 'string' ? payload.transcript_path : null,
+  );
+  if (intent === 'fullstack') return false;
   let runtimeExists = false;
   try { await fs.promises.access(runtimePath); runtimeExists = true; } catch {}
   if (!runtimeExists) return false;
@@ -170,6 +193,15 @@ async function emitOrdinaryResume(payload, source) {
   const cursor = field('Cursor');
   const next = field('Next');
 
+  // The session's CURRENT handoff intent — structured transcript evidence, the
+  // same shared module the Stop gate uses. A session whose latest request is
+  // planning (`/ukit:handoff-create`) must never be pushed into implementing a
+  // stale RUN.md, compact or not. `known` false (no transcript path, unreadable,
+  // module absent) keeps the existing resume behaviour.
+  const { intent } = await readHandoffIntent(
+    typeof payload.transcript_path === 'string' ? payload.transcript_path : null,
+  );
+
   // A brand-new session (startup / clear) did not start this run and may be about
   // something else entirely (e.g. planning). Tell it the run exists, but do NOT
   // order a resume and do NOT use the resume marker the Stop gate treats as proof
@@ -184,6 +216,21 @@ async function emitOrdinaryResume(payload, source) {
     process.exit(0);
   }
 
+  // Planning intent outranks a live cursor: the user asked this session to plan,
+  // so report the paused run and let the planning continue. This is the one place
+  // an automatic resume must yield — /ukit:handoff-create is planning-only by
+  // contract, and /ukit:handoff-fullstack remains the explicit way to resume.
+  if (intent === 'create') {
+    process.stdout.write([
+      'UKit note: docs/AI_HANDOFF/RUN.md has an unfinished handoff-fullstack run '
+        + `(Phase: ${phase}; Next: ${next || 'not recorded'}), but this session's current request`,
+      'is planning (/ukit:handoff-create). Stop gate and resume will not force the run here —',
+      'finish the planning first. To resume implementation explicitly, run /ukit:handoff-fullstack;',
+      'to discard the run, /ukit:handoff-clear.',
+    ].join('\n') + '\n');
+    process.exit(0);
+  }
+
   const out = [
     'UKIT HANDOFF RESUME — an unfinished handoff-fullstack run was found on disk.',
     `  Goal:   ${goal || '(not recorded)'}`,

package/template_project/.claude/ukit/runtime/handoff-intent.mjs

@@ -0,0 +1,293 @@
+// handoff-intent.mjs — durable intent separation for the handoff pipeline.
+//
+// Why this exists: a single session can carry more than one handoff command over
+// its life. The Stop gate (stop-coordinator.mjs) and the SessionStart resume hook
+// (handoff-resume.sh) must react to the session's CURRENT intent, not to any
+// historical one. A session that ran `/ukit:handoff-fullstack` earlier and is now
+// planning with `/ukit:handoff-create` must NOT be bounced into implementing a
+// stale RUN.md — while a session actively driving a fullstack run must still be
+// held to completion. "Session ran fullstack once" is therefore not ownership;
+// "the most recent handoff intent is fullstack" is.
+//
+// The intent is derived from STRUCTURED transcript evidence only — real user-turn
+// slash-command tags (Claude Code), native command-expansion headings (omp, Codex),
+// Skill tool calls, and SessionStart / host-injected hook context. Raw text matching
+// is deliberately NOT used: the marker strings also appear in tool output, bash
+// commands and source files that any session may read (TASK-007 established this;
+// this module keeps it). Each host is recognised by its OWN real envelope shape; an
+// unknown format returns `null` rather than a guess, so fail-closed callers keep
+// behaving fail-closed.
+//
+// Exports (independently testable — callers import the module directly):
+//   HANDOFF_FULLSTACK_TAG / HANDOFF_CREATE_TAG — the two user-turn command tags
+//   HANDOFF_RESUME_BANNER                       — the SessionStart resume marker
+//   classifyHandoffEntry(entry)                 — 'fullstack' | 'create' | null for one JSONL entry
+//   classifyHandoffLine(line)                    — same, from a raw JSONL line
+//   transcriptHandoffIntent(path, opts)          — { intent, known } for a whole transcript;
+//        `intent` is the MOST RECENT qualifying intent, `known=false` when the scan
+//        could not complete (missing/unreadable path, budget overrun) — callers keep
+//        their fail-closed posture on `known=false`.
+
+import fs from 'node:fs/promises';
+
+export const HANDOFF_FULLSTACK_TAG = /<command-name>\/?(?:ukit:)?handoff-fullstack\b/;
+export const HANDOFF_CREATE_TAG = /<command-name>\/?(?:ukit:)?handoff-create\b/;
+export const HANDOFF_RESUME_BANNER = 'UKIT HANDOFF RESUME — an unfinished handoff-fullstack run';
+
+// omp and Codex do NOT wrap a slash command in `<command-name>` tags the way
+// Claude Code's user turn does. Their native evidence is the command *expansion*:
+// omp replaces `/ukit:handoff-fullstack` with the command body, whose FIRST
+// non-empty line is the H1 `# /ukit:handoff-fullstack — …`; Codex records the same
+// expanded body as a `response_item`/`message` with `input_text` blocks. Matching
+// the FIRST line only (not any heading in the body) keeps prose references to the
+// command inside the document from being mistaken for an invocation.
+const NATIVE_COMMAND_HEADING = /^\s{0,3}#{1,3}\s+\/?(?:ukit:)?(handoff-create|handoff-fullstack)\b/;
+
+// The unique customType the omp bridge stamps on host-injected UKit hook context
+// (`sendContext` → `hookContextMessage`). A resume banner only counts as intent
+// when it arrives inside one of these — an `irc:incoming` / `advisor` message that
+// happens to quote the banner is another agent's text, not this session's intent.
+const UKIT_HOOK_CONTEXT_TYPE = 'ukit-hook-context';
+
+// Block types that carry TOOL OUTPUT rather than the user's own words. A user
+// turn that contains one of these is a tool_result round-trip (the harness wraps
+// it in `role: user`), never a command the user typed — so it is never intent.
+const TOOL_OUTPUT_BLOCK_TYPES = new Set(['tool_result', 'toolResult', 'tool-result']);
+
+/** First non-empty line of a string, trimmed' or ''. */
+function firstNonEmptyLine(text) {
+  for (const line of String(text).split('\n')) {
+    if (line.trim()) return line;
+  }
+  return '';
+}
+
+/**
+ * Does this text open with a native (omp/Codex) command-expansion heading?
+ * Only the FIRST non-empty line is inspected, so an H1 that appears later in the
+ * document body — e.g. a marketing heading inside the command's own markdown —
+ * is never treated as the session's intent.
+ * @returns {'create' | 'fullstack' | null}
+ */
+function nativeCommandIntent(text) {
+  const m = firstNonEmptyLine(text).match(NATIVE_COMMAND_HEADING);
+  if (!m) return null;
+  return m[1] === 'handoff-create' ? 'create' : 'fullstack';
+}
+
+// Bounds for the tail scan. Recency is what matters, so the reader walks the
+// NEWEST lines first and stops at the first qualifying intent. A transcript
+// larger than `maxBytes` is scanned from its tail only: a recent intent is still
+// found, but "no intent in the window" is reported as `known=false` (fail-closed),
+// since the session's single command tag may predate the window. A deadline
+// overrun also returns `known=false` rather than a guess.
+export const INTENT_SCAN_BUDGET_MS = 1200;
+export const INTENT_SCAN_MAX_BYTES = 32 * 1024 * 1024;
+
+/**
+ * Split a user turn's content into (a) the user's own words, (b) the individual
+ * text blocks a native command expansion may arrive in, and (c) whether any block
+ * is TOOL OUTPUT. A `tool_result` round-trip is the harness wrapping tool output in
+ * a `role: user` turn — it is never something the user typed, so it never carries
+ * intent (TASK-007). Both Claude Code (`text`) and Codex (`input_text`) text blocks
+ * are user words.
+ */
+function splitUserContent(content) {
+  if (typeof content === 'string') return { text: content, blocks: content ? [content] : [], hasToolOutput: false };
+  if (!Array.isArray(content)) return { text: '', blocks: [], hasToolOutput: false };
+  let text = '';
+  let hasToolOutput = false;
+  const blocks = [];
+  for (const b of content) {
+    if (!b || typeof b !== 'object') continue;
+    if (TOOL_OUTPUT_BLOCK_TYPES.has(b.type)) { hasToolOutput = true; continue; }
+    if ((b.type === 'text' || b.type === 'input_text') && typeof b.text === 'string') {
+      text += (text ? '\n' : '') + b.text;
+      blocks.push(b.text);
+    }
+  }
+  return { text, blocks, hasToolOutput };
+}
+
+/**
+ * Classify a user turn (Claude Code `type:'user'`, omp `type:'message'` role user,
+ * Codex `type:'response_item'` payload message role user). Structured evidence only:
+ * a Claude Code `<command-name>` tag, or a native command-expansion heading on the
+ * first line of a user text block.
+ * @returns {'fullstack' | 'create' | null}
+ */
+function classifyUserTurn(content) {
+  const { text, blocks, hasToolOutput } = splitUserContent(content);
+  // Check the planning tag first: a single turn carrying both is a create turn.
+  if (HANDOFF_CREATE_TAG.test(text)) return 'create';
+  if (HANDOFF_FULLSTACK_TAG.test(text)) return 'fullstack';
+  // Native (omp / Codex) command expansion — the FIRST line of a user text block.
+  // A user turn that is purely tool output has no user text to match, so a
+  // `tool_result` carrying the marker string can never register as intent.
+  for (const block of blocks) {
+    const intent = nativeCommandIntent(block);
+    if (intent) return intent;
+  }
+  if (hasToolOutput) return null;
+  return null;
+}
+
+/**
+ * Classify assistant tool-call blocks. Handles both Claude Code (`tool_use`, name
+ * `Skill`, input.skill) and omp (`toolCall`, name/arguments.skill).
+ */
+function classifyAssistantBlocks(blocks) {
+  if (!Array.isArray(blocks)) return null;
+  for (const b of blocks) {
+    if (!b || typeof b !== 'object') continue;
+    if (b.type === 'tool_use' && b.name === 'Skill') {
+      const skill = String(b.input?.skill ?? '');
+      if (/^(?:ukit:)?handoff-create$/.test(skill)) return 'create';
+      if (/^(?:ukit:)?handoff-fullstack$/.test(skill)) return 'fullstack';
+      continue;
+    }
+    if (b.type === 'toolCall') {
+      const name = String(b.name ?? '');
+      const skill = String(b.arguments?.skill ?? '');
+      if (/^(?:ukit:)?handoff-create$/i.test(name) || /^(?:ukit:)?handoff-create$/.test(skill)) return 'create';
+      if (/^(?:ukit:)?handoff-fullstack$/i.test(name) || /^(?:ukit:)?handoff-fullstack$/.test(skill)) return 'fullstack';
+    }
+  }
+  return null;
+}
+
+/**
+ * Classify one transcript entry as a handoff intent.
+ *
+ * Recognises the REAL shapes of the three supported hosts, and refuses to guess on
+ * any other envelope:
+ *   - Claude Code:  `{ type:'user', message:{ role:'user', content } }`,
+ *                   `{ type:'assistant', message:{ content:[tool_use…] } }`,
+ *                   `{ type:'attachment', attachment:{ hookEvent:'SessionStart', … } }`
+ *   - omp:          `{ type:'message', message:{ role:'user'|'assistant', content:[…] } }`
+ *                   (content blocks `text` / `toolCall`), and host-injected hook
+ *                   context `{ type:'custom_message', customType:'ukit-hook-context', … }`
+ *   - Codex:        `{ type:'response_item', payload:{ type:'message', role:'user', content:[input_text…] } }`
+ *
+ * Anything else — including a format we do not recognise — returns null (never a
+ * guessed intent), so the caller's fail-closed posture is preserved.
+ * @returns {'fullstack' | 'create' | null}
+ */
+export function classifyHandoffEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  if (entry.type === 'user' && entry.message && entry.message.role === 'user') {
+    return classifyUserTurn(entry.message.content);
+  }
+  if (entry.type === 'message' && entry.message && entry.message.role === 'user') {
+    return classifyUserTurn(entry.message.content);
+  }
+  if (entry.type === 'message' && entry.message && entry.message.role === 'assistant') {
+    return classifyAssistantBlocks(entry.message.content);
+  }
+  if (entry.type === 'response_item' && entry.payload) {
+    const payload = entry.payload;
+    if (payload.type === 'message' && payload.role === 'user') {
+      return classifyUserTurn(payload.content);
+    }
+    // Codex records tool calls as separate `function_call` items (string args), not
+    // a Skill tool call — they cannot carry a typed slash-command intent.
+    return null;
+  }
+  if (entry.type === 'assistant' && Array.isArray(entry.message?.content)) {
+    return classifyAssistantBlocks(entry.message.content);
+  }
+  if (entry.type === 'attachment' && entry.attachment && entry.attachment.hookEvent === 'SessionStart') {
+    const a = entry.attachment;
+    if ([a.content, a.stdout, a.text].some((v) => typeof v === 'string' && v.includes(HANDOFF_RESUME_BANNER))) {
+      return 'fullstack';
+    }
+  }
+  // omp host-injected hook context (the bridge's `ukit-hook-context` customType).
+  // Gated on the customType so another agent's `irc:incoming` / an `advisor` message
+  // that merely quotes the banner cannot register as this session's intent.
+  if (entry.type === 'custom_message' && entry.customType === UKIT_HOOK_CONTEXT_TYPE) {
+    if (typeof entry.content === 'string' && entry.content.includes(HANDOFF_RESUME_BANNER)) {
+      return 'fullstack';
+    }
+  }
+  return null;
+}
+
+/**
+ * Classify one raw JSONL transcript line. Returns null when the line is not
+ * parseable or carries no handoff intent.
+ */
+export function classifyHandoffLine(line) {
+  try {
+    return classifyHandoffEntry(JSON.parse(line));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read a session transcript and return its MOST RECENT handoff intent.
+ * @returns {Promise<{ intent: 'fullstack'|'create'|null, known: boolean }>}
+ *   `known=false` means the scan could not be completed (no path, unreadable,
+ *   budget overrun); callers keep their existing blocking behaviour there.
+ */
+export async function transcriptHandoffIntent(transcriptPath, {
+  budgetMs = INTENT_SCAN_BUDGET_MS,
+  maxBytes = INTENT_SCAN_MAX_BYTES,
+} = {}) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) {
+    return { intent: null, known: false };
+  }
+  let handle;
+  try {
+    handle = await fs.open(transcriptPath, 'r');
+    const stat = await handle.stat();
+    const size = Number(stat.size) || 0;
+    const start = Math.max(0, size - maxBytes);
+    const deadline = Date.now() + budgetMs;
+    const chunk = Buffer.allocUnsafe(Math.min(Math.max(1, size - start), 4 * 1024 * 1024));
+    let text = '';
+    let pos = start;
+    while (pos < size) {
+      if (Date.now() > deadline) return { intent: null, known: false };
+      const toRead = Math.min(chunk.length, size - pos);
+      const { bytesRead } = await handle.read(chunk, 0, toRead, pos);
+      if (!bytesRead) break;
+      text += chunk.toString('utf8', 0, bytesRead);
+      pos += bytesRead;
+    }
+    let lines = text.split('\n');
+    // A tail window starts mid-line: the first fragment is not a whole entry.
+    if (start > 0) lines = lines.slice(1);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      const line = lines[i];
+      if (!line) continue;
+      // Cheap prefilter — skip JSON.parse for lines that cannot be evidence.
+      if (!line.includes('handoff-create') && !line.includes('handoff-fullstack') && !line.includes('HANDOFF RESUME')) {
+        continue;
+      }
+      const intent = classifyHandoffLine(line);
+      if (intent) return { intent, known: true };
+    }
+    // Nothing found. Only a scan of the WHOLE transcript proves "no handoff
+    // intent"; a tail window that missed it (the invoking turn usually appears
+    // once, near the start of an omp session) cannot, so it stays unknown and
+    // callers keep blocking.
+    return { intent: null, known: start === 0 };
+  } catch {
+    return { intent: null, known: false };
+  } finally {
+    try { await handle?.close(); } catch {}
+  }
+}
+
+/**
+ * Back-compat boolean view of the same scan: did this transcript ever show the
+ * session driving (or being handed) a handoff-fullstack run? Returns true, false,
+ * or null (unknown) exactly as the original stop-coordinator helper did.
+ */
+export async function transcriptShowsHandoffRun(transcriptPath, opts = {}) {
+  const { intent, known } = await transcriptHandoffIntent(transcriptPath, opts);
+  if (!known) return null;
+  return intent === 'fullstack';
+}

package/template_project/.claude/ukit/runtime/stop-coordinator.mjs

@@ -855,79 +855,40 @@ function formatPredicateState(result) {
   return result.terms.map((t) => `${t.term}=${t.pass ? 'pass' : `FAIL (${t.detail})`}`).join(', ');
 }
 
-// ─── Session ownership (does THIS session drive the run?) ─────────────────
-// Structured evidence that a session itself started or resumed a handoff-fullstack
-// run. Raw-text matching is NOT enough: the marker strings appear in tool output,
-// bash commands and source files any session may read, so only these shapes count:
-//   - a real user turn carrying the slash-command tag for handoff-fullstack
-//   - a Skill tool call naming handoff-fullstack
-//   - a SessionStart hook attachment carrying the resume injection
-const HANDOFF_COMMAND_TAG = /<command-name>\/?(?:ukit:)?handoff-fullstack\b/;
-const HANDOFF_RESUME_BANNER = 'UKIT HANDOFF RESUME \u2014 an unfinished handoff-fullstack run';
-const OWNERSHIP_SCAN_BUDGET_MS = 1200;
-const OWNERSHIP_SCAN_MAX_BYTES = 64 * 1024 * 1024;
-
-function textOfUserTurn(content) {
-  if (typeof content === 'string') return content;
-  if (!Array.isArray(content)) return '';
-  // tool_result blocks are tool output, never the user's own words.
-  return content.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n');
-}
-
-function entryShowsHandoffRun(entry) {
-  if (!entry || typeof entry !== 'object') return false;
-  if (entry.type === 'user' && entry.message && entry.message.role === 'user') {
-    return HANDOFF_COMMAND_TAG.test(textOfUserTurn(entry.message.content));
-  }
-  if (entry.type === 'assistant' && Array.isArray(entry.message?.content)) {
-    return entry.message.content.some((b) => b && b.type === 'tool_use' && b.name === 'Skill'
-      && /^(?:ukit:)?handoff-fullstack$/.test(String(b.input?.skill ?? '')));
+// ─── Session intent (does THIS session CURRENTLY drive the run?) ──────────
+// Structured-evidence rules live in the shared handoff-intent module so the
+// SessionStart resume hook and this Stop lane classify a transcript identically.
+// Only the MOST RECENT handoff intent counts: a session that ran
+// /ukit:handoff-fullstack earlier and has since run /ukit:handoff-create is
+// planning, not implementing, and must not be bounced into a stale RUN.md. The
+// converse also holds — a create-then-fullstack session reacquires ownership.
+// Evidence is structured only (real user-turn command tags, Skill calls,
+// SessionStart resume injections); raw text is never used, because the marker
+// strings also appear in tool output, bash commands and source files any session
+// may read (TASK-007).
+let handoffIntentModulePromise = null;
+function loadHandoffIntentModule() {
+  if (!handoffIntentModulePromise) {
+    handoffIntentModulePromise = import(new URL('./handoff-intent.mjs', import.meta.url).href)
+      .catch(() => null);
   }
-  if (entry.type === 'attachment' && entry.attachment && entry.attachment.hookEvent === 'SessionStart') {
-    const a = entry.attachment;
-    return [a.content, a.stdout, a.text].some((v) => typeof v === 'string' && v.includes(HANDOFF_RESUME_BANNER));
-  }
-  return false;
+  return handoffIntentModulePromise;
 }
 
 /**
- * Stream the session transcript (JSONL) for structured handoff-run evidence.
- * Returns true (found), false (whole transcript scanned, none found) or null
- * (unknown: no path, unreadable, or scan budget/size cap hit). Callers treat
- * null as "cannot prove this session is not the owner" and keep the legacy
- * blocking behaviour — a real run must never be released by a lost read.
+ * Does the transcript show this session as the CURRENT owner of a handoff-fullstack
+ * run? Returns true (yes), false (whole window scanned, latest intent is not
+ * fullstack), or null (unknown: no path, unreadable, budget hit, or the shared
+ * module is unavailable). Callers treat null as "cannot prove this session is not
+ * the owner" and keep the legacy blocking behaviour — a real run must never be
+ * released by a lost read.
  */
-export async function transcriptShowsHandoffRun(transcriptPath, {
-  budgetMs = OWNERSHIP_SCAN_BUDGET_MS,
-  maxBytes = OWNERSHIP_SCAN_MAX_BYTES,
-} = {}) {
-  if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return null;
-  let handle;
-  try {
-    handle = await fs.open(transcriptPath, 'r');
-    const deadline = Date.now() + budgetMs;
-    const chunk = Buffer.allocUnsafe(1024 * 1024);
-    let carry = '';
-    let total = 0;
-    const scanLine = (line) => {
-      // Cheap prefilter: skip JSON.parse for lines that cannot be evidence.
-      if (!line.includes('handoff-fullstack') && !line.includes('HANDOFF RESUME')) return false;
-      try { return entryShowsHandoffRun(JSON.parse(line)); } catch { return false; }
-    };
-    for (;;) {
-      const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
-      if (!bytesRead) return scanLine(carry);
-      total += bytesRead;
-      const lines = (carry + chunk.toString('utf8', 0, bytesRead)).split('\n');
-      carry = lines.pop() ?? '';
-      for (const line of lines) if (scanLine(line)) return true;
-      if (total >= maxBytes || Date.now() > deadline) return null;
-    }
-  } catch {
-    return null;
-  } finally {
-    try { await handle?.close(); } catch {}
-  }
+export async function transcriptShowsHandoffRun(transcriptPath, opts = {}) {
+  const mod = await loadHandoffIntentModule();
+  if (!mod || typeof mod.transcriptHandoffIntent !== 'function') return null;
+  const { intent, known } = await mod.transcriptHandoffIntent(transcriptPath, opts);
+  if (!known) return null;
+  return intent === 'fullstack';
 }
 
 /**
@@ -1015,8 +976,10 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   if (terminal === 'done' && !exitPredicate) return { kind: 'none' }; // legacy phase-only release
 
   // Session scope: a run owned by another session (or abandoned) must not
-  // hijack an unrelated session. Only a positive "scanned the whole transcript,
-  // no handoff evidence" releases; unknown (null) keeps the block.
+  // hijack an unrelated session, and a session whose CURRENT intent is planning
+  // must not be bounced into a stale run. Only a positive "scanned the whole
+  // transcript, latest intent is not fullstack" releases; unknown (null) keeps
+  // the block, so a real run is never released by a lost read.
   if (gate.scope === 'session' && await transcriptShowsHandoffRun(transcriptPath) === false) {
     return { kind: 'none' };
   }

package/template_project/docs/AI_HANDOFF/RULES.md

@@ -137,7 +137,8 @@ chạy **đến khi không còn gì để làm**:
   `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`, uncommitted WIP.
+  `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
@@ -146,6 +147,27 @@ chạy **đến khi không còn gì để làm**:
 - 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;
   muốn nối run cũ thì chạy `/ukit:handoff-fullstack`. Không đọc được transcript → giữ hành vi chặn cũ.
+- **Tách ý định — create CHỈ plan**: `/ukit:handoff-create` chỉ viết SPEC.md/PLAN.md/tasks, không sửa
+  code sản phẩm, không gọi executor, không tự escalate sang implement; plan dài cứ queue ở `ready`
+  chờ lệnh tường minh. Ý định handoff tính theo **lệnh gần nhất** trong transcript, chỉ từ structured
+  evidence của đúng host: Claude Code (`<command-name>` tag), omp (`message` role user có dòng đầu là
+  heading mở rộng `# /ukit:handoff-*`, và `custom_message` `ukit-hook-context`), Codex (`response_item`
+  message `input_text`). Format transcript lạ → trả `null` (không đoán), nên caller giữ nguyên thế
+  fail-closed. Kết quả: session vừa chạy create — kể cả khi trước đó từng chạy fullstack — có ý định hiện
+  tại là *planning*, nên Stop gate lẫn hook compact/resume đều không ép nó chạy lại `RUN.md` cũ.
+  `/ukit:handoff-fullstack` gọi tường minh sẽ giành lại quyền sở hữu và resume việc đã queue; run đang
+  implement vẫn bị ép hoàn tất. Không đọc được transcript → giữ hành vi cũ (nghiêng về block/resume),
+  không release nhầm run thật.
+- **Create không bao giờ ghi đè run sống**: `RUN.md` có `Phase:` ≠ `done`/`blocked` = run fullstack đang
+  sống. `/ukit:handoff-create` lúc đó KHÔNG được chạm `RUN.md`/`INDEX.md`/`PLAN.md`/`SPEC.md`/`ACTIVE.md`/
+  `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
+  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.
 - Phase F: docs sync (WORKLOG luôn; PROJECT/CODE_MAP/CHANGELOG khi đổi surface) →