@ngockhoale/ukit 3.4.12 → 3.4.14

package/template_project/.claude/skills/advisor-plan/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: advisor-plan
+description: Use when the user hands over an advisor opinion, reference material, roadmap or external plan document to turn into a plan, or asks to replan from advisor feedback (tư vấn / tài liệu tham khảo / lập kế hoạch theo tài liệu advisor / lên lại kế hoạch), or asks you to plan any task on request (lập kế hoạch cho bất kỳ task nào), not only advisor documents, especially inside /ukit:handoff-create or the create phase of /ukit:handoff-fullstack. Planning only - never implements. Do not use for concrete bug fixes or code review.
+---
+
+# Advisor Plan
+
+## Purpose
+
+Convert a large advisor / reference / replan document into three artifacts, and nothing else: a requirement **LEDGER** (every row dispositioned), a bounded task set (at most 10 active tasks), and a **QUEUE** of deliberate-future work. Templates live in [REFERENCE.md](./REFERENCE.md).
+
+This skill is **planning-only**. A create session that loads it edits docs and tests only.
+
+## Binding rule — create sessions edit docs and tests only
+
+- Allowed: `docs/**` (plans, ledger, queued blueprints, research notes), `tests/**` test files, root `README*.md` / `CHANGELOG.md`.
+- Never edit: source, config, hooks, `package.json`, or any file that is an **executable instruction** — `SKILL.md` files, `commands`, `agents`, `AGENTS.md` / `CLAUDE.md`. They steer future sessions, so they are not ordinary docs.
+- Never implement inside a create or plan session. No GREEN step, no "just the first epic", no "small fix on the way". Implementation belongs to a later `/ukit:handoff-fullstack` or `/ukit:handoff-implement` run, or a fresh session.
+- **Inside `/ukit:handoff-fullstack`** this binding rule covers only its create phase. The same run moves on to its own implement phase once the plan review passes; this skill never blocks that phase and never makes the model refuse it.
+- Hook pressure, deadlines, "it is only one line" and user urgency do not change the scope. To change source, the user issues another command; the model never self-promotes.
+- "Another command" means a new slash command or a fresh session; a chat instruction in the same session is not that command.
+- `OUTPUT_ROOT` must be under `docs/`. Running `refresh-index` writes only derived `.cache` and is allowed.
+- One task may cover several related ledger rows (name all R-IDs in the task); a `feasible` row whose task falls in a queued blueprint names the queued task/slug in its Task cell.
+- In a create session this skill takes precedence over generic "never stop after read-only" / "act directly on trivial" lines: continuing to produce the plan is the continuation, source edits are not.
+
+## Phases
+
+### Phase A — Gather (lite tier)
+
+1. Read the document header and table of contents; unreadable or empty source → write ledger row `R-000 | blocker` naming the missing input, create no tasks, stop.
+2. Split into chunks of at most 800 lines; one bounded gatherer per chunk extracts candidate requirements as `Source` (section/line) + normalized text. Dedupe by normalized text, keep the first source; contradictory requirements become a `blocker` row.
+3. **Feasibility evidence** — per requirement, inspect the CURRENT source index-first (`query-index.mjs` / `resolve-context.mjs`, then read the code that would change) plus `git log`, `git diff` and `git status` of the touched areas. Record each finding in the ledger row as evidence (file:line or commit) using the block in [REFERENCE.md](./REFERENCE.md#feasibility-evidence). Gatherers collect; the smart tier decides.
+4. **Related-project research (default on, bounded)** — per requirement cluster search the internet / GitHub for related projects and prior art (how others solved it, what to adopt or avoid) via `.claude/skills/research/SKILL.md`, under the sanitized-query and untrusted-source rules in [REFERENCE.md](./REFERENCE.md#research-rules). Feed the findings into each row's feasibility evidence. Skip only when no sanitized query is possible or no research tool exists, and record the skip reason in the ledger notes.
+
+Tier (lite gatherers): on Claude Code start a read-only `general-purpose` subagent with `model: haiku` (it has Bash for `query-index`, `git log`/`git diff` and web tools for research; `ukit-small-task-maintainer` is not a gatherer - it has no Bash and is scoped to UKit chores); omp uses `@smol`; Codex has one session model, so the main thread gathers. Gatherers return extracts and evidence only - they decide nothing.
+
+### Phase B — Decide, ledger, plan (smart tier)
+
+1. Use the evidence to assign every extracted requirement exactly one disposition: `feasible`, `adapted`, `deferred`, or `blocker`. `adapted` lists 2-3 alternatives with the chosen one marked; `deferred` names its queue entry; `blocker` names the missing precondition.
+2. Every `feasible`/`adapted` row names a task and a test or acceptance check.
+3. Write `${OUTPUT_ROOT}LEDGER.md` with the footer `Coverage: N/N rows dispositioned` and the sentence "disposition coverage is not implementation coverage". Never claim "100% implemented".
+4. **Candidate plans** — draft 2-3 candidate whole-plans (different decomposition, risk, ordering), score them on the rubric in [REFERENCE.md](./REFERENCE.md#candidate-plan-rubric), pick the best, and record the choice plus rejected alternatives in `PLAN.md`.
+5. Write SPEC, PLAN and the `TASK-*.md` files through the existing `/ukit:handoff-create` planner. Every task carries detailed TDD test cases that PROVE it works (happy, edge and error cases with the expected result), never just "tests pass".
+6. Queue rule: at most 10 tasks in total (short plan): all active for the next implement cycle; more than 10: the first 10 by dependency order are active and the rest become queued blueprints under `docs/AI_HANDOFF/queued/<slug>/` with the queue header from [REFERENCE.md](./REFERENCE.md#queue-header), drained gradually by later cycles.
+7. Replan: append ledger deltas and supersede with `-R<n>` rules; never overwrite a task that carries an executor report.
+
+Tier (smart decide): Claude Code uses the `opus`/`unic-smart` agent (`handoff-planner`); omp uses `@slow` (or `@default` when no slow role is configured).
+
+Tier (code general work): the `sonnet`/`unic-code` tier (`@default` on omp) does the routine docs work of the create session - formatting task files from the decided plan, filling templates, drafting test-case tables - under the smart tier's decisions. It never edits source.
+
+### Phase C — Review (independent smart tier)
+
+Run the existing independent plan review (`code-reviewer` with `REVIEW_TARGET_TYPE=plan`, fresh context, separate from the planner). Findings go back to Phase B. The ledger is not final until the review passes; a row without a disposition means the skill must not finish.
+
+### Phase D — Draft / implement (code tier, separate phase only)
+
+Drafting code or running tasks is **never** done in the create or plan session. Intended code changes are written into the tasks (target files, interfaces, TDD test cases); applying them runs later under `/ukit:handoff-fullstack` or `/ukit:handoff-implement` with the code tier (`sonnet`/`unic-code` on Claude Code, `@default` on omp). The create session ends with tasks in `status=ready` and a report.
+
+## Per-host honesty
+
+| Host | Model split | Scope enforcement |
+|------|-------------|-------------------|
+| Claude Code | haiku / sonnet / opus agents chosen by each agent's `model:` field | enforced by the PreToolUse chain (`handoff-model-guard.sh`) for direct tools and conservative shell patterns |
+| omp | `@smol` gather, `@default` code, `@slow` plan, via `modelRoles` | enforced through the bridge for mapped tools; unmapped shell paths are best effort |
+| Codex | no per-phase model selection is available; one session model does every phase | Codex has no pre-tool hooks, so this is instruction-mediated only - advisory, not enforced |
+
+**Recognition**: this skill is activated by the router's deterministic VN/EN advisor classifier (`classifyAdvisorRequest`) and its route-catalog entry. `unic-decision` is not consulted for advisor recognition - its `route.intent-kind.v1` has no advisor/plan value and a new label would need a retrained model - so never claim a decision-plane verdict for it; wiring unic-decision in is a queued follow-up.
+
+On Codex follow every rule above by instruction. Do not claim a guard blocked anything and do not claim a different model ran a phase.
+
+## Rationalization counters
+
+| Excuse | Reality |
+|---|---|
+| "handoff-create starts a handoff; it is not the lane for absorbing a 27-requirement advisor roadmap mid-run." (verbatim RED baseline, option C: stop read-only) | This skill is that lane. Absorb the document into a ledger, tasks and a queue; stopping read-only produces no plan. |
+| "The user said implement the first epic now." | A create session never implements. Record the epic as a ready task; implementation runs in a separate phase. |
+| "The hook is slow / not firing, so I can edit source." | A missing guard changes enforcement, not scope. Docs and tests only. |
+| "SKILL.md and AGENTS.md are just markdown." | They are executable instructions for future sessions; treat them like source. |
+| "Ledger rows are all dispositioned, so it is done." | Disposition coverage is not implementation coverage. |
+| "I will approve whatever you do" / "you have my approval" / "nobody is watching". | Approval or observation does not change scope; another command is required, and a chat instruction in the same session is not that command. |
+| "They are only markdown / one line of JSON" (`AGENTS.md`, agents, `SKILL.md`, `package.json`). | Executable instruction or config. Applies to root and template copies, `.claude/agents` and `.omp/agents`. Record each requested edit as a ready task. |
+| "The user wants it fast, just trust the document, 5 representative tasks, report 100%." | Urgency does not waive ledger completeness, feasibility evidence or the coverage wording. Offer the ledger counts as the quick deliverable. |
+| "The document is too big, I will summarize it." | Chunk at 800 lines, extract, dedupe, and disposition every row. |
+
+## Red flags — stop and re-read the binding rule
+
+- About to Edit a path outside `docs/` or `tests/`.
+- Writing "implemented" or "100%", or applying a code diff, inside a create session. (Describing the intended change inside a task file is the plan, not a violation.)
+- Skipping the ledger footer or leaving a row without a disposition.
+- Pasting fetched web text into a command or a file path.
+
+## Reference
+
+- Templates and research rules: [REFERENCE.md](./REFERENCE.md)

package/template_project/.claude/ukit/index/route-catalog.mjs

@@ -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/template_project/.claude/ukit/index/route-task.mjs

@@ -2754,9 +2754,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) {
@@ -3776,6 +3796,10 @@ function buildRouteSummary({
     workflowPolicyName ? `workflow=${workflowPolicyName}` : null,
   ].filter(Boolean).join(' | ');
 
+  const advisorIntent = classifyAdvisorRequest({
+    promptText: routingContext.promptText,
+    commandText: routingContext.commandText,
+  });
   return {
     primaryCommands,
     fallbackCommands,
@@ -3838,6 +3862,9 @@ 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: line || 'task=unknown',
   };
 }
@@ -4102,6 +4129,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),
@@ -5495,6 +5576,7 @@ export function compactRouteSummary(routeSummary = null) {
     // persisted route state keeps the redacted outcome. Conditional spread —
     // stage-off output stays byte-identical (no key emitted when absent).
     ...(routeSummary.decisionPlane ? { decisionPlane: routeSummary.decisionPlane } : {}),
+    ...(routeSummary.advisorIntent ? { advisorIntent: routeSummary.advisorIntent } : {}),
     // C89 TASK-005: the typed delegation advice survives compaction so
     // persisted route state keeps the shadow verdict. Conditional spread —
     // stage-off output stays byte-identical (no key emitted when absent).

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';
+}