@ngockhoale/ukit 3.3.2 → 3.4.0

package/src/index/playbookRegistry.js

@@ -0,0 +1,691 @@
+// playbookRegistry.js — playbook registry + playbookId route resolution
+// (C84 TASK-007, BL-009 + BL-012).
+//
+// A natural prompt resolves to a playbook with no /playbook command. This
+// module owns two things: (1) the registry — scan project .ukit/playbooks >
+// ~/.ukit/playbooks > packaged template_user/playbooks, parse `id:` + `lanes:`
+// frontmatter (malformed → skipped with reason, surfaced via `ukit doctor`);
+// (2) the ARCH §Routing Decision Table — all 15 work-group rows plus the
+// handoff-cycle escape row — with confusable pairs resolved by discriminator
+// signals, never trigger text alone.
+//
+// Unknown/malformed/missing ids degrade: playbookId stays null and a `reason`
+// rides the route — routing never blocks on playbook resolution (ARCH
+// §Failure Modes / GAP M01).
+//
+// Mirror parity: template_project/.claude/ukit/index/playbook-registry.mjs
+// carries the identical logic (the mirror cannot import src/). Both twins are
+// locked by tests/consistency/registryParity.test.js.
+
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { deriveEscalationTriggers, deriveRiskFloor } from './routeResolver.js';
+
+const PLAYBOOK_NAME_RE = /\.md$/i;
+// src/index/playbookRegistry.js is two dirs below the package root —
+// '../..' lands on it. The installed mirror
+// (.claude/ukit/index/playbook-registry.mjs) walks four dirs instead so the
+// repo checkout resolves the same template_user tree; on a real installed
+// project the mirror's walk lands outside the project (no template_user
+// dir), ENOENT skips the tier, and the ~/.ukit seed is the effective builtin.
+// Install-aware callers may pass `builtinDir` explicitly.
+const PACKAGE_BUILTIN_PLAYBOOK_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..', '..',
+  'template_user', 'playbooks',
+);
+// SPEC §14 + BL-020: `issue-implementation.md` renamed to
+// `feature-implementation.md`; the old id stays a reverse alias so user-dir
+// installs seeded under the pre-rename filename still resolve the canonical row.
+export const PLAYBOOK_ID_ALIASES = Object.freeze({
+  'issue-implementation': 'feature-implementation',
+});
+
+// --- Shared signal vocabulary ------------------------------------------------
+// Compiled once; every row's discriminator reads the same normalized signals so
+// confusable pairs split on the discriminator column, never trigger text.
+const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b/i;
+const CHANGE_VERB_RE = /\b(fix|update|modify|change|rename|refactor|restructure|remove|delete|move|migrate|improve|patch|rework|sửa|đổi|cập nhật|thay thế|xóa)\b/i;
+const INVESTIGATION_TRIGGER_RE = /\b(how does|how do|why does|why do|why is|why are|explain|what happens|investigate|understand how|validate the assumption|tại sao|như thế nào|thế nào)\b/i;
+const DEFECT_TRIGGER_RE = /\b(fix|bug|defect|broken|crash(?:es|ed)?|regression|not working|doesn['’]?t work|won['’]?t work|fails?|failing|không hoạt động|lỗi)\b/i;
+const CHECK_VERB_RE = /\b(verify|check|confirm|prove|validate|assert)\b/i;
+const EXPLAIN_ASK_RE = /\b(how|why|explain|understand)\b/i;
+const INTERMITTENT_RE = /\b(sometimes|intermittent|flaky|occasionally|random|sporadic|hangs?|hang|leak|in 5|one in \d+|about \d+ in \d+)\b/i;
+const TEST_HARNESS_RE = /\b(spec|test|tests|assertion)\b/i;
+const CONTRACT_SIGNAL_RE = /\b(oauth|sso|jwt|api|contract|schema|public|persistent|multi[- ]?(?:screen|file|step)|complex[- ]?state|auth\b|password|token|session|payment|billing|checkout|hard[- ]to[- ]reverse|irreversible|reset[- ]all|user[- ]data|destructive|delete all)\b/i;
+const MULTI_SURFACE_RE = /\b(across files|multi(?:ple)? files|multi[- ]?screen|several screens|end[- ]?to[- ]?end|wiring)\b/i;
+// BL-033: a spike ask that also demands wiring/shipping/integration into a
+// shipped surface is a feature ask wearing spike vocabulary — the disposable
+// signal does not apply. Confusable pair 5's feature-side veto.
+const WIRE_OR_SHIP_RE = /\b(?:wir(?:e|ed|ing)|integrat\w*|ship|deploy)\b(?:\s+[\w-]{1,20}){0,4}\s+into\b/i;
+const FORENSICS_TRIGGER_RE = /\b(hangs?|leaks?|cpuprofile|heap\s*(?:dump|snapshot|profile)|memory profile|dropped (?:a )?(?:cpu|heap|profile) artifact)\b/i;
+const REFACTOR_TRIGGER_RE = /\b(extract|rename|restructure|refactor|split|move (?:this|the) (?:function|module|file|class|logic))\b/i;
+const DATA_MOVE_RE = /\b(schema|table|column|database|db|migration|data(?:base)? move|move (?:the |this )?(?:data|rows?|records?|sessions?))\b/i;
+const PERFORMANCE_TRIGGER_RE = /\b(slow|perf(?:ormance)?|takes? ~?\d|\d+ ?(?:ms|s|seconds?|minutes?)\b|latency|optimi[sz]e|speed up|baseline)\b/i;
+const DECISION_TRIGGER_RE = /\b(should we|choose between|which is better|design fork|pick between|vs\b|versus\b)\b/i;
+const PROTOTYPE_TRIGGER_RE = /\b(spike|prototype|try (?:a|out|the)|proof[- ]of[- ]concept|poc\b|experiment with)\b/i;
+const MIGRATION_TRIGGER_RE = /\b(migrat\w*|move (?:the |this |all )?[\w-]*\b|new schema|port (?:the|to)|upgrade (?:the )?(?:schema|data))\b/i;
+const VERIFICATION_TRIGGER_RE = /\b(verify|check|confirm|prove|validate|assert)\b/i;
+const SKILL_EVAL_TRIGGER_RE = /\b(make (?:this|it)(?: [\w-]+)* a skill|(?:convert|turn|extract)[\w -]*skill|skill[- ]evaluation|did (?:this|the) [\w -]*(?:help|improve)|(?:new|the) [\w-]*skill (?:improve|help)|score (?:the|a) skill)\b/i;
+// BL-026 review fix: skill-authoring asks carry defect vocabulary when they
+// describe turning a past fix into a reusable skill — guards the bug-fix row.
+const SKILL_ASK_RE = SKILL_EVAL_TRIGGER_RE;
+const AUTONOMOUS_TRIGGER_RE = /\b(finish (?:this|the) backlog|bounded (?:long )?goal|finish the (?:task|list|queue))\b/i;
+const RELEASE_TRIGGER_RE = /\b(publish|ship it|release|bump (?:the )?version|deploy|cut a release|tag (?:the )?release)\b/i;
+const HANDOFF_CYCLE_TRIGGER_RE = /\b(handoff|multi[- ]?task cycle|task pipeline|execute the plan|worktree)\b/i;
+
+// session-pickup discriminator needs the resumable-record check.
+function hasResumableRecord(projectRoot) {
+  if (!projectRoot) return false;
+  try {
+    const runsDir = path.join(projectRoot, '.ukit', 'storage', 'runs');
+    const entries = fsSync.readdirSync(runsDir, { withFileTypes: true });
+    return entries.some((entry) => entry.isFile() && entry.name.endsWith('.json'));
+  } catch {
+    return false;
+  }
+}
+
+// ARCH §Routing Decision Table — the 15 work-group rows + the handoff-cycle
+// escape row (ARCH's 16th row: multi-task cycle / gated pipeline → per-task
+// playbook, never a file of its own). Row order is ARCH order; a row matches
+// when any trigger hits AND its discriminator passes. Discriminators split the
+// confusable pairs named in ARCH — they are the contract, triggers are hints.
+export const PLAYBOOK_ROUTING_TABLE = Object.freeze([
+  {
+    workGroup: 'small-feature',
+    playbookId: 'small-feature',
+    lanes: ['local-fix', 'local-build'],
+    triggers: [/create|add|write|build|implement|scaffold|tạo|thêm|update/i],
+    // confusable pair 1: no escalation trigger AND single-surface scope. The
+    // `!s.escalated` clause is the BL-010 fast-path guard — any derived
+    // floor-raising trigger (the six listed triggers map to risk codes +
+    // contract signals) escalates to feature-implementation.
+    discriminator: (s) => !s.escalated && !s.contractSignal && !s.multiSurface && s.changeVerbOrCreate,
+    fastPath: 'small-feature',
+  },
+  {
+    workGroup: 'feature-implementation',
+    playbookId: 'feature-implementation',
+    lanes: ['local-build', 'shared-edit', 'map-impact'],
+    triggers: [/implement|add|create|build|integrat|ship|deliver|wir(?:e|ed|ing)/i],
+    // confusable pairs 1/5/8: articulated contract OR ≥1 escalation trigger,
+    // and the ask is not a disposable spike nor the ship chain itself.
+    discriminator: (s) => (s.contractSignal || s.multiSurface || s.escalated || s.wiredShipAsk) && !s.disposable && !s.releaseAsk,
+  },
+  {
+    workGroup: 'bug-fix',
+    playbookId: 'bug-fix',
+    lanes: ['find-cause'],
+    triggers: [/fix|bug|defect|broken|crash|regression|not working|doesn['’]?t work|won['’]?t work|fails?|failing|không hoạt động|lỗi/i],
+    // confusable pairs 3/4: deterministic repro (no live/intermittent signal,
+    // or a test-harness repro), and a change is requested — not an
+    // explanation ask, not a verification ask. ARCH §Fast-Path Separation:
+    // bug-fix is the second fast path (TASK-009 owns the completion floor).
+    fastPath: 'bug-fix',
+    // T-026 review fix: a skill-ask that happens to mention a fix ("make this
+    // repeated fix flow a skill") is skill-authoring, not a defect order.
+    discriminator: (s) => !s.explanationAsk && !s.questionAsk && !s.forensicsSignal && !s.checkFirst && !s.skillAsk,
+  },
+  {
+    workGroup: 'investigation',
+    playbookId: 'investigation',
+    lanes: ['find-cause', 'map-impact'],
+    triggers: [/how does|how do|why does|why do|why is|why are|explain|what happens|investigate|understand how|validate the assumption|tại sao|như thế nào|thế nào/i],
+    // confusable pair 4: explanation asked, no change requested.
+    discriminator: (s) => !s.changeRequested,
+  },
+  {
+    workGroup: 'runtime-forensics',
+    playbookId: 'runtime-forensics',
+    lanes: ['find-cause'],
+    triggers: [/\bhangs?\b|\bleaks?\b|sometimes|intermittent|flaky|occasionally|about \d+ in \d+|\bin 5\b|cpuprofile|\bheap\b|dropped.*artifact/i],
+    // confusable pair 3: no deterministic repro — a named test-harness
+    // failure IS a repro and stays bug-fix.
+    discriminator: (s) => !s.testHarness,
+  },
+  {
+    workGroup: 'refactor',
+    playbookId: 'refactor',
+    lanes: ['shared-edit', 'map-impact'],
+    triggers: [/extract|rename|restructure|refactor|split|migrate all callers/i],
+    // confusable pair 7: behavior must not change — no data/contract move.
+    discriminator: (s) => !s.dataMove,
+  },
+  {
+    workGroup: 'performance',
+    playbookId: 'performance',
+    lanes: ['local-build', 'find-cause'],
+    triggers: [/slow|perf|takes? ~?\d|latency|optimi[sz]e|speed up|\d+ ?(?:ms|s|seconds?|minutes?)\b|baseline/i],
+    // confusable pair: measured baseline exists or is step 1 — a live/
+    // intermittent symptom is runtime-forensics, not performance. BL-022:
+    // unmeasured slowness (trigger hit, !measurable, no other row claim)
+    // emits the investigation playbookId in resolvePlaybookId below — this
+    // row still refuses it here so measurable stays the split column.
+    discriminator: (s) => s.measurable && !s.forensicsSignal,
+  },
+  {
+    workGroup: 'architecture-decision',
+    playbookId: 'architecture-decision',
+    lanes: ['map-impact', 'shared-edit'],
+    triggers: [/should we|choose between|which is better|design fork|pick between|versus|\bvs\b/i],
+    // a decision must be recorded, not prototyped — and an explanation ask
+    // ("how does X pick") is investigation, not a fork.
+    discriminator: (s) => !s.explanationAsk && !s.disposable,
+  },
+  {
+    workGroup: 'prototype',
+    playbookId: 'prototype',
+    lanes: ['local-build'],
+    triggers: [/spike|prototype|try (?:a|out|the)|proof[- ]of[- ]concept|\bpoc\b|experiment/i],
+    // confusable pair 5: a disposable artifact settles the fork — a spike ask
+    // that demands wiring/shipping is a feature ask, not disposable.
+    discriminator: (s) => s.disposable,
+  },
+  {
+    workGroup: 'migration',
+    playbookId: 'migration',
+    lanes: ['shared-edit', 'map-impact'],
+    triggers: [/migrat|move (?:the |this |all )?[\w-]*|new schema|port (?:the|to)/i],
+    // confusable pair 7: behavior change + data/contract move (rollback needed).
+    discriminator: (s) => s.dataMove,
+  },
+  {
+    workGroup: 'verification',
+    playbookId: 'verification',
+    lanes: ['local-fix', 'review-release'],
+    triggers: [/\bverify\b|\bcheck\b|\bconfirm\b|\bprove\b|\bvalidate\b|\bassert\b/i],
+    // the ask IS a check — a check verb leads, or no defect verb exists at all.
+    discriminator: (s) => s.checkFirst || s.defectIdx === -1,
+  },
+  {
+    workGroup: 'skill-evaluation',
+    playbookId: 'skill-evaluation',
+    lanes: ['local-build', 'review-release'],
+    triggers: [/make (?:this|it)(?: [\w-]+)* a skill|(?:convert|turn|extract)[\w -]*skill|did (?:this|the|a) [\w -]*(?:help|improve)|skill[- ]evaluation|(?:new|the) [\w-]*skill (?:improve|help)|score (?:the|a) skill/i],
+    // confusable pair 6: measuring a behavior change, not checking an artifact.
+    discriminator: () => true,
+  },
+  {
+    workGroup: 'session-pickup',
+    playbookId: 'session-pickup',
+    lanes: ['local-fix', 'local-build'],
+    triggers: [/làm tiếp|resume|continue|pick (?:it|this) back up/i],
+    // confusable pair 2: a prior resumable record must exist — never
+    // fabricate continuity on a fresh goal.
+    discriminator: (s) => s.hasResumableRecord,
+  },
+  {
+    workGroup: 'autonomous-run',
+    playbookId: 'autonomous-run',
+    lanes: ['shared-edit', 'map-impact'],
+    triggers: [/finish (?:this|the) backlog|bounded (?:long )?goal|finish the (?:task|list|queue)/i],
+    // confusable pair 2: a fresh bounded goal — a prior resumable record
+    // would make this session-pickup territory.
+    discriminator: (s) => !s.hasResumableRecord,
+  },
+  {
+    workGroup: 'release',
+    playbookId: 'release',
+    lanes: ['review-release'],
+    triggers: [/publish|ship it|release|bump (?:the )?version|cut a release|tag (?:the )?release|deploy/i],
+    // confusable pair 8: the ask IS the ship chain — "add changelog entry"
+    // stays small-feature.
+    discriminator: (s) => s.releaseAsk,
+  },
+  {
+    // ARCH row 16: multi-task cycle / gated change → per-task playbook inside
+    // the handoff pipeline. There is no file for this row; it resolves a
+    // workGroup so the route names the pipeline instead of a playbook.
+    workGroup: 'handoff-cycle',
+    playbookId: null,
+    lanes: [],
+    triggers: [/handoff|multi[- ]?task cycle|task pipeline|execute the (?:plan|pipeline)/i],
+    path: 'handoff',
+    discriminator: () => true,
+  },
+]);
+
+// workGroup → canonical playbookId (inverse lookup for registry records).
+const WORKGROUP_TO_PLAYBOOK = Object.freeze(Object.fromEntries(
+  PLAYBOOK_ROUTING_TABLE
+    .filter((row) => row.playbookId)
+    .map((row) => [row.workGroup, row.playbookId]),
+));
+const PLAYBOOK_TO_WORKGROUP = Object.freeze(Object.fromEntries(
+  PLAYBOOK_ROUTING_TABLE
+    .filter((row) => row.playbookId)
+    .map((row) => [row.playbookId, row.workGroup]),
+));
+
+// C88 FR-009: sub-playbooks are file-level records on an existing work
+// group's row — they ship no routing-table row of their own (SPEC §3), so
+// this map is the bridge from record id to host workGroup. Record hygiene
+// only: `loadRegistry` would otherwise emit `workGroup: null` for these
+// files; routing never resolves them as targets.
+export const SUB_PLAYBOOK_WORKGROUP = Object.freeze({
+  hillclimb: 'performance',
+  babysit: 'release',
+  shipping: 'release',
+  orchestrate: 'autonomous-run',
+  'autopilot-full': 'release',
+  'autopilot-stack': 'release',
+  'worktree-cleanup': 'session-pickup',
+  'open-pr': 'release',
+});
+
+const PERFORMANCE_ROW = PLAYBOOK_ROUTING_TABLE.find((row) => row.workGroup === 'performance');
+const INVESTIGATION_ROW = PLAYBOOK_ROUTING_TABLE.find((row) => row.workGroup === 'investigation');
+
+function matchFirst(text, regexes) {
+  for (const regex of regexes) {
+    const index = text.search(regex);
+    if (index !== -1) return index;
+  }
+  return -1;
+}
+
+function buildRouteSignals({
+  signalText,
+  executionMode,
+  escalationTriggers,
+  projectRoot,
+}) {
+  // C85-019b: question-tagged mutation verbs are asks, not orders. Strip
+  // interrogative clauses from the verb scan BEFORE computing changeIdx —
+  // "should I fix X?" and "X … chưa?" mention the verb as subject matter,
+  // never as an imperative. A real order ("sửa file X cho tôi?") survives
+  // because no consult pattern consumes its clause.
+  const verbScanText = signalText
+    .replace(/(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+[^\n?]*/g, ' ')
+    .replace(/[^\n.,;?]{0,80}\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|không|khong|rồi|roi|nhỉ|nhi|ạ|a)\s*[?.!]?\s*$/g, ' ')
+    .replace(/\b(?:có|co)\s+(?:nên|nen|cần|can|phải|phai)\s+[^\n?]*/g, ' ');
+  const changeIdx = verbScanText.search(CHANGE_VERB_RE);
+  const createIdx = verbScanText.search(CREATE_VERB_RE);
+  const explainIdx = signalText.search(EXPLAIN_ASK_RE);
+  const defectIdx = signalText.search(DEFECT_TRIGGER_RE);
+  const checkIdx = signalText.search(CHECK_VERB_RE);
+  const investigationIdx = signalText.search(INVESTIGATION_TRIGGER_RE);
+  const consultLead = /(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+/
+    .test(signalText)
+    || /\b(?:co|có)\s+(?:nên|nen|cần|can|phải|phai)\s+/.test(signalText)
+    || /\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|nhỉ|nhi|rồi|roi)\s*[?.!]?\s*$/.test(signalText);
+  const firstVerbIdx = [changeIdx, createIdx].filter((i) => i !== -1).sort((a, b) => a - b)[0] ?? -1;
+  const explanationAsk = explainIdx !== -1 && (firstVerbIdx === -1 || explainIdx < firstVerbIdx);
+  const changeRequested = !consultLead && firstVerbIdx !== -1 && (explainIdx === -1 || firstVerbIdx < explainIdx);
+  const checkFirst = checkIdx !== -1 && (defectIdx === -1 || checkIdx < defectIdx);
+  // C85-019: a QUESTION about a defect is not a defect order. The bug-fix floor
+  // demands repro+root-cause receipts — demanding them on a "did it get fixed
+  // yet?" turn forces edits nobody asked for (user-reported lock). Question
+  // shape = '?', a leading/standalone interrogative in English or Vietnamese
+  // (diacritics break \b, so Vietnamese particles test raw substrings), or a
+  // status-check ask ('đã … chưa', '… or not'). Any interrogative shape with
+  // NO change verb before it is a consult, never a fix order; 'fix X' without
+  // a question mark still routes bug-fix.
+  const questionShaped = /\?\s*$/.test(signalText)
+    || /\b(how|why|what|when|which|where|who|is|are|does|do|did|can|could|would|should|will)\b/.test(signalText)
+    || /(?:có|co)\s+(?:phải|phai)\s+/.test(signalText)
+    || /(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|thế nào|the nao|như thế nào|nhu the nao|tại sao|tai sao|là gì|la gi|bao giờ|bao gio|khi nào|khi nao|ở đâu|o dau|không biết|khong biet)/.test(signalText)
+    || /(?:chưa|chua|đúng không|dung khong|không|khong)\s*[?.!]?\s*$/.test(signalText);
+  const questionAsk = questionShaped && !changeRequested;
+  return {
+    signalText,
+    executionMode,
+    changeIdx,
+    createIdx,
+    explainIdx,
+    defectIdx,
+    checkIdx,
+    investigationIdx,
+    explanationAsk,
+    changeRequested,
+    questionAsk,
+    checkFirst,
+    changeVerbOrCreate: changeIdx !== -1 || createIdx !== -1,
+    contractSignal: CONTRACT_SIGNAL_RE.test(signalText) || /\boauth\b/i.test(signalText),
+    multiSurface: MULTI_SURFACE_RE.test(signalText),
+    escalated: Array.isArray(escalationTriggers) && escalationTriggers.length > 0,
+    disposable: (PROTOTYPE_TRIGGER_RE.test(signalText) || /\b(spike|disposable|throwaway)\b/i.test(signalText))
+      && !WIRE_OR_SHIP_RE.test(signalText),
+    wiredShipAsk: WIRE_OR_SHIP_RE.test(signalText),
+    releaseAsk: RELEASE_TRIGGER_RE.test(signalText),
+    forensicsSignal: FORENSICS_TRIGGER_RE.test(signalText)
+      || (INTERMITTENT_RE.test(signalText) && !TEST_HARNESS_RE.test(signalText)),
+    testHarness: TEST_HARNESS_RE.test(signalText),
+    measurable: /\d/.test(signalText) || MEASURABLE_RE.test(signalText),
+    dataMove: DATA_MOVE_RE.test(signalText),
+    hasResumableRecord: hasResumableRecord(projectRoot),
+    // BL-026 review fix: ask to convert/author a skill — beats defect verbs in
+    // the same sentence ("make this repeated fix flow a skill").
+    skillAsk: SKILL_ASK_RE.test(signalText),
+  };
+}
+
+// BL-022: measurable = a stated or referenced measurement — a unit-bearing
+// duration, a named measure (latency/baseline/benchmark/profile), or an
+// explicit resource (cpu/memory/heap). Bare "slow"/"faster" vocabulary is a
+// symptom, not a measurement: those asks route investigation instead.
+const MEASURABLE_RE = /\b(latency|baseline|benchmark|profile|cpu|memory|heap|takes?|in \d+ ?(?:ms|s|seconds?|minutes?)|\d+ ?(?:ms|s|seconds?|minutes?)|seconds?|minutes?|ms\b)\b/i;
+
+// --- Playbook file frontmatter (registry-strict variant) ---------------------
+// Same fence grammar as src/core/userPlaybooks.js but `id:` + `lanes:` are
+// REQUIRED — a registry file without them is malformed (FR-007), where the
+// workflow-policy loader tolerates filename-stem ids.
+function parsePlaybookMeta(raw, filePath) {
+  if (!raw.startsWith('---\n')) {
+    return null;
+  }
+  const fenceIndex = raw.indexOf('\n---', 3);
+  if (fenceIndex === -1) {
+    return null; // unterminated frontmatter
+  }
+  const metaText = raw.slice(4, fenceIndex);
+  const meta = {};
+  for (const line of metaText.split('\n')) {
+    const match = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+    if (match) {
+      meta[match[1]] = match[2].trim();
+    }
+  }
+  const id = typeof meta.id === 'string' && meta.id !== '' ? meta.id : null;
+  if (id === null) {
+    return null; // no usable id
+  }
+  const lanesValue = meta.lanes ?? '';
+  const inner = lanesValue.startsWith('[') && lanesValue.endsWith(']')
+    ? lanesValue.slice(1, -1)
+    : lanesValue;
+  const lanes = inner
+    .split(',')
+    .map((lane) => lane.trim().replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean);
+  // `lanes:` is REQUIRED for registry files — absent or empty means the file
+  // declares no lane ownership and is malformed, not "any lane".
+  if (lanes.length === 0) {
+    return null;
+  }
+  const body = raw.slice(fenceIndex + 4).replace(/^\n/, '');
+  if (body.trim() === '') {
+    return null; // empty body → not a playbook
+  }
+  return { id, lanes };
+}
+
+function registryCandidateDirs({ projectRoot, homeDir, builtinDir } = {}) {
+  const candidates = [];
+  if (projectRoot) {
+    candidates.push({ dir: path.join(projectRoot, '.ukit', 'playbooks'), source: 'project' });
+  }
+  if (homeDir !== null) {
+    const base = homeDir || os.homedir();
+    candidates.push({ dir: path.join(base, '.ukit', 'playbooks'), source: 'user' });
+  }
+  const resolvedBuiltinDir = builtinDir ?? PACKAGE_BUILTIN_PLAYBOOK_DIR;
+  candidates.push({ dir: resolvedBuiltinDir, source: 'builtin' });
+  return candidates;
+}
+
+function inferWorkGroup(playbookId, recordId) {
+  return PLAYBOOK_TO_WORKGROUP[playbookId]
+    ?? Object.entries(PLAYBOOK_ID_ALIASES).find(([, fileId]) => fileId === recordId)?.[0]
+    // BL-020 reverse alias: a record id that IS an alias (pre-rename user-dir
+    // file) resolves the workGroup through its canonical playbook id.
+    ?? PLAYBOOK_TO_WORKGROUP[PLAYBOOK_ID_ALIASES[recordId]]
+    // C88 FR-009: sub-playbook records (no routing row) resolve their host
+    // work-group through the frozen map.
+    ?? SUB_PLAYBOOK_WORKGROUP[recordId]
+    ?? null;
+}
+
+// Scan the three precedence dirs, first-wins per playbookId. Returns
+// PlaybookRecord[] — valid records deduplicated by id (project > user >
+// builtin); malformed files appear with frontmatterValid: false + reason so
+// `ukit doctor` can warn without the route path paying for them.
+export async function loadRegistry({ projectRoot = null, homeDir = null, builtinDir = null } = {}) {
+  const byId = new Map();
+  const records = [];
+  for (const { dir, source } of registryCandidateDirs({ projectRoot, homeDir, builtinDir })) {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      continue; // missing/unreadable tier — fall through
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !PLAYBOOK_NAME_RE.test(entry.name)) {
+        continue;
+      }
+      const filePath = path.join(dir, entry.name);
+      let raw;
+      try {
+        raw = await fs.readFile(filePath, 'utf8');
+      } catch {
+        continue;
+      }
+      const meta = parsePlaybookMeta(raw, filePath);
+      if (meta === null) {
+        records.push({
+          playbookId: null,
+          file: filePath,
+          workGroup: null,
+          lanes: [],
+          frontmatterValid: false,
+          source,
+          reason: 'malformed-frontmatter',
+        });
+        continue;
+      }
+      if (byId.has(meta.id)) {
+        continue; // higher-precedence tier already registered this id
+      }
+      const record = {
+        playbookId: meta.id,
+        file: filePath,
+        workGroup: inferWorkGroup(meta.id, meta.id),
+        lanes: meta.lanes,
+        frontmatterValid: true,
+        source,
+      };
+      byId.set(meta.id, record);
+      records.push(record);
+    }
+  }
+  return records;
+}
+
+function findRegistryRecord(records, playbookId) {
+  const direct = records.find((r) => r.frontmatterValid && r.playbookId === playbookId);
+  if (direct) return direct;
+  // Aliases work both directions (BL-020): canonical → file name, and file
+  // name → canonical when the record itself carries the pre-rename id.
+  const aliasId = PLAYBOOK_ID_ALIASES[playbookId];
+  if (aliasId) {
+    const viaAlias = records.find((r) => r.frontmatterValid && r.playbookId === aliasId);
+    if (viaAlias) return viaAlias;
+  }
+  const reverse = records.find(
+    (r) => r.frontmatterValid && PLAYBOOK_ID_ALIASES[r.playbookId] === playbookId,
+  );
+  return reverse ?? null;
+}
+
+// resolvePlaybookId({promptText, executionMode, intentMode, escalationTriggers,
+// projectRoot, homeDir, builtinDir, registry}) →
+//   { playbookId|null, workGroup|null, lane, reason?, file?, source? }.
+// Never throws on IO failure — the degrade contract is part of the shape.
+export async function resolvePlaybookId({
+  promptText = '',
+  commandText = '',
+  targetFile = null,
+  executionMode = null,
+  intentMode = null,
+  escalationTriggers = [],
+  projectRoot = null,
+  homeDir = null,
+  builtinDir = null,
+  registry = null,
+  riskSignals = [],
+} = {}) {
+  const lane = executionMode ?? null;
+  try {
+    const signalText = [promptText, commandText]
+      .map((value) => String(value || '').trim().toLowerCase())
+      .filter(Boolean)
+      .join('\n');
+    if (signalText === '') {
+      return { playbookId: null, workGroup: null, lane, path: null, fastPath: null, reason: 'no-route-match' };
+    }
+    // Merge caller-supplied triggers with the deterministic derive — a caller
+    // that computed none (schema stages off) must not blind the contract
+    // discriminators to real escalation signals in the prompt.
+    const floor = deriveRiskFloor({
+      promptText,
+      commandText,
+      targetFile,
+      executionMode,
+      riskSignals,
+    });
+    const mergedTriggers = [...new Set([
+      ...(Array.isArray(escalationTriggers) ? escalationTriggers : []),
+      ...deriveEscalationTriggers(floor),
+    ])];
+    const signals = buildRouteSignals({
+      signalText,
+      executionMode,
+      escalationTriggers: mergedTriggers,
+      projectRoot,
+    });
+    const matched = PLAYBOOK_ROUTING_TABLE.filter((row) => {
+      if (matchFirst(signalText, row.triggers) === -1) {
+        return false;
+      }
+      try {
+        return row.discriminator(signals) === true;
+      } catch {
+        return false;
+      }
+    });
+    // BL-022 (SPEC §14): unmeasured slowness — the performance trigger hit but
+    // the row refused (!measurable / !forensicsSignal) and no other row
+    // claimed the prompt — resolves through the investigation row instead of
+    // degrading: the honest next step is "measure first". Emitted here rather
+    // than as an investigation-row trigger so prompts that name slowness AND
+    // hit a second row (e.g. "why is the migration slow") keep their existing
+    // resolution instead of turning ambiguous.
+    const unmeasuredSlowness =
+      matched.length === 0
+      && matchFirst(signalText, PERFORMANCE_ROW.triggers) !== -1
+      && !signals.measurable
+      && !signals.forensicsSignal;
+    if (matched.length === 0 && !unmeasuredSlowness) {
+      // BL-010: a real prompt that no row claims is still a direct-in-session
+      // route (ARCH §Routing Decision Table Path column) — path: 'direct',
+      // fastPath: 'none' rather than null so route state records it honestly.
+      return { playbookId: null, workGroup: null, lane, path: 'direct', fastPath: 'none', reason: 'no-route-match' };
+    }
+    if (matched.length > 1) {
+      return {
+        playbookId: null,
+        workGroup: null,
+        lane,
+        path: 'direct',
+        fastPath: 'none',
+        reason: 'ambiguous-route',
+        candidates: matched.map((row) => row.workGroup),
+      };
+    }
+    const row = unmeasuredSlowness ? INVESTIGATION_ROW : matched[0];
+    const resolvedLane = row.lanes.includes(executionMode)
+      ? executionMode
+      : (row.lanes[0] ?? lane);
+    if (!row.playbookId) {
+      // handoff-cycle: a pipeline row, never a file.
+      return { playbookId: null, workGroup: row.workGroup, lane: resolvedLane, path: 'handoff', fastPath: 'none', reason: 'handoff-pipeline' };
+    }
+    const records = registry ?? await loadRegistry({ projectRoot, homeDir, builtinDir });
+    const record = findRegistryRecord(records, row.playbookId);
+    if (!record) {
+      // Row matched but the file is not registered (deleted post-install, or
+      // a playbook this cycle does not ship) — degrade to plain mode with the
+      // group named; the route record notes playbookLoad: missing.
+      return {
+        playbookId: null,
+        workGroup: row.workGroup,
+        lane: resolvedLane,
+        path: row.path ?? 'direct',
+        // The route STILL resolves the fast path — the playbook file may be
+        // deleted post-install, but the work group and its ceremony class are
+        // what the escalation trigger contract operates on.
+        fastPath: row.fastPath ?? 'none',
+        reason: 'playbook-missing',
+      };
+    }
+    return {
+      playbookId: row.playbookId,
+      workGroup: record.workGroup ?? row.workGroup,
+      lane: resolvedLane,
+      path: row.path ?? 'direct',
+      fastPath: row.fastPath ?? 'none',
+      file: record.file,
+      source: record.source,
+    };
+  } catch {
+    return { playbookId: null, workGroup: null, lane, path: null, fastPath: null, reason: 'registry-error' };
+  }
+}
+
+// Call-site helper: derive escalation triggers from the route signals and
+// resolve the playbook in one step. Both router surfaces merge the result into
+// the route record — playbookId/workGroup on state + audit rows.
+export async function resolvePlaybookRoute({
+  promptText = '',
+  commandText = '',
+  targetFile = null,
+  executionMode = null,
+  intentMode = null,
+  escalationTriggers = [],
+  projectRoot = null,
+  homeDir = null,
+  builtinDir = null,
+  registry = null,
+} = {}) {
+  const floor = deriveRiskFloor({
+    promptText,
+    commandText,
+    targetFile,
+    executionMode,
+  });
+  const mergedTriggers = [...new Set([
+    ...(Array.isArray(escalationTriggers) ? escalationTriggers : []),
+    ...deriveEscalationTriggers(floor),
+  ])];
+  const resolution = await resolvePlaybookId({
+    promptText,
+    commandText,
+    targetFile,
+    executionMode,
+    intentMode,
+    escalationTriggers: mergedTriggers,
+    projectRoot,
+    homeDir,
+    builtinDir,
+    registry,
+  });
+  return {
+    playbookId: resolution.playbookId ?? null,
+    workGroup: resolution.workGroup ?? null,
+    lane: resolution.lane ?? executionMode ?? null,
+    // BL-010 (ARCH Task Contract): `path` = direct|handoff, `fastPath` =
+    // none|small-feature|bug-fix. Route state names the enum `fastPathKind`
+    // because routeSummary.fastPath already carries the FR-004 eligibility
+    // object — one field, two consumers, no collision.
+    path: resolution.path ?? null,
+    fastPath: resolution.fastPath ?? null,
+    reason: resolution.reason ?? null,
+    playbookLoad: resolution.reason === 'playbook-missing' ? 'missing' : null,
+  };
+}