@ngockhoale/ukit 2.7.12 → 2.8.0

package/src/index/taskRouting.js

@@ -10,7 +10,109 @@ import {
   CONTRACT_RISK_PROFILES,
   EXECUTION_CONTRACTS,
   EXECUTION_MODE_ORDER,
+  MODEL_TIER_BY_CONTRACT,
 } from '../core/executionContracts.js';
+import { resolveModelRoles, readMergedRuntimeConfig } from '../core/runtimeConfig.js';
+import { resolvePlaybook } from '../core/userPlaybooks.js';
+
+// --- v3 route-side advisory blocks (docs/pstack/SPEC-playbook-todo.md, ------------------
+// SPEC-principle-index.md, SPEC-model-roles.md). All three are additive stdout text —
+// they never change mode selection. Static text is byte-stable for prompt-cache reuse.
+// Mirrored literally in templates/.claude/ukit/index/route-task.mjs (parity-locked by
+// tests/consistency/executionContractSync.test.js).
+
+// 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';
+}
+
+// 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.`;
+}
 
 const MAX_ACTIVE_ROUTE_SKILLS = 2;
 
@@ -42,6 +144,272 @@ function deriveContextDocs({ taskType = null, intentMode = null } = {}) {
   return unique(docs).slice(0, CONTEXT_DOCS_MAX);
 }
 
+// --- M01.1: additive ResolvedTaskRoute v1 (docs/pstack/CONTRACTS.md C01) -------------------
+// 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_ORDER ladder.
+export const ROUTE_EXECUTION_MODES = [...EXECUTION_MODE_ORDER, 'informational'];
+const ROUTE_ESCALATION_CEILING = 'review-release';
+const ROUTE_GOAL_MAX_LENGTH = 240;
+
+// 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 = buildRouteSignalText(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 ?? MODEL_TIER_BY_CONTRACT[executionMode] ?? 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,
+  };
+}
+
+
 export async function deriveTaskRoute({
   rootDir = process.cwd(),
   promptText = '',
@@ -51,8 +419,15 @@ export async function deriveTaskRoute({
   lastExplicitUserPromptText = '',
   commandNamespace = '.claude',
   autonomyLevel = 'balanced',
+  runtimeConfig = null,
+  homeDir = undefined,
 } = {}) {
   const absoluteRoot = path.resolve(rootDir);
+  // M01.1: additive route-schema stage. Absent config / absent key / unknown value all
+  // resolve to "off" — the route then stays byte-identical to the pre-M01.1 shape.
+  const resolvedRuntimeConfig = runtimeConfig
+    ?? await readMergedRuntimeConfig(absoluteRoot, { homeDir });
+  const routeSchemaStage = resolveRouteSchemaStage(resolvedRuntimeConfig);
   const normalizedPrompt = String(promptText || '').trim();
   const normalizedCommand = String(commandText || '').trim();
   const normalizedTarget = normalizeRelativeFile(absoluteRoot, targetFile);
@@ -177,6 +552,13 @@ export async function deriveTaskRoute({
     ? await checkHandoffBudget(absoluteRoot)
     : null;
   const worklogBudget = await checkWorklogBudget(absoluteRoot);
+  // SPEC FR-009: the lane's workflow policy resolves through the playbook layer —
+  // project playbook > user playbook > builtin. resolvePlaybook already falls back to
+  // the builtin table, so a null result only means the lane has no policy at all.
+  const workflowPolicyName = WORKFLOW_POLICY_BY_MODE[executionMode] ?? null;
+  const resolvedWorkflowPolicy = workflowPolicyName
+    ? await resolvePlaybook(workflowPolicyName, { projectRoot: absoluteRoot, homeDir })
+    : null;
   const routeSummary = buildRouteSummary({
     activeSkills,
     routingContext: {
@@ -197,6 +579,9 @@ export async function deriveTaskRoute({
     nextAction,
     handoffBudget,
     worklogBudget,
+    routeSchemaStage,
+    runtimeConfig: resolvedRuntimeConfig,
+    resolvedWorkflowPolicy,
   });
   const approachSelector = routeSummary?.approachSelector ?? null;
 
@@ -235,6 +620,9 @@ export function buildRouteSummary({
   handoffBudget = null,
   worklogBudget = null,
   contextDocs = null,
+  routeSchemaStage = 'off',
+  runtimeConfig = null,
+  resolvedWorkflowPolicy = null,
 } = {}) {
   const autonomyLevel = routingContext.autonomyLevel ?? 'balanced';
   const delegationRecommendation = deriveDelegationRecommendation({
@@ -279,6 +667,15 @@ export 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
@@ -298,6 +695,19 @@ export 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 summaryLine = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
     handoffFile ? `handoff=${handoffFile}` : null,
@@ -308,6 +718,7 @@ export function buildRouteSummary({
     editGuardHint ? `editGuard=${editGuardHint}` : null,
     delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
+    workflowPolicyName ? `workflow=${workflowPolicyName}` : null,
     handoffBudget?.warning ? `budget=${handoffBudget.warning}` : null,
     worklogBudget?.warning ? `budget=${worklogBudget.warning}` : null,
   ].filter(Boolean).join(' | ');
@@ -324,6 +735,8 @@ export function buildRouteSummary({
     approachSelector,
     executionContract,
     completionState,
+    // M01.1 additive C01 groups — present only when routing.routeSchema.stage != "off".
+    ...(resolvedRouteFields ?? {}),
     continuationState,
     autonomyLevel,
     continuousExecution,
@@ -337,6 +750,13 @@ export 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,
     line: summaryLine || 'task=unknown',
   };
 }
@@ -515,27 +935,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 });
   // A pure consultation question ("Rồi việc kế tiếp của tôi phải làm gì…?", "how do I
   // measure this on another machine?") asks for an answer, not a repository change. The
   // signal regexes are English-only, so a Vietnamese (or signal-free English) question

package/src/index/verificationPlan.js

@@ -5,6 +5,9 @@ import { detectPackageManagerFromFingerprint, getDeclaredPackageManager } from '
 import { resolveContext } from './resolveContext.js';
 
 const RISKY_SKILL_IDS = new Set(['discover-security', 'repo-maintenance']);
+// SPEC-typed-verdicts §2.5: commands matching a test runner can mint a
+// `test-verified` verdict; everything else a plan routes is `check-only`.
+const TEST_RUNNER_COMMAND = /(?:^|\s)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)|(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+test(?:\s|$)/i;
 const TRACKED_VERIFICATION_FILES = [
   'package.json',
   'package-lock.json',
@@ -144,6 +147,19 @@ export async function deriveVerificationPlan({
     }
 
     const primaryCommandList = unique(commands);
+    // SPEC-typed-verdicts §2.5: each routed command carries the verdict kind it can
+    // honestly produce — test runners prove `test-verified`; type-check/lint-only
+    // commands are `check-only` and cannot satisfy lanes requiring runtime proof.
+    const verdictKind = {};
+    for (const command of [...primaryCommandList, ...fallbackCommands]) {
+      verdictKind[command] = TEST_RUNNER_COMMAND.test(command) ? 'test-verified' : 'check-only';
+    }
+    const laneRequiresRuntimeProof = !docsOnly
+      && (risky || primaryTargets.some((filePath) => !isTestLikeFile(filePath)));
+    if (laneRequiresRuntimeProof
+      && primaryCommandList.every((command) => verdictKind[command] === 'check-only')) {
+      notes.push('verify: check-only insufficient for this lane — verify on the real surface (run the feature / inspect the artifact).');
+    }
     const fallbackCommandList = unique(fallbackCommands.filter((command) => !primaryCommandList.includes(command)));
     const reasonList = unique(reasons);
     const noteList = unique(notes);
@@ -156,6 +172,7 @@ export async function deriveVerificationPlan({
       fallbackCommands: fallbackCommandList,
       reasons: reasonList,
       notes: noteList,
+      verdictKind,
       executionPolicy: deriveExecutionPolicy({
         taskType: effectiveTaskType,
         mode,

package/src/manifest/validateManifest.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 
 const VALID_ITEM_TYPES = new Set(['command', 'skill', 'agent', 'hook', 'config', 'link']);
 const VALID_MERGE_STRATEGIES = new Set(['overwrite_with_backup', 'skip', 'append', 'prepend', 'merge_env_overwrite_with_backup']);
+const VALID_ITEM_LEVELS = new Set(['project', 'user']);
 
 function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -33,6 +34,10 @@ export function validateManifest(manifest) {
     errors.push('Manifest `name` must be a non-empty string.');
   }
 
+  if (manifest.level !== undefined && manifest.level !== 'user') {
+    errors.push("Manifest `level` must be 'user' when provided.");
+  }
+
   if (!Array.isArray(manifest.items) || manifest.items.length === 0) {
     errors.push('Manifest `items` must be a non-empty array.');
     return { valid: errors.length === 0, errors };
@@ -91,6 +96,20 @@ export function validateManifest(manifest) {
       );
     }
 
+    if (item.level !== undefined && !VALID_ITEM_LEVELS.has(item.level)) {
+      errors.push(`${prefix}.level must be one of: ${Array.from(VALID_ITEM_LEVELS).join(', ')}`);
+    }
+
+    if (manifest.level === 'user' || item.level === 'user') {
+      if (item.type === 'link') {
+        errors.push(`${prefix}.type must not be 'link' for user-level items.`);
+      }
+
+      if (item.mergeStrategy !== 'skip') {
+        errors.push(`${prefix}.mergeStrategy must be 'skip' for user-level items.`);
+      }
+    }
+
     if (typeof item.enabledByDefault !== 'boolean') {
       errors.push(`${prefix}.enabledByDefault must be a boolean.`);
     }

package/templates/.claude/config/providers.md

@@ -11,9 +11,7 @@ Provider: **UNIC**
 
 ## API Key
 
-```
-anh-khoa-rat-dep-trai
-```
+Set the provider credential through the runtime's private environment or user-level secret configuration. Never commit a real key to the repository or generated project files.
 
 ## Available Models
 

package/templates/.claude/skills/principle-attack-the-premise/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: principle-attack-the-premise
+description: When two or more fixes sharing one premise have failed, question the premise instead of attempting a third fix. Apply during debugging and repeated-failure loops.
+disable-model-invocation: true
+---
+
+# Attack the Premise
+
+**Why:** Repeated failures on the same approach usually mean the shared assumption is wrong, not that the attempts were unlucky. A third fix on a false premise is a third failure.
+
+- Track what every failed fix assumed; the common assumption is the suspect.
+- After two failures sharing a premise, stop fixing and test the premise directly.
+- Reproduce the premise's prediction in isolation before building on it again.
+- Escalate with the premise named, not just "it still fails."
+
+**Test:** If two fixes failed and both assumed X, the next action verifies X — not a third fix.

package/templates/.claude/skills/principle-boundary-discipline/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: principle-boundary-discipline
+description: Guards at boundaries, pure functions inside. Apply when handling external input, I/O, or untrusted data.
+disable-model-invocation: true
+---
+
+# Boundary Discipline
+
+**Why:** Validation scattered through the interior means every function distrusts its input and none can be reasoned about alone. Check once at the edge; keep the inside pure.
+
+- Validate, parse, and normalize at the system boundary — never deeper.
+- Inside the boundary, functions assume well-formed input and stay pure where possible.
+- Errors from outside become typed/domain errors at the boundary, not deep in logic.
+- Never let raw external shapes leak past the first layer.
+
+**Test:** Interior functions contain no defensive checks for malformed external input — the boundary already guaranteed shape.

package/templates/.claude/skills/principle-encode-lessons-in-structure/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: principle-encode-lessons-in-structure
+description: Turn repeated lessons into lint rules, flags, or scripts — not more prose. Apply when the same mistake or instruction recurs.
+disable-model-invocation: true
+---
+
+# Encode Lessons in Structure
+
+**Why:** Prose instructions are re-read, re-forgotten, and re-violated. A rule encoded in a check, flag, or script enforces itself forever at zero attention cost.
+
+- When the same correction appears twice, encode it: lint rule, test, flag, script, or template.
+- Prefer a mechanism that fails loudly over documentation that advises quietly.
+- Keep the prose pointer minimal — the structure is the lesson.
+- Apply to process too: a repeated manual step is a script waiting to exist.
+
+**Test:** The next occurrence of the mistake fails a check automatically instead of needing a reviewer to catch it.