@ngockhoale/ukit 3.4.12 → 3.4.14

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) →