@ngockhoale/ukit 3.0.0 → 3.0.2

package/scripts/bench/v3-ceremony.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * v3-ceremony.mjs — planned-ceremony delta harness (SPEC FR-008, M05.1').
+ *
+ * Seeds a fixture project (same shape as seedOrchestrationLadderFixtureProject /
+ * the corpus test seeder), runs every V3_ROUTE_CORPUS case through
+ * deriveTaskRoute twice — routing.fastPath.stage 'off' vs 'shadow' (rigor stays
+ * 'shadow' in both so riskFloor is emitted on both sides) — and prints a report
+ * of the planned-ceremony surface: skills, helper commands, advisory blocks,
+ * suppressed ceremony, elapsedMs.
+ *
+ * This is a measurement tool, not a gate: it always exits 0. A zero delta is a
+ * finding, not a failure.
+ *
+ * Usage:
+ *   node scripts/bench/v3-ceremony.mjs [--tsv]
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { buildCodeIndex } from '../../src/index/buildIndex.js';
+import { deriveTaskRoute } from '../../src/index/taskRouting.js';
+import { V3_ROUTE_CORPUS } from '../../tests/fixtures/v3RouteCorpus.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+// fastPath off vs on; rigor stays 'shadow' in both runs so riskFloor is emitted
+// and the only moving part is the Fast Path stage itself.
+const CONFIG_OFF = { routing: { rigor: { stage: 'shadow' }, fastPath: { stage: 'off' } } };
+const CONFIG_ON = { routing: { rigor: { stage: 'shadow' }, fastPath: { stage: 'shadow' } } };
+
+async function createFixtureFile(rootDir, relativePath, contents = 'export default true;\n') {
+  const absolutePath = path.join(rootDir, relativePath);
+  await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+  await fs.writeFile(absolutePath, contents, 'utf8');
+}
+
+// Same seeded project shape as the corpus test — the ladder fixture plus the
+// db/migrations tree the schema-change cases target.
+async function seedFixtureProject(rootDir) {
+  await fs.mkdir(path.join(rootDir, '.claude', 'skills'), { recursive: true });
+  await fs.writeFile(
+    path.join(rootDir, 'package.json'),
+    JSON.stringify({
+      packageManager: 'yarn@1.22.22',
+      scripts: {
+        test: 'vitest',
+        lint: 'eslint .',
+        typecheck: 'tsc --noEmit',
+      },
+    }, null, 2),
+    'utf8',
+  );
+
+  await createFixtureFile(rootDir, 'src/core/fileOps.js', 'export function writeFileAtomic(input) { return input; }\n');
+  await createFixtureFile(rootDir, 'src/core/applyPlan.js', 'export function applyPlan(plan) { return plan; }\n');
+  await createFixtureFile(rootDir, 'src/pages/AdminHome.js', 'export function AdminHome() { return true; }\n');
+  await createFixtureFile(rootDir, 'src/api/auth/login.js', 'export async function login() { return { ok: true }; }\n');
+  await createFixtureFile(rootDir, 'src/db/migrations/001_init.sql', 'CREATE TABLE sessions (id text);\n');
+  await createFixtureFile(rootDir, 'src/db/migrations/002_drop_sessions.sql', 'DROP TABLE sessions;\n');
+  await createFixtureFile(rootDir, '.claude/hooks/skill-router.sh', '#!/bin/bash\necho skill-router\n');
+  await createFixtureFile(rootDir, 'template_project/.claude/ukit/runtime/reinject-context.mjs', 'export function reinject() { return true; }\n');
+  await createFixtureFile(rootDir, 'template_project/.claude/ukit/index/route-task.mjs', 'export function routeTask() { return true; }\n');
+  await createFixtureFile(rootDir, 'template_project/ukit/storage/config.json', '{ "version": "1.4.2" }\n');
+
+  await buildCodeIndex({ rootDir });
+}
+
+// The planned-ceremony surface of one route: which skills were activated, which
+// helper commands were planned, which advisory blocks were emitted, and what
+// Fast Path suppressed.
+function measureRoute(route) {
+  const summary = route?.routeSummary ?? {};
+  const helperCommands = [
+    ...(summary.primaryCommands ?? []),
+    ...(summary.fallbackCommands ?? []),
+    summary.helperHint,
+    summary.nextActionCommand,
+  ].filter(Boolean);
+  const advisoryBlocks = [
+    summary.workflowPolicy ? 'workflowPolicy' : null,
+    summary.principleIndex ? 'principleIndex' : null,
+    summary.modelRolesBlock ? 'modelRolesBlock' : null,
+  ].filter(Boolean);
+  return {
+    executionMode: summary.executionMode ?? route?.routingContext?.executionMode ?? null,
+    riskFloor: summary.riskFloor?.floor ?? null,
+    skills: (route?.activeSkills ?? []).map((entry) => entry.id),
+    helperCommands: [...new Set(helperCommands)],
+    advisoryBlocks,
+    eligible: summary.fastPath?.eligible ?? null,
+    suppressed: summary.fastPath?.suppressed ?? [],
+  };
+}
+
+async function measureCase(rootDir, entry, runtimeConfig) {
+  const started = performance.now();
+  const route = await deriveTaskRoute({
+    rootDir,
+    promptText: entry.prompt,
+    commandText: entry.commandText ?? '',
+    targetFile: entry.targetFile,
+    commandNamespace: '.codex',
+    runtimeConfig,
+  });
+  return { ...measureRoute(route), elapsedMs: Math.round(performance.now() - started) };
+}
+
+async function runCase(rootDir, entry) {
+  const row = { name: entry.name, lang: entry.lang, targetFile: entry.targetFile ?? null };
+  try {
+    row.fastPathOff = await measureCase(rootDir, entry, CONFIG_OFF);
+  } catch (error) {
+    row.fastPathOff = { error: error?.message ?? String(error) };
+  }
+  try {
+    row.fastPathOn = await measureCase(rootDir, entry, CONFIG_ON);
+  } catch (error) {
+    row.fastPathOn = { error: error?.message ?? String(error) };
+  }
+  if (row.fastPathOff.error || row.fastPathOn.error) {
+    row.error = row.fastPathOff.error ?? row.fastPathOn.error;
+  }
+  return row;
+}
+
+function sumMetric(cases, side, metric) {
+  return cases.reduce((total, entry) => total + (entry[side]?.[metric]?.length ?? 0), 0);
+}
+
+function buildSummary(cases) {
+  const totals = {};
+  for (const side of ['fastPathOff', 'fastPathOn']) {
+    totals[side] = {
+      skills: sumMetric(cases, side, 'skills'),
+      helperCommands: sumMetric(cases, side, 'helperCommands'),
+      advisoryBlocks: sumMetric(cases, side, 'advisoryBlocks'),
+      suppressed: sumMetric(cases, side, 'suppressed'),
+      elapsedMs: cases.reduce((total, entry) => total + (entry[side]?.elapsedMs ?? 0), 0),
+    };
+  }
+  const fastPathEligibleCount = cases.filter((entry) => entry.fastPathOn?.eligible === true).length;
+  return {
+    caseCount: cases.length,
+    fastPathOff: totals.fastPathOff,
+    fastPathOn: totals.fastPathOn,
+    delta: {
+      skills: totals.fastPathOn.skills - totals.fastPathOff.skills,
+      helperCommands: totals.fastPathOn.helperCommands - totals.fastPathOff.helperCommands,
+      advisoryBlocks: totals.fastPathOn.advisoryBlocks - totals.fastPathOff.advisoryBlocks,
+      suppressed: totals.fastPathOn.suppressed - totals.fastPathOff.suppressed,
+      elapsedMs: totals.fastPathOn.elapsedMs - totals.fastPathOff.elapsedMs,
+      fastPathEligibleCount,
+    },
+  };
+}
+
+function renderTsv(report) {
+  const header = [
+    'name', 'mode', 'riskFloor', 'eligible',
+    'off.skills', 'off.helpers', 'off.advisory', 'off.suppressed', 'off.ms',
+    'on.skills', 'on.helpers', 'on.advisory', 'on.suppressed', 'on.ms',
+  ];
+  const cell = (value) => String(value ?? '').replaceAll('\t', ' ');
+  const rows = report.cases.map((entry) => {
+    const off = entry.fastPathOff ?? {};
+    const on = entry.fastPathOn ?? {};
+    return [
+      entry.name,
+      on.executionMode ?? off.executionMode,
+      on.riskFloor ?? off.riskFloor,
+      on.eligible,
+      off.skills?.length, off.helperCommands?.length, off.advisoryBlocks?.length, off.suppressed?.length, off.elapsedMs,
+      on.skills?.length, on.helperCommands?.length, on.advisoryBlocks?.length, on.suppressed?.length, on.elapsedMs,
+    ].map(cell).join('\t');
+  });
+  const d = report.summary.delta;
+  rows.push([
+    'SUMMARY', `${report.summary.caseCount} cases`, '', `eligible=${d.fastPathEligibleCount}`,
+    report.summary.fastPathOff.skills, report.summary.fastPathOff.helperCommands,
+    report.summary.fastPathOff.advisoryBlocks, report.summary.fastPathOff.suppressed,
+    report.summary.fastPathOff.elapsedMs,
+    report.summary.fastPathOn.skills, report.summary.fastPathOn.helperCommands,
+    report.summary.fastPathOn.advisoryBlocks, report.summary.fastPathOn.suppressed,
+    report.summary.fastPathOn.elapsedMs,
+  ].map(cell).join('\t'));
+  return [header.join('\t'), ...rows].join('\n');
+}
+
+async function main() {
+  const tsv = process.argv.slice(2).includes('--tsv');
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ukit-v3-ceremony-'));
+  try {
+    await seedFixtureProject(tmpDir);
+    const cases = [];
+    for (const entry of V3_ROUTE_CORPUS) {
+      cases.push(await runCase(tmpDir, entry));
+    }
+    const report = { cases, summary: buildSummary(cases) };
+    console.log(tsv ? renderTsv(report) : JSON.stringify(report, null, 2));
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// Measurement tool, not a gate: even a catastrophic failure reports and exits 0.
+try {
+  await main();
+} catch (error) {
+  console.log(JSON.stringify({ cases: [], summary: null, fatal: error?.message ?? String(error) }));
+}

package/scripts/install/sync-installed-mirror.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // C5 (docs/AI_REPORT/archive/2026-09-20-CORRECTNESS.md §C5) — scoped mirror sync/check.
 //
-// The installed `.claude/` + `.omp/` mirror is a *rendered* copy of `templates/.claude`
-// + `templates/.omp`, and hand-copying it drifted three separate ways this cycle:
+// The installed `.claude/` + `.omp/` mirror is a *rendered* copy of `template_project/.claude`
+// + `template_project/.omp`, and hand-copying it drifted three separate ways this cycle:
 // a template change never re-copied, a raw copy that kept its literal `{{token}}`
 // because nobody rendered it, and `settings.json`'s two gateway-injected env keys,
 // which make whole-file byte identity impossible by construction. Parallel lanes
@@ -26,7 +26,7 @@
 //     user-owned, not template-derived. They are excluded from drift AND from apply —
 //     a hands-off file must never read as drift, and this tool is not an installer.
 //   * Mirror-only detection is limited to the target directories of *selected,
-//     non-link* manifest items — directories UKit owns wholesale from `templates/`.
+//     non-link* manifest items — directories UKit owns wholesale from `template_project/`.
 //     A blanket walk of `.claude/` reports ~226 false positives, because pack-gated
 //     skill libraries (e.g. `.claude/skills/frontend-vue/**` on a `core`-only project)
 //     are present in the mirror but intentionally outside the current plan. Those

package/scripts/perf/audit-perf.mjs

@@ -57,10 +57,10 @@ const HOTSPOT_P50_MS = 50;
 // telemetry `node --finish` child armed by hook-telemetry.sh.
 const PROCESSES_PER_HOOK_ROW = 3;
 
-const HOOKS_SUBPATH = ['templates', '.claude', 'hooks'];
+const HOOKS_SUBPATH = ['template_project', '.claude', 'hooks'];
 const CHAIN_RUNNER_LABEL = 'hook-chain-runner';
 // The ONE append API every hook writes through — the subject of the O5 benchmark.
-const TELEMETRY_MODULE_SUBPATH = ['templates', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'];
+const TELEMETRY_MODULE_SUBPATH = ['template_project', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'];
 
 // Index/router helpers a prompt or an edit pays a cold start for (SPEC §2.5).
 const ROUTER_HELPERS = [
@@ -383,7 +383,7 @@ function loadSettings(root, override) {
   const candidates = override
     ? [override]
     : [
-      path.join(root, 'templates', '.claude', 'settings.json'),
+      path.join(root, 'template_project', '.claude', 'settings.json'),
       path.join(root, '.claude', 'settings.json'),
     ];
   for (const candidate of candidates) {
@@ -438,7 +438,7 @@ function scratchRoot(label) {
 
 function benchmarkFloor(root, iterations) {
   const env = { ...process.env, CLAUDE_PROJECT_DIR: root };
-  const telemetryTwin = path.join(root, 'templates', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs');
+  const telemetryTwin = path.join(root, 'template_project', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs');
   const scratch = scratchRoot('floor');
   try {
     return {
@@ -464,7 +464,7 @@ function benchmarkFloor(root, iterations) {
 /** The telemetry writer a tree ships, preferring the template (like hooksDir). */
 function telemetryModulePath(root) {
   const candidates = [
-    path.join(root, 'templates', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'),
+    path.join(root, 'template_project', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'),
     path.join(root, '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'),
   ];
   return candidates.find((candidate) => fs.existsSync(candidate)) || null;
@@ -554,9 +554,9 @@ function recentHotPathAdditions(root, sinceDays) {
         '--name-only',
         '--diff-filter=A',
         '--',
-        'templates/.claude/hooks',
-        'templates/.claude/ukit/runtime',
-        'templates/.claude/ukit/index',
+        'template_project/.claude/hooks',
+        'template_project/.claude/ukit/runtime',
+        'template_project/.claude/ukit/index',
         '.claude/hooks',
         '.claude/ukit/runtime',
       ],
@@ -763,7 +763,7 @@ function buildFindings(context) {
       id: 'c29-c32-hot-path-additions',
       area: `recent hot-path additions — ${addedFiles.length} files across ${additions.length} commits`,
       evidence: 'git-log',
-      evidenceDetail: `git log --since=${context.sinceDays} days ago --diff-filter=A -- templates/.claude/hooks templates/.claude/ukit/runtime templates/.claude/ukit/index: ${addedFiles.slice(0, 12).join(', ')}${addedFiles.length > 12 ? `, +${addedFiles.length - 12} more` : ''}`,
+      evidenceDetail: `git log --since=${context.sinceDays} days ago --diff-filter=A -- template_project/.claude/hooks template_project/.claude/ukit/runtime template_project/.claude/ukit/index: ${addedFiles.slice(0, 12).join(', ')}${addedFiles.length > 12 ? `, +${addedFiles.length - 12} more` : ''}`,
       p50ms: null,
       p95ms: null,
       totalMs: null,

package/scripts/perf/perf-findings.json

@@ -9,8 +9,8 @@
       "rows": 62854,
       "files": 120
     },
-    "settings": "/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/templates/.claude/settings.json",
-    "hooksDir": "/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/templates/.claude/hooks",
+    "settings": "/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/template_project/.claude/settings.json",
+    "hooksDir": "/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/template_project/.claude/hooks",
     "benchmarkIterations": 2,
     "gitLogWindowDays": 14
   },
@@ -279,7 +279,7 @@
       "id": "c29-c32-hot-path-additions",
       "area": "recent hot-path additions — 24 files across 18 commits",
       "evidence": "git-log",
-      "evidenceDetail": "git log --since=14 days ago --diff-filter=A -- templates/.claude/hooks templates/.claude/ukit/runtime templates/.claude/ukit/index: templates/.claude/hooks/block-dangerous.mjs, templates/.claude/hooks/record-execution.mjs, templates/.claude/hooks/sensitive-data-guard.mjs, templates/.claude/ukit/runtime/hook-field-salvage.mjs, templates/.claude/hooks/session-episode.sh, templates/.claude/hooks/project-important.sh, templates/.claude/hooks/project-important.sh, templates/.claude/ukit/runtime/project-important.mjs, templates/.claude/ukit/runtime/sensitive-value-scanner.mjs, templates/.claude/ukit/runtime/hook-chain-budget.mjs, templates/.claude/ukit/runtime/stop-coordinator.mjs, templates/.claude/ukit/runtime/hook-payload-store.mjs, +12 more",
+      "evidenceDetail": "git log --since=14 days ago --diff-filter=A -- template_project/.claude/hooks template_project/.claude/ukit/runtime template_project/.claude/ukit/index: template_project/.claude/hooks/block-dangerous.mjs, template_project/.claude/hooks/record-execution.mjs, template_project/.claude/hooks/sensitive-data-guard.mjs, template_project/.claude/ukit/runtime/hook-field-salvage.mjs, template_project/.claude/hooks/session-episode.sh, template_project/.claude/hooks/project-important.sh, template_project/.claude/hooks/project-important.sh, template_project/.claude/ukit/runtime/project-important.mjs, template_project/.claude/ukit/runtime/sensitive-value-scanner.mjs, template_project/.claude/ukit/runtime/hook-chain-budget.mjs, template_project/.claude/ukit/runtime/stop-coordinator.mjs, template_project/.claude/ukit/runtime/hook-payload-store.mjs, +12 more",
       "p50ms": null,
       "p95ms": null,
       "totalMs": null,
@@ -318,7 +318,7 @@
       "id": "telemetry-append-overhead",
       "area": "telemetry append overhead — appendTelemetryRow, in-process against a throwaway project root",
       "evidence": "micro-benchmark",
-      "evidenceDetail": "appendTelemetryRow over 2 iterations against a temp project root (the audited telemetry dir is never written): p50 0.407ms, p95 0.407ms, max 0.407ms, total 0.464ms; writer templates/.claude/ukit/runtime/hook-telemetry.mjs",
+      "evidenceDetail": "appendTelemetryRow over 2 iterations against a temp project root (the audited telemetry dir is never written): p50 0.407ms, p95 0.407ms, max 0.407ms, total 0.464ms; writer template_project/.claude/ukit/runtime/hook-telemetry.mjs",
       "p50ms": 0.407125,
       "p95ms": 0.407125,
       "totalMs": 0.464083,

package/scripts/perf/perf-measure.md

@@ -17,7 +17,7 @@ node scripts/perf/diff-perf-findings.mjs <earlier-snapshot>.json scripts/perf/pe
 node --test tests/handoff/c33/perfFindings.test.js
 
 - root: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit`
-- settings.json: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/templates/.claude/settings.json`
+- settings.json: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/template_project/.claude/settings.json`
 - hooks resolved from: `NOT FOUND`
 - telemetry: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/.ukit/storage/cache/hook-latency` — 62854 rows in 120 files
 - snapshot provenance: generatedAt `2026-09-20T23:07:33.744Z`, telemetryRows: 62854, telemetryFiles: 120 — hooks append continuously, so a report is a point-in-time view, not a stable dataset
@@ -39,7 +39,7 @@ A hook row = wrapper bash + node runtime + advisory telemetry child = **3 proces
 |---|---|---|---|---|
 | `appendTelemetryRow` → throwaway temp root | 2 | 0.407 | 0.407 | 0.407 |
 
-Writer: `templates/.claude/ukit/runtime/hook-telemetry.mjs`. Measured against a temp project root, so auditing a tree never adds rows to the dataset it is counting.
+Writer: `template_project/.claude/ukit/runtime/hook-telemetry.mjs`. Measured against a temp project root, so auditing a tree never adds rows to the dataset it is counting.
 
 ## 4. Per-hook standalone re-run (`/bin/bash <script>` with `{}` on stdin, ms)
 | hook | p50 | p95 | max |
@@ -210,24 +210,24 @@ split or never staged stdin: it is excluded, never counted as a 0ms stage.
 
 | commit | date | subject | files added |
 |---|---|---|---|
-| `c0443e73` | 2026-09-20 | handoff: wave 2 — TASK-003 (block-dangerous.mjs port) + TASK-004 (record-execution.mjs + ledger emitter) + manifest module entries | `templates/.claude/hooks/block-dangerous.mjs`, `templates/.claude/hooks/record-execution.mjs` |
-| `79f747b6` | 2026-09-20 | handoff: wave 1 — TASK-001 (runner .mjs module-steps) + TASK-002 (sensitive-data-guard port + field-salvage) | `templates/.claude/hooks/sensitive-data-guard.mjs`, `templates/.claude/ukit/runtime/hook-field-salvage.mjs` |
-| `6b339905` | 2026-09-20 | handoff: wave 3 — TASK-231, TASK-232 | `templates/.claude/hooks/session-episode.sh` |
-| `4903ee62` | 2026-09-18 | handoff: restore wave-4a files removed by stale worktree diff | `templates/.claude/hooks/project-important.sh` |
-| `2b367850` | 2026-09-18 | handoff: wave 4a — TASK-041 (sessionstart wiring, hook template+manifest) | `templates/.claude/hooks/project-important.sh` |
-| `5ffefb09` | 2026-09-18 | handoff: wave 3 — TASK-038 | `templates/.claude/ukit/runtime/project-important.mjs`, `templates/.claude/ukit/runtime/sensitive-value-scanner.mjs` |
-| `ebb846b8` | 2026-09-17 | handoff: R4.5 fix round 1 — TASK-018, TASK-023 | `templates/.claude/ukit/runtime/hook-chain-budget.mjs` |
-| `c9da9734` | 2026-09-17 | handoff: wave 6 — TASK-025 copy-back (Stop coordinator) | `templates/.claude/ukit/runtime/stop-coordinator.mjs` |
-| `a1361afd` | 2026-09-17 | handoff: wave 5 — TASK-031 copy-back | `templates/.claude/ukit/runtime/hook-payload-store.mjs` |
-| `66787f98` | 2026-09-17 | handoff: wave 5 — TASK-019 copy-back | `templates/.claude/ukit/runtime/hook-telemetry.mjs`, `templates/.claude/ukit/runtime/hook-telemetry.sh` |
-| `3afc88e6` | 2026-09-17 | handoff: wave 5 — TASK-029 copy-back (context capacity negotiation) | `templates/.claude/ukit/runtime/context-capacity.mjs` |
-| `6f224875` | 2026-09-17 | handoff: wave 3 — TASK-028 copy-back | `templates/.claude/ukit/runtime/async-lock.mjs` |
-| `e4b647a3` | 2026-09-17 | handoff: wave 3 — TASK-016 copy-back | `templates/.claude/ukit/runtime/hook-process.mjs` |
-| `7aa89361` | 2026-09-17 | handoff: wave 2 — TASK-015, TASK-017 | `templates/.claude/ukit/runtime/transcript-tail.mjs` |
-| `2652bbff` | 2026-09-17 | milestone: TASK-014 bounded stdin transport (H01) | `templates/.claude/ukit/runtime/hook-input.mjs`, `templates/.claude/ukit/runtime/hook-input.sh` |
-| `6b40da83` | 2026-09-12 | handoff: wave 1 batch 2 — TASK-016 wall-clock watchdog hook (hardPolicy=split) | `templates/.claude/hooks/task-watchdog.sh`, `templates/.claude/ukit/runtime/task-watchdog.mjs` |
-| `0fc81692` | 2026-09-12 | handoff: wave 1 fix — anchor runtime-dir ignores, track lost TASK-014 CLI twin | `templates/.claude/ukit/index/task-budget-validator.mjs` |
-| `cfc3b7f1` | 2026-09-08 | 2.3.0 — fail-closed sensitive-data gate; contract tables unified to executionContracts.js; tierLane wiring; evidence + vision hardening | `templates/.claude/hooks/sensitive-data-guard.sh` |
+| `c0443e73` | 2026-09-20 | handoff: wave 2 — TASK-003 (block-dangerous.mjs port) + TASK-004 (record-execution.mjs + ledger emitter) + manifest module entries | `template_project/.claude/hooks/block-dangerous.mjs`, `template_project/.claude/hooks/record-execution.mjs` |
+| `79f747b6` | 2026-09-20 | handoff: wave 1 — TASK-001 (runner .mjs module-steps) + TASK-002 (sensitive-data-guard port + field-salvage) | `template_project/.claude/hooks/sensitive-data-guard.mjs`, `template_project/.claude/ukit/runtime/hook-field-salvage.mjs` |
+| `6b339905` | 2026-09-20 | handoff: wave 3 — TASK-231, TASK-232 | `template_project/.claude/hooks/session-episode.sh` |
+| `4903ee62` | 2026-09-18 | handoff: restore wave-4a files removed by stale worktree diff | `template_project/.claude/hooks/project-important.sh` |
+| `2b367850` | 2026-09-18 | handoff: wave 4a — TASK-041 (sessionstart wiring, hook template+manifest) | `template_project/.claude/hooks/project-important.sh` |
+| `5ffefb09` | 2026-09-18 | handoff: wave 3 — TASK-038 | `template_project/.claude/ukit/runtime/project-important.mjs`, `template_project/.claude/ukit/runtime/sensitive-value-scanner.mjs` |
+| `ebb846b8` | 2026-09-17 | handoff: R4.5 fix round 1 — TASK-018, TASK-023 | `template_project/.claude/ukit/runtime/hook-chain-budget.mjs` |
+| `c9da9734` | 2026-09-17 | handoff: wave 6 — TASK-025 copy-back (Stop coordinator) | `template_project/.claude/ukit/runtime/stop-coordinator.mjs` |
+| `a1361afd` | 2026-09-17 | handoff: wave 5 — TASK-031 copy-back | `template_project/.claude/ukit/runtime/hook-payload-store.mjs` |
+| `66787f98` | 2026-09-17 | handoff: wave 5 — TASK-019 copy-back | `template_project/.claude/ukit/runtime/hook-telemetry.mjs`, `template_project/.claude/ukit/runtime/hook-telemetry.sh` |
+| `3afc88e6` | 2026-09-17 | handoff: wave 5 — TASK-029 copy-back (context capacity negotiation) | `template_project/.claude/ukit/runtime/context-capacity.mjs` |
+| `6f224875` | 2026-09-17 | handoff: wave 3 — TASK-028 copy-back | `template_project/.claude/ukit/runtime/async-lock.mjs` |
+| `e4b647a3` | 2026-09-17 | handoff: wave 3 — TASK-016 copy-back | `template_project/.claude/ukit/runtime/hook-process.mjs` |
+| `7aa89361` | 2026-09-17 | handoff: wave 2 — TASK-015, TASK-017 | `template_project/.claude/ukit/runtime/transcript-tail.mjs` |
+| `2652bbff` | 2026-09-17 | milestone: TASK-014 bounded stdin transport (H01) | `template_project/.claude/ukit/runtime/hook-input.mjs`, `template_project/.claude/ukit/runtime/hook-input.sh` |
+| `6b40da83` | 2026-09-12 | handoff: wave 1 batch 2 — TASK-016 wall-clock watchdog hook (hardPolicy=split) | `template_project/.claude/hooks/task-watchdog.sh`, `template_project/.claude/ukit/runtime/task-watchdog.mjs` |
+| `0fc81692` | 2026-09-12 | handoff: wave 1 fix — anchor runtime-dir ignores, track lost TASK-014 CLI twin | `template_project/.claude/ukit/index/task-budget-validator.mjs` |
+| `cfc3b7f1` | 2026-09-08 | 2.3.0 — fail-closed sensitive-data gate; contract tables unified to executionContracts.js; tierLane wiring; evidence + vision hardening | `template_project/.claude/hooks/sensitive-data-guard.sh` |
 
 ## 13. Findings emitted
 

package/src/cli/commands/doctor.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import os from 'node:os';
+import { parse } from 'yaml';
 import { pathExists, readJsonIfExists } from '../../core/fileOps.js';
 import { buildPathConfig } from '../../core/paths.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
@@ -32,8 +33,8 @@ import { loadPlaybooks } from '../../core/userPlaybooks.js';
 import { userMemoryStats } from '../../core/memory/userMemory.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
-const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway', '--docs', '--permissions', '--json']);
-const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway, --docs, --permissions, --json';
+const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway', '--docs', '--permissions', '--conformance', '--json']);
+const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway, --docs, --permissions, --conformance, --json';
 
 export function printDoctorHelp() {
   console.log('Usage: ukit doctor [options]');
@@ -47,6 +48,7 @@ export function printDoctorHelp() {
   console.log('  --docs          Run doc-contract checks (manifests/documentation.yaml projects only)');
   console.log('  --permissions   Print the full per-host permission report table');
   console.log('  --json          Emit the permission report as JSON ({permissions:{...}})');
+  console.log('  --conformance   Print the engine conformance matrix (enforcement class per host)');
 }
 
 function printPermissionSection(permissionReport, { verbose }) {
@@ -91,6 +93,40 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
     return;
   }
 
+  // TASK-002 / FR-003 — `--conformance` is a standalone diagnostic surface: it
+  // prints the enforcement-class matrix from manifests/engineConformance.yaml
+  // and returns. Missing/malformed manifest degrades to an `unavailable` line;
+  // it never throws and never affects the exit code (advisory report only).
+  if (argv.includes('--conformance')) {
+    const conformancePath = path.join(packageRoot, 'manifests', 'engineConformance.yaml');
+    let conformance = null;
+    let unavailableReason = null;
+    try {
+      conformance = parse(await fs.readFile(conformancePath, 'utf8'));
+    } catch (error) {
+      unavailableReason = error?.code === 'ENOENT'
+        ? 'manifests/engineConformance.yaml not found'
+        : (error?.message ?? String(error));
+    }
+    const classes = conformance?.classes;
+    if (!unavailableReason && (conformance?.version !== 1 || !classes || typeof classes !== 'object')) {
+      unavailableReason = 'unexpected manifest shape (expected version: 1 with classes)';
+    }
+    if (unavailableReason) {
+      console.log(`[UKit]   conformance: unavailable (${unavailableReason})`);
+      return;
+    }
+    console.log('[UKit] Engine conformance matrix:');
+    for (const [className, classEntry] of Object.entries(classes)) {
+      const hosts = classEntry?.hosts ?? {};
+      for (const [host, cell] of Object.entries(hosts)) {
+        const detail = cell?.evidence ?? cell?.note;
+        console.log(`[UKit]   ${host} · ${className}: ${cell?.support ?? 'unknown'}${detail ? ` (${detail})` : ''}`);
+      }
+    }
+    return;
+  }
+
   const pathConfig = buildPathConfig({ packageRoot, projectRoot });
   const runtimePaths = buildRuntimePaths(projectRoot);
   const manifest = await loadManifest(pathConfig.manifestPath);

package/src/core/buildPlan.js

@@ -75,8 +75,8 @@ async function isSelfInstall({ templatesRoot, projectRoot }) {
 }
 
 // In the UKit source repo, docs/ holds canonical sources that deliberately diverge from the
-// shipped copies under templates/ (docs/PROMPT_CACHING.md is the full ruleset while
-// templates/docs/ ships a distilled version). The refresh-on-update strategy would silently
+// shipped copies under template_project/ (docs/PROMPT_CACHING.md is the full ruleset while
+// template_project/docs/ ships a distilled version). The refresh-on-update strategy would silently
 // clobber those canonical files, so downgrade docs overwrites to skip: seed a missing doc, but
 // never overwrite one that already exists.
 async function downgradeSelfInstallDocOverwrites(planEntries, { templatesRoot, projectRoot }) {
@@ -267,7 +267,7 @@ export async function buildInstallPlan({
     });
   }
 
-  // Auto-discover files in templates/ not covered by manifest
+  // Auto-discover files in template_project/ not covered by manifest
   if (manifest.autoDiscoverTemplates === true) {
     const allTemplateFiles = await walkDirectory(templatesRoot);
 

package/src/core/compact/contextBudget.js

@@ -6,8 +6,8 @@ import { fileURLToPath } from 'node:url';
 // code-side defaults, CLAUDE_CODE_AUTO_COMPACT_WINDOW in .claude/settings.json, and
 // compaction.thresholdTokens in .omp/config.yml — is read or derived from here, so retuning
 // UKit for a different model context window is a three-number edit in
-// templates/ukit/storage/config.json and nothing else.
-const SHIPPED_CONFIG_URL = new URL('../../../templates/ukit/storage/config.json', import.meta.url);
+// template_project/ukit/storage/config.json and nothing else.
+const SHIPPED_CONFIG_URL = new URL('../../../template_project/ukit/storage/config.json', import.meta.url);
 
 // Only reachable if the package ships without its own templates. Deliberately conservative:
 // a 200k model survives these, a 1M model merely compacts earlier than it had to.

package/src/core/compact/threshold.js

@@ -4,8 +4,8 @@ import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
 import {
   readContextCapacityRecord,
   SOFT_TO_CAP_RATIO,
-} from '../../../templates/.claude/ukit/runtime/compact-threshold.mjs';
-import { resolveContextCapTokens } from '../../../templates/.claude/ukit/runtime/context-capacity.mjs';
+} from '../../../template_project/.claude/ukit/runtime/compact-threshold.mjs';
+import { resolveContextCapTokens } from '../../../template_project/.claude/ukit/runtime/context-capacity.mjs';
 import { buildRuntimePaths } from '../runtimePaths.js';
 import { buildCompactMachineKey, compressLine, estimateTokenCount } from '../token/index.js';
 import { compactContextBlock } from './index.js';
@@ -605,7 +605,7 @@ export function resolveThresholdCompactBudget({
 // advisories), and a brand-new session must not inherit a sibling's totals. The newest
 // record's flat fields stay projected at the document's top level so readers that predate
 // this shape (raw JSON readers) still see a coherent state.
-// Mirrors templates/.claude/ukit/runtime/compact-threshold.mjs — keep in lockstep.
+// Mirrors template_project/.claude/ukit/runtime/compact-threshold.mjs — keep in lockstep.
 const PRESSURE_SESSIONS_MAX = 8;
 
 function normalizeSessionId(value) {

package/src/core/docContracts.js

@@ -47,21 +47,21 @@ const STALE_VERSION_ALLOWLIST = {
     'same interpolated runtime.nodeVersion — environment fact, not a UKit release pin',
   'docs/WORKLOG_ARCHIVE.md':
     'worklog history records past versions as release facts — immutable historical prose',
-  'templates/.gitignore':
+  'template_project/.gitignore':
     'comment records the release that removed a legacy adapter — historical fact',
-  'templates/.claude/agents/code-reviewer.md':
+  'template_project/.claude/agents/code-reviewer.md':
     'rubric row quotes the literal "v1.5.5+ contract" reviewer refusal wording — contractual string',
-  'templates/.omp/agents/code-reviewer.md':
+  'template_project/.omp/agents/code-reviewer.md':
     'omp mirror of the same reviewer rubric row — contractual string',
-  'templates/.claude/ukit/index/unic-gateway.mjs':
+  'template_project/.claude/ukit/index/unic-gateway.mjs':
     'code comments record the omp version gateway detection was verified against — evidence',
-  'templates/.omp/hooks/pre/ukit-bridge.js':
+  'template_project/.omp/hooks/pre/ukit-bridge.js':
     'code comments record omp versions verified during source reads — evidence',
-  'templates/.omp/config.yml':
+  'template_project/.omp/config.yml':
     'comment records the omp version the config keys were verified against — evidence',
 };
 
-// Files covered by stale-version + render-vars beyond `templates/` generated
+// Files covered by stale-version + render-vars beyond `template_project/` generated
 // surfaces: the repo-rendered root instructions (registry class is `canonical`
 // because they are also the project-owner file) and derived mirrors.
 const RENDERED_EXTRA_TARGETS = ['CLAUDE.md', 'AGENTS.md'];
@@ -240,10 +240,10 @@ async function checkLinks(rootDir, registry) {
         const resolved = path.normalize(path.join(path.dirname(rel), target));
         let ok = await existsPath(path.join(rootDir, resolved));
         // Tolerances: (a) root-relative links (docs write `docs/x.md` from repo
-        // root), (b) runtime surfaces shipped under templates/ (`.omp/...` in
-        // source repo lives at templates/.omp/...).
+        // root), (b) runtime surfaces shipped under template_project/ (`.omp/...` in
+        // source repo lives at template_project/.omp/...).
         if (!ok) ok = await existsPath(path.join(rootDir, target));
-        if (!ok) ok = await existsPath(path.join(rootDir, 'templates', target));
+        if (!ok) ok = await existsPath(path.join(rootDir, 'template_project', target));
         if (!ok) broken.push(`${rel}:${i + 1} → ${target}`);
       }
     }
@@ -271,10 +271,10 @@ async function checkStaleVersion(rootDir, registry) {
     return makeCheck(id, label, 'error', { skipped: true, detail: 'package.json version unreadable' });
   }
   // Scanned set mirrors staleVersionProse: any-extension files under
-  // canonical/generated templates/ entries + the rendered root instructions.
+  // canonical/generated template_project/ entries + the rendered root instructions.
   const files = new Set(RENDERED_EXTRA_TARGETS);
   for (const e of registry.entries) {
-    if (typeof e.path !== 'string' || !e.path.startsWith('templates/')) continue;
+    if (typeof e.path !== 'string' || !e.path.startsWith('template_project/')) continue;
     if (!['canonical', 'generated'].includes(e.class)) continue;
     if (e.path.endsWith('/')) {
       for (const f of await walkFiles(rootDir, e.path.slice(0, -1))) files.add(f);
@@ -307,11 +307,11 @@ async function checkRenderVars(rootDir, registry) {
   const id = 'render-vars';
   const label = 'no unresolved {{var}} placeholders in rendered targets';
   // Rendered surfaces: repo outputs (CLAUDE.md/AGENTS.md) + derived mirrors.
-  // templates/ generated files legitimately keep {{var}} for install-time
+  // template_project/ generated files legitimately keep {{var}} for install-time
   // interpolation, so they are out of scope.
   const targets = new Set(RENDERED_EXTRA_TARGETS);
   for (const e of registry.entries) {
-    if (typeof e.path !== 'string' || e.class !== 'derived' || e.path.startsWith('templates/')) continue;
+    if (typeof e.path !== 'string' || e.class !== 'derived' || e.path.startsWith('template_project/')) continue;
     // Only .md doc surfaces are render targets — scripts/components/templates
     // inside derived dirs legitimately use {{ }} as their own placeholders.
     if (e.path.endsWith('/')) {
@@ -353,7 +353,7 @@ async function checkCommands(rootDir, registry) {
       const name = m[1];
       const inRepo = await existsPath(path.join(rootDir, '.claude/commands/ukit', name));
       const inTemplates = await existsPath(
-        path.join(rootDir, 'templates/.claude/commands/ukit', name),
+        path.join(rootDir, 'template_project/.claude/commands/ukit', name),
       );
       if (!inRepo && !inTemplates) missing.push(`${rel}: .claude/commands/ukit/${name}`);
     }
@@ -579,11 +579,11 @@ async function checkRegistry(rootDir, registry, fileExists) {
 }
 
 async function checkTemplates(rootDir) {
-  const id = 'templates';
+  const id = 'template_project';
   const label = '_TEMPLATE.md copies declare the Executor Report header fields (FR-013)';
   const copies = [
     'docs/AI_HANDOFF/tasks/_TEMPLATE.md',
-    'templates/docs/AI_HANDOFF/tasks/_TEMPLATE.md',
+    'template_project/docs/AI_HANDOFF/tasks/_TEMPLATE.md',
   ];
   const foundAny = await Promise.all(
     copies.map((rel) => existsPath(path.join(rootDir, rel))),

package/src/core/ensureGitignore.js

@@ -4,7 +4,7 @@ import { writeFileAtomic } from './fileOps.js';
 
 // Root-anchored (leading `/`) so the block only ignores project-root entries.
 // Unanchored dir entries (`.claude/`) match same-named dirs at ANY depth and
-// hid templates/.claude from git — the C12 trap `ukit install` kept re-adding.
+// hid template_project/.claude from git — the C12 trap `ukit install` kept re-adding.
 // Entries with an inner slash (`.claude/ukit/...`) are already root-anchored
 // by gitignore semantics.
 const UKIT_ENTRIES = [