@kognai/orchestrator-core 0.1.0

package/dist/lib/sprint-state.d.ts

@@ -0,0 +1,71 @@
+/**
+ * sprint-state.ts — TICKET-098: split sprint task definitions (committed,
+ * immutable) from sprint task runtime status (gitignored, mutable).
+ *
+ * Problem solved: prior design stored `status`, `attempt_count`,
+ * `rejected_reason` inside `workspace/sprints/sprint-XXXX.json` which is
+ * git-tracked. Any git operation (rebase, fetch, checkout) that touched
+ * the file silently clobbered runtime state. Multiple writers racing on
+ * the same file made it worse. The push-with-rebase fix (TICKET-095) made
+ * it catastrophic by ACTIVELY resetting source to origin on every
+ * divergent push.
+ *
+ * Solution: source file contains ONLY task definitions. Runtime status
+ * lives in `.swarm-state/sprint-XXXX.json` (gitignored). Git never sees
+ * it. Multiple writers still need atomic-write but no longer race with
+ * git itself.
+ *
+ * TICKET-215 Phase 3b-3: the repo root now resolves via engine-paths
+ * (KOGNAI_ROOT / cwd) instead of `process.cwd()` directly, so the module is
+ * location-independent and can live in @kognai/orchestrator-core. When run
+ * from a product repo root, resolveEnginePaths().root === the old cwd — same
+ * <root>/.swarm-state path, no behavior change.
+ */
+export interface TaskState {
+    status: string;
+    attempt_count?: number;
+    rejected_reason?: string;
+}
+export type SprintStateMap = Record<string, TaskState>;
+/** Read the gitignored state file for a sprint. Returns empty map if absent. */
+export declare function readState(sprintFile: string): SprintStateMap;
+/**
+ * Update one task's runtime status. Idempotent — no-op if nothing changed.
+ * Caller should pass undefined for fields that shouldn't be touched.
+ */
+export declare function updateTaskStatus(sprintFile: string, taskId: string, status?: string, attempt_count?: number, rejected_reason?: string): void;
+/**
+ * Bulk apply task statuses from an ACTIVE file's tasks array. Used by
+ * sprint-runner sync-on-exit to mirror orchestrator's per-task updates
+ * back into persistent state. Idempotent at the field level.
+ */
+export declare function applyActiveTasksToState(sprintFile: string, activeTasks: Array<{
+    id: string;
+    status?: string;
+    attempt_count?: number;
+    rejected_reason?: string;
+    score?: number;
+    grade?: string;
+    rejection_reason?: string;
+}>): {
+    updates: number;
+    attempted: number;
+};
+/**
+ * Merge source (definitions) + state (runtime) into the unified shape the
+ * orchestrator expects. Used at runtime to build the ACTIVE file.
+ *
+ * Backward-compat: if source still has status fields (pre-migration), use
+ * them as initial values; state always wins when present.
+ */
+export declare function loadSprintMerged(sprintFile: string): any;
+/**
+ * One-shot migration helper: read every sprint file in workspace/sprints/,
+ * if it contains tasks with status/attempt_count/rejected_reason inline,
+ * extract those fields into .swarm-state/ and strip them from source.
+ * Idempotent — safe to run multiple times.
+ */
+export declare function migrateSprintFile(sprintFile: string): {
+    migrated: number;
+    sourceStripped: boolean;
+};

package/dist/lib/sprint-state.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * sprint-state.ts — TICKET-098: split sprint task definitions (committed,
+ * immutable) from sprint task runtime status (gitignored, mutable).
+ *
+ * Problem solved: prior design stored `status`, `attempt_count`,
+ * `rejected_reason` inside `workspace/sprints/sprint-XXXX.json` which is
+ * git-tracked. Any git operation (rebase, fetch, checkout) that touched
+ * the file silently clobbered runtime state. Multiple writers racing on
+ * the same file made it worse. The push-with-rebase fix (TICKET-095) made
+ * it catastrophic by ACTIVELY resetting source to origin on every
+ * divergent push.
+ *
+ * Solution: source file contains ONLY task definitions. Runtime status
+ * lives in `.swarm-state/sprint-XXXX.json` (gitignored). Git never sees
+ * it. Multiple writers still need atomic-write but no longer race with
+ * git itself.
+ *
+ * TICKET-215 Phase 3b-3: the repo root now resolves via engine-paths
+ * (KOGNAI_ROOT / cwd) instead of `process.cwd()` directly, so the module is
+ * location-independent and can live in @kognai/orchestrator-core. When run
+ * from a product repo root, resolveEnginePaths().root === the old cwd — same
+ * <root>/.swarm-state path, no behavior change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readState = readState;
+exports.updateTaskStatus = updateTaskStatus;
+exports.applyActiveTasksToState = applyActiveTasksToState;
+exports.loadSprintMerged = loadSprintMerged;
+exports.migrateSprintFile = migrateSprintFile;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const engine_paths_1 = require("./engine-paths");
+const ROOT = (0, engine_paths_1.resolveEnginePaths)().root;
+const STATE_DIR = (0, path_1.join)(ROOT, '.swarm-state');
+function ensureStateDir() {
+    if (!(0, fs_1.existsSync)(STATE_DIR)) {
+        (0, fs_1.mkdirSync)(STATE_DIR, { recursive: true });
+    }
+}
+function stateFileFor(sprintFile) {
+    const name = (0, path_1.basename)(sprintFile);
+    return (0, path_1.join)(STATE_DIR, name);
+}
+/** Read the gitignored state file for a sprint. Returns empty map if absent. */
+function readState(sprintFile) {
+    const sf = stateFileFor(sprintFile);
+    if (!(0, fs_1.existsSync)(sf))
+        return {};
+    try {
+        return JSON.parse((0, fs_1.readFileSync)(sf, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Atomic write of the state map for a sprint. */
+function writeState(sprintFile, state) {
+    ensureStateDir();
+    const sf = stateFileFor(sprintFile);
+    const tmp = `${sf}.tmp.${process.pid}.${Date.now()}`;
+    (0, fs_1.writeFileSync)(tmp, JSON.stringify(state, null, 2));
+    (0, fs_1.renameSync)(tmp, sf);
+}
+/**
+ * Update one task's runtime status. Idempotent — no-op if nothing changed.
+ * Caller should pass undefined for fields that shouldn't be touched.
+ */
+function updateTaskStatus(sprintFile, taskId, status, attempt_count, rejected_reason) {
+    const state = readState(sprintFile);
+    const prev = state[taskId] || { status: 'pending' };
+    const next = { ...prev };
+    let changed = false;
+    if (status !== undefined && status !== prev.status) {
+        next.status = status;
+        changed = true;
+    }
+    if (attempt_count !== undefined && attempt_count !== prev.attempt_count) {
+        next.attempt_count = attempt_count;
+        changed = true;
+    }
+    if (rejected_reason !== undefined && rejected_reason !== prev.rejected_reason) {
+        next.rejected_reason = rejected_reason;
+        changed = true;
+    }
+    if (!changed)
+        return;
+    state[taskId] = next;
+    writeState(sprintFile, state);
+}
+/**
+ * Bulk apply task statuses from an ACTIVE file's tasks array. Used by
+ * sprint-runner sync-on-exit to mirror orchestrator's per-task updates
+ * back into persistent state. Idempotent at the field level.
+ */
+function applyActiveTasksToState(sprintFile, activeTasks) {
+    const state = readState(sprintFile);
+    let updates = 0;
+    let attempted = 0;
+    for (const t of activeTasks) {
+        if (!t.id || !t.status)
+            continue;
+        const prev = (state[t.id] || { status: 'pending' });
+        // CTO-006 telemetry-blackout hotfix (2026-05-29, Slice A of TICKET-135):
+        // previously only updated when status changed, which meant attempt_count,
+        // score etc. silently dropped across retries (status stayed 'rejected'
+        // through 3 attempts → 2nd + 3rd attempt's fields lost). The CTO's
+        // 10-sprint zero-ship diagnosis turned on score being '?' in every
+        // retrospective. Now: detect ANY field change and merge through. Status
+        // transition still drives the 'attempted' counter.
+        const merged = {
+            status: t.status,
+            attempt_count: t.attempt_count ?? prev.attempt_count,
+            rejected_reason: t.rejected_reason ?? prev.rejected_reason,
+            score: t.score ?? prev.score,
+            grade: t.grade ?? prev.grade,
+            rejection_reason: t.rejection_reason ?? prev.rejection_reason,
+        };
+        const changed = JSON.stringify(merged) !== JSON.stringify(prev);
+        if (changed) {
+            state[t.id] = merged;
+            updates++;
+            if (prev.status !== t.status && t.status !== 'pending')
+                attempted++;
+        }
+    }
+    if (updates > 0)
+        writeState(sprintFile, state);
+    return { updates, attempted };
+}
+/**
+ * Merge source (definitions) + state (runtime) into the unified shape the
+ * orchestrator expects. Used at runtime to build the ACTIVE file.
+ *
+ * Backward-compat: if source still has status fields (pre-migration), use
+ * them as initial values; state always wins when present.
+ */
+function loadSprintMerged(sprintFile) {
+    const source = JSON.parse((0, fs_1.readFileSync)(sprintFile, 'utf-8'));
+    const state = readState(sprintFile);
+    if (Array.isArray(source.tasks)) {
+        source.tasks = source.tasks.map((t) => {
+            const s = state[t.id];
+            if (!s) {
+                // No state entry yet — keep source's status (or default to pending)
+                return { ...t, status: t.status ?? 'pending', attempt_count: t.attempt_count ?? 0 };
+            }
+            return {
+                ...t,
+                status: s.status,
+                attempt_count: s.attempt_count ?? 0,
+                ...(s.rejected_reason ? { rejected_reason: s.rejected_reason } : {}),
+            };
+        });
+    }
+    return source;
+}
+/**
+ * One-shot migration helper: read every sprint file in workspace/sprints/,
+ * if it contains tasks with status/attempt_count/rejected_reason inline,
+ * extract those fields into .swarm-state/ and strip them from source.
+ * Idempotent — safe to run multiple times.
+ */
+function migrateSprintFile(sprintFile) {
+    if (!(0, fs_1.existsSync)(sprintFile))
+        return { migrated: 0, sourceStripped: false };
+    const source = JSON.parse((0, fs_1.readFileSync)(sprintFile, 'utf-8'));
+    if (!Array.isArray(source.tasks))
+        return { migrated: 0, sourceStripped: false };
+    const state = readState(sprintFile);
+    let migrated = 0;
+    let stripped = false;
+    for (const t of source.tasks) {
+        if (!t.id)
+            continue;
+        const hasRuntime = (t.status !== undefined) || (t.attempt_count !== undefined) || (t.rejected_reason !== undefined);
+        if (hasRuntime) {
+            // Only adopt source's runtime fields if state doesn't already have them
+            if (!state[t.id]) {
+                state[t.id] = {
+                    status: t.status ?? 'pending',
+                    attempt_count: t.attempt_count ?? 0,
+                    ...(t.rejected_reason ? { rejected_reason: t.rejected_reason } : {}),
+                };
+                migrated++;
+            }
+            delete t.status;
+            delete t.attempt_count;
+            delete t.rejected_reason;
+            stripped = true;
+        }
+    }
+    if (migrated > 0)
+        writeState(sprintFile, state);
+    if (stripped) {
+        // Atomic write of source
+        const tmp = `${sprintFile}.tmp.${process.pid}.${Date.now()}`;
+        (0, fs_1.writeFileSync)(tmp, JSON.stringify(source, null, 2));
+        (0, fs_1.renameSync)(tmp, sprintFile);
+    }
+    return { migrated, sourceStripped: stripped };
+}

package/dist/lib/stuck-handler.d.ts

@@ -0,0 +1,17 @@
+export interface StuckDetection {
+    stuck: boolean;
+    reason: string;
+    scores: number[];
+    rejection_reasons: string[];
+}
+export interface EscalationDecision {
+    action: 'bump_tier' | 'rephrase_context' | 'escalate_human';
+    reasoning: string;
+    new_tier?: 'cloud-code' | 'apex';
+    budget_override?: number;
+    rephrased_context?: string;
+    telegram_message?: string;
+}
+export declare function escalationPaused(swarmStateDir?: string): boolean;
+export declare function detectStuckPattern(sprintId: string, taskId: string, swarmStateDir?: string): StuckDetection;
+export declare function escalateStuckTask(sprintId: string, taskId: string, taskContext: string, taskTitle: string, detection: StuckDetection, swarmStateDir?: string): Promise<EscalationDecision>;

package/dist/lib/stuck-handler.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escalationPaused = escalationPaused;
+exports.detectStuckPattern = detectStuckPattern;
+exports.escalateStuckTask = escalateStuckTask;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const anthropic_direct_1 = require("./anthropic-direct");
+const DEFAULT_SWARM_STATE_DIR = '.swarm-state';
+// Kill-switch filename — matches TICKET-204 spec + the TICKET-201 dispatcher-paused
+// convention (.swarm-state/<feature>-paused). `touch .swarm-state/escalation-paused`
+// to disable all stuck-task escalation without a code change.
+const PAUSE_FLAG = 'escalation-paused';
+function envInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function envFloat(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseFloat(raw);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function variance(values) {
+    if (values.length === 0)
+        return 0;
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const sq = values.reduce((acc, v) => acc + (v - mean) ** 2, 0);
+    return sq / values.length;
+}
+function readStateFile(swarmStateDir, sprintId) {
+    const path = (0, node_path_1.join)(swarmStateDir, `${sprintId}.json`);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const raw = (0, node_fs_1.readFileSync)(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && parsed.tasks && typeof parsed.tasks === 'object') {
+            return parsed.tasks;
+        }
+        if (parsed && typeof parsed === 'object') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function escalationPaused(swarmStateDir = DEFAULT_SWARM_STATE_DIR) {
+    return (0, node_fs_1.existsSync)((0, node_path_1.join)(swarmStateDir, PAUSE_FLAG));
+}
+function detectStuckPattern(sprintId, taskId, swarmStateDir = DEFAULT_SWARM_STATE_DIR) {
+    const minAttempts = envInt('STUCK_MIN_ATTEMPTS', 3);
+    const varianceThreshold = envFloat('STUCK_VARIANCE_THRESHOLD', 5);
+    const scoreCeiling = envFloat('STUCK_SCORE_CEILING', 40);
+    const empty = { stuck: false, reason: '', scores: [], rejection_reasons: [] };
+    const tasks = readStateFile(swarmStateDir, sprintId);
+    if (!tasks)
+        return { ...empty, reason: 'no_state_file' };
+    const entry = tasks[taskId];
+    if (!entry)
+        return { ...empty, reason: 'no_task_entry' };
+    if (entry.status === 'done' || entry.status === 'awaiting_human') {
+        return { ...empty, reason: `status_${entry.status}` };
+    }
+    const attemptCount = entry.attempt_count ?? 0;
+    if (attemptCount < minAttempts) {
+        return { ...empty, reason: 'insufficient_attempts' };
+    }
+    const scoreHistory = Array.isArray(entry.score_history) ? entry.score_history.filter((s) => typeof s === 'number') : [];
+    const rejectionHistory = Array.isArray(entry.rejection_history) ? entry.rejection_history.slice() : [];
+    if (scoreHistory.length < minAttempts) {
+        return { ...empty, reason: 'insufficient_score_history', scores: scoreHistory, rejection_reasons: rejectionHistory };
+    }
+    const recentScores = scoreHistory.slice(-minAttempts);
+    const maxScore = Math.max(...scoreHistory);
+    if (maxScore >= scoreCeiling) {
+        return {
+            stuck: false,
+            reason: 'score_ceiling_reached',
+            scores: recentScores,
+            rejection_reasons: rejectionHistory,
+        };
+    }
+    const v = variance(recentScores);
+    if (v < varianceThreshold) {
+        return {
+            stuck: true,
+            reason: `low_variance_${v.toFixed(2)}_below_${varianceThreshold}_after_${attemptCount}_attempts`,
+            scores: recentScores,
+            rejection_reasons: rejectionHistory,
+        };
+    }
+    return {
+        stuck: false,
+        reason: `variance_${v.toFixed(2)}_above_threshold`,
+        scores: recentScores,
+        rejection_reasons: rejectionHistory,
+    };
+}
+function safeParseJSON(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Try to extract a JSON object from surrounding prose
+        const match = text.match(/\{[\s\S]*\}/);
+        if (match) {
+            try {
+                return JSON.parse(match[0]);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+}
+function validateDecision(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const action = obj.action;
+    const reasoning = obj.reasoning;
+    if (typeof action !== 'string' || typeof reasoning !== 'string')
+        return null;
+    if (action !== 'bump_tier' && action !== 'rephrase_context' && action !== 'escalate_human')
+        return null;
+    const decision = { action, reasoning };
+    if (action === 'bump_tier') {
+        const tier = obj.new_tier;
+        if (tier !== 'cloud-code' && tier !== 'apex')
+            return null;
+        decision.new_tier = tier;
+        if (typeof obj.budget_override === 'number')
+            decision.budget_override = obj.budget_override;
+    }
+    else if (action === 'rephrase_context') {
+        if (typeof obj.rephrased_context !== 'string' || obj.rephrased_context.trim().length === 0)
+            return null;
+        decision.rephrased_context = obj.rephrased_context;
+    }
+    else if (action === 'escalate_human') {
+        if (typeof obj.telegram_message !== 'string' || obj.telegram_message.trim().length === 0)
+            return null;
+        decision.telegram_message = obj.telegram_message;
+    }
+    return decision;
+}
+function buildEscalationPrompt(taskId, taskTitle, taskContext, detection) {
+    const attempts = detection.scores
+        .slice()
+        .reverse()
+        .map((score, idx) => {
+        const reason = detection.rejection_reasons[detection.rejection_reasons.length - 1 - idx] ?? 'unknown';
+        return `  - attempt ${detection.scores.length - idx}: score=${score}, rejection="${reason}"`;
+    })
+        .join('\n');
+    return [
+        'You are the CEO+CTO escalation council for the Kognai multi-agent platform.',
+        `A coder agent is stuck on task "${taskId}" — "${taskTitle}".`,
+        '',
+        'Task context:',
+        taskContext,
+        '',
+        `Detector reason: ${detection.reason}`,
+        'Recent attempts (newest first):',
+        attempts || '  (none)',
+        '',
+        'Decide ONE action and return STRICT JSON with this shape:',
+        '{',
+        '  "action": "bump_tier" | "rephrase_context" | "escalate_human",',
+        '  "reasoning": "<short justification>",',
+        '  "new_tier": "cloud-code" | "apex",        // required iff action=bump_tier',
+        '  "budget_override": <number, optional>,    // only when action=bump_tier',
+        '  "rephrased_context": "<full new context>",// required iff action=rephrase_context',
+        '  "telegram_message": "<message for human>" // required iff action=escalate_human',
+        '}',
+        '',
+        'Return ONLY the JSON object — no commentary, no markdown fences.',
+    ].join('\n');
+}
+function writeEscalationLog(swarmStateDir, taskId, decision, detection) {
+    try {
+        const dir = (0, node_path_1.join)(swarmStateDir, 'escalations');
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const path = (0, node_path_1.join)(dir, `${taskId}-${stamp}.json`);
+        const payload = {
+            task_id: taskId,
+            timestamp: new Date().toISOString(),
+            detection,
+            decision,
+        };
+        (0, node_fs_1.writeFileSync)(path, JSON.stringify(payload, null, 2), 'utf8');
+    }
+    catch {
+        // Best-effort logging; never throw.
+    }
+}
+function fallbackDecision(taskId, note) {
+    return {
+        action: 'escalate_human',
+        reasoning: `Stuck-task escalation API call failed (${note}) — manual review needed for ${taskId}`,
+        telegram_message: `⚠️ Coder agent stuck on ${taskId}. Escalation council unreachable (${note}). Please review.`,
+    };
+}
+async function escalateStuckTask(sprintId, taskId, taskContext, taskTitle, detection, swarmStateDir = DEFAULT_SWARM_STATE_DIR) {
+    const model = process.env.STUCK_ESCALATION_MODEL ?? 'claude-sonnet-4-20250514';
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        const decision = fallbackDecision(taskId, 'missing ANTHROPIC_API_KEY');
+        writeEscalationLog(swarmStateDir, taskId, decision, detection);
+        return decision;
+    }
+    const prompt = buildEscalationPrompt(taskId, taskTitle, taskContext, detection);
+    let decision;
+    try {
+        // Raw HTTPS via anthropic-direct — codebase convention. There is no
+        // @anthropic-ai/sdk dependency available to scripts/ (it lives only in
+        // packages/kognai-build); the SDK import shipped by the swarm would throw
+        // at require-time. See scripts/lib/anthropic-direct.ts.
+        const response = await (0, anthropic_direct_1.callAnthropic)({
+            model,
+            system: 'You are the Kognai escalation council (CEO + CTO). Given a stuck task and its failure history, return ONLY a JSON EscalationDecision object.',
+            user: prompt,
+            max_tokens: 1500,
+            temperature: 0.2,
+            timeout_ms: Number.parseInt(process.env.ESCALATION_TIMEOUT_MS ?? '120000', 10),
+        });
+        const text = (response.content || '').trim();
+        const parsed = safeParseJSON(text);
+        const validated = validateDecision(parsed);
+        decision = validated ?? fallbackDecision(taskId, 'invalid council response');
+    }
+    catch (err) {
+        const note = err instanceof Error ? err.message : 'unknown error';
+        decision = fallbackDecision(taskId, note);
+    }
+    // Note: sprintId is part of the calling sprint; we keep escalation log per task in shared dir.
+    void sprintId;
+    writeEscalationLog(swarmStateDir, taskId, decision, detection);
+    return decision;
+}

package/dist/lib/task-contract-checker.d.ts

@@ -0,0 +1,17 @@
+/**
+ * task-contract-checker.ts — Sprint TICKET-005-RULE3
+ * Rule 3 (Task Contracts): autonomous sprint proposals must declare
+ * inputs, outputs, and success_criteria.
+ *
+ * This prevents vague "just implement something" briefs from reaching the coder.
+ */
+import type { SprintProposal } from './cto-gate-types';
+export interface TaskContractResult {
+    valid: boolean;
+    missing: string[];
+}
+/**
+ * Check that a sprint proposal includes all required contract fields.
+ * Each field must be present and a non-empty array.
+ */
+export declare function checkTaskContracts(sprint: SprintProposal): TaskContractResult;

package/dist/lib/task-contract-checker.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * task-contract-checker.ts — Sprint TICKET-005-RULE3
+ * Rule 3 (Task Contracts): autonomous sprint proposals must declare
+ * inputs, outputs, and success_criteria.
+ *
+ * This prevents vague "just implement something" briefs from reaching the coder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkTaskContracts = checkTaskContracts;
+const CONTRACT_FIELDS = [
+    'inputs',
+    'outputs',
+    'success_criteria',
+];
+/**
+ * Check that a sprint proposal includes all required contract fields.
+ * Each field must be present and a non-empty array.
+ */
+function checkTaskContracts(sprint) {
+    const missing = [];
+    for (const field of CONTRACT_FIELDS) {
+        const value = sprint[field];
+        if (!Array.isArray(value) || value.length === 0) {
+            missing.push(field);
+        }
+    }
+    return { valid: missing.length === 0, missing };
+}

package/dist/lib/task-router/index.d.ts

@@ -0,0 +1,17 @@
+export { TaskTarget, TIMEOUT_BUDGETS, TaskRoute, RoutingLogEntry, } from './types';
+export { resolveRoute } from './router/resolve-route';
+export { generateExecutionId } from './router/generate-execution-id';
+import type { TaskTarget, TaskRoute, RoutingLogEntry } from './types';
+/**
+ * Write a routing decision line to logs/routing/YYYY-MM-DD.jsonl
+ * and a compact idempotency line to logs/routing/executed.jsonl.
+ * Non-fatal: all errors are silently swallowed so routing logs never block execution.
+ */
+export declare function logRoutingDecision(entry: RoutingLogEntry): void;
+/**
+ * Primary entry point: resolves a route for the given task target.
+ *
+ * @param target - The task target ('local' | 'cloud-code' | 'cloud-exec' | 'cloud-post')
+ * @returns The resolved route with provider, model, endpoint, and timeout
+ */
+export declare function getTaskRoute(target: TaskTarget): TaskRoute;

package/dist/lib/task-router/index.js

@@ -0,0 +1,52 @@
+"use strict";
+// Kognai Task Router — Sprint-063
+// Barrel export + logRoutingDecision utility
+// DO NOT let linters revert this file — it must re-export from ./router/* subdir
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateExecutionId = exports.resolveRoute = exports.TIMEOUT_BUDGETS = void 0;
+exports.logRoutingDecision = logRoutingDecision;
+exports.getTaskRoute = getTaskRoute;
+const fs_1 = require("fs");
+const path_1 = require("path");
+var types_1 = require("./types");
+Object.defineProperty(exports, "TIMEOUT_BUDGETS", { enumerable: true, get: function () { return types_1.TIMEOUT_BUDGETS; } });
+// Re-export from router/ subdirectory (NOT flat siblings)
+var resolve_route_1 = require("./router/resolve-route");
+Object.defineProperty(exports, "resolveRoute", { enumerable: true, get: function () { return resolve_route_1.resolveRoute; } });
+var generate_execution_id_1 = require("./router/generate-execution-id");
+Object.defineProperty(exports, "generateExecutionId", { enumerable: true, get: function () { return generate_execution_id_1.generateExecutionId; } });
+const resolve_route_2 = require("./router/resolve-route");
+/**
+ * Write a routing decision line to logs/routing/YYYY-MM-DD.jsonl
+ * and a compact idempotency line to logs/routing/executed.jsonl.
+ * Non-fatal: all errors are silently swallowed so routing logs never block execution.
+ */
+function logRoutingDecision(entry) {
+    try {
+        const logDir = (0, path_1.join)(process.cwd(), 'logs', 'routing');
+        (0, fs_1.mkdirSync)(logDir, { recursive: true });
+        const today = new Date().toISOString().slice(0, 10);
+        const logged_at = new Date().toISOString();
+        const fullLine = JSON.stringify({ ...entry, logged_at });
+        const idempLine = JSON.stringify({
+            execution_id: entry.execution_id,
+            task_id: entry.task_id,
+            sprint_id: entry.sprint_id,
+            logged_at,
+        });
+        (0, fs_1.appendFileSync)((0, path_1.join)(logDir, `${today}.jsonl`), fullLine + '\n', 'utf-8');
+        (0, fs_1.appendFileSync)((0, path_1.join)(logDir, 'executed.jsonl'), idempLine + '\n', 'utf-8');
+    }
+    catch {
+        // non-fatal — routing log must never block execution
+    }
+}
+/**
+ * Primary entry point: resolves a route for the given task target.
+ *
+ * @param target - The task target ('local' | 'cloud-code' | 'cloud-exec' | 'cloud-post')
+ * @returns The resolved route with provider, model, endpoint, and timeout
+ */
+function getTaskRoute(target) {
+    return (0, resolve_route_2.resolveRoute)(target);
+}

package/dist/lib/task-router/router/generate-execution-id.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generates a deterministic execution ID from sprintId and taskId.
+ * Uses SHA256 hash of `${sprintId}:${taskId}` to create a consistent identifier.
+ *
+ * @param sprintId - The unique identifier for the sprint
+ * @param taskId - The unique identifier for the task
+ * @returns A 64-character hexadecimal SHA256 hash string
+ * @throws Error if sprintId or taskId is not provided
+ */
+export declare function generateExecutionId(sprintId: string, taskId: string): string;