@ngockhoale/ukit 2.7.13 → 3.0.0

package/src/core/runtimeConfig.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { buildRuntimePaths } from './runtimePaths.js';
+import { buildUserPaths } from './userPaths.js';
 import { loadShippedCompactBudget } from './compact/contextBudget.js';
 import { buildConfigContracts } from './executionContracts.js';
 
@@ -18,6 +19,67 @@ const VALID_AGENTS = new Set(['claude-code', 'codex', 'antigravity', 'omp']);
 // 'unattended' is the only mode implemented this cycle; interactive/safe-auto are reserved.
 export const VALID_PERMISSION_MODES = new Set(['interactive', 'safe-auto', 'unattended']);
 
+// --- modelRoles (SPEC-model-roles, v3 mechanic #4) -------------------------------------
+// Role labels name WHAT the model is for, not which tier it is. Values are cost-tier
+// names ('lite'|'code'|'smart'|'vision') or 'inherit-parent' — never raw provider model
+// IDs; the host adapter resolves tier→actual model. Arrays = panels (one agent per
+// entry; list length sets the panel count). omp's .omp/config.yml modelRoles resolves
+// @smol/@default/@slow to the same tiers (smol↔lite, default↔code, slow↔smart).
+export const MODEL_ROLE_TIERS = new Set(['lite', 'code', 'smart', 'vision']);
+export const MODEL_ROLE_INHERIT = 'inherit-parent';
+export const DEFAULT_MODEL_ROLES = Object.freeze({
+  code: 'code',
+  judgment: 'smart',
+  'review-panel': ['smart', 'code', 'lite'],
+  'fast-worker': 'lite',
+  vision: 'vision',
+});
+
+function isValidModelRoleValue(value) {
+  if (typeof value === 'string') {
+    return MODEL_ROLE_TIERS.has(value) || value === MODEL_ROLE_INHERIT;
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0
+      && value.every((entry) => MODEL_ROLE_TIERS.has(entry) || entry === MODEL_ROLE_INHERIT);
+  }
+  return false;
+}
+
+// Resolves the effective role→tier map. Invalid entries warn + fall back to the
+// default for that role — never block, never throw. Unknown role names are dropped
+// with a warning so a stale config cannot invent roles the skills don't speak.
+export function resolveModelRoles(config = null) {
+  const warnings = [];
+  const resolved = {
+    code: DEFAULT_MODEL_ROLES.code,
+    judgment: DEFAULT_MODEL_ROLES.judgment,
+    'review-panel': [...DEFAULT_MODEL_ROLES['review-panel']],
+    'fast-worker': DEFAULT_MODEL_ROLES['fast-worker'],
+    vision: DEFAULT_MODEL_ROLES.vision,
+  };
+  const configured = config?.modelRoles;
+  if (configured === undefined || configured === null) {
+    return { roles: resolved, warnings };
+  }
+  if (!isPlainObject(configured)) {
+    warnings.push('modelRoles must be an object; using defaults.');
+    return { roles: resolved, warnings };
+  }
+  for (const [role, value] of Object.entries(configured)) {
+    if (!(role in DEFAULT_MODEL_ROLES)) {
+      warnings.push(`modelRoles.${role} is not a known role; ignored.`);
+      continue;
+    }
+    if (!isValidModelRoleValue(value)) {
+      warnings.push(`modelRoles.${role} must be a tier name, 'inherit-parent', or a non-empty array of those; using default.`);
+      continue;
+    }
+    resolved[role] = Array.isArray(value) ? [...value] : value;
+  }
+  return { roles: resolved, warnings };
+}
+
 const BLOCKED_MERGE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 
 function isPlainObject(value) {
@@ -47,6 +109,62 @@ function mergeObjects(base, override) {
   return merged;
 }
 
+// User-level layer (SPEC §5 FR-005): ~/.ukit/storage/config.json merges between the
+// built-in defaults and the project config — project wins every key. `version` and
+// `agent` are project-managed: a stale user file must not pin a project to an old
+// version or a removed agent, so they are stripped (warn once per process per key).
+const PROJECT_MANAGED_USER_KEYS = new Set(['version', 'agent']);
+const warnedManagedUserKeys = new Set();
+
+function stripProjectManagedKeys(userRaw) {
+  if (!isPlainObject(userRaw)) {
+    return userRaw;
+  }
+  const stripped = { ...userRaw };
+  for (const key of PROJECT_MANAGED_USER_KEYS) {
+    if (!(key in stripped)) {
+      continue;
+    }
+    delete stripped[key];
+    if (!warnedManagedUserKeys.has(key)) {
+      warnedManagedUserKeys.add(key);
+      console.warn(`[UKit] Ignoring project-managed key "${key}" in user-level config (~/.ukit/storage/config.json).`);
+    }
+  }
+  return stripped;
+}
+
+async function readUserConfig(homeDir) {
+  const userPaths = buildUserPaths(homeDir === undefined ? {} : { homeDir });
+  try {
+    const raw = await fs.readFile(userPaths.configPath, 'utf8');
+    return { exists: true, rawConfig: JSON.parse(raw), parseError: null };
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return { exists: false, rawConfig: null, parseError: null };
+    }
+    // parseError also covers non-ENOENT read failures (e.g. EACCES) — the user
+    // layer is ignored either way.
+    return { exists: true, rawConfig: null, parseError: error?.message ?? String(error) };
+  }
+}
+
+// Raw merged view (pre-validation) for consumers that only need key values — the
+// router reads routing.* through this without pulling warn/validate semantics into
+// the hot path. Returns {} when neither layer exists or both are unreadable.
+export async function readMergedRuntimeConfig(projectRoot, { homeDir } = {}) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  let projectRaw = null;
+  try {
+    projectRaw = JSON.parse(await fs.readFile(runtimePaths.configPath, 'utf8'));
+  } catch {
+    projectRaw = null;
+  }
+  const user = await readUserConfig(homeDir);
+  const userLayer = user.parseError ? null : stripProjectManagedKeys(user.rawConfig);
+  return mergeObjects(userLayer ?? {}, projectRaw ?? {});
+}
+
 function pushBooleanError(errors, value, label) {
   if (typeof value !== 'boolean') {
     errors.push(`${label} must be boolean.`);
@@ -137,6 +255,20 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       enabled: true,
       defaultModel: 'claude-sonnet-5',
     },
+    // M01.1 stage keys (docs/pstack/MIGRATION_ROLLBACK named-keys table). Every stage
+    // key treats absence as "off"; stages promote off -> shadow -> canary -> default.
+    routing: {
+      routeSchema: { stage: 'off' },
+    },
+    // SPEC-model-roles: role→tier map injected into delegating-lane route output.
+    // Values are tier names or 'inherit-parent' — never raw provider model IDs.
+    modelRoles: {
+      code: 'code',
+      judgment: 'smart',
+      'review-panel': ['smart', 'code', 'lite'],
+      'fast-worker': 'lite',
+      vision: 'vision',
+    },
     orchestration: {
       enabled: true,
       orchestratorModel: 'claude-sonnet-5',
@@ -396,6 +528,34 @@ export function validateRuntimeConfig(config) {
     }
   }
 
+  // routing.* stage keys are optional-present and additive-namespaced: absent → valid
+  // (pre-M01.1 configs); present → each known stage key must hold a reserved stage.
+  // Unknown siblings under routing.* stay valid so later milestones can add stages
+  // without breaking older validators.
+  if (config.routing !== undefined) {
+    if (!isPlainObject(config.routing)) {
+      errors.push('routing must be an object.');
+    } else {
+      const VALID_ROUTE_STAGES = new Set(['off', 'shadow', 'canary', 'default']);
+      if (config.routing.routeSchema !== undefined) {
+        if (!isPlainObject(config.routing.routeSchema)) {
+          errors.push('routing.routeSchema must be an object.');
+        } else if (config.routing.routeSchema.stage !== undefined
+          && !VALID_ROUTE_STAGES.has(config.routing.routeSchema.stage)) {
+          errors.push(`routing.routeSchema.stage must be one of: ${[...VALID_ROUTE_STAGES].join(', ')}.`);
+        }
+      }
+    }
+  }
+
+  // modelRoles is optional-present and additive-namespaced (SPEC-model-roles): absent →
+  // valid (pre-v3 configs); present → must be an object. Entry-level issues (unknown
+  // role, bad value) never error here — resolveModelRoles warns + falls back per entry
+  // so a bad role value can never block the whole config.
+  if (config.modelRoles !== undefined && !isPlainObject(config.modelRoles)) {
+    errors.push('modelRoles must be an object.');
+  }
+
   if (!isPlainObject(config.orchestration)) {
     errors.push('orchestration must be an object.');
   } else {
@@ -687,7 +847,7 @@ function normalizeLegacyOpencodeEntries(config) {
   return config;
 }
 
-export async function inspectRuntimeConfig(projectRoot) {
+export async function inspectRuntimeConfig(projectRoot, { homeDir } = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   let exists = false;
   let rawConfig = null;
@@ -704,7 +864,11 @@ export async function inspectRuntimeConfig(projectRoot) {
     }
   }
 
-  const config = normalizeLegacyOpencodeEntries(buildDefaultRuntimeConfig(rawConfig ?? {}));
+  const user = await readUserConfig(homeDir);
+  const userLayer = user.parseError ? null : stripProjectManagedKeys(user.rawConfig);
+  const mergedRaw = mergeObjects(userLayer ?? {}, rawConfig ?? {});
+
+  const config = normalizeLegacyOpencodeEntries(buildDefaultRuntimeConfig(mergedRaw));
   const validation = validateRuntimeConfig(config);
   const errors = [
     ...(parseError ? [`config.json parse error: ${parseError}`] : []),
@@ -718,12 +882,13 @@ export async function inspectRuntimeConfig(projectRoot) {
     parseError,
     valid: exists && !parseError && validation.valid,
     errors,
+    user: { exists: user.exists, parseError: user.parseError },
   };
 }
 
-export async function loadRuntimeConfig(projectRoot) {
-  const inspection = await inspectRuntimeConfig(projectRoot);
-  if (inspection.exists && !inspection.valid) {
+export async function loadRuntimeConfig(projectRoot, { homeDir } = {}) {
+  const inspection = await inspectRuntimeConfig(projectRoot, { homeDir });
+  if (inspection.errors.length > 0) {
     console.warn(`[UKit] Invalid UKit runtime config: ${inspection.errors.join('; ')}`);
     return buildDefaultRuntimeConfig();
   }

package/src/core/userPaths.js

@@ -0,0 +1,21 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export function buildUserPaths({ homeDir = os.homedir() } = {}) {
+  const userRoot = path.join(homeDir, '.ukit');
+  const storageRoot = path.join(userRoot, 'storage');
+  const memoryRoot = path.join(storageRoot, 'memory');
+  const memoryV2Dir = path.join(memoryRoot, 'v2');
+
+  return {
+    homeDir,
+    userRoot,
+    storageRoot,
+    configPath: path.join(storageRoot, 'config.json'),
+    playbooksDir: path.join(userRoot, 'playbooks'),
+    memoryRoot,
+    memoryV2Dir,
+    memoryV2RecordsPath: path.join(memoryV2Dir, 'records.json'),
+    installMetaPath: path.join(userRoot, 'install.json'),
+  };
+}

package/src/core/userPlaybooks.js

@@ -0,0 +1,185 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { buildUserPaths } from './userPaths.js';
+// Cycle note: taskRouting.js (TASK-007) imports resolvePlaybook from this module,
+// making this a cyclic import. Safe because WORKFLOW_POLICIES /
+// WORKFLOW_POLICY_BY_MODE are only dereferenced inside function bodies at call
+// time — never at module top-level — so the live binding is always initialized.
+import { WORKFLOW_POLICIES, WORKFLOW_POLICY_BY_MODE } from '../index/taskRouting.js';
+
+// Playbook file format (SPEC FR-009): `playbooks/<id>.md` with optional
+// frontmatter `---\nid: <id>\nlanes: [a, b]\n---` followed by the markdown body.
+// Missing `id` → filename stem; missing `lanes` → []. A file whose body is empty
+// after frontmatter, or that cannot be read/parsed, is skipped so resolution
+// falls through to the next precedence level (builtin < user < project).
+
+function parseFrontmatter(raw) {
+  if (!raw.startsWith('---\n')) {
+    return { meta: {}, body: raw };
+  }
+  // Search from 3: in `---\n---` the closing fence's leading \n is the same
+  // newline that terminates the opening fence.
+  const fenceIndex = raw.indexOf('\n---', 3);
+  if (fenceIndex === -1) {
+    return null; // unterminated frontmatter → malformed file
+  }
+  const after = raw.slice(fenceIndex + 4);
+  if (after.length > 0 && !after.startsWith('\n')) {
+    return null; // `---x` is not a closing fence
+  }
+  const meta = {};
+  for (const line of raw.slice(4, fenceIndex).split('\n')) {
+    const match = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+    if (match) {
+      meta[match[1]] = match[2].trim();
+    }
+  }
+  return { meta, body: after.replace(/^\n/, '') };
+}
+
+function parseLanes(value) {
+  if (value == null || value === '') {
+    return [];
+  }
+  const inner = value.startsWith('[') && value.endsWith(']')
+    ? value.slice(1, -1)
+    : value;
+  return inner
+    .split(',')
+    .map((lane) => lane.trim().replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean);
+}
+
+// Returns {id, lanes, body, sourcePath} or null when the file is malformed or
+// carries no usable body.
+function parsePlaybookFile(raw, filePath) {
+  const parsed = parseFrontmatter(raw);
+  if (parsed === null) {
+    return null;
+  }
+  const body = parsed.body.trim();
+  if (body === '') {
+    return null;
+  }
+  const stem = path.basename(filePath, '.md');
+  return {
+    id: typeof parsed.meta.id === 'string' && parsed.meta.id !== ''
+      ? parsed.meta.id
+      : stem,
+    lanes: parseLanes(parsed.meta.lanes),
+    body,
+    sourcePath: filePath,
+  };
+}
+
+async function readPlaybookFile(filePath) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return null; // missing or unreadable → not a playbook at this level
+  }
+  const entry = parsePlaybookFile(raw, filePath);
+  if (entry === null) {
+    console.warn(`[UKit] Warning: skipping malformed playbook ${filePath}`);
+  }
+  return entry;
+}
+
+export async function loadPlaybooks(dir) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') {
+      console.warn(`[UKit] Warning: cannot read playbook dir ${dir} — ${error.message}`);
+    }
+    return new Map();
+  }
+  const playbooks = new Map();
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) {
+      continue;
+    }
+    const filePath = path.join(dir, entry.name);
+    const playbook = await readPlaybookFile(filePath);
+    if (playbook !== null) {
+      playbooks.set(playbook.id, playbook);
+    }
+  }
+  return playbooks;
+}
+
+function isSafePolicyName(policyName) {
+  return (
+    typeof policyName === 'string'
+    && policyName !== ''
+    && !policyName.includes('/')
+    && !policyName.includes('\\')
+    && !policyName.includes('..')
+  );
+}
+
+export async function resolvePlaybook(
+  policyName,
+  { projectRoot, homeDir, builtins = WORKFLOW_POLICIES } = {},
+) {
+  if (!isSafePolicyName(policyName)) {
+    return null;
+  }
+  const candidates = [];
+  if (projectRoot) {
+    candidates.push({
+      dir: path.join(projectRoot, '.ukit', 'playbooks'),
+      source: 'project',
+    });
+  }
+  candidates.push({
+    dir: buildUserPaths({ homeDir }).playbooksDir,
+    source: 'user',
+  });
+  for (const { dir, source } of candidates) {
+    const playbook = await readPlaybookFile(path.join(dir, `${policyName}.md`));
+    if (playbook !== null) {
+      return { id: playbook.id, body: playbook.body, source };
+    }
+  }
+  const builtinBody = builtins[policyName];
+  if (typeof builtinBody === 'string' && builtinBody !== '') {
+    return { id: policyName, body: builtinBody, source: 'builtin' };
+  }
+  return null;
+}
+
+export async function listPlaybooks(
+  { projectRoot, homeDir, builtins = WORKFLOW_POLICIES } = {},
+) {
+  // Builtin lanes are derived from the shipped lane→policy map (inverse of
+  // WORKFLOW_POLICY_BY_MODE); injected builtins not in that map list no lanes.
+  const builtinLanes = {};
+  for (const [lane, policy] of Object.entries(WORKFLOW_POLICY_BY_MODE)) {
+    (builtinLanes[policy] ??= []).push(lane);
+  }
+  const merged = new Map();
+  for (const id of Object.keys(builtins)) {
+    merged.set(id, { id, source: 'builtin', lanes: builtinLanes[id] ?? [] });
+  }
+  const userDir = buildUserPaths({ homeDir }).playbooksDir;
+  for (const [dir, source] of [
+    [userDir, 'user'],
+    [projectRoot ? path.join(projectRoot, '.ukit', 'playbooks') : null, 'project'],
+  ]) {
+    if (dir === null) {
+      continue;
+    }
+    for (const playbook of (await loadPlaybooks(dir)).values()) {
+      merged.set(playbook.id, {
+        id: playbook.id,
+        source,
+        lanes: playbook.lanes,
+      });
+    }
+  }
+  return [...merged.values()].sort((a, b) => a.id.localeCompare(b.id));
+}