@ngockhoale/ukit 3.4.12 → 3.4.14

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.14 - 2026-10-04
+
+**New `advisor-plan` skill, a create-session write-scope guard, and a deliberate-future queue contract.**
+`advisor-plan` turns an advisor opinion, reference document, roadmap or replan request
+into a plan and nothing else (planning-only; it never implements). It builds a requirement
+LEDGER where every row is dispositioned (`feasible`/`adapted`/`deferred`/`blocker`),
+backed by feasibility evidence read from the current source and `git log`/`diff`/`status`;
+drafts 2-3 candidate plans and scores them before picking one; gives every task detailed
+TDD test cases (happy, edge, error) instead of "tests pass"; and applies a queue
+threshold — at most 10 active tasks, the rest become queued blueprints. Ledger coverage
+means rows dispositioned, not implemented.
+
+- **Create write-scope guard.** While a session's latest handoff intent is `create`
+  (`/ukit:handoff-create`), `handoff-model-guard.sh` (`createScopeVerdict`) allows docs
+  and test files only and blocks source/config/hook/agent/skill/command/`AGENTS.md`
+  writes. Claude Code is enforced through the PreToolUse `Edit|Write` and `Bash` chains;
+  omp is enforced for the tools its bridge maps (`apply_patch`/`ast_edit` → `Edit`);
+  Codex has no pre-tool hooks, so the scope is advisory only (instruction-mediated) and
+  is not enforced. Patch-body edits (`*** Update File:`, unified-diff headers) are parsed
+  for their targets. Known gaps: the shell check is a regex, not a parser, so writes via
+  `node -e`, `python -c`, `ruby -e`, `wget -O`, `tar -x`, `unzip`, `git pull|switch|worktree add`, git aliases, `eval`/`bash -c` indirection and similar slip through, and a `>` or
+  the word `install` in an argument can block a harmless command; a missing transcript
+  fails open silently and an inconclusive intent scan fails open with a systemMessage.
+  Kill switch: `handoff.createScopeGuard`.
+- **Automatic routing.** A deterministic EN/VN classifier (`classifyAdvisorRequest`, three
+  identical copies) force-loads `advisor-plan` into the first active-skill slot for advisor /
+  reference / replan hand-offs and explicit "plan this task" requests; implementation orders
+  that merely mention a plan or advisor do not load it. Known gap: `unic-decision` is not
+  consulted for this recognition (its `route.intent-kind.v1` has no advisor value); wiring it
+  in is queued follow-up work.
+- **Deliberate-future queue.** Queued blueprints under `docs/AI_HANDOFF/queued/<slug>/`
+  may carry `QueueIntent: deliberate-future`, `QueueOrder`, `QueueDrain` and
+  `QueueSource` in their `HANDOFF.md` header. `/ukit:handoff-fullstack` reports them as
+  `Backlog: <slug>` instead of folding them into the current cycle (an explicit slug
+  drains one); blueprints without the header keep the legacy fold-in behaviour. No new
+  INDEX status was added.
+- **Route catalog.** `advisor-plan` (order 12.15) with a matching `advisor-plan-skill`
+  manifest item. `classifyAdvisorRequest` stamps `advisorIntent` (`advisor` | `reference` |
+  `replan`) on the route summary in English and Vietnamese (diacritics folded; "advisory
+  lock", "legal advisor" and bug-fix-verb prompts stay null); mirrored in `taskRouting.js`,
+  `route-task.mjs` and `skill-router.sh`.
+- Docs: `docs/HOST_CAPABILITY_MATRIX.md` gains a per-host "Create write-scope guard
+  (C94)" note; `STATUS.md`, `CODE_MAP.md` and `skill-audits/advisor-plan/` updated.
+  Tests: `advisorPlanSkill`, `createScopeGuard`, `advisorReleaseDocs`, `advisorIntentRouting`,
+  `advisorStatusDocs`, `routeCatalog`.
+
+## 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/manifests/documentation.yaml

@@ -405,6 +405,16 @@ entries:
     load_policy: never
     validation: [none]
     archive_policy: immutable
+  - id: docs-skill-audits
+    path: docs/skill-audits/
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/skill-audits/
+    merge_strategy: none
+    load_policy: never
+    validation: [none]
+    archive_policy: immutable
 
   # ── template_project/ canonical authoring sources ───────────────────────────────
   - id: tpl-claude-md

package/manifests/platform.full.yaml

@@ -555,6 +555,19 @@ items:
     packs:
       - core
 
+  - id: advisor-plan-skill
+    type: skill
+    sourceTemplate: .claude/skills/advisor-plan
+    targetPath: .claude/skills/advisor-plan
+    requires:
+      - docs-quality-skill
+      - docs-ai-handoff
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: docs-manager-skill
     type: skill
     sourceTemplate: .claude/skills/docs-manager

package/package.json

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

package/src/index/routeCatalog.js

@@ -237,6 +237,24 @@ export const ROUTE_CATALOG = [
       { type: 'prompt', regex: /(?<![A-Za-z0-9_])(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)(?![A-Za-z0-9_])/i, score: 7 },
     ],
   },
+  {
+    id: 'advisor-plan',
+    path: '.claude/skills/advisor-plan/SKILL.md',
+    order: 12.15,
+    contextMode: 'standalone',
+    signals: [
+      { type: 'prompt', regex: /\b(?:advis[eo]r)(?:'s|s)?\s+(?:\w+\s+){0,3}(?:docs?|documents?|opinions?|feedback|notes?|plans?|roadmaps?|recommendations?|reports?)\b/i, score: 9 },
+      { type: 'prompt', regex: /\b(?:turn|convert|translate|break(?: down)?|distill)\b.{0,48}\b(?:roadmap|reference|advis[eo]r|external plan)\b.{0,48}\b(?:into|to)\b.{0,16}\b(?:plan|tasks?|ledger)\b/i, score: 9 },
+      { type: 'prompt', regex: /\b(?:roadmap|reference|external plan)\s+(?:material|docs?|documents?)\b.{0,48}\bplan\b/i, score: 9 },
+      { type: 'prompt', regex: /\bplan(?:ning)?\s+(?:from|using|based on|per|according to)\b.{0,48}\b(?:reference|roadmap|advis[eo]r|external|document)\b/i, score: 9 },
+      { type: 'prompt', regex: /\b(?:replan|re-plan|plan again)\b.{0,60}\b(?:advis[eo]r|feedback|documents?|reference|roadmap)\b/i, score: 7 },
+      { type: 'prompt', regex: /\b(?:planning[- ]only|plan[- ]only|plan (?:any|this|the|a) (?:task|feature|work).{0,48}(?:do not|don't|without|never) implement\w*)\b/i, score: 7 },
+      { type: 'prompt', regex: /\bplan\s+(?:this|these|the following)\s+(?:task|tasks|work|request|feature)\b/i, score: 7 },
+      { type: 'prompt', regex: /(?<![A-Za-z0-9_])(?:lập kế hoạch|lap ke hoach|lên kế hoạch|len ke hoach)\s+cho\s+(?:task|việc|viec|tính năng|tinh nang|yêu cầu|yeu cau|feature)(?![A-Za-z0-9_])/i, score: 7 },
+      { type: 'prompt', regex: /(?<![A-Za-z0-9_])(?:lập kế hoạch|lap ke hoach|lên lại kế hoạch|len lai ke hoach|lên kế hoạch lại|len ke hoach lai).{0,60}(?:tài liệu|tai lieu|tư vấn|tu van|advisor|tham khảo|tham khao|roadmap)/i, score: 9 },
+      { type: 'prompt', regex: /(?<![A-Za-z0-9_])(?:tài liệu tư vấn|tai lieu tu van|tư vấn của advisor|tu van cua advisor|lên lại kế hoạch|len lai ke hoach|lập kế hoạch cho bất kỳ task nào|lap ke hoach cho bat ky task nao)/i, score: 7 },
+    ],
+  },
   {
     id: 'update-status',
     path: '.claude/skills/update-status/SKILL.md',

package/src/index/taskRouting.js

@@ -755,6 +755,10 @@ export function buildRouteSummary({
   const modelRolesBlock = MODEL_ROLES_DELEGATING_MODES.has(executionMode)
     ? formatModelRolesBlock(modelRolesResolution.roles)
     : null;
+  const advisorIntent = classifyAdvisorRequest({
+    promptText: routingContext.promptText,
+    commandText: routingContext.commandText,
+  });
   const summaryLine = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
     handoffFile ? `handoff=${handoffFile}` : null,
@@ -832,6 +836,9 @@ export function buildRouteSummary({
     // only when subagentOrchestrator.roleAdvice.stage != 'off' (conditional
     // spread keeps the stage-off route byte-identical).
     ...(delegationAdvice ? { delegationAdvice } : {}),
+    // FR-004 additive field — present only when the prompt is an advisor/reference/replan
+    // request, so every other route stays byte-identical.
+    ...(advisorIntent ? { advisorIntent } : {}),
     line: summaryLine || 'task=unknown',
   };
 }
@@ -1106,6 +1113,60 @@ function hasAdvisoryOnlyAssertion({ promptText = '', commandText = '' } = {}) {
   const mutationOrder = /(?<![A-Za-z0-9_])(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\s+the|cap\s+nhat|viet|chay|cai|chinh|trien\s+khai|cau\s+hinh)(?![A-Za-z0-9_])/.test(residue);
   return !mutationOrder;
 }
+// <advisor-intent:begin>
+// FR-004: an advisor/reference/replan request hands over a document or roadmap
+// and wants a plan back (the advisor-plan route). Deterministic, no I/O.
+// Every kind needs plan/document context, so "advisory lock", "hang-advisory",
+// a "legal advisor" label or "replan the SQL index" stay null. Three copies
+// (taskRouting.js, route-task.mjs, skill-router.sh) — keep them identical.
+export function classifyAdvisorRequest({ promptText = '', commandText = '' } = {}) {
+  const folded = `${promptText ?? ''}\n${commandText ?? ''}`
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/\u0111/g, 'd')
+    .trim();
+  if (!folded) return null;
+  // A prompt that opens with a bug-fix/edit verb is a code change, not a plan request.
+  if (/^(?:please\s+|pls\s+)?(?:fix|debug|rename|remove|delete|refactor|edit|sua\s+loi|xoa|doi\s+ten)(?![a-z0-9_])/.test(folded)) return null;
+  const text = folded.replace(/\b(?:legal|financial|tax|investment|academic|career|mortgage)\s+advisors?\b/g, ' ');
+  const PLAN = '(?:plans?|planning|ke\\s+hoach|phuong\\s+an|lo\\s+trinh|roadmaps?|blueprints?|specs?)';
+  const hasPlan = new RegExp(`\\b${PLAN}\\b`).test(text);
+  const hasDoc = /\b(?:tai\s+lieu|documents?|docs?|feedback|gop\s+y)\b|\.md\b/.test(text);
+  const replanToken = /\bre-?plan(?:ning|ned)?\b/;
+  if ((replanToken.test(text)
+      && new RegExp(`\\b(?:advisors?|feedback|gop\\s+y|reference|handoff(?:-create)?|backlog|${PLAN})\\b`).test(text.replace(replanToken, ' ')))
+    || /\b(?:lap|len|vach|xay\s+dung)\s+lai\s+(?:ke\s+hoach|plan|phuong\s+an|lo\s+trinh|roadmap)\b/.test(text)
+    || /\b(?:revise|rework|redo|rewrite)\s+(?:(?:the|this|my|our|that)\s+)?(?:plan|roadmap)\b/.test(text)) {
+    return 'replan';
+  }
+  // An explicit "plan this task" order stands on its own; the document kinds below
+  // are gated so an implementation order that merely mentions a plan, spec, doc or
+  // advisor ("implement the plan from the spec") stays null. Plan-making verbs
+  // ("create a plan", "handoff-create") are not implementation orders.
+  if (/\bplan\s+(?:this|these|the\s+following)\s+(?:task|tasks|work|request|feature)\b/.test(text)
+    || /\b(?:lap|len)\s+ke\s+hoach\s+cho\s+(?:(?:task|viec|yeu\s+cau)\s+nay|task|viec|tinh\s+nang|yeu\s+cau|feature)\b/.test(text)) {
+    return 'advisor';
+  }
+  const orderText = text
+    .replace(/\bhandoff-create\b/g, ' handoff ')
+    .replace(/\b(?:create|build|make|write|draft|produce|generate|tao|viet|soan|lap)\s+(?:(?:a|an|the|me|my|our|one|new|detailed|full|giup|cho|toi|ra)\s+){0,3}(?:plans?|roadmaps?|blueprints?|specs?|ke\s+hoach|phuong\s+an|lo\s+trinh)\b/g, ' ');
+  if (hasMutationOrder({ promptText: orderText })) return null;
+  if ((/\badvisors?\b/.test(text) && (hasPlan || hasDoc || /\bhandoff-create\b/.test(text)))
+    || (/\b(?:tu|co)\s+van\b(?!\s+de\b)/.test(text) && (hasPlan || /\btai\s+lieu\b|\bhandoff-create\b/.test(text)))
+    || (/\bhandoff-create\b/.test(text) && (hasPlan || hasDoc))) {
+    return 'advisor';
+  }
+  if (/\breference\s+(?:docs?|documents?|roadmaps?|plans?|specs?|material|brief)\b/.test(text)
+    || /\b(?:roadmap|plan|spec|document|doc)\s+(?:as|for)\s+(?:a\s+|the\s+)?reference\b/.test(text)
+    || (/\btai\s+lieu\s+tham\s+khao\b/.test(text) && hasPlan)
+    || /\b(?:plan|ke\s+hoach)\b[^.\n]{0,40}\b(?:from|based\s+on|according\s+to|theo|dua\s+(?:tren|vao))\s+(?:(?:this|the|a|nay)\s+)?(?:roadmap|spec|brief|document|doc|tai\s+lieu)\b/.test(text)) {
+    return 'reference';
+  }
+  return null;
+}
+// <advisor-intent:end>
+
 // C85-019: mutation vocabulary ≠ mutation order. The same residue logic the
 // advisory gate uses — quotes, negated clauses, conditionals (nếu/để/cho/if),
 // reported demands (yêu cầu/ép/requires), necessity phrases (cần được/must be),
@@ -1529,9 +1590,29 @@ async function selectActiveSkills({ rootDir, promptText, commandText, targetFile
     .filter((entry) => entry.score > 0)
     .filter((entry) => shouldKeepRouteEntryForIntent(entry, intentMode))
     .sort((a, b) => b.score - a.score || a.order - b.order);
+  // FR-004: a classified advisor/reference/replan hand-off always loads
+  // advisor-plan, even when no catalog signal fired. It takes the FIRST of the
+  // MAX_ACTIVE_ROUTE_SKILLS slots; the best-scoring other route fills the second.
+  const advisorKind = classifyAdvisorRequest({ promptText, commandText });
+  const advisorCatalogEntry = advisorKind
+    ? ROUTE_CATALOG.find((entry) => entry.id === 'advisor-plan')
+    : null;
+  // A catalog-only advisor-plan hit on an implementation order ("implement the
+  // advisor plan in docs/plan.md") must not load a planning-only skill.
+  const dropCatalogAdvisor = !advisorKind
+    && hasMutationOrder({ promptText, commandText })
+    && !/\b(?:planning[- ]only|plan[- ]only)\b|\b(?:turn|convert|translate|break(?: down)?|distill)\b.{0,48}\b(?:into|to)\b.{0,16}\b(?:plan|tasks?|ledger)\b/i.test(String(promptText ?? ''));
+  const candidates = advisorCatalogEntry
+    ? [
+        scoreSkillRouteEntry(advisorCatalogEntry, routeSignals),
+        ...scoredEntries.filter((entry) => entry.id !== 'advisor-plan'),
+      ]
+    : dropCatalogAdvisor
+      ? scoredEntries.filter((entry) => entry.id !== 'advisor-plan')
+      : scoredEntries;
   const active = [];
 
-  for (const entry of scoredEntries) {
+  for (const entry of candidates) {
     if (await pathExists(path.join(rootDir, entry.path))) {
       active.push(entry);
       if (active.length >= MAX_ACTIVE_ROUTE_SKILLS) {

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

@@ -14,6 +14,103 @@ $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`.
+
+### Write scope — documentation and tests only
+
+This command may add or update **documentation** (`docs/**`, root `README*.md` /
+`CHANGELOG.md`) and **tests**/testing files only. Inside `docs/` the guard still denies
+script extensions (`docs/**/*.{sh,js,mjs,cjs,ts,py}`), any path with a hidden segment
+(`docs/.x/...`) and extensions outside the doc allowlist (`.md .mdx .txt .json .yaml .yml
+.png .svg`; e.g. `.html` is denied) — plan those as prose or a `.md` file instead. Under
+`tests/` the guard likewise denies shell/runtime extensions (`.sh .ps1 .cmd ...`) and hidden segments. It must **never** edit source, config,
+hooks, `package.json`, skills, commands, agents, or `AGENTS.md` / `CLAUDE.md` — those are
+executable instructions for future sessions. There is no GREEN step and no escalation into
+implementation: urgency, hook friction or "just one line" do not widen the scope; changing
+source takes another command from the human.
+
+Guard strength per host: **Claude Code** and **omp** enforce this through the PreToolUse
+chain (omp via its bridge; unmapped shell paths are best effort). The guard checks the target
+path of Write/Edit/MultiEdit/NotebookEdit and the file headers inside an `apply_patch` /
+unified-diff body (`*** Add|Update|Delete File:`, `*** Move to:`, `diff --git`, `---`/`+++`);
+a patch-like body with no parseable path is denied. Shell commands are a regex check, not a
+parser: `node -e`, `python -c` and similar interpreter one-liners are an accepted gap. **Codex** has no pre-tool
+hooks, so the rule is advisory there — instruction-mediated only. Codex also has no per-phase
+model selection: never claim a guard blocked anything, or that a different model ran a phase.
+
+### Advisor intake — large advisor / reference / replan documents
+
+When the router flags advisor, reference-document or replan intent (or the human asks to plan
+any task on request), load the `advisor-plan` skill; it adds no new slash command. It turns
+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.
+- **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
+  the rejected ones in `PLAN.md`. Every task carries detailed TDD test cases (happy, edge,
+  error with expected results) that prove it works.
+- **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`.
+- **Queue threshold:** at most 10 tasks in total: all active (`ready`). More than 10: the
+  first 10 by dependency order are active and the rest become queued blueprints under
+  `docs/AI_HANDOFF/queued/<slug>/` whose `HANDOFF.md` header carries
+  `QueueIntent: deliberate-future`. Queue contract: the header also carries `QueueOrder: <int>`
+  (drain order, lowest first), `QueueDrain: separate-backlog` and `QueueSource: <R-IDs/epics>`;
+  `/ukit:handoff-fullstack` reports such a blueprint as `Backlog: <slug>`, never folds it into
+  the current cycle, and drains it only when the human names the slug (one blueprint per invocation).
+
+Model split on Claude Code: haiku/`unic-lite` gathers, opus/`unic-smart` decides, and
+sonnet/`unic-code` implements later; omp maps these to `@smol`/`@slow`/`@default`.
+
 ---
 
 ## Question Policy — this is the one phase that may ask
@@ -47,7 +144,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 +153,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 +175,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 +189,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 +203,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 +214,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 +229,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 +247,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 +257,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,29 @@ 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.
+   Blueprints WITHOUT the `QueueIntent` metadata are still folded in as described above.
+   A blueprint whose header carries `QueueIntent: deliberate-future` is the exception: it is
+   **not folded** in; report it as `Backlog: <slug>` and leave it untouched.
+   Backlog items do not count toward `index:all-done` / `ExitPredicate`, so they never block completion. Only
+   an explicit slug in the invocation drains one (one blueprint per invocation). The
+   create phase of this command applies the same advisor intake as `/ukit:handoff-create`.
+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