@ngockhoale/ukit 3.0.3 → 3.0.5

package/template_project/.claude/ukit/runtime/resumable-run.mjs

@@ -0,0 +1,596 @@
+#!/usr/bin/env node
+// TASK-006 (C52 M04.1, SPEC §5 FR-012..FR-014): the compact resumable run record
+// (C10). One versioned, bounded, redacted record per taskId persisted under
+// `.ukit/storage/runs/<safeTaskId>.json` so a compacted/interrupted run can
+// resume phase/nextAction/hypotheses without rereading master docs.
+//
+// Persistence reuses the ledger's fail-closed discipline (TASK-027): every write
+// goes through withAsyncLock with a bounded deadline; on timeout/abort the record
+// is journaled to `<target>.journal` (JSONL, bounded, newest-wins snapshots) and
+// NEVER written unlocked — the next acquired lock drains the journal first and
+// lands the newest record in one atomic tmp+rename write.
+//
+// Freshness: `sourceSnapshot` carries source/index/config FINGERPRINTS (never
+// file copies). A material change on read marks the record `stale` and
+// selectively invalidates dependent plans (hypotheses/nextAction, decisions on
+// config change) while completed receipts (evidenceRefs, workflow.completedBlocks)
+// are kept. Corrupt state degrades to `invalid` with one concrete warning.
+//
+// Dual-read tolerance: unknown/newer fields are ignored by readers and preserved
+// by validation; records with a higher schemaVersion still validate so an older
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { withAsyncLock, LOCK_MAX_SLICE_MS } from './async-lock.mjs';
+import { scanText } from './sensitive-value-scanner.mjs';
+import { buildRuntimePaths, readJson } from './token-utils.mjs';
+
+// Deadline policy lives at the hook entry point (reinject-context.mjs arms
+// UKIT_HOOK_DEADLINE_MS and announces via §8 systemMessage). A library module
+// must never arm its own process.exit timer at import time — it raced the
+// importer's announcing deadline and produced silent exit-0 (BUG-C23-04 class).
+
+export const RESUMABLE_RUN_SCHEMA_VERSION = 1;
+
+// C10 bounds (SPEC §7): hypotheses ≤8, decisions ≤12, evidenceRefs ≤24,
+// escalationHistory ≤8. invariants/unresolvedFailures/completedBlocks get the
+// same bounded treatment so the record can never grow without limit.
+const ARRAY_BOUNDS = {
+  invariants: 16,
+  hypotheses: 8,
+  decisions: 12,
+  evidenceRefs: 24,
+  escalationHistory: 8,
+  unresolvedFailures: 8,
+};
+const MAX_COMPLETED_BLOCKS = 32;
+const MAX_STRING_LENGTH = 512;
+const MAX_SNAPSHOT_KEYS = 16;
+const MAX_SERIALIZED_BYTES = 64 * 1024;
+const RUN_JOURNAL_MAX_RECORDS = 32;
+const RUN_JOURNAL_LOCK_BUDGET_MS = 400;
+
+// Redaction: a record must never carry prompt bodies, source text, or secrets.
+// Key names are matched normalized (lowercase, separators stripped) so
+// `promptText`, `prompt_text`, `api-key` all hit the same rule. `token` alone is
+// deliberately absent — budget fields legitimately count tokens; the value
+// scanner below still catches real secret VALUES anywhere in the record.
+const FORBIDDEN_KEY_NAMES = new Set([
+  'prompt', 'prompttext', 'rawprompt', 'userprompt', 'systemprompt',
+  'secret', 'password', 'passwd', 'credential', 'credentials',
+  'apikey', 'apisecret', 'accesstoken', 'authtoken', 'refreshtoken',
+  'sessiontoken', 'bearertoken', 'privatekey', 'signingkey',
+  'sourcetext', 'sourcecode', 'rawsource', 'filecontent', 'filecontents',
+]);
+
+// Selective invalidation map (FR-014): a material source/index change invalidates
+// plan-shaped sections only; a config change additionally invalidates decisions.
+// Completed receipts (evidenceRefs, workflow.completedBlocks) are never touched —
+// they are facts, not plans.
+const INVALIDATION_CODES = {
+  plans: ['hypotheses', 'nextAction'],
+  decisions: ['decisions'],
+  receipts: ['evidenceRefs'],
+  escalations: ['escalationHistory'],
+  failures: ['unresolvedFailures'],
+};
+const CHANGED_KEY_TO_CODES = {
+  source: ['plans'],
+  index: ['plans'],
+  config: ['plans', 'decisions'],
+};
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Filesystem-safe taskId segment: strips path separators, traversal dots, and
+// control characters; bounded length so the filename stays portable.
+export function safeTaskId(taskId) {
+  const cleaned = String(taskId ?? '')
+    .replace(/[\\/]/g, '_')
+    .replace(/\.+/g, '_')
+    .replace(/[^A-Za-z0-9._-]/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 80);
+  return cleaned || 'task';
+}
+
+export function resumableRunPath(projectRoot, taskId) {
+  return path.join(
+    buildRuntimePaths(projectRoot).storageRoot,
+    'runs',
+    `${safeTaskId(taskId)}.json`,
+  );
+}
+
+function runJournalPathFor(target) {
+  return `${target}.journal`;
+}
+
+// --- validation ---------------------------------------------------------------
+
+function collectRedactionErrors(value, pathLabel, errors) {
+  if (typeof value === 'string') {
+    if (value.length > MAX_STRING_LENGTH) {
+      errors.push(`${pathLabel} exceeds the ${MAX_STRING_LENGTH}-char bound.`);
+    }
+    const scan = scanText(value);
+    if (scan.hasSecret) {
+      errors.push(`${pathLabel} carries a secret-shaped value (${scan.labels.join(', ')}).`);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => collectRedactionErrors(item, `${pathLabel}[${index}]`, errors));
+    return;
+  }
+  if (isPlainObject(value)) {
+    for (const [key, child] of Object.entries(value)) {
+      const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, '');
+      const childPath = pathLabel ? `${pathLabel}.${key}` : key;
+      if (FORBIDDEN_KEY_NAMES.has(normalized)) {
+        errors.push(`${childPath} is a forbidden field (prompt/secret/source-shaped).`);
+        continue; // do not descend — the field itself is the violation
+      }
+      collectRedactionErrors(child, childPath, errors);
+    }
+  }
+}
+
+function requireObjectField(record, field, shape, errors) {
+  const value = record[field];
+  if (!isPlainObject(value)) {
+    errors.push(`${field} must be an object.`);
+    return;
+  }
+  for (const [subField, kind] of Object.entries(shape)) {
+    const sub = value[subField];
+    if (kind === 'string' && typeof sub !== 'string') {
+      errors.push(`${field}.${subField} must be a string.`);
+    } else if (kind === 'number' && (typeof sub !== 'number' || !Number.isFinite(sub))) {
+      errors.push(`${field}.${subField} must be a finite number.`);
+    } else if (kind === 'string[]' && (!Array.isArray(sub) || sub.some((v) => typeof v !== 'string'))) {
+      errors.push(`${field}.${subField} must be an array of strings.`);
+    }
+  }
+}
+
+/**
+ * Validate a C10 record. Returns { valid, errors } — errors name the offending
+ * field and the violated bound. Unknown fields are tolerated (dual-read), but
+ * every known field must be well-typed, bounded, and free of prompt/secret
+ * material.
+ */
+export function validateResumableRun(record) {
+  const errors = [];
+  if (!isPlainObject(record)) {
+    return { valid: false, errors: ['record must be a plain object.'] };
+  }
+
+  if (!Number.isInteger(record.schemaVersion) || record.schemaVersion < 1) {
+    errors.push('schemaVersion must be an integer >= 1.');
+  }
+  if (typeof record.taskId !== 'string' || record.taskId.length === 0) {
+    errors.push('taskId must be a non-empty string.');
+  }
+  if (typeof record.taskBoundary !== 'string' || record.taskBoundary.length === 0) {
+    errors.push('taskBoundary must be a non-empty string.');
+  }
+
+  requireObjectField(record, 'route', {
+    routeVersion: 'string',
+    mode: 'string',
+    rigor: 'string',
+    contractVersion: 'string',
+  }, errors);
+  requireObjectField(record, 'budget', {
+    policyVersion: 'string',
+    consumed: 'number',
+    remaining: 'number',
+  }, errors);
+  requireObjectField(record, 'workflow', {
+    workflowId: 'string',
+    workflowVersion: 'string',
+    phase: 'string',
+    completedBlocks: 'string[]',
+  }, errors);
+  if (Array.isArray(record.workflow?.completedBlocks)
+    && record.workflow.completedBlocks.length > MAX_COMPLETED_BLOCKS) {
+    errors.push(`workflow.completedBlocks exceeds the ${MAX_COMPLETED_BLOCKS}-entry bound.`);
+  }
+
+  for (const [field, bound] of Object.entries(ARRAY_BOUNDS)) {
+    const value = record[field];
+    if (!Array.isArray(value)) {
+      errors.push(`${field} must be an array.`);
+      continue;
+    }
+    if (value.length > bound) {
+      errors.push(`${field} exceeds the ${bound}-entry bound (${value.length} entries).`);
+    }
+  }
+
+  if (record.nextAction !== null && typeof record.nextAction !== 'string') {
+    errors.push('nextAction must be a string or null.');
+  }
+
+  // sourceSnapshot = fingerprints, not file copies: flat string→string map only.
+  if (!isPlainObject(record.sourceSnapshot)) {
+    errors.push('sourceSnapshot must be an object of fingerprints.');
+  } else {
+    const entries = Object.entries(record.sourceSnapshot);
+    if (entries.length > MAX_SNAPSHOT_KEYS) {
+      errors.push(`sourceSnapshot exceeds the ${MAX_SNAPSHOT_KEYS}-key bound.`);
+    }
+    for (const [key, value] of entries) {
+      if (typeof value !== 'string') {
+        errors.push(`sourceSnapshot.${key} must be a fingerprint string, not a file copy.`);
+      }
+    }
+  }
+
+  collectRedactionErrors(record, '', errors);
+
+  if (errors.length === 0) {
+    try {
+      const size = Buffer.byteLength(JSON.stringify(record), 'utf8');
+      if (size > MAX_SERIALIZED_BYTES) {
+        errors.push(`record exceeds the ${MAX_SERIALIZED_BYTES}-byte serialized bound.`);
+      }
+    } catch {
+      errors.push('record is not serializable.');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// --- persistence ---------------------------------------------------------------
+
+async function readStageConfig(projectRoot) {
+  const config = await readJson(buildRuntimePaths(projectRoot).configPath, null);
+  const stage = config?.continuity?.resumableRun?.stage;
+  return typeof stage === 'string' ? stage : 'off';
+}
+
+let atomicWriteCounter = 0;
+
+async function writeJsonAtomic(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${atomicWriteCounter++}`;
+  try {
+    await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    try {
+      await fs.rename(tempPath, filePath);
+    } catch (renameError) {
+      // EXDEV: tmp and destination on different mounts — copy over and unlink.
+      if (renameError?.code !== 'EXDEV') throw renameError;
+      await fs.copyFile(tempPath, filePath);
+      await fs.rm(tempPath, { force: true });
+    }
+  } catch (error) {
+    try {
+      await fs.rm(tempPath, { force: true });
+    } catch {
+      // best-effort cleanup
+    }
+    throw error;
+  }
+}
+
+// Append a dropped record to the per-target JSONL journal under a journal-local
+// lock (the record lock is unavailable — that is why this path runs). Bounded:
+// snapshots are newest-wins, so a full journal trims the oldest entries rather
+// than rejecting the newest state.
+async function appendRunJournal(target, record) {
+  const journalPath = runJournalPathFor(target);
+  try {
+    const outcome = await withAsyncLock(
+      journalPath,
+      { deadlineMs: RUN_JOURNAL_LOCK_BUDGET_MS },
+      async () => {
+        let lines = [];
+        try {
+          lines = (await fs.readFile(journalPath, 'utf8'))
+            .split('\n')
+            .filter((line) => line.trim());
+        } catch (error) {
+          if (error?.code !== 'ENOENT') return false;
+        }
+        lines.push(JSON.stringify({ v: 1, ts: Date.now(), record }));
+        if (lines.length > RUN_JOURNAL_MAX_RECORDS) {
+          lines = lines.slice(lines.length - RUN_JOURNAL_MAX_RECORDS);
+        }
+        await fs.writeFile(journalPath, `${lines.join('\n')}\n`, 'utf8');
+        return true;
+      },
+    );
+    return outcome?.ok === true && outcome.value === true;
+  } catch {
+    return false; // journaling is best-effort; never resurrect the write over it
+  }
+}
+
+// Read every journaled record for this target. A torn trailing line is skipped,
+// never applied — the next lock retries it only if the writer journaled again.
+async function drainRunJournal(target) {
+  const journalPath = runJournalPathFor(target);
+  let text;
+  try {
+    text = await fs.readFile(journalPath, 'utf8');
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (isPlainObject(parsed?.record)) records.push(parsed.record);
+    } catch {
+      // torn line — skip
+    }
+  }
+  return records;
+}
+
+function recordTimestamp(record) {
+  return Number.isFinite(record?.updatedAt) ? record.updatedAt : 0;
+}
+
+/**
+ * Persist a C10 record. Fail-closed: invalid or redacted-failing records are
+ * never written; a busy lock journals the record instead of writing unlocked.
+ * Gated on `continuity.resumableRun.stage` (absence = off) unless the caller
+ * injects `{ config }` — wiring (TASK-007) passes the resolved stage.
+ *
+ * @returns {Promise<{ok:true, path:string} | {ok:false, reason:string, journaled?:boolean, errors?:string[]}>}
+ */
+export async function writeResumableRun(projectRoot, record, {
+  signal,
+  deadlineMs = LOCK_MAX_SLICE_MS,
+  config,
+} = {}) {
+  const stage = config !== undefined
+    ? (config?.continuity?.resumableRun?.stage ?? 'off')
+    : await readStageConfig(projectRoot);
+  if (stage === 'off' || typeof stage !== 'string') {
+    return { ok: false, reason: 'stage-off' };
+  }
+
+  const validation = validateResumableRun(record);
+  if (!validation.valid) {
+    return { ok: false, reason: 'invalid', errors: validation.errors };
+  }
+
+  const target = resumableRunPath(projectRoot, record.taskId);
+  const stamped = {
+    ...record,
+    schemaVersion: record.schemaVersion ?? RESUMABLE_RUN_SCHEMA_VERSION,
+    recordedAt: Number.isFinite(record.recordedAt) ? record.recordedAt : Date.now(),
+    // A caller-provided updatedAt is honored so reconciliation ordering is
+    // deterministic: the newest stamped record wins, whether it arrives through
+    // this write or was journaled by an earlier busy one.
+    updatedAt: Number.isFinite(record.updatedAt) ? record.updatedAt : Date.now(),
+  };
+
+  const outcome = await withAsyncLock(target, { signal, deadlineMs }, async () => {
+    // Reconcile first: journaled snapshots from earlier busy writes are
+    // candidates alongside the incoming record; the newest updatedAt wins and
+    // lands in ONE atomic write. The journal is removed only after the write
+    // lands, so a crash mid-section leaves the records re-appliable.
+    const journaled = await drainRunJournal(target);
+    const candidates = [...journaled, stamped];
+    const winner = candidates.reduce((a, b) => (recordTimestamp(b) >= recordTimestamp(a) ? b : a));
+    await writeJsonAtomic(target, winner);
+    try {
+      await fs.rm(runJournalPathFor(target), { force: true });
+    } catch {
+      // a leftover journal re-applies idempotently on the next lock
+    }
+    return winner;
+  });
+
+  if (outcome?.ok === true) {
+    return { ok: true, path: target };
+  }
+  const journaled = await appendRunJournal(target, stamped);
+  return { ok: false, reason: outcome?.reason ?? 'busy', journaled };
+}
+
+// --- resume / freshness --------------------------------------------------------
+
+function changedSnapshotKeys(snapshot, fingerprint) {
+  if (fingerprint === undefined || fingerprint === null) return [];
+  const source = isPlainObject(snapshot) ? snapshot : {};
+  if (typeof fingerprint === 'string') {
+    return source.source === fingerprint ? [] : ['source'];
+  }
+  if (!isPlainObject(fingerprint)) return [];
+  return Object.keys(fingerprint).filter((key) => source[key] !== fingerprint[key]);
+}
+
+function applyInvalidationCodes(record, codes) {
+  const fields = new Set();
+  for (const code of codes) {
+    for (const field of INVALIDATION_CODES[code] ?? []) fields.add(field);
+  }
+  const next = { ...record };
+  for (const field of fields) {
+    next[field] = field === 'nextAction' ? null : [];
+  }
+  return { record: next, invalidated: [...fields] };
+}
+
+/**
+ * Read the C10 record for a task. Never throws on corrupt state.
+ *
+ * @returns {Promise<{status:'fresh'|'stale'|'invalid'|'absent', record:object|null,
+ *   invalidated?:string[], warnings:string[]}>}
+ */
+export async function readResumableRun(projectRoot, {
+  taskId,
+  taskBoundary,
+  sourceFingerprint,
+} = {}) {
+  const target = resumableRunPath(projectRoot, taskId);
+  let text;
+  try {
+    text = await fs.readFile(target, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { status: 'absent', record: null, warnings: [] };
+    return {
+      status: 'invalid',
+      record: null,
+      warnings: [`resumable run record unreadable: ${error?.code ?? error?.message}`],
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return {
+      status: 'invalid',
+      record: null,
+      warnings: [`resumable run record at ${target} is corrupt JSON: ${error.message}`],
+    };
+  }
+
+  const validation = validateResumableRun(parsed);
+  if (!validation.valid) {
+    return {
+      status: 'invalid',
+      record: null,
+      warnings: [`resumable run record at ${target} failed validation: ${validation.errors[0]}`],
+    };
+  }
+
+  // A new explicit task boundary resets the record — the persisted state belongs
+  // to a different logical task.
+  if (typeof taskBoundary === 'string' && taskBoundary.length > 0
+    && parsed.taskBoundary !== taskBoundary) {
+    return { status: 'absent', record: null, warnings: [] };
+  }
+
+  const changed = changedSnapshotKeys(parsed.sourceSnapshot, sourceFingerprint);
+  if (changed.length > 0) {
+    const codes = changed.flatMap((key) => CHANGED_KEY_TO_CODES[key] ?? ['plans']);
+    const { record, invalidated } = applyInvalidationCodes(parsed, codes);
+    return {
+      status: 'stale',
+      record,
+      invalidated,
+      warnings: [`source/index fingerprint changed (${changed.join(', ')}); dependent plans invalidated`],
+    };
+  }
+
+  return { status: 'fresh', record: parsed, warnings: [] };
+}
+
+/**
+ * Selectively invalidate sections of a persisted record by code
+ * ('plans' | 'decisions' | 'receipts' | 'escalations' | 'failures'). Locked like
+ * a write; a busy lock journals nothing (invalidation is safe to retry).
+ */
+export async function invalidateResumableRun(projectRoot, taskId, codes, {
+  signal,
+  deadlineMs = LOCK_MAX_SLICE_MS,
+} = {}) {
+  const target = resumableRunPath(projectRoot, taskId);
+  const codeList = Array.isArray(codes) ? codes : [codes];
+
+  const outcome = await withAsyncLock(target, { signal, deadlineMs }, async () => {
+    // Reconcile the journal first so invalidation applies to the newest known
+    // state, not a superseded on-disk record.
+    const journaled = await drainRunJournal(target);
+    let parsed;
+    try {
+      parsed = JSON.parse(await fs.readFile(target, 'utf8'));
+    } catch (error) {
+      if (error?.code !== 'ENOENT') return { ok: false, reason: 'invalid' };
+      parsed = null;
+    }
+    const candidates = [...journaled, ...(parsed ? [parsed] : [])];
+    if (candidates.length === 0) return { ok: false, reason: 'absent' };
+    const base = candidates.reduce((a, b) => (recordTimestamp(b) >= recordTimestamp(a) ? b : a));
+    const { record, invalidated } = applyInvalidationCodes(base, codeList);
+    record.updatedAt = Date.now();
+    await writeJsonAtomic(target, record);
+    try {
+      await fs.rm(runJournalPathFor(target), { force: true });
+    } catch {
+      // leftover journal re-applies idempotently on the next lock
+    }
+    return { ok: true, invalidated };
+  });
+
+  if (outcome?.ok === true) return outcome.value;
+  return { ok: false, reason: outcome?.reason ?? 'busy' };
+}
+
+/**
+ * The shared resume-side fingerprint (TASK-007, FR-014/FR-015): the two keys a
+ * consumer can recompute cheaply at resume time — `index` (the code-index meta
+ * artifact's generatedAt stamp; a rebuild always changes it) and `config` (a
+ * content hash of the raw project runtime config). Producers MAY snapshot more
+ * keys (e.g. a project-verification `source` fingerprint); readers only compare
+ * the keys they pass in. `indexGeneratedAtMs` lets the route path pass the value
+ * it already computed instead of re-reading the artifact.
+ */
+export async function resumableRunSourceFingerprint(projectRoot, { indexGeneratedAtMs } = {}) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  let index = indexGeneratedAtMs;
+  if (index === undefined) {
+    const meta = await readJson(
+      path.join(projectRoot, '.cache', 'index', 'meta.json'),
+      null,
+    );
+    const parsed = Date.parse(String(meta?.generatedAt ?? ''));
+    index = Number.isNaN(parsed) ? null : parsed;
+  }
+  let configText = null;
+  try {
+    configText = await fs.readFile(runtimePaths.configPath, 'utf8');
+  } catch {
+    configText = null;
+  }
+  return {
+    index: index === null || index === undefined ? 'none' : String(index),
+    config: configText === null
+      ? 'none'
+      : crypto.createHash('sha256').update(configText).digest('hex').slice(0, 32),
+  };
+}
+
+// --- CLI (diagnostics) ---------------------------------------------------------
+
+async function main() {
+  const [command, rootArg, taskId] = process.argv.slice(2);
+  const projectRoot = path.resolve(rootArg || process.cwd());
+  if (command === 'read' && taskId) {
+    const result = await readResumableRun(projectRoot, { taskId });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  process.stderr.write('usage: resumable-run.mjs read <projectRoot> <taskId>\n');
+  process.exitCode = 2;
+}
+
+function isDirectRun() {
+  const argvPath = process.argv[1];
+  if (!argvPath) return Promise.resolve(false);
+  // Compare real paths: a project under a symlinked root makes import.meta.url
+  // resolve to the real path while argv[1] keeps the symlinked spelling.
+  return fs.realpath(argvPath)
+    .then((real) => real === fileURLToPath(import.meta.url))
+    .catch(() => false);
+}
+
+isDirectRun().then((direct) => {
+  if (direct) return main();
+  return undefined;
+});

package/template_project/.claude/ukit/runtime/sensitive-value-scanner.mjs

@@ -19,13 +19,10 @@
 
 import { createHash } from 'node:crypto';
 
-// Hook-context self-deadline (2.4.1 orphan-leak class): a hook wrapper passes
-// UKIT_HOOK_DEADLINE_MS so a wedged scan can never orphan this process past
-// the hook budget. CLI usage never sets it and is never self-killed.
-const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
-if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
-  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
-}
+// No import-time deadline: this is a pure library (no CLI entry). Deadline
+// policy belongs to the hook entry point that imports it — an import-time
+// process.exit timer races the importer's §8 announce and exits silently
+// (BUG-C23-04 class regression).
 
 function sha256(value) {
   return createHash('sha256').update(value).digest('hex');

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

@@ -497,7 +497,7 @@ async function evalIndexAllDone(projectRoot) {
   const rows = String(text)
     .split('\n')
     .map((line) => line.trim())
-    .filter((line) => /^\|TASK-/i.test(line));
+    .filter((line) => /^\|\s*TASK-/i.test(line));
   if (rows.length === 0) return { pass: false, detail: 'INDEX.md has no task rows' };
   const failing = [];
   for (const row of rows) {

package/template_project/docs/AI_HANDOFF/PLAN.md

@@ -12,21 +12,21 @@ QUALITY GATE: mỗi task split ra phải kèm Test Plan (xem mục bên dưới)
 Không có Test Plan → task không được phép chuyển sang status `ready`.
 -->
 
-## 1. Intent / Goal
+## §1 Intent / Goal
 
 <!-- 1-2 câu mô tả thứ user muốn đạt. Không paste lại nguyên prompt. -->
 
-## 2. Scope
+## §2 Scope
 
 - In scope:
 - Out of scope:
 - Risk surface (file/module rủi ro share):
 
-## 3. Approach
+## §3 Approach
 
 <!-- Cách làm ngắn gọn. Reuse code có sẵn trước khi tạo mới. -->
 
-## 4. Test Plan (REQUIRED — TDD-style)
+## §4 Test Plan (REQUIRED — TDD-style)
 
 Liệt kê test sẽ viết TRƯỚC khi code. Mỗi test phải có:
 
@@ -42,7 +42,7 @@ Bắt buộc tối thiểu:
 
 Nếu task không thể test (config-only, doc-only, prototype throw-away): ghi `Test plan: N/A — lý do: <…>` và đính kèm phương án verify thủ công.
 
-## 5. Verification Commands
+## §5 Verification Commands
 
 Lệnh chính xác executor sẽ chạy:
 
@@ -53,14 +53,14 @@ Lệnh chính xác executor sẽ chạy:
 # node scripts/smoke.mjs
 ```
 
-## 6. Acceptance Criteria
+## §6 Acceptance Criteria
 
 - [ ] Tất cả test ở Test Plan PASS (kèm output trong report).
 - [ ] Không có regression ở suite liên quan.
 - [ ] Reviewer (model riêng) báo `APPROVED` hoặc `APPROVED-WITH-MINOR`.
 - [ ] Docs/CHANGELOG cập nhật nếu user-facing.
 
-## 7. Task Split (Phase 2 — TDD-embedded, MANDATORY)
+## Task Split (Phase 2 — TDD-embedded, MANDATORY)
 
 Khi human approve plan, AI tạo từng `tasks/TASK-xxx.md` theo cấu trúc ở `tasks/_TEMPLATE.md`.
 

package/template_project/docs/AI_HANDOFF/RULES.md

@@ -158,7 +158,7 @@ chạy **đến khi không còn gì để làm**:
 - Output: PLAN.md đầy đủ + Planner Self-Audit. Chạy standalone (`/ukit:handoff-create`) thì dừng ở đây chờ human xem; chạy trong `/ukit:handoff-fullstack` thì đi thẳng tiếp sang Phase 2 — plan review độc lập là gate thay cho human.
 
 **Phase 2 — Create Tasks (TDD-embedded, MANDATORY)** (smart/reasoning model, thường cùng phase 1)
-- Human approve plan → AI split `PLAN.md §7` sang nhiều `tasks/TASK-xxx.md`.
+- Human approve plan → AI split `PLAN.md` sang nhiều `tasks/TASK-xxx.md`.
 - **Mỗi TASK file BẮT BUỘC có Test Plan của riêng nó**, không chỉ trỏ về PLAN.md. Cụ thể:
   - `§ Test Cases`: bảng test (loại, tên test, expected) cho phần task này — happy + ≥2 edge case KHÁC loại nhau (vd null/empty + boundary/concurrent, không tính 2 case gần giống nhau) + regression (nếu fix bug).
   - `§ Test Files`: đường dẫn cụ thể file test sẽ tạo/sửa (ví dụ `tests/auth/login.test.js`).