@ngockhoale/ukit 3.3.3 → 3.4.0

package/src/core/runtimeConfig.js

@@ -217,6 +217,17 @@ export function resolveDecisionRuntimeStage(config = null, key = 'vm') {
   return resolveConfigStage(config, `decisionRuntime.${key}.stage`);
 }
 
+// C89 TASK-002 (SPEC §11): subagentOrchestrator family stage resolver —
+// resolves `subagentOrchestrator.<key>.stage` for one pinned family flag
+// ('telemetry', 'referenceHandoff', 'roleAdvice', 'contextSelection').
+// Same grammar and semantics as resolveDecisionRuntimeStage: absent config,
+// absent family, non-string key, or malformed stage all resolve 'off' — a
+// bad config can never promote a subagentOrchestrator slice.
+export function resolveSubagentOrchestratorStage(config = null, key = 'telemetry') {
+  if (typeof key !== 'string' || key.trim() === '') return 'off';
+  return resolveConfigStage(config, `subagentOrchestrator.${key}.stage`);
+}
+
 // Pushes a stage-enum error when `node.stage` is present but not reserved.
 // Absent stage is valid (absence = 'off'); a non-object node is reported by
 // the caller's own "must be an object" check.
@@ -226,6 +237,73 @@ function pushStageError(errors, node, label) {
   }
 }
 
+// C85 BL-016 (SPEC FR-004): the closed verification-depth enum the crossCheck
+// overrides may tighten/loosen within — kept here (not imported from
+// src/index/crossCheckMatrix.js) so core never depends on the index layer.
+// The parity test pins this set against the matrix module's CROSS_CHECK_DEPTHS.
+export const VALID_CROSS_CHECK_DEPTHS = new Set(['none', 'runnable', 'review-round', 'escalate']);
+
+// The only keys a bound leaf may carry; every other key inside crossCheck is
+// rejected so a later milestone cannot smuggle an unbounded knob through the
+// maintainer config.
+const CROSS_CHECK_BOUND_KEYS = new Set(['depth', 'minDepth', 'maxDepth']);
+const CROSS_CHECK_SECTION_KEYS = new Set(['enabled', 'byRole', 'byModel']);
+
+// Validates one crossCheck bound leaf or project map. A node carrying any of
+// depth/minDepth/maxDepth IS a bound leaf — its remaining keys must be bound
+// keys too, and every depth value must be in the enum. Otherwise the node is
+// treated as a {project|'*' → bound} map and each value is re-validated.
+function validateCrossCheckBound(errors, node, label) {
+  if (!isPlainObject(node)) {
+    errors.push(`${label} must be an object.`);
+    return;
+  }
+  const carriesBoundKey = Object.keys(node).some((key) => CROSS_CHECK_BOUND_KEYS.has(key));
+  if (carriesBoundKey) {
+    for (const [key, value] of Object.entries(node)) {
+      if (!CROSS_CHECK_BOUND_KEYS.has(key)) {
+        errors.push(`crossCheck.${label}.${key} is not a supported override key (expected depth, minDepth, maxDepth).`);
+      } else if (!VALID_CROSS_CHECK_DEPTHS.has(value)) {
+        errors.push(`crossCheck.${label}.${key} must be one of: ${[...VALID_CROSS_CHECK_DEPTHS].join(', ')}.`);
+      }
+    }
+    return;
+  }
+  for (const [project, leaf] of Object.entries(node)) {
+    validateCrossCheckBound(errors, leaf, `${label}.${project}`);
+  }
+}
+
+// crossCheck section: maintainer-level bounded overrides, shipped ON.
+// Optional-present like routing.* — absent → valid (pre-C85 configs); present
+// → only the reserved keys, enum-constrained depth bounds, no freeform knobs.
+function validateCrossCheck(errors, crossCheck) {
+  if (crossCheck === undefined) return;
+  if (!isPlainObject(crossCheck)) {
+    errors.push('crossCheck must be an object.');
+    return;
+  }
+  for (const key of Object.keys(crossCheck)) {
+    if (!CROSS_CHECK_SECTION_KEYS.has(key)) {
+      errors.push(`crossCheck.${key} is not a supported key (expected enabled, byRole, byModel).`);
+    }
+  }
+  if (crossCheck.enabled !== undefined) {
+    pushBooleanError(errors, crossCheck.enabled, 'crossCheck.enabled');
+  }
+  for (const mapKey of ['byRole', 'byModel']) {
+    const map = crossCheck[mapKey];
+    if (map === undefined) continue;
+    if (!isPlainObject(map)) {
+      errors.push(`crossCheck.${mapKey} must be an object.`);
+      continue;
+    }
+    for (const [name, entry] of Object.entries(map)) {
+      validateCrossCheckBound(errors, entry, `${mapKey}.${name}`);
+    }
+  }
+}
+
 export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
@@ -309,6 +387,17 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       fastPath: { stage: 'default' },
       escalation: { stage: 'default' },
     },
+    // C85 BL-016 (SPEC FR-004): adaptive cross-check depth overrides.
+    // Maintainer-level config only — no user-facing settings. Bounded
+    // {role|model}×{project} overrides may tighten/loosen the resolved
+    // verification depth within the closed enum (none | runnable |
+    // review-round | escalate); the depth matrix stays the resolver.
+    // Absent/empty maps mean "matrix defaults apply" — the feature ships ON.
+    crossCheck: {
+      enabled: true,
+      byRole: {},
+      byModel: {},
+    },
     // C52 M07: `unic-decision` is the owner's local non-LLM Lava/JEV model in
     // UNIC Provider. Its OpenAI-compatible API is transport only, not proof of
     // remote hosting or generative-LLM billing. Preferred for every bounded
@@ -376,7 +465,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       },
       escalation: {
         enabled: true,
+        // C85 BL-018: fix-loop repeat counting joins on routeFingerprint/
+        // requestKey (historySignals.fixLoopCount) — never session-wide
+        // counters (GAP M12). At debugLoopThreshold the lane deepens through
+        // the laneDeepening/verificationDepth decision; laneDeepening:false
+        // keeps the tier-bump ladder only. debugLoopThreshold is the shared
+        // threshold for tier-bump AND lane escalation.
         debugLoopThreshold: 2,
+        laneDeepening: true,
         tierOrder: ['lite', 'code', 'smart'],
         cap: 'smart',
       },
@@ -499,6 +595,19 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       diagnostics: { stage: 'default' },
     },
 
+    // C89 TASK-002 (SPEC §11): subagentOrchestrator family — pinned keys
+    // `telemetry` (child-run usage provenance records), `referenceHandoff`
+    // (contract/result-envelope handoff), `roleAdvice` (typed delegation
+    // shadow) and `contextSelection` (context manifest). All ship 'off':
+    // telemetry is opt-in shadow observation and the other three gates are
+    // behavior changes — a bad or absent value can never promote a slice.
+    subagentOrchestrator: {
+      telemetry: { stage: 'off' },
+      referenceHandoff: { stage: 'off' },
+      roleAdvice: { stage: 'off' },
+      contextSelection: { stage: 'off' },
+    },
+
     // C52 M06 experiments (SPEC §5 FR-021–FR-023). 3.3.0 zero-config: enabled;
     // each experiment still runs only where a caller invokes it and never
     // auto-promotes its own result.
@@ -688,6 +797,10 @@ export function validateRuntimeConfig(config) {
     }
   }
 
+  // C85 BL-016: crossCheck bounded overrides — optional-present, schema
+  // bounded to the closed depth enum (VALID_CROSS_CHECK_DEPTHS).
+  validateCrossCheck(errors, config.crossCheck);
+
   // 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
@@ -829,6 +942,26 @@ export function validateRuntimeConfig(config) {
       }
     }
   }
+
+  // C89 TASK-002 (SPEC §11) subagentOrchestrator — optional-present; one
+  // stage key per pinned slice (subagentOrchestrator.telemetry,
+  // .referenceHandoff, .roleAdvice, .contextSelection). Absent → valid;
+  // malformed stage → error + resolver falls back to 'off'.
+  if (config.subagentOrchestrator !== undefined) {
+    if (!isPlainObject(config.subagentOrchestrator)) {
+      errors.push('subagentOrchestrator must be an object.');
+    } else {
+      for (const key of ['telemetry', 'referenceHandoff', 'roleAdvice', 'contextSelection']) {
+        const stageKey = config.subagentOrchestrator[key];
+        if (stageKey === undefined) continue;
+        if (!isPlainObject(stageKey)) {
+          errors.push(`subagentOrchestrator.${key} must be an object.`);
+        } else {
+          pushStageError(errors, stageKey, `subagentOrchestrator.${key}`);
+        }
+      }
+    }
+  }
   // C52 M06 experiments — optional-present; both experiments are
   // disabled-by-default booleans plus bounded breakers.
   if (config.experiments !== undefined) {

package/src/core/userPlaybooks.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { buildUserPaths } from './userPaths.js';
 // Cycle note: taskRouting.js (TASK-007) imports resolvePlaybook from this module,
@@ -8,6 +9,14 @@ import { buildUserPaths } from './userPaths.js';
 // time — never at module top-level — so the live binding is always initialized.
 import { WORKFLOW_POLICIES, WORKFLOW_POLICY_BY_MODE } from '../index/taskRouting.js';
 
+// TASK-007 (BL-009): playbooks also ship as files under the package's
+// template_user/playbooks — the install pipeline seeds them into ~/.ukit, but
+// a dev checkout or a pre-seed install should resolve them as builtin too.
+const PACKAGE_BUILTIN_PLAYBOOK_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..', '..', 'template_user', 'playbooks',
+);
+
 // 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
@@ -123,7 +132,7 @@ function isSafePolicyName(policyName) {
 
 export async function resolvePlaybook(
   policyName,
-  { projectRoot, homeDir, builtins = WORKFLOW_POLICIES } = {},
+  { projectRoot, homeDir, builtins = WORKFLOW_POLICIES, builtinDir = PACKAGE_BUILTIN_PLAYBOOK_DIR } = {},
 ) {
   if (!isSafePolicyName(policyName)) {
     return null;
@@ -139,6 +148,11 @@ export async function resolvePlaybook(
     dir: buildUserPaths({ homeDir }).playbooksDir,
     source: 'user',
   });
+  // Packaged template_user files sit between the user tier and the inline
+  // builtin table — a dev checkout resolves them the same as a seeded install.
+  if (builtinDir) {
+    candidates.push({ dir: builtinDir, source: 'builtin' });
+  }
   for (const { dir, source } of candidates) {
     const playbook = await readPlaybookFile(path.join(dir, `${policyName}.md`));
     if (playbook !== null) {
@@ -153,7 +167,7 @@ export async function resolvePlaybook(
 }
 
 export async function listPlaybooks(
-  { projectRoot, homeDir, builtins = WORKFLOW_POLICIES } = {},
+  { projectRoot, homeDir, builtins = WORKFLOW_POLICIES, builtinDir = PACKAGE_BUILTIN_PLAYBOOK_DIR } = {},
 ) {
   // 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.
@@ -167,6 +181,7 @@ export async function listPlaybooks(
   }
   const userDir = buildUserPaths({ homeDir }).playbooksDir;
   for (const [dir, source] of [
+    [builtinDir || null, 'builtin'],
     [userDir, 'user'],
     [projectRoot ? path.join(projectRoot, '.ukit', 'playbooks') : null, 'project'],
   ]) {
@@ -177,7 +192,7 @@ export async function listPlaybooks(
       merged.set(playbook.id, {
         id: playbook.id,
         source,
-        lanes: playbook.lanes,
+        lanes: playbook.lanes.length > 0 ? playbook.lanes : (builtinLanes[playbook.id] ?? playbook.lanes),
       });
     }
   }

package/src/decision/registry.js

@@ -189,6 +189,25 @@ export const DECISION_REGISTRY = Object.freeze([
     cacheSensitivity: 'none',
     leasePolicy: 'none',
   },
+  {
+    decisionKey: 'route.delegation-role.v1',
+    schemaVersion: 1,
+    family: 'route',
+    owner: 'taskRouting',
+    kind: 'choice',
+    // C89 TASK-005 (SPEC §6 FR-04): owner-bounded role pick inside the typed
+    // delegation advice shadow — the model may only answer from the
+    // deterministic shortlist the route already derived.
+    description: 'Delegation role for a delegated lane: retriever | reasoner | reviewer.',
+    candidatePolicy: 'owner-shortlist',
+    hardConstraints: ['lane-eligibility', 'risk-floor'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-route',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'none',
+  },
   {
     decisionKey: 'route.rigor.v1',
     schemaVersion: 1,

package/src/diagnostics/feedbackEvents.js

@@ -141,6 +141,7 @@ export async function collectFeedbackEvents(projectRoot, { limitLedgers = 500, m
       const base = {
         ts: typeof entry.ts === 'number' ? entry.ts : 0,
         requestKey: typeof entry.requestKey === 'string' ? entry.requestKey : undefined,
+        routeFingerprint: typeof entry.routeFingerprint === 'string' ? entry.routeFingerprint : undefined,
         targetFile: typeof entry.targetFile === 'string' ? entry.targetFile : undefined,
         taskType: typeof entry.taskType === 'string' ? entry.taskType : undefined,
         executionMode: typeof entry.executionMode === 'string' ? entry.executionMode : undefined,
@@ -159,13 +160,14 @@ export async function collectFeedbackEvents(projectRoot, { limitLedgers = 500, m
     }
 
     // re-route: audit is newest-first — entry i is the later entry, i+1 the
-    // previous one for the same promptFingerprint + targetFile.
+    // previous one for the same routeFingerprint (BL-018: the fingerprint
+    // join, not promptFingerprint + targetFile — same-symptom detection keys
+    // on routeFingerprint/requestKey, never session-wide counters).
     for (let i = 0; i < auditEntries.length - 1; i += 1) {
       const later = auditEntries[i];
       const prev = auditEntries[i + 1];
-      if (typeof later.promptFingerprint !== 'string' || !later.promptFingerprint) continue;
-      if (later.promptFingerprint !== prev.promptFingerprint) continue;
-      if (later.targetFile !== prev.targetFile) continue;
+      if (typeof later.routeFingerprint !== 'string' || !later.routeFingerprint) continue;
+      if (later.routeFingerprint !== prev.routeFingerprint) continue;
       if (later.wideningBlocked === true) continue;
       const prevMode = prev.executionMode;
       const newMode = later.executionMode;
@@ -174,6 +176,7 @@ export async function collectFeedbackEvents(projectRoot, { limitLedgers = 500, m
         ts: typeof later.ts === 'number' ? later.ts : 0,
         kind: 're-route',
         requestKey: typeof later.requestKey === 'string' ? later.requestKey : undefined,
+        routeFingerprint: later.routeFingerprint,
         targetFile: typeof later.targetFile === 'string' ? later.targetFile : undefined,
         taskType: typeof later.taskType === 'string' ? later.taskType : undefined,
         executionMode: typeof later.executionMode === 'string' ? later.executionMode : undefined,

package/src/diagnostics/routeOutcomes.js

@@ -1,5 +1,6 @@
-// Route-outcome join (SPEC §4, SI-102): joins route-audit.json entries to
-// per-request exec-ledger ledgers on requestKey and aggregates outcome stats
+// Route-outcome join (SPEC §4, SI-102): joins route-audit.json entries —
+// plus rows spilled past the ring cap to route-audit.segments.jsonl (BL-004) —
+// to per-request exec-ledger ledgers on requestKey and aggregates outcome stats
 // per executionMode / taskType. Read-only; never throws.
 
 import fs from 'node:fs/promises';
@@ -14,10 +15,13 @@ function zeroedResult(extra = {}) {
     ledgersScanned: 0,
     auditRowsScanned: 0,
     joined: 0,
-    unmatchedAudit: 0,
-    unmatchedLedger: 0,
     byMode: {},
     byTaskType: {},
+    // BL-019 (SPEC FR-001): additive per-(mode,tier) success-rate buckets —
+    // "<mode>|<tier>" keys beside byMode/byTaskType — plus the row-level join
+    // for deriveTierStats (the measured tier map consumes it).
+    byModeTier: {},
+    joinedRows: [],
     joinCoverage: 0,
     ...extra,
   };
@@ -45,6 +49,29 @@ async function readJson(filePath) {
   }
 }
 
+// BL-004: evicted ring rows spill to this append-only JSONL sidecar — same row
+// shape as ring entries; malformed lines are skipped like parseSidecarLines.
+const SEGMENTS_REL = 'route-audit.segments.jsonl';
+
+async function readJsonLines(filePath) {
+  const rows = [];
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const item = JSON.parse(line);
+        if (item && typeof item === 'object' && !Array.isArray(item)) rows.push(item);
+      } catch {
+        // skip malformed segment lines
+      }
+    }
+  } catch {
+    // missing/unreadable sidecar → no spilled rows
+  }
+  return rows;
+}
+
 function bump(bucket, ledger, auditEntry) {
   bucket.joined += 1;
   if (ledger.writeSucceeded === true) bucket.writeOk += 1;
@@ -61,6 +88,9 @@ function bump(bucket, ledger, auditEntry) {
 export async function collectRouteOutcomes(projectRoot, { limitLedgers = 500 } = {}) {
   try {
     const cacheDir = path.join(projectRoot, '.ukit', 'storage', 'cache');
+    // BL-004: rows evicted past the 40-entry ring cap spill to the segments
+    // sidecar — they must still reach the join or coverage silently decays.
+    const segmentEntries = await readJsonLines(path.join(cacheDir, SEGMENTS_REL));
     const auditDoc = await readJson(path.join(cacheDir, 'route-audit.json'));
     const auditEntries = Array.isArray(auditDoc?.entries) ? auditDoc.entries : [];
 
@@ -74,10 +104,20 @@ export async function collectRouteOutcomes(projectRoot, { limitLedgers = 500 } =
 
     const result = zeroedResult();
     result.ledgersScanned = ledgers.length;
-    result.auditRowsScanned = auditEntries.length;
+    result.auditRowsScanned = auditEntries.length + segmentEntries.length;
 
     const auditByKey = new Map();
-    for (const entry of auditEntries) {
+    // Dedupe on requestKey, newest wins — last `set` wins, so scan oldest→
+    // newest: segments are appended oldest→newest (forward), the ring is
+    // stored newest-first (reverse it), and ring rows always post-date
+    // their spilled twins so the ring is scanned last.
+    for (const entry of segmentEntries) {
+      if (entry && typeof entry.requestKey === 'string' && entry.requestKey) {
+        auditByKey.set(entry.requestKey, entry);
+      }
+    }
+    for (let i = auditEntries.length - 1; i >= 0; i -= 1) {
+      const entry = auditEntries[i];
       if (entry && typeof entry.requestKey === 'string' && entry.requestKey) {
         auditByKey.set(entry.requestKey, entry);
       }
@@ -94,13 +134,18 @@ export async function collectRouteOutcomes(projectRoot, { limitLedgers = 500 } =
       const taskKey = entry.taskType ?? UNCLASSIFIED;
       const modeBucket = result.byMode[modeKey] ??= emptyBucket();
       const taskBucket = result.byTaskType[taskKey] ??= emptyBucket();
+      const modeTierBucket = result.byModeTier[`${modeKey}|${entry.modelTier ?? UNCLASSIFIED}`]
+        ??= emptyBucket();
       modeBucket.routes += 1;
       taskBucket.routes += 1;
+      modeTierBucket.routes += 1;
       const ledger = ledgers.find((candidate) => candidate.requestKey === entry.requestKey);
       if (!ledger) continue;
       result.joined += 1;
+      result.joinedRows.push({ audit: entry, ledger });
       bump(modeBucket, ledger, entry);
       bump(taskBucket, ledger, entry);
+      bump(modeTierBucket, ledger, entry);
     }
 
     result.unmatchedAudit = auditByKey.size - result.joined;

package/src/diagnostics/skillAccuracy.js

@@ -21,6 +21,9 @@ import { listLedgerFiles, LEDGER_DIR_REL } from './ledgerFiles.js';
 
 const CACHE_DIR_REL = path.join('.ukit', 'storage', 'cache');
 const AUDIT_REL = path.join(CACHE_DIR_REL, 'route-audit.json');
+// BL-004: rows evicted past the 40-entry ring cap spill to this append-only
+// JSONL sidecar — same row shape; malformed lines skipped like parseSidecarLines.
+const SEGMENTS_REL = path.join(CACHE_DIR_REL, 'route-audit.segments.jsonl');
 const ARTIFACT_REL = path.join('.ukit', 'storage', 'learning', 'skill-accuracy.json');
 const CONFIG_REL = path.join('.ukit', 'storage', 'config.json');
 const MAX_SKILL_IDS = 8;
@@ -62,6 +65,25 @@ async function readJson(filePath) {
   }
 }
 
+async function readJsonLines(filePath) {
+  const rows = [];
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const item = JSON.parse(line);
+        if (item && typeof item === 'object') rows.push(item);
+      } catch {
+        // skip malformed segment lines
+      }
+    }
+  } catch {
+    // missing/unreadable sidecar → no spilled rows
+  }
+  return rows;
+}
+
 // Default true when `learning`/`feedback` is absent (namespace lands in TASK-232).
 async function feedbackEnabled(projectRoot) {
   const config = await readJson(path.join(projectRoot, CONFIG_REL));
@@ -106,8 +128,26 @@ export async function collectSkillAccuracy(projectRoot, { limitLedgers = 500 } =
     const auditEntries = Array.isArray(auditDoc?.entries)
       ? auditDoc.entries.filter(isObject)
       : [];
-    result.auditRowsScanned = auditEntries.length;
-
+    // BL-004: rows evicted past the ring cap live in the segments sidecar —
+    // they still carry skillIds and must reach the join.
+    const segmentEntries = (await readJsonLines(path.join(projectRoot, SEGMENTS_REL)))
+      .filter(isObject);
+    result.auditRowsScanned = auditEntries.length + segmentEntries.length;
+    // Dedupe on requestKey (newest wins, per collectRouteOutcomes): last write
+    // wins, so scan oldest→newest — segments append oldest→newest (forward),
+    // the ring stores newest-first (reversed), and ring rows post-date their
+    // spilled twins so the ring is scanned last. Unkeyed rows keep today's
+    // pass-through semantics.
+    const auditByKey = new Map();
+    const unkeyedEntries = [];
+    for (const entry of [...segmentEntries, ...auditEntries.slice().reverse()]) {
+      if (typeof entry.requestKey === 'string' && entry.requestKey) {
+        auditByKey.set(entry.requestKey, entry);
+      } else {
+        unkeyedEntries.push(entry);
+      }
+    }
+    const dedupedEntries = [...auditByKey.values(), ...unkeyedEntries];
     const ledgerDir = path.join(projectRoot, LEDGER_DIR_REL);
     const ledgerNames = await listLedgerFiles(ledgerDir, limitLedgers);
     const ledgerByKey = new Map();
@@ -120,7 +160,7 @@ export async function collectSkillAccuracy(projectRoot, { limitLedgers = 500 } =
       }
     }
 
-    for (const entry of auditEntries) {
+    for (const entry of dedupedEntries) {
       const ids = skillIdsOf(entry);
       if (ids.length === 0) continue;
       const ledger = typeof entry.requestKey === 'string'