@ngockhoale/ukit 3.3.3 → 3.4.1

package/src/index/verificationMap.js

@@ -0,0 +1,404 @@
+// verificationMap.js — verification-map table + recipe resolution
+// (C85 TASK-014, BL-014 / SPEC FR-002 / ARCH §Verification Map).
+//
+// The map is DATA: template_user/playbooks/verification-map.json carries one
+// launch/doctor/drive/expected/evidence/cleanup row per playbook work group
+// (verbatim from ARCH §Verification Map) plus a per-artifact-class recipe table
+// (ui|cli|docs|config). This module is the single query surface for both shell
+// consumers (verification-guard.sh imports the .mjs twin and resolves recipes
+// without parsing prose) and node consumers (stop-coordinator.mjs completion
+// policy, ukit doctor's recipe-vs-package.json check).
+//
+// Resolution order mirrors the playbook registry:
+//   <projectRoot>/.ukit/playbooks/verification-map.json
+//   <homeDir>/.ukit/playbooks/verification-map.json
+//   packaged template_user/playbooks/verification-map.json (builtin)
+// The first file that parses AND validates wins; a malformed higher tier cannot
+// shadow a valid lower tier. Every miss/malformed case fails closed to
+// map=null — consumers fall back to pre-map behavior, never fabricated checks.
+//
+// Mirror parity: template_project/.claude/ukit/index/verification-map.mjs
+// carries the identical logic (the mirror cannot import src/). Both twins are
+// locked by tests/consistency/verificationMapParity.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';
+
+const MAP_FILENAME = 'verification-map.json';
+// src/index/verificationMap.js is two dirs below the package root — '../..'
+// lands on it. The installed mirror (.claude/ukit/index/verification-map.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. Callers may pass `builtinPath`.
+const PACKAGE_BUILTIN_MAP_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..', '..',
+  'template_user', 'playbooks', MAP_FILENAME,
+);
+
+export const ARTIFACT_CLASSES = Object.freeze(['ui', 'cli', 'docs', 'config']);
+const ARTIFACT_CLASS_SET = new Set(ARTIFACT_CLASSES);
+
+const PLAYBOOK_ROW_KEYS = ['launch', 'doctor', 'drive', 'expected', 'evidence', 'cleanup'];
+
+// ─── Artifact classification ────────────────────────────────────────────────
+// The artifact class comes from the files a change actually touched — the same
+// git --porcelain path list verification-guard.sh already computes. Priority is
+// deliberate: any UI file makes the diff `ui` (the ARCH falsifying bar blocks an
+// unverified UI change), explicit CLI surfaces next, and docs/config only when
+// the whole diff is docs/config. A diff with no signal classifies `null` —
+// `recipeForArtifact` then returns null and every consumer keeps the pre-map
+// behavior (SPEC §10: unknown class → no recipe → unchanged).
+
+const UI_PATH_RE = /(^|\/)(components?|pages?|views?|screens?|layouts?|widgets?)\//i;
+const UI_EXT_RE = /\.(jsx|tsx|vue|svelte|css|scss|sass|less|html|styl)$/i;
+const DOCS_PATH_RE = /(^|\/)(docs?|wiki)\//i;
+const DOCS_EXT_RE = /\.(md|mdx|rst|adoc|txt)$/i;
+const CONFIG_BASENAME_RE = /^(?:[^/]*\.(json|ya?ml|toml|ini|env|cfg|conf)|\.?[A-Za-z][\w.-]*(rc|file|config|ignore|rc\.js|rc\.cjs|rc\.mjs|rc\.json|rc\.ya?ml)|dockerfile|compose[^/]*\.ya?ml|makefile|justfile)$/i;
+const CLI_PATH_RE = /(^|\/)(bin|cli|cmd|commands)\//i;
+const CLI_EXT_RE = /\.(sh|bash|zsh|ps1|bat|cmd)$/i;
+const LOCKFILE_RE = /(^|\/)(?:package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|composer\.lock|gemfile\.lock|poetry\.lock|cargo\.lock|go\.sum)$/i;
+// Runtime-produced files are never the artifact being verified: UKit internal
+// storage (.ukit/**) and the router's own state files appear in every real
+// diff, and counting them would poison the whole-set docs/config rules.
+const INTERNAL_STATE_RE = /(^|\/)\.ukit\/|(^|\/)(?:skill-router-state|route-cache|verification-progress|decisions)\.json$|(^|\/)decisions\.tsv$/i;
+/**
+ * Classify a change's artifact class from the set of paths it touched.
+ * `changedPaths` are repo-relative paths (git --porcelain entries already have
+ * their status prefix stripped by the caller). Returns one of ARTIFACT_CLASSES
+ * or null for "no classifiable signal" (pre-map behavior everywhere downstream).
+ */
+
+// `git status --porcelain` C-quotes paths containing spaces/non-ASCII
+// ("src/My Widget.jsx") — the trailing quote must go before the class regexes
+// run or the entry silently misclassifies to null and the recipe lane skips
+// (fail-open). `-z` callers never produce quotes; this is a defensive net for
+// the porcelain form. Octal escapes (\303\244) are not valid JSON — the
+// fallback keeps the inner text, still classified by extension/dir, never
+// dropped.
+function unquotePorcelainPath(entry) {
+  if (entry.length >= 2 && entry.startsWith('"') && entry.endsWith('"')) {
+    const inner = entry.slice(1, -1);
+    try {
+      const parsed = JSON.parse(entry);
+      if (typeof parsed === 'string') return parsed;
+    } catch { /* octal escapes are not valid JSON — keep the inner text */ }
+    return inner;
+  }
+  return entry;
+}
+
+export function classifyArtifactClass(changedPaths = []) {
+  const paths = (Array.isArray(changedPaths) ? changedPaths : [])
+    .map((entry) => String(entry || '').trim())
+    .filter(Boolean)
+    // Rename entries carry "old -> new"; the destination is the changed artifact.
+    .map((entry) => entry.split(' -> ').pop())
+    .map(unquotePorcelainPath)
+    .filter((entry) => !INTERNAL_STATE_RE.test(entry));
+  if (paths.length === 0) return null;
+  // Lockfile-only diffs carry no verification recipe — they are dependency
+  // bookkeeping, verified by the next real change that runs the project.
+  if (paths.every((entry) => LOCKFILE_RE.test(entry))) return null;
+  if (paths.some((entry) => UI_PATH_RE.test(entry) || UI_EXT_RE.test(entry))) return 'ui';
+  if (paths.some((entry) => CLI_PATH_RE.test(entry) || CLI_EXT_RE.test(entry))) return 'cli';
+  if (paths.every((entry) => DOCS_PATH_RE.test(entry) || DOCS_EXT_RE.test(entry))) return 'docs';
+  if (paths.every((entry) => CONFIG_BASENAME_RE.test(path.basename(entry)))) return 'config';
+  return null;
+}
+
+// ─── Map loading ────────────────────────────────────────────────────────────
+
+export function verificationMapCandidatePaths({ projectRoot = null, homeDir = null, builtinPath = null } = {}) {
+  const candidates = [];
+  if (projectRoot) {
+    candidates.push({ path: path.join(projectRoot, '.ukit', 'playbooks', MAP_FILENAME), source: 'project' });
+  }
+  if (homeDir !== null) {
+    const base = homeDir || os.homedir();
+    candidates.push({ path: path.join(base, '.ukit', 'playbooks', MAP_FILENAME), source: 'user' });
+  }
+  candidates.push({ path: builtinPath ?? PACKAGE_BUILTIN_MAP_PATH, source: 'builtin' });
+  return candidates;
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Shape check. A valid map needs `version: 1`, at least one playbook row
+ * carrying every required recipe column, and an `artifactClasses` table whose
+ * rows are objects. Returns { ok, reason } — `reason` is a bounded code the
+// doctor check prints verbatim (never the raw parse text on the report line).
+ */
+export function validateVerificationMap(map) {
+  if (!isPlainObject(map)) return { ok: false, reason: 'not-an-object' };
+  if (map.version !== 1) return { ok: false, reason: 'unsupported-version' };
+  if (!isPlainObject(map.playbooks) || Object.keys(map.playbooks).length === 0) {
+    return { ok: false, reason: 'missing-playbooks' };
+  }
+  for (const [id, row] of Object.entries(map.playbooks)) {
+    if (!isPlainObject(row)) return { ok: false, reason: `playbook-row-not-object:${id}` };
+    for (const key of PLAYBOOK_ROW_KEYS) {
+      if (key === 'evidence') {
+        if (!Array.isArray(row.evidence) || row.evidence.length === 0
+          || !row.evidence.every((entry) => typeof entry === 'string' && entry.trim())) {
+          return { ok: false, reason: `playbook-row-missing-evidence:${id}` };
+        }
+      } else if (typeof row[key] !== 'string' || !row[key].trim()) {
+        return { ok: false, reason: `playbook-row-missing-key:${id}.${key}` };
+      }
+    }
+  }
+  if (!isPlainObject(map.artifactClasses)) return { ok: false, reason: 'missing-artifact-classes' };
+  for (const [name, row] of Object.entries(map.artifactClasses)) {
+    if (!ARTIFACT_CLASS_SET.has(name)) return { ok: false, reason: `unknown-artifact-class:${name}` };
+    if (!isPlainObject(row)) return { ok: false, reason: `artifact-row-not-object:${name}` };
+    if (row.evidenceRequired !== undefined
+      && (!Array.isArray(row.evidenceRequired)
+        || !row.evidenceRequired.every((entry) => typeof entry === 'string' && entry.trim()))) {
+      return { ok: false, reason: `artifact-row-bad-evidence:${name}` };
+    }
+  }
+  return { ok: true, reason: null };
+}
+
+/**
+ * Inspect (never throws): walk the candidate tiers, return the first valid map
+ * plus its provenance. On total failure `map` is null and `reason` says why —
+ * `no-map` (nothing readable at any tier) or a validation reason from the
+ * last readable-but-invalid candidate. Consumers treat map===null as
+// "pre-map behavior", the fail-closed contract of ARCH §Failure Modes.
+ */
+export async function inspectVerificationMap({ projectRoot = null, homeDir = null, builtinPath = null } = {}) {
+  let lastInvalidReason = 'no-map';
+  for (const candidate of verificationMapCandidatePaths({ projectRoot, homeDir, builtinPath })) {
+    let raw;
+    try {
+      raw = await fs.readFile(candidate.path, 'utf8');
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      lastInvalidReason = `invalid-json:${candidate.source}`;
+      continue;
+    }
+    const verdict = validateVerificationMap(parsed);
+    if (!verdict.ok) {
+      lastInvalidReason = `${verdict.reason}@${candidate.source}`;
+      continue;
+    }
+    return { map: parsed, path: candidate.path, source: candidate.source, reason: null };
+  }
+  return { map: null, path: null, source: null, reason: lastInvalidReason };
+}
+
+/**
+ * loadVerificationMap(root?) → VerificationMap|null.
+ * `root` is the project root (project-tier map lookup); pass an options object
+ * `{projectRoot, homeDir, builtinPath}` to control every tier. Fails closed:
+ * missing/malformed map → null.
+ */
+export async function loadVerificationMap(rootOrOptions = null) {
+  const options = isPlainObject(rootOrOptions)
+    ? rootOrOptions
+    : { projectRoot: rootOrOptions || null };
+  const { map } = await inspectVerificationMap(options);
+  return map;
+}
+
+// ─── Recipe resolution ──────────────────────────────────────────────────────
+
+function normalizeArtifactClass(artifactClass) {
+  const normalized = String(artifactClass || '').trim().toLowerCase();
+  return ARTIFACT_CLASS_SET.has(normalized) ? normalized : null;
+}
+
+/**
+ * recipeForArtifact({playbookId, artifactClass, map?}) → recipe | null.
+ *
+ * The resolved recipe is the artifact-class row merged with the routed
+ * playbook row (for observability — the class row is what gates):
+ *   { playbookId, artifactClass, check, harness?, fallback?, evidenceRequired[],
+ *     playbook: {launch,doctor,drive,expected,evidence[],cleanup}|null }
+ *
+ * - unknown/missing `artifactClass` → null (pre-map behavior, SPEC §10);
+ * - `map` omitted → loaded on demand (project tier under `projectRoot`);
+ * - map===null / missing class row → null;
+ * - unknown/absent `playbookId` → `playbook: null`, the class row still resolves
+ *   (recipes key on the artifact, not the route).
+ */
+export async function recipeForArtifact({
+  playbookId = null,
+  artifactClass = null,
+  map: mapOption,
+  projectRoot = null,
+} = {}) {
+  const cls = normalizeArtifactClass(artifactClass);
+  if (!cls) return null;
+  const map = mapOption !== undefined ? mapOption : await loadVerificationMap(projectRoot);
+  if (!isPlainObject(map)) return null;
+  const classRow = map.artifactClasses?.[cls];
+  if (!isPlainObject(classRow)) return null;
+
+  const playbookRow = (() => {
+    const id = String(playbookId || '').trim();
+    if (!id) return null;
+    const row = map.playbooks?.[id];
+    if (!isPlainObject(row)) return null;
+    const shaped = {};
+    for (const key of PLAYBOOK_ROW_KEYS) {
+      shaped[key] = key === 'evidence'
+        ? (Array.isArray(row.evidence) ? [...row.evidence] : [])
+        : (typeof row[key] === 'string' ? row[key] : '');
+    }
+    return shaped;
+  })();
+
+  const harness = isPlainObject(classRow.harness) && typeof classRow.harness.packageScript === 'string'
+    ? { packageScript: classRow.harness.packageScript }
+    : null;
+
+  return {
+    playbookId: playbookRow ? String(playbookId).trim() : null,
+    artifactClass: cls,
+    name: typeof classRow.name === 'string' ? classRow.name : cls,
+    check: typeof classRow.check === 'string' && classRow.check.trim() ? classRow.check : null,
+    harness,
+    fallback: typeof classRow.fallback === 'string' && classRow.fallback.trim() ? classRow.fallback.trim() : null,
+    evidenceRequired: Array.isArray(classRow.evidenceRequired)
+      ? classRow.evidenceRequired.filter((entry) => typeof entry === 'string' && entry.trim())
+      : [],
+    playbook: playbookRow,
+  };
+}
+
+// ─── Receipt satisfaction ───────────────────────────────────────────────────
+// Shared by the stop gate (execution-ledger.mjs requires evidence) and the
+// guard's advisory findings — the ledger carries the same semantics pinned by
+// tests/consistency/receiptSatisfactionParity.test.js (runtime/ cannot import
+// index/ — partial installs break — so parity is enforced by test, not a
+// shared import). A required class token may carry `|` alternatives
+// (`render-observation|io-case` — the ARCH evidence cell verbatim): any ONE
+// alternative satisfies it. A class is satisfied when the ledger carries a
+// receipt whose attested `evidence.class` matches an alternative
+// (UKIT_EVIDENCE=class=…;surface=… — direct proof the guard may not have
+// observed), or when the playbook-finding bank records the class — whole
+// token or one alternative — as status 'satisfied'. Findings are latest-wins:
+// ledger.playbookFindings (latest per class, banked outside the evictable
+// receipt window) governs — a later 'missing' finding revokes an earlier
+// 'satisfied' one, and a satisfied class survives receipt eviction via the
+// bank. A failed attestation never satisfies — a failed run that happened to
+// attest a class is not proof of the class.
+
+export function receiptEvidenceSatisfied(requiredClass, ledger = {}) {
+  const token = String(requiredClass || '').trim();
+  const alternatives = token
+    .split('|')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (alternatives.length === 0) return false;
+  const matchesClass = (value) => {
+    const cls = typeof value === 'string' ? value.trim() : '';
+    return cls === token || alternatives.includes(cls);
+  };
+  // The banked latest-per-class status governs the receipt window; several
+  // banked keys can match one anyOf token, so the newest entry wins. A
+  // playbook-finding receipt folds into the bank regardless of its success
+  // flag — the receipt scan below mirrors that.
+  let bankedTs = -1;
+  let bankedStatus = null;
+  const bank = ledger?.playbookFindings;
+  if (bank && typeof bank === 'object') {
+    for (const [key, entry] of Object.entries(bank)) {
+      if (!matchesClass(key)) continue;
+      const ts = typeof entry?.ts === 'number' ? entry.ts : 0;
+      if (ts >= bankedTs) {
+        bankedTs = ts;
+        bankedStatus = typeof entry?.status === 'string' ? entry.status : null;
+      }
+    }
+  }
+  const receipts = Array.isArray(ledger?.receipts) ? ledger.receipts : [];
+  let attested = false;
+  let scannedStatus = null;
+  for (const receipt of receipts) {
+    if (!receipt || typeof receipt !== 'object') continue;
+    if (receipt.kind === 'playbook-finding') {
+      if (matchesClass(receipt.class) && typeof receipt.status === 'string') {
+        scannedStatus = receipt.status; // chronological — last write wins
+      }
+      continue;
+    }
+    if (receipt.success === false) continue;
+    const cls = receipt?.evidence?.class;
+    if (typeof cls === 'string' && alternatives.includes(cls.trim())) attested = true;
+  }
+  if (attested) return true;
+  const findingStatus = bankedTs >= 0 ? bankedStatus : scannedStatus;
+  return findingStatus === 'satisfied';
+}
+
+// ─── Doctor recipe check ────────────────────────────────────────────────────
+/**
+ * doctorRecipeCheck({map, packageJsonScripts}) → { checked, missing[], mapAbsent }.
+ *
+ * ARCH §Failure Modes "verification recipe demands absent harness": a recipe
+ * whose named package.json script is absent degrades to a capability-negotiated
+ * FALLBACK RECEIPT — the returned `fallback` text is the receipt spec to print,
+ * never a fabricated command. `map===null` (absent/malformed) reports
+ * mapAbsent with zero missing entries — a broken map is itself a doctor warning
+// (the caller composes the row), not silent data.
+ */
+export function doctorRecipeCheck({ map = null, packageJsonScripts = {} } = {}) {
+  if (!isPlainObject(map)) {
+    return { checked: 0, missing: [], mapAbsent: true };
+  }
+  const scripts = isPlainObject(packageJsonScripts) ? packageJsonScripts : {};
+  const missing = [];
+  let checked = 0;
+  for (const [className, row] of Object.entries(map.artifactClasses || {})) {
+    const script = row?.harness?.packageScript;
+    if (typeof script !== 'string' || !script.trim()) continue;
+    checked += 1;
+    if (!Object.hasOwn(scripts, script)) {
+      missing.push({
+        artifactClass: className,
+        script,
+        check: typeof row.check === 'string' ? row.check : null,
+        fallback: typeof row.fallback === 'string' ? row.fallback : null,
+      });
+    }
+  }
+  return { checked, missing, mapAbsent: false };
+}
+
+// Sync layer for hook runtimes that evaluate inside a deadline (the guard's
+// git-porcelain path is already synchronous there). Same fail-closed contract.
+export function loadVerificationMapSync(rootOrOptions = null) {
+  const options = isPlainObject(rootOrOptions)
+    ? rootOrOptions
+    : { projectRoot: rootOrOptions || null };
+  const { projectRoot = null, homeDir = null, builtinPath = null } = options;
+  for (const candidate of verificationMapCandidatePaths({ projectRoot, homeDir, builtinPath })) {
+    let raw;
+    try {
+      raw = fsSync.readFileSync(candidate.path, 'utf8');
+    } catch {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (validateVerificationMap(parsed).ok) return parsed;
+    } catch {}
+  }
+  return null;
+}

package/template_project/.claude/hooks/observability-emit.mjs

@@ -0,0 +1,14 @@
+// observability-emit.mjs — TASK-003 (FR-003, BL-005) in-proc chain step.
+//
+// Thin entry the hook-chain-runner loads for the SessionStart /
+// session_start chains. All behavior lives in the parity-locked emit
+// module under ukit/runtime/ so the same record writer is importable by
+// TASK-005's terminal emitters and this step stays a one-line delegate.
+//
+// Advisory end-to-end: runHook always returns { code: 0 } — a telemetry
+// fault can never block or delay session start. Listed FIRST in the chain
+// so the `execution.started` record lands before any slow .sh member can
+// exhaust the chain budget (a timeout further down would silently skip a
+// trailing emit step).
+
+export { runHook } from '../ukit/runtime/observability-emit.mjs';

package/template_project/.claude/hooks/record-execution.mjs

@@ -64,8 +64,9 @@ async function record({ rawInput, projectRoot, env, signal, deadlineMs }) {
   if (typeof ledger.setLedgerMessageEmitter === 'function') {
     ledger.setLedgerMessageEmitter(emit);
   }
+  let receiptResult = null;
   try {
-    await ledger.recordExecutionReceipt({
+    receiptResult = await ledger.recordExecutionReceipt({
       projectRoot,
       payload,
       toolName: payload.tool_name,
@@ -80,6 +81,23 @@ async function record({ rawInput, projectRoot, env, signal, deadlineMs }) {
       ledger.setLedgerMessageEmitter(null);
     }
   }
+  // TASK-005 (FR-005): a committed completion receipt (write/verification
+  // terminal fields) emits `outcome.observed` — the ledger minted the
+  // descriptor inside its lock, this hook emits it here so the telemetry
+  // write never delays the ledger lock. Fire-and-forget: a failed emit
+  // returns null and must not touch the advisory exit.
+  if (receiptResult?.value?.outcome && typeof ledger.emitTerminalOutcome === 'function') {
+    try {
+      await ledger.emitTerminalOutcome({
+        projectRoot,
+        outcome: receiptResult.value.outcome,
+        payload,
+        harness: env.UKIT_HARNESS || 'claude-code',
+        env,
+        deadlineMs: Number.isFinite(deadlineMs) ? Math.min(250, deadlineMs) : 250,
+      });
+    } catch { /* telemetry never blocks the receipt */ }
+  }
   return { code: 0, stdout: emitted.join(''), stderr: '' };
 }