@ngockhoale/ukit 2.7.12 → 2.8.0

package/templates/.claude/ukit/index/route-task.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs/promises';
 // module-bottom direct-CLI check. Normal-path fs stays async.
 import * as fsSync from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -54,6 +55,438 @@ function deriveContextDocs({ taskType = null, intentMode = null } = {}) {
   ];
   return unique(docs).slice(0, CONTEXT_DOCS_MAX);
 }
+
+// --- M01.1: additive ResolvedTaskRoute v1 (docs/pstack/CONTRACTS.md C01) -------------------
+// Literal mirror of the canonical block in src/index/taskRouting.js — this file cannot
+// import from src/, so the copy is locked by tests/consistency/executionContractSync.test.js.
+// Emitted only when `routing.routeSchema.stage` (runtime config, default "off") is not
+// "off". All fields are additive on top of the existing routeSummary shape — legacy
+// top-level fields are never removed or renamed, so older consumers keep working.
+export const ROUTE_VERSION = 1;
+export const ROUTE_CONTRACT_VERSION = 1;
+export const ROUTE_SCHEMA_STAGES = new Set(['off', 'shadow', 'canary', 'default']);
+export const ROUTE_INTENT_KINDS = new Set(['informational', 'delivery', 'mutation', 'investigation', 'review']);
+export const ROUTE_MUTABILITIES = new Set(['read-only', 'mutating', 'mixed']);
+export const ROUTE_RIGOR_LEVELS = new Set(['R0', 'R1', 'R2', 'R3', 'R4']);
+export const ROUTE_MODEL_TIERS = new Set(['lite', 'code', 'smart']);
+// 'informational' is a real router emission (no completion contract) even though it is
+// not part of the seven-lane execution-mode ladder.
+export const ROUTE_EXECUTION_MODES = [
+  'tiny-fix',
+  'local-fix',
+  'local-build',
+  'find-cause',
+  'shared-edit',
+  'map-impact',
+  'review-release',
+  'informational',
+];
+const ROUTE_ESCALATION_CEILING = 'review-release';
+const ROUTE_GOAL_MAX_LENGTH = 240;
+
+// --- v3 route-side advisory blocks (docs/pstack/SPEC-playbook-todo.md, ------------------
+// SPEC-principle-index.md, SPEC-model-roles.md). Literal mirror of the canonical block in
+// src/index/taskRouting.js — this file cannot import from src/, so the copy is locked by
+// tests/consistency/executionContractSync.test.js. All three are additive stdout text —
+// they never change mode selection. Static text is byte-stable for prompt-cache reuse.
+
+// SPEC-playbook-todo §2.1: numbered step lists the model copies verbatim into its todo
+// list. Header carries the "new task" re-match rule (§2.5); tail carries the narrowed
+// ask-surface (§2.4). Emitted on matching lanes only (§2.2).
+export const WORKFLOW_POLICIES = Object.freeze({
+  'bug-fix': `You own this bug. Reproduce, root-cause, fix, verify on the same surface.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Reproduce it yourself on the matching surface — ask the user only with a stated
+   reason the surface cannot reach the target.
+2. Binary-search the cause: form candidate hypotheses, rule them out until one
+   survives; confirm the surviving mechanism with runtime evidence.
+3. Make the smallest fix that kills the mechanism — belt-and-suspenders that
+   "might help" is a hypothesis, not a fix; it does not ship.
+4. Verify on the same surface: the original repro now passes. "Inconclusive" or
+   wrong-surface is not a pass. A unit test shows branch behavior, not bug absence.
+5. Keep the rejected hypotheses — one line each, why ruled out.
+Reply: what was broken, root cause, fix, how verified — paste failing-then-passing
+repro output verbatim.
+Ask the human only for: irreversible writes, a genuine preference call no experiment settles, or a real dead end. Everything else: do it, report it.`,
+  'issue-implementation': `You own this task. Normalize the goal, build, verify.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. State the done condition as a checkable predicate before writing code.
+2. Find the established analog — follow it unless you name why it does not fit.
+3. Name the data shape and its organizing structure before writing logic.
+4. Implement the smallest change satisfying the predicate.
+5. Verify against the predicate on the real artifact — not "it compiles".
+6. Widen once: check the impact surface the route named, no broader.
+Reply: what changed, the predicate, the evidence it now holds.
+Ask the human only for: irreversible writes, a genuine preference call no experiment settles, or a real dead end. Everything else: do it, report it.`,
+});
+
+// Lane → policy (§2.2). tiny-fix/local-fix stay lean (Fast Path); review-release and
+// informational carry no policy.
+export const WORKFLOW_POLICY_BY_MODE = Object.freeze({
+  'find-cause': 'bug-fix',
+  'local-build': 'issue-implementation',
+  'shared-edit': 'issue-implementation',
+  'map-impact': 'issue-implementation',
+});
+
+// SPEC-principle-index §2.1: ~16-line index, one line per principle; group headers are
+// the index's own compression. §2.3 citation contract is the trailing line.
+export const PRINCIPLE_INDEX = `Principles (cite only leaves read this session; name the decision it changed):
+Core — laziness-protocol: smallest change that solves it; bias to deletion.
+      foundational-thinking: pick core types/data structures before logic.
+      subtract-before-you-add: remove dead weight before building.
+      minimize-reader-load: collapse one-caller wrappers; shrink mutable scope.
+      attack-the-premise: 2+ fixes sharing one premise failed → question the premise.
+Arch — model-the-domain: encode domain in structure, not scattered conditionals.
+      boundary-discipline: guards at boundaries; pure functions inside.
+      migrate-callers-then-delete: migrate every caller, delete old API same wave.
+Verify — prove-it-works: verify the real artifact, not proxy/self-report/compiles.
+      fix-root-causes: reproduce first; no nil-guards that silence crashes.
+      sequence-verifiable-units: small units each ending verifiable.
+      test-behavior-not-implementation: assert what consumers observe.
+Exec — guard-the-context-window: bulk to subagents; summaries in main thread.
+      never-block-on-the-human: proceed, report, course-correct after.
+      encode-lessons-in-structure: rule → lint/flag/script, not more prose.
+When a principle shapes a decision, cite it and the choice it changed — only if you read the leaf this session.`;
+
+// SPEC-model-roles §2.2: lanes that may delegate get the role block; Fast Path lanes
+// (tiny-fix/local-fix) never delegate so the block would be dead context there.
+export const MODEL_ROLES_DELEGATING_MODES = new Set([
+  'local-build',
+  'find-cause',
+  'shared-edit',
+  'map-impact',
+  'review-release',
+]);
+
+// Principle index emission (§2.1): every non-trivial route — taskType non-trivial/
+// shared-simple, or any mutating lane — except the Fast Path lanes, where a one-line
+// edit does not need a principle index.
+export function shouldEmitPrincipleIndex({ taskType = null, executionMode = null } = {}) {
+  if (executionMode === 'tiny-fix' || executionMode === 'local-fix') {
+    return false;
+  }
+  if (taskType === 'non-trivial' || taskType === 'shared-simple') {
+    return true;
+  }
+  return Boolean(executionMode) && executionMode !== 'informational';
+}
+
+// SPEC-model-roles §2.1 mirror of src/core/runtimeConfig.js — role labels name WHAT the
+// model is for. Values are cost-tier names or 'inherit-parent' — never raw provider
+// model IDs. Arrays = panels (one agent per entry; list length sets the panel count).
+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 (configured === null || typeof configured !== 'object' || Array.isArray(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 };
+}
+
+// Formats the model-roles injection block from the resolved role map. Byte-stable for
+// unchanged config (fixed role order, no timestamps).
+export function formatModelRolesBlock(roles = null) {
+  const resolved = roles ?? resolveModelRoles(null).roles;
+  const panel = Array.isArray(resolved['review-panel'])
+    ? resolved['review-panel'].join('+')
+    : String(resolved['review-panel']);
+  return `Model roles: code→${resolved.code}, judgment→${resolved.judgment}, review-panel→${panel},
+fast-worker→${resolved['fast-worker']}, vision→${resolved.vision}. Delegate via role name; inherit-parent = same model as parent.`;
+}
+
+// Stage keys treat absence as "off" (MIGRATION_ROLLBACK named-keys table). Unknown or
+// malformed values degrade to "off" — the conservative reading that keeps the route
+// byte-identical to the pre-M01.1 shape.
+export function resolveRouteSchemaStage(config = null) {
+  const stage = config?.routing?.routeSchema?.stage;
+  return ROUTE_SCHEMA_STAGES.has(stage) ? stage : 'off';
+}
+
+// A bare delivery command ("push this to git", "đẩy bộ này lên git") performs no
+// repository mutation the ledger could ever receipt. With no edit/review/debug/build
+// signal present, routing it to an investigation lane fabricates write debt and the
+// completion gate then demands an edit that cannot exist. Extracted from
+// deriveExecutionMode so the C01 intent.kind mapping can reuse the identical predicate
+// (delivery-only → 'delivery') instead of duplicating the regexes.
+function isDeliveryOnlyRequest({ signalText = '', scores = {}, targetFile = null } = {}) {
+  const signalRaw = String(signalText || '').toLowerCase();
+  const deliveryWordSignal = /\bgit\s+push\b/.test(signalRaw)
+    || /\bpush\b[^\n]{0,60}\b(?:git|github|gitlab|remote|origin|repo)\b/.test(signalRaw)
+    || /\b(?:git|github|gitlab|remote|origin|repo)\b[^\n]{0,60}\bpush\b/.test(signalRaw)
+    || /\bday\b(?:\s+\S+){0,3}?\s+len\b/.test(signalRaw);
+  return deliveryWordSignal
+    && scores.editCertainty === 0
+    && !scores.implementSignal
+    && !scores.reviewSignal
+    && !scores.debugSignal
+    && !scores.failureSignal
+    && !scores.impactSignal
+    && !scores.buildSignal
+    && !scores.directTransformSignal
+    && !scores.smallFixSignal
+    && !scores.sharedRisk
+    && !targetFile;
+}
+
+// CONTRACTS.md "Intent vocabulary mapping": taskType informs mode priors, not
+// intent.kind; intentMode maps to kind as question/explanation → informational,
+// ship/deliver → delivery, code change → mutation, root-cause/diagnosis →
+// investigation, review/audit → review.
+function deriveRouteIntentKind({ executionMode = null, intentMode = null, deliveryOnly = false } = {}) {
+  if (executionMode === 'find-cause') return 'investigation';
+  if (executionMode === 'review-release') return 'review';
+  if (executionMode === 'informational') return deliveryOnly ? 'delivery' : 'informational';
+  if (executionMode) return 'mutation';
+  if (intentMode === 'review-specific') return 'review';
+  if (intentMode === 'debug-specific') return 'investigation';
+  if (intentMode === 'implement-specific' || intentMode === 'docs-specific') return 'mutation';
+  return 'informational';
+}
+
+// Existing read-only vs mutating classification: only the informational lane carries
+// no write debt; every contract lane is mutating.
+function deriveRouteMutability(executionMode = null) {
+  return executionMode && executionMode !== 'informational' ? 'mutating' : 'read-only';
+}
+
+function compactRouteGoal(text = '') {
+  const goal = String(text || '').trim();
+  if (!goal) return null;
+  return goal.length > ROUTE_GOAL_MAX_LENGTH ? `${goal.slice(0, ROUTE_GOAL_MAX_LENGTH)}…` : goal;
+}
+
+// Builds the additive C01 groups for one resolved route. rigor stays null until
+// M01.2 derives it; ceremonyBudget/capabilityPolicy are empty shaped objects M02/M01.2
+// populate; escalation.current mirrors the selected mode.
+function buildResolvedRouteFields({
+  routingContext = {},
+  activeSkillIds = [],
+  executionMode = null,
+  executionContract = null,
+  completionState = null,
+} = {}) {
+  const signalText = buildNormalizedRouteSignalText(routingContext.promptText, routingContext.commandText);
+  const deliveryOnly = isDeliveryOnlyRequest({
+    signalText,
+    scores: routingContext.executionScores ?? {},
+    targetFile: routingContext.targetFile ?? null,
+  });
+  return {
+    routeVersion: ROUTE_VERSION,
+    intent: {
+      kind: deriveRouteIntentKind({
+        executionMode,
+        intentMode: routingContext.intentMode ?? null,
+        deliveryOnly,
+      }),
+      mutability: deriveRouteMutability(executionMode),
+      goal: compactRouteGoal(routingContext.lastExplicitUserPromptText ?? routingContext.promptText),
+      doneConditions: [],
+    },
+    execution: {
+      mode: executionMode,
+      rigor: null,
+      phase: null,
+      contractVersion: ROUTE_CONTRACT_VERSION,
+      modelTier: executionContract?.modelTier ?? null,
+    },
+    evidence: {
+      observations: [],
+      riskSignals: [],
+      activationReasons: [],
+      suppressionReasons: [],
+      completionRequirements: unique(completionState?.missingEvidence ?? []),
+    },
+    ceremonyBudget: {
+      policyVersion: ROUTE_CONTRACT_VERSION,
+      rigor: null,
+      limits: {},
+      consumed: {},
+      exceptions: [],
+    },
+    capabilityPolicy: {
+      policyVersion: ROUTE_CONTRACT_VERSION,
+      required: [],
+      recommended: [],
+      suppressed: [],
+      activeSkillIds: unique(activeSkillIds),
+    },
+    escalation: {
+      current: { mode: executionMode, rigor: null },
+      ceiling: ROUTE_ESCALATION_CEILING,
+      triggers: [],
+      history: [],
+    },
+  };
+}
+
+// Plain-JS validator for the additive C01 groups. Returns { valid, errors }; it never
+// throws and never inspects legacy fields — old consumers may carry anything else.
+export function validateResolvedRoute(route = null) {
+  const errors = [];
+  const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (!isObject(route)) {
+    return { valid: false, errors: ['route must be an object.'] };
+  }
+  if (route.routeVersion !== ROUTE_VERSION) {
+    errors.push(`routeVersion must be ${ROUTE_VERSION}.`);
+  }
+  if (!isObject(route.intent)) {
+    errors.push('intent must be an object.');
+  } else {
+    if (!ROUTE_INTENT_KINDS.has(route.intent.kind)) {
+      errors.push(`intent.kind must be one of: ${[...ROUTE_INTENT_KINDS].join(', ')}.`);
+    }
+    if (!ROUTE_MUTABILITIES.has(route.intent.mutability)) {
+      errors.push(`intent.mutability must be one of: ${[...ROUTE_MUTABILITIES].join(', ')}.`);
+    }
+    if (route.intent.goal !== null && typeof route.intent.goal !== 'string') {
+      errors.push('intent.goal must be a string or null.');
+    }
+    if (!Array.isArray(route.intent.doneConditions)) {
+      errors.push('intent.doneConditions must be an array.');
+    }
+  }
+  if (!isObject(route.execution)) {
+    errors.push('execution must be an object.');
+  } else {
+    if (route.execution.mode !== null && !ROUTE_EXECUTION_MODES.includes(route.execution.mode)) {
+      errors.push(`execution.mode must be null or one of: ${ROUTE_EXECUTION_MODES.join(', ')}.`);
+    }
+    if (route.execution.rigor !== null && !ROUTE_RIGOR_LEVELS.has(route.execution.rigor)) {
+      errors.push(`execution.rigor must be null or one of: ${[...ROUTE_RIGOR_LEVELS].join(', ')}.`);
+    }
+    if (route.execution.contractVersion !== ROUTE_CONTRACT_VERSION) {
+      errors.push(`execution.contractVersion must be ${ROUTE_CONTRACT_VERSION}.`);
+    }
+    if (route.execution.modelTier !== null && !ROUTE_MODEL_TIERS.has(route.execution.modelTier)) {
+      errors.push(`execution.modelTier must be null or one of: ${[...ROUTE_MODEL_TIERS].join(', ')}.`);
+    }
+  }
+  if (!isObject(route.evidence)) {
+    errors.push('evidence must be an object.');
+  } else {
+    for (const key of ['observations', 'riskSignals', 'activationReasons', 'suppressionReasons', 'completionRequirements']) {
+      if (!Array.isArray(route.evidence[key])) {
+        errors.push(`evidence.${key} must be an array.`);
+      }
+    }
+  }
+  if (!isObject(route.ceremonyBudget)) {
+    errors.push('ceremonyBudget must be an object.');
+  } else {
+    if (route.ceremonyBudget.rigor !== null && !ROUTE_RIGOR_LEVELS.has(route.ceremonyBudget.rigor)) {
+      errors.push(`ceremonyBudget.rigor must be null or one of: ${[...ROUTE_RIGOR_LEVELS].join(', ')}.`);
+    }
+    if (!isObject(route.ceremonyBudget.limits)) {
+      errors.push('ceremonyBudget.limits must be an object.');
+    }
+    if (!isObject(route.ceremonyBudget.consumed)) {
+      errors.push('ceremonyBudget.consumed must be an object.');
+    }
+    if (!Array.isArray(route.ceremonyBudget.exceptions)) {
+      errors.push('ceremonyBudget.exceptions must be an array.');
+    }
+  }
+  if (!isObject(route.capabilityPolicy)) {
+    errors.push('capabilityPolicy must be an object.');
+  } else {
+    for (const key of ['required', 'recommended', 'suppressed', 'activeSkillIds']) {
+      if (!Array.isArray(route.capabilityPolicy[key])) {
+        errors.push(`capabilityPolicy.${key} must be an array.`);
+      }
+    }
+  }
+  if (!isObject(route.escalation)) {
+    errors.push('escalation must be an object.');
+  } else {
+    if (!isObject(route.escalation.current)) {
+      errors.push('escalation.current must be an object.');
+    } else {
+      if (route.escalation.current.mode !== null && !ROUTE_EXECUTION_MODES.includes(route.escalation.current.mode)) {
+        errors.push(`escalation.current.mode must be null or one of: ${ROUTE_EXECUTION_MODES.join(', ')}.`);
+      }
+      if (route.escalation.current.rigor !== null && !ROUTE_RIGOR_LEVELS.has(route.escalation.current.rigor)) {
+        errors.push(`escalation.current.rigor must be null or one of: ${[...ROUTE_RIGOR_LEVELS].join(', ')}.`);
+      }
+    }
+    if (!Array.isArray(route.escalation.triggers)) {
+      errors.push('escalation.triggers must be an array.');
+    }
+    if (!Array.isArray(route.escalation.history)) {
+      errors.push('escalation.history must be an array.');
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// Compact serialization whitelist (C01 compatibility rule): adapter/runtime consumers
+// get a bounded view that may omit verbose evidence but never mode, rigor, required
+// completion evidence, or escalation state. Returns null for legacy (stage-off)
+// summaries so compact output stays byte-identical when the schema stage is off.
+export function compactResolvedRoute(routeSummary = null) {
+  if (!routeSummary || typeof routeSummary !== 'object' || routeSummary.routeVersion == null) {
+    return null;
+  }
+  return {
+    routeVersion: routeSummary.routeVersion,
+    intent: routeSummary.intent ?? null,
+    execution: routeSummary.execution ?? null,
+    evidence: {
+      completionRequirements: unique(routeSummary.evidence?.completionRequirements ?? []),
+    },
+    ceremonyBudget: routeSummary.ceremonyBudget ?? null,
+    capabilityPolicy: routeSummary.capabilityPolicy ?? null,
+    escalation: routeSummary.escalation ?? null,
+  };
+}
 const STOPWORDS = new Set([
   'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',
   'this', 'that', 'it', 'as', 'by', 'be', 'use', 'using', 'implement', 'fix', 'task',
@@ -153,7 +586,7 @@ async function resolveVisionModel({ rootDir = process.cwd() } = {}) {
     gateway = null;
   }
 
-  const config = await readJson(path.join(rootDir, '.ukit', 'storage', 'config.json'), null);
+  const config = await readMergedConfig(rootDir);
   const fallbackModel = config?.orchestration?.modelTiers?.vision?.fallbackModel;
 
   if (gateway?.unicMode && gateway.aliasAvailable === false) {
@@ -424,10 +857,22 @@ async function buildRouteHotFingerprint({ rootDir, input, budget }) {
   }
 
   if (!payload.ioBudgetExhausted && !budget.expired()) {
-    const configPath = path.join(absoluteRoot, '.ukit', 'storage', 'config.json');
-    const configStat = await countRouteIo(budget, statOrNothing(configPath));
-    payload.config = configStat
-      ? { ...statFingerprintTuple(configStat), content: await countRouteIo(budget, readJson(configPath, null)) }
+    // Fingerprint both layers: a user-config edit must invalidate the hot cache the
+    // same way a project-config edit does.
+    const projectConfigStat = await countRouteIo(
+      budget,
+      statOrNothing(path.join(absoluteRoot, '.ukit', 'storage', 'config.json')),
+    );
+    const userConfigStat = await countRouteIo(
+      budget,
+      statOrNothing(path.join(os.homedir(), '.ukit', 'storage', 'config.json')),
+    );
+    payload.config = (projectConfigStat || userConfigStat)
+      ? {
+          project: statFingerprintTuple(projectConfigStat),
+          user: statFingerprintTuple(userConfigStat),
+          content: await countRouteIo(budget, readMergedConfig(absoluteRoot)),
+        }
       : null;
   }
 
@@ -678,7 +1123,7 @@ export async function routeTask(input = {}, { signal = null, deadlineMs = null,
   // Phase 2 — bounded full computation. Mirrors main()'s pipeline minus the shared-state,
   // audit and helper-cache-seeding writes (main() stays the single writer for those).
   const escalationConfig = scan.configJson
-    ?? await readJson(path.join(absoluteRoot, '.ukit', 'storage', 'config.json'), null);
+    ?? await readMergedConfig(absoluteRoot);
   const preparedRoute = await prepareTaskRoute({
     rootDir: absoluteRoot,
     promptText: normalizedInput.promptText,
@@ -812,7 +1257,7 @@ async function main() {
   const previousStateOwnershipBlocked = hasRouteStateOwner(persistedPreviousState)
     && !isRouteStateCompatible(persistedPreviousState, sessionId);
   const previousState = previousStateOwnershipBlocked ? {} : persistedPreviousState;
-  const escalationConfig = await readJson(path.join(rootDir, '.ukit', 'storage', 'config.json'), null);
+  const escalationConfig = await readMergedConfig(rootDir);
   const targetFile = readFlagValue(args, '--target');
   const taskType = readFlagValue(args, '--type');
   const commandText = readFlagValue(args, '--tool-command') ?? '';
@@ -1207,12 +1652,21 @@ async function finalizeTaskRoute({
     contextRecommendation,
     verificationRecommendation,
   });
+  // SPEC FR-009 mirror: project playbook > user playbook > builtin. resolveWorkflowPolicy
+  // already falls back to the builtin table, so null only means the lane has no policy.
+  const workflowPolicyName = WORKFLOW_POLICY_BY_MODE[routingContext.executionMode] ?? null;
+  const resolvedWorkflowPolicy = workflowPolicyName
+    ? await resolveWorkflowPolicy(workflowPolicyName, { projectRoot: absoluteRoot })
+    : null;
   const routeSummary = buildRouteSummary({
     activeSkills,
     routingContext,
     contextRecommendation,
     verificationRecommendation,
     nextAction,
+    routeSchemaStage: resolveRouteSchemaStage(escalationConfig),
+    runtimeConfig: escalationConfig,
+    resolvedWorkflowPolicy,
   });
   routeSummary.continuationState = advanceContinuationState(
     routeSummary.continuationState,
@@ -1289,6 +1743,20 @@ function printRouteState(state) {
   if (helperDisplay) {
     console.log(`helper: ${helperDisplay}`);
   }
+  // v3 advisory blocks (SPEC-playbook-todo / SPEC-principle-index / SPEC-model-roles):
+  // additive stdout text, byte-stable for unchanged config.
+  if (state.routeSummary?.workflowPolicyName) {
+    console.log(`workflow: ${state.routeSummary.workflowPolicyName} — copy steps verbatim into your todo list; skipped steps keep skip:<reason>`);
+  }
+  if (state.routeSummary?.workflowPolicy) {
+    console.log(state.routeSummary.workflowPolicy);
+  }
+  if (state.routeSummary?.principleIndex) {
+    console.log(state.routeSummary.principleIndex);
+  }
+  if (state.routeSummary?.modelRolesBlock) {
+    console.log(state.routeSummary.modelRolesBlock);
+  }
 }
 
 function hasRouteSummaryField(routeSummary, field) {
@@ -2147,6 +2615,9 @@ function buildRouteSummary({
   verificationRecommendation = null,
   nextAction = null,
   contextDocs = null,
+  routeSchemaStage = 'off',
+  runtimeConfig = null,
+  resolvedWorkflowPolicy = null,
 } = {}) {
   const autonomyLevel = routingContext.autonomyLevel ?? 'balanced';
   const delegationRecommendation = deriveDelegationRecommendation({
@@ -2201,6 +2672,15 @@ function buildRouteSummary({
     nextActionType: nextAction?.type ?? null,
     completionState,
   });
+  const resolvedRouteFields = routeSchemaStage !== 'off'
+    ? buildResolvedRouteFields({
+        routingContext,
+        activeSkillIds: activeSkills.map((entry) => entry.id),
+        executionMode,
+        executionContract,
+        completionState,
+      })
+    : null;
   const helperHint = compactHelperHint(
     compactHelperLane
       ? contextRecommendation?.command
@@ -2221,6 +2701,19 @@ function buildRouteSummary({
   const docsSegment = resolvedContextDocs.length > 0
     ? `docs=[${resolvedContextDocs.slice(0, CONTEXT_DOCS_MAX).map((p) => path.posix.basename(String(p).replaceAll('\\', '/'))).join(',')}]`
     : null;
+  // v3 advisory blocks (SPEC-playbook-todo / SPEC-principle-index / SPEC-model-roles):
+  // additive stdout text only — never change mode selection.
+  const workflowPolicyName = WORKFLOW_POLICY_BY_MODE[executionMode] ?? null;
+  const workflowPolicy = workflowPolicyName
+    ? (resolvedWorkflowPolicy?.body ?? WORKFLOW_POLICIES[workflowPolicyName])
+    : null;
+  const principleIndex = shouldEmitPrincipleIndex({ taskType, executionMode })
+    ? PRINCIPLE_INDEX
+    : null;
+  const modelRolesResolution = resolveModelRoles(runtimeConfig);
+  const modelRolesBlock = MODEL_ROLES_DELEGATING_MODES.has(executionMode)
+    ? formatModelRolesBlock(modelRolesResolution.roles)
+    : null;
   const line = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
     handoffFile ? `handoff=${handoffFile}` : null,
@@ -2231,6 +2724,7 @@ function buildRouteSummary({
     editGuardHint ? `editGuard=${editGuardHint}` : null,
     delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
+    workflowPolicyName ? `workflow=${workflowPolicyName}` : null,
   ].filter(Boolean).join(' | ');
 
   return {
@@ -2246,6 +2740,8 @@ function buildRouteSummary({
     executionContract,
     tierLane,
     completionState,
+    // M01.1 additive C01 groups — present only when routing.routeSchema.stage != "off".
+    ...(resolvedRouteFields ?? {}),
     continuationState,
     autonomyLevel,
     continuousExecution,
@@ -2258,6 +2754,13 @@ function buildRouteSummary({
     helperHint,
     contextMode,
     contextDocs: resolvedContextDocs,
+    workflowPolicyName,
+    workflowPolicy,
+    // TASK-007: emitted only when a policy is emitted — the stage-off route shape
+    // stays unchanged on lanes that carry no workflow policy.
+    ...(workflowPolicy ? { workflowPolicySource: resolvedWorkflowPolicy?.source ?? 'builtin' } : {}),
+    principleIndex,
+    modelRolesBlock,
     ...(visionLane ? {
       visionLane: true,
       visionReason: routingContext.visionReason ?? null,
@@ -2434,27 +2937,8 @@ function deriveExecutionMode({
   const strongImpactLead = scores.sharedRisk
     && (scores.impactSignal || /\b(check all affected|map all affected|across all affected)\b/.test(raw));
   const boundedLocalBuildCandidate = scores.buildSignal && scores.boundedEditSignal && scores.explicitTarget && !scores.sharedRisk;
-  // A bare delivery command ("push this to git", "đẩy bộ này lên git") performs no
-  // repository mutation the ledger could ever receipt. With no edit/review/debug/
-  // build signal present, routing it to an investigation lane fabricates write debt
-  // and the completion gate then demands an edit that cannot exist. Delivery-only
-  // requests carry no completion contract instead.
-  const deliveryWordSignal = /\bgit\s+push\b/.test(signalRaw)
-    || /\bpush\b[^\n]{0,60}\b(?:git|github|gitlab|remote|origin|repo)\b/.test(signalRaw)
-    || /\b(?:git|github|gitlab|remote|origin|repo)\b[^\n]{0,60}\bpush\b/.test(signalRaw)
-    || /\bday\b(?:\s+\S+){0,3}?\s+len\b/.test(signalRaw);
-  const deliveryOnlySignal = deliveryWordSignal
-    && scores.editCertainty === 0
-    && !scores.implementSignal
-    && !scores.reviewSignal
-    && !scores.debugSignal
-    && !scores.failureSignal
-    && !scores.impactSignal
-    && !scores.buildSignal
-    && !scores.directTransformSignal
-    && !scores.smallFixSignal
-    && !scores.sharedRisk
-    && !targetFile;
+  // Delivery-only requests carry no completion contract (see isDeliveryOnlyRequest).
+  const deliveryOnlySignal = isDeliveryOnlyRequest({ signalText: signalRaw, scores, targetFile });
 
   if (isInformationalPrompt({ promptText, commandText, scores })) {
     return 'informational';
@@ -3724,10 +4208,22 @@ function compactRouteSummary(routeSummary = null) {
     nextActionType: routeSummary.nextActionType ?? null,
     nextActionCommand: routeSummary.nextActionCommand ?? null,
     helperHint: routeSummary.helperHint ?? null,
+    // v3 advisory blocks: survive compaction so printRouteState and cached/shared route
+    // states still emit them. Null when the lane suppresses them — cheap either way.
+    workflowPolicyName: routeSummary.workflowPolicyName ?? null,
+    workflowPolicy: routeSummary.workflowPolicy ?? null,
+    ...(routeSummary.workflowPolicy ? {
+      workflowPolicySource: routeSummary.workflowPolicySource ?? 'builtin',
+    } : {}),
+    principleIndex: routeSummary.principleIndex ?? null,
+    modelRolesBlock: routeSummary.modelRolesBlock ?? null,
     ...(routeSummary.escalatedTier ? {
       escalatedTier: routeSummary.escalatedTier,
       escalationReason: routeSummary.escalationReason ?? null,
     } : {}),
+    // M01.1 compact whitelist (C01): grouped fields survive compaction minus verbose
+    // evidence; absent entirely when the route schema stage is off.
+    ...(compactResolvedRoute(routeSummary) ?? {}),
     ...(routeSummary.visionLane ? {
       visionLane: true,
       visionReason: routeSummary.visionReason ?? null,
@@ -4063,6 +4559,134 @@ async function readJson(filePath, fallback = null) {
   }
 }
 
+// --- User-level .ukit layer (SPEC §5 FR-006/FR-009) -------------------------------
+// Self-contained mirror of src/core/runtimeConfig.js merge semantics and
+// src/core/userPlaybooks.js resolution — this file cannot import from src/.
+const BLOCKED_MERGE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+const PROJECT_MANAGED_USER_KEYS = new Set(['version', 'agent']);
+const warnedManagedUserKeys = new Set();
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// Plain-object recursion; arrays and scalars are replaced wholesale. `override` wins.
+function mergeConfigObjects(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override === undefined ? base : override;
+  }
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (BLOCKED_MERGE_KEYS.has(key)) {
+      continue;
+    }
+    const current = merged[key];
+    if (isPlainObject(current) && isPlainObject(value)) {
+      merged[key] = mergeConfigObjects(current, value);
+      continue;
+    }
+    merged[key] = value;
+  }
+  return merged;
+}
+
+// `version`/`agent` are project-managed: a stale user file must not pin a project to
+// an old version or a removed agent. Warn once per process per stripped key.
+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;
+}
+
+// Raw merged view (pre-validation): user layer under the project layer, project wins
+// every key. Missing or malformed files are skipped — never throws.
+async function readMergedConfig(rootDir) {
+  const projectRaw = await readJson(path.join(rootDir, '.ukit', 'storage', 'config.json'), null);
+  const userRaw = await readJson(path.join(os.homedir(), '.ukit', 'storage', 'config.json'), null);
+  return mergeConfigObjects(stripProjectManagedKeys(userRaw) ?? {}, projectRaw ?? {});
+}
+
+// Playbook file format (SPEC FR-009): optional `---` frontmatter then the markdown
+// body. Returns the trimmed body, or null when the file is missing, malformed, or
+// carries no usable body (caller falls through to the next precedence level).
+async function readPlaybookBody(filePath) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  let body = raw;
+  if (raw.startsWith('---\n')) {
+    // In `---\n---` the closing fence's leading \n is the newline that terminates the
+    // opening fence; `---x` is not a closing fence.
+    const fenceIndex = raw.indexOf('\n---', 3);
+    if (fenceIndex === -1) {
+      console.warn(`[UKit] Warning: skipping malformed playbook ${filePath}`);
+      return null;
+    }
+    const after = raw.slice(fenceIndex + 4);
+    if (after.length > 0 && !after.startsWith('\n')) {
+      console.warn(`[UKit] Warning: skipping malformed playbook ${filePath}`);
+      return null;
+    }
+    body = after.replace(/^\n/, '');
+  }
+  const trimmed = body.trim();
+  if (trimmed === '') {
+    console.warn(`[UKit] Warning: skipping malformed playbook ${filePath}`);
+    return null;
+  }
+  return trimmed;
+}
+
+function isSafePlaybookName(policyName) {
+  return (
+    typeof policyName === 'string'
+    && policyName !== ''
+    && !policyName.includes('/')
+    && !policyName.includes('\\')
+    && !policyName.includes('..')
+  );
+}
+
+// Resolves a workflow policy through the playbook layer: project playbook > user
+// playbook > builtin table. Returns { body, source } or null when nothing matches.
+async function resolveWorkflowPolicy(policyName, { projectRoot } = {}) {
+  if (!isSafePlaybookName(policyName)) {
+    return null;
+  }
+  for (const [dir, source] of [
+    [projectRoot ? path.join(projectRoot, '.ukit', 'playbooks') : null, 'project'],
+    [path.join(os.homedir(), '.ukit', 'playbooks'), 'user'],
+  ]) {
+    if (dir === null) {
+      continue;
+    }
+    const body = await readPlaybookBody(path.join(dir, `${policyName}.md`));
+    if (body !== null) {
+      return { body, source };
+    }
+  }
+  const builtinBody = WORKFLOW_POLICIES[policyName];
+  if (typeof builtinBody === 'string' && builtinBody !== '') {
+    return { body: builtinBody, source: 'builtin' };
+  }
+  return null;
+}
+
 function normalize(text) {
   return String(text ?? '')
     .toLowerCase()