principles-disciple 1.127.0 → 1.129.0

package/dist/core/hygiene/tracker.js

@@ -0,0 +1,110 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createEmptyHygieneStats } from '../../types/hygiene-types.js';
+import { atomicWriteFileSync } from '../../utils/io.js';
+/**
+ * HygieneTracker - Tracks agent behavior regarding workspace organization and persistence.
+ */
+export class HygieneTracker {
+    statsFile;
+    currentStats;
+    logger;
+    constructor(stateDir, logger) {
+        this.statsFile = path.join(stateDir, 'hygiene-stats.json');
+        this.logger = logger;
+        // Ensure state directory exists
+        if (!fs.existsSync(stateDir)) {
+            try {
+                fs.mkdirSync(stateDir, { recursive: true });
+            }
+            catch (e) {
+                this.logger?.error(`[PD] Failed to create state directory ${stateDir}: ${String(e)}`);
+            }
+        }
+        this.currentStats = this.loadStats();
+    }
+    loadStats() {
+        const [today] = new Date().toISOString().split('T');
+        if (fs.existsSync(this.statsFile)) {
+            try {
+                const content = fs.readFileSync(this.statsFile, 'utf-8');
+                if (content.trim()) {
+                    const allStats = JSON.parse(content);
+                    if (allStats[today]) {
+                        return allStats[today];
+                    }
+                }
+            }
+            catch (e) {
+                this.logger?.error(`[PD] Failed to load/parse hygiene-stats.json: ${String(e)}`);
+                // If file is corrupted, we might want to back it up and start fresh
+                try {
+                    const backupPath = `${this.statsFile}.bak`;
+                    fs.renameSync(this.statsFile, backupPath);
+                    this.logger?.warn(`[PD] Corrupted hygiene stats backed up to ${backupPath}`);
+                    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reason: catch parameter intentionally unused - error handling only
+                }
+                catch (_renameErr) {
+                    // Empty - corrupted stats backup is non-fatal
+                }
+            }
+        }
+        return createEmptyHygieneStats(today);
+    }
+    saveStats() {
+        let allStats = {};
+        // Check if we need to rotate date (reset currentStats if date changed)
+        const [today] = new Date().toISOString().split('T');
+        if (this.currentStats.date !== today) {
+            this.currentStats = createEmptyHygieneStats(today);
+        }
+        if (fs.existsSync(this.statsFile)) {
+            try {
+                const content = fs.readFileSync(this.statsFile, 'utf-8');
+                if (content.trim()) {
+                    allStats = JSON.parse(content);
+                }
+            }
+            catch (e) {
+                this.logger?.error(`[PD] Failed to parse hygiene-stats.json for saving: ${String(e)}`);
+            }
+        }
+        allStats[this.currentStats.date] = this.currentStats;
+        try {
+            // Use a temporary file for atomic write if possible, or simple write
+            atomicWriteFileSync(this.statsFile, JSON.stringify(allStats, null, 2));
+        }
+        catch (e) {
+            this.logger?.error(`[PD] Failed to write hygiene-stats.json: ${String(e)}`);
+        }
+    }
+    /**
+     * Records a persistence action (writing to memory or plan).
+     */
+    recordPersistence(action) {
+        this.currentStats.persistenceCount++;
+        this.currentStats.lastPersistenceTime = action.ts;
+        this.currentStats.totalCharsPersisted += action.contentLength;
+        const fileName = path.basename(action.path);
+        this.currentStats.persistenceByFile[fileName] = (this.currentStats.persistenceByFile[fileName] || 0) + 1;
+        this.saveStats();
+        this.logger?.info(`[PD] Hygiene: Persisted state to ${fileName} (${action.contentLength} chars)`);
+    }
+    /**
+     * Records a grooming action (cleaning up the workspace).
+     */
+    recordGrooming() {
+        this.currentStats.groomingExecutedCount++;
+        this.currentStats.lastGroomingTime = new Date().toISOString();
+        this.saveStats();
+        this.logger?.info(`[PD] Hygiene: Workspace grooming executed.`);
+    }
+    getStats() {
+        // Check for date change on every get
+        const [today] = new Date().toISOString().split('T');
+        if (this.currentStats.date !== today) {
+            this.currentStats = createEmptyHygieneStats(today);
+        }
+        return this.currentStats;
+    }
+}

package/dist/core/init.d.ts

@@ -0,0 +1,30 @@
+import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
+/**
+ * Ensures that the workspace has the necessary template files for Principles Disciple.
+ * This function flattens 'core' templates to the root so OpenClaw can find them.
+ */
+export declare function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: string, language?: string): void;
+/**
+ * Core thinking model definitions (T-01 through T-10).
+ * Derived from the Core Principle Registry — the single source of truth.
+ */
+export declare const CORE_THINKING_MODELS: Array<{
+    id: string;
+    name: string;
+    description: string;
+}>;
+/**
+ * Initialize core thinking models into the training store if it's empty.
+ * This ensures every workspace has evaluable principles for nocturnal reflection.
+ *
+ * @param stateDir - State directory path
+ * @param logger - Plugin logger
+ * @returns true if initialization was performed, false if already had principles
+ */
+export declare function ensureCorePrinciples(stateDir: string, logger: PluginLogger): boolean;
+/**
+ * Ensures that the state directory has the necessary files (like pain_dictionary.json).
+ */
+export declare function ensureStateTemplates(ctx: {
+    logger: PluginLogger;
+}, stateDir: string, language?: string): void;

package/{src/core/init.ts → dist/core/init.js}

@@ -1,67 +1,59 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
 import { PD_DIRS } from './paths.js';
 import { defaultContextConfig } from '../types.js';
-import { loadStore, setPrincipleState, type PrincipleTrainingState } from './principle-training-state.js';
+import { loadStore, setPrincipleState } from './principle-training-state.js';
 import { addPrincipleToLedger } from './principle-tree-ledger.js';
-import type { LedgerPrinciple } from './principle-tree-ledger.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 import { createDefaultKeywordStore, saveKeywordStore } from './empathy-keyword-matcher.js';
 import { CORE_PRINCIPLES } from '@principles/core/runtime-v2';
-
 /**
  * Default PROFILE.json content
  */
 const DEFAULT_PROFILE = {
-  name: "Principles Disciple Agent",
-  version: "1.0.0",
-  contextInjection: defaultContextConfig
+    name: "Principles Disciple Agent",
+    version: "1.0.0",
+    contextInjection: defaultContextConfig
 };
-
 const CORE_GUIDANCE_VERSION = 'pd-core-guidance-v2';
 const CORE_GUIDANCE_FILES = new Set(['AGENTS.md', 'TOOLS.md']);
-
-function getCoreGuidanceVersionMarker(): string {
+function getCoreGuidanceVersionMarker() {
     return `pd-core-guidance-version: ${CORE_GUIDANCE_VERSION}`;
 }
-
-function hasOutdatedCoreGuidance(file: string, content: string): boolean {
-    if (!CORE_GUIDANCE_FILES.has(file)) return false;
-    if (content.includes(getCoreGuidanceVersionMarker())) return false;
-    if (content.includes('pd_spawn_agent')) return true;
-    if (!content.includes('subagents')) return true;
-    if (!content.includes('sessions_spawn')) return true;
+function hasOutdatedCoreGuidance(file, content) {
+    if (!CORE_GUIDANCE_FILES.has(file))
+        return false;
+    if (content.includes(getCoreGuidanceVersionMarker()))
+        return false;
+    if (content.includes('pd_spawn_agent'))
+        return true;
+    if (!content.includes('subagents'))
+        return true;
+    if (!content.includes('sessions_spawn'))
+        return true;
     return false;
 }
-
 /**
  * Ensures that the workspace has the necessary template files for Principles Disciple.
  * This function flattens 'core' templates to the root so OpenClaw can find them.
  */
-     
-export function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: string, language = 'en') {
+export function ensureWorkspaceTemplates(api, workspaceDir, language = 'en') {
     try {
         const __filename = fileURLToPath(import.meta.url);
         const __dirname = path.dirname(__filename);
-        
         // 1. Copy common workspace templates (e.g., docs/*)
         const commonTemplatesDir = path.resolve(__dirname, '..', '..', 'templates', 'workspace');
         if (fs.existsSync(commonTemplatesDir)) {
             api.logger.info(`[PD] Syncing workspace templates: ${workspaceDir}...`);
-             
-             
             copyRecursiveSync(commonTemplatesDir, workspaceDir, api);
         }
-
         // 2. Copy language-specific core templates (AGENTS.md, SOUL.md, etc.)
         // CRITICAL: These MUST be at the root of the workspace for OpenClaw to recognize them.
         let coreTemplatesDir = path.resolve(__dirname, '..', '..', 'templates', 'langs', language, 'core');
         if (!fs.existsSync(coreTemplatesDir)) {
             coreTemplatesDir = path.resolve(__dirname, '..', '..', 'templates', 'langs', 'zh', 'core');
         }
-        
         if (fs.existsSync(coreTemplatesDir)) {
             api.logger.info(`[PD] Flattening ${language} core templates to workspace root...`);
             // We copy contents of 'core' directory directly to workspaceDir root
@@ -69,14 +61,14 @@ export function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: s
             for (const file of coreFiles) {
                 const srcPath = path.join(coreTemplatesDir, file);
                 const destPath = path.join(workspaceDir, file);
-                
                 // If it's a core file and we want to ensure latest templates are used
                 // but don't want to destroy user custom data, we check if we should overwrite.
                 // For now, we only copy if missing to be safe, but log it.
                 if (!fs.existsSync(destPath)) {
                     fs.copyFileSync(srcPath, destPath);
                     api.logger.info(`[PD] Initialized core file: ${file}`);
-                } else if (CORE_GUIDANCE_FILES.has(file)) {
+                }
+                else if (CORE_GUIDANCE_FILES.has(file)) {
                     const existingContent = fs.readFileSync(destPath, 'utf8');
                     if (hasOutdatedCoreGuidance(file, existingContent)) {
                         api.logger.warn(`[PD] Outdated core guidance detected in ${file}. Review the latest template guidance for peer sessions, subagents, and sessions_spawn routing.`);
@@ -84,24 +76,18 @@ export function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: s
                 }
             }
         }
-
         // 3. Copy pain memory seed files
         const painTemplatesDir = path.resolve(__dirname, '..', '..', 'templates', 'langs', language, 'pain');
         const painDestDir = path.join(workspaceDir, PD_DIRS.PAIN_SAMPLES);
-        
         if (fs.existsSync(painTemplatesDir)) {
             if (!fs.existsSync(painDestDir)) {
                 fs.mkdirSync(painDestDir, { recursive: true });
             }
-             
-             
             copyRecursiveSync(painTemplatesDir, painDestDir, api);
         }
-
         // 4. Initialize PROFILE.json with default contextInjection config
         const principlesDir = path.join(workspaceDir, PD_DIRS.IDENTITY);
         const profilePath = path.join(principlesDir, 'PROFILE.json');
-        
         if (!fs.existsSync(profilePath)) {
             // Ensure .principles directory exists
             if (!fs.existsSync(principlesDir)) {
@@ -110,32 +96,30 @@ export function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: s
             atomicWriteFileSync(profilePath, JSON.stringify(DEFAULT_PROFILE, null, 2));
             api.logger.info(`[PD] Initialized PROFILE.json with default contextInjection config`);
         }
-    } catch (err) {
+    }
+    catch (err) {
         api.logger.error(`[PD] Failed to initialize workspace templates: ${String(err)}`);
     }
 }
-
 /**
  * Standard recursive copy that preserves directory structure.
  * Special handling: maps 'okr' directory to 'memory/okr' for runtime compatibility.
  */
- 
-function copyRecursiveSync(srcDir: string, destDir: string, api: OpenClawPluginApi | { logger: PluginLogger }) {
+function copyRecursiveSync(srcDir, destDir, api) {
     const items = fs.readdirSync(srcDir);
-
     for (const item of items) {
         const srcPath = path.join(srcDir, item);
         // Special mapping: okr -> memory/okr (runtime path expects memory/okr/)
         const destItemName = item === 'okr' ? path.join('memory', 'okr') : item;
         const destPath = path.join(destDir, destItemName);
         const stat = fs.statSync(srcPath);
-
         if (stat.isDirectory()) {
             if (!fs.existsSync(destPath)) {
                 fs.mkdirSync(destPath, { recursive: true });
             }
             copyRecursiveSync(srcPath, destPath, api);
-        } else {
+        }
+        else {
             if (!fs.existsSync(destPath)) {
                 // Ensure parent directory exists
                 const destParent = path.dirname(destPath);
@@ -148,21 +132,15 @@ function copyRecursiveSync(srcDir: string, destDir: string, api: OpenClawPluginA
         }
     }
 }
-
 /**
  * Core thinking model definitions (T-01 through T-10).
  * Derived from the Core Principle Registry — the single source of truth.
  */
-export const CORE_THINKING_MODELS: Array<{
-  id: string;
-  name: string;
-  description: string;
-}> = CORE_PRINCIPLES.map(p => ({
-  id: p.id,
-  name: p.name,
-  description: p.statement,
+export const CORE_THINKING_MODELS = CORE_PRINCIPLES.map(p => ({
+    id: p.id,
+    name: p.name,
+    description: p.statement,
 }));
-
 /**
  * Initialize core thinking models into the training store if it's empty.
  * This ensures every workspace has evaluable principles for nocturnal reflection.
@@ -171,82 +149,75 @@ export const CORE_THINKING_MODELS: Array<{
  * @param logger - Plugin logger
  * @returns true if initialization was performed, false if already had principles
  */
-export function ensureCorePrinciples(stateDir: string, logger: PluginLogger): boolean {
-  try {
-    const store = loadStore(stateDir);
-    const existingIds = Object.keys(store).filter(k => k !== '_tree');
-
-    // If already has principles, skip initialization
-    if (existingIds.length > 0) {
-      return false;
+export function ensureCorePrinciples(stateDir, logger) {
+    try {
+        const store = loadStore(stateDir);
+        const existingIds = Object.keys(store).filter(k => k !== '_tree');
+        // If already has principles, skip initialization
+        if (existingIds.length > 0) {
+            return false;
+        }
+        logger.info(`[PD] Initializing core thinking models (${CORE_THINKING_MODELS.length} principles) into training store`);
+        for (const model of CORE_THINKING_MODELS) {
+            const state = {
+                principleId: model.id,
+                evaluability: 'deterministic',
+                applicableOpportunityCount: 0,
+                observedViolationCount: 0,
+                complianceRate: 0,
+                violationTrend: 0,
+                generatedSampleCount: 0,
+                approvedSampleCount: 0,
+                includedTrainRunIds: [],
+                deployedCheckpointIds: [],
+                internalizationStatus: 'needs_training',
+            };
+            setPrincipleState(stateDir, state);
+            // Also write to Ledger Tree so bootstrapRules() can find them
+            const now = new Date().toISOString();
+            const ledgerPrinciple = {
+                id: model.id,
+                version: 1,
+                text: model.description,
+                coreAxiomId: model.id,
+                triggerPattern: '',
+                action: '',
+                status: 'active',
+                priority: 'P1',
+                scope: 'general',
+                evaluability: 'deterministic',
+                valueScore: 0,
+                adherenceRate: 0,
+                painPreventedCount: 0,
+                derivedFromPainIds: [],
+                ruleIds: [],
+                conflictsWithPrincipleIds: [],
+                createdAt: now,
+                updatedAt: now,
+                suggestedRules: [],
+            };
+            addPrincipleToLedger(stateDir, ledgerPrinciple);
+        }
+        const firstId = CORE_THINKING_MODELS[0]?.id ?? 'T-01';
+        const lastId = CORE_THINKING_MODELS[CORE_THINKING_MODELS.length - 1]?.id ?? 'T-10';
+        logger.info(`[PD] Initialized ${CORE_THINKING_MODELS.length} core thinking models: ${firstId} through ${lastId}`);
+        return true;
     }
-
-    logger.info(`[PD] Initializing core thinking models (${CORE_THINKING_MODELS.length} principles) into training store`);
-
-    for (const model of CORE_THINKING_MODELS) {
-      const state: PrincipleTrainingState = {
-        principleId: model.id,
-        evaluability: 'deterministic',
-        applicableOpportunityCount: 0,
-        observedViolationCount: 0,
-        complianceRate: 0,
-        violationTrend: 0,
-        generatedSampleCount: 0,
-        approvedSampleCount: 0,
-        includedTrainRunIds: [],
-        deployedCheckpointIds: [],
-        internalizationStatus: 'needs_training',
-      };
-      setPrincipleState(stateDir, state);
-
-      // Also write to Ledger Tree so bootstrapRules() can find them
-      const now = new Date().toISOString();
-      const ledgerPrinciple: LedgerPrinciple = {
-        id: model.id,
-        version: 1,
-        text: model.description,
-        coreAxiomId: model.id,
-        triggerPattern: '',
-        action: '',
-        status: 'active',
-        priority: 'P1',
-        scope: 'general',
-        evaluability: 'deterministic',
-        valueScore: 0,
-        adherenceRate: 0,
-        painPreventedCount: 0,
-        derivedFromPainIds: [],
-        ruleIds: [],
-        conflictsWithPrincipleIds: [],
-        createdAt: now,
-        updatedAt: now,
-        suggestedRules: [],
-      };
-      addPrincipleToLedger(stateDir, ledgerPrinciple);
+    catch (err) {
+        logger.error(`[PD] Failed to initialize core principles: ${String(err)}`);
+        return false;
     }
-
-    const firstId = CORE_THINKING_MODELS[0]?.id ?? 'T-01';
-    const lastId = CORE_THINKING_MODELS[CORE_THINKING_MODELS.length - 1]?.id ?? 'T-10';
-    logger.info(`[PD] Initialized ${CORE_THINKING_MODELS.length} core thinking models: ${firstId} through ${lastId}`);
-    return true;
-  } catch (err) {
-    logger.error(`[PD] Failed to initialize core principles: ${String(err)}`);
-    return false;
-  }
 }
-
 /**
  * Ensures that the state directory has the necessary files (like pain_dictionary.json).
  */
-export function ensureStateTemplates(ctx: { logger: PluginLogger }, stateDir: string, language = 'en') {
+export function ensureStateTemplates(ctx, stateDir, language = 'en') {
     try {
         const __filename = fileURLToPath(import.meta.url);
         const __dirname = path.dirname(__filename);
-        
         if (!fs.existsSync(stateDir)) {
             fs.mkdirSync(stateDir, { recursive: true });
         }
-
         // 1. Copy common state files
         const commonFiles = ['pain_settings.json'];
         for (const filename of commonFiles) {
@@ -257,19 +228,16 @@ export function ensureStateTemplates(ctx: { logger: PluginLogger }, stateDir: st
                 ctx.logger.info(`[PD] Initialized ${filename} in stateDir: ${destPath}`);
             }
         }
-
         // 2. Copy language-specific dictionary
         let dictTemplate = path.resolve(__dirname, '..', '..', 'templates', 'langs', language, 'pain_dictionary.json');
         if (!fs.existsSync(dictTemplate)) {
             dictTemplate = path.resolve(__dirname, '..', '..', 'templates', 'langs', 'en', 'pain_dictionary.json');
         }
-        
         const dictDest = path.join(stateDir, 'pain_dictionary.json');
         if (!fs.existsSync(dictDest) && fs.existsSync(dictTemplate)) {
             fs.copyFileSync(dictTemplate, dictDest);
             ctx.logger.info(`[PD] Initialized pain dictionary in stateDir: ${dictDest} (Lang: ${language})`);
         }
-
         // 3. Initialize empathy keyword store for new users
         // loadKeywordStore() creates the file if missing, but we call it explicitly
         // here so the file exists before any agent/workflow tries to read it
@@ -280,7 +248,8 @@ export function ensureStateTemplates(ctx: { logger: PluginLogger }, stateDir: st
             saveKeywordStore(stateDir, store);
             ctx.logger.info(`[PD] Initialized empathy keyword store in stateDir: ${empathyFile}`);
         }
-    } catch (err) {
+    }
+    catch (err) {
         ctx.logger.error(`[PD] Failed to initialize state templates: ${String(err)}`);
     }
 }

package/dist/core/local-worker-routing.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Local Worker Routing Policy — Task Classification and Routing Decisions
+ * ======================================================================
+ *
+ * Phase: PRI-74 Routing Guidance Migration (follow-up to PRI-75 Prompt Injection SDK Migration)
+ *
+ * This file is a THIN ADAPTER.
+ * Pure classification logic lives in @principles/core/prompt-builder/routing-guidance.ts.
+ * This file handles I/O (deployment registry, promotion state) and combines
+ * pure classification with deployment checks.
+ *
+ * ARCHITECTURE:
+ *   - Pure: classifyTaskKind, buildReason, buildBlockers, keyword constants → core
+ *   - I/O: getDeployment, isRoutingEnabledForProfile, isCheckpointDeployable, getPromotionState → plugin
+ *
+ * TASK CLASSIFICATION TAXONOMY:
+ *   Pure-classification output from classifyTaskKind() in @principles/core/prompt-builder/routing-guidance.ts:
+ *     reader_eligible      — clearly suitable for local-reader
+ *     editor_eligible     — clearly suitable for local-editor
+ *     high_entropy_disallowed — high-complexity tasks that must stay on main agent
+ *     ambiguous_scope     — tasks that are unclear and need main-agent judgment
+ *   Plugin layer adds I/O-bound categories via deployment checks in classifyTask():
+ *     profile_mismatch    — target profile incompatible with task classification
+ *     deployment_unavailable — no enabled deployment exists for the target profile
+ *
+ * FAIL-CLOSED PRINCIPLE:
+ *   - When in doubt → stay_main
+ *   - Unclear intent → stay_main
+ *   - High complexity → stay_main
+ *   - No enabled deployment → stay_main
+ */
+import type { WorkerProfile } from './model-deployment-registry.js';
+import { type RoutingInput as CoreRoutingInput } from '@principles/core/prompt-builder';
+export type { RoutingInput } from '@principles/core/prompt-builder';
+/**
+ * The result of a routing classification decision.
+ * Always includes a `reason` and a `blockers` list for full explainability.
+ */
+export interface RoutingDecision {
+    /**
+     * The routing verdict.
+     * - `route_local` — the task may be delegated to `targetProfile`
+     * - `stay_main` — the task must remain on the main agent
+     */
+    decision: 'route_local' | 'stay_main';
+    /**
+     * Which profile the task should be routed to (if decision === 'route_local').
+     * Null if decision === 'stay_main'.
+     */
+    targetProfile: WorkerProfile | null;
+    /**
+     * The task classification category that led to this decision.
+     */
+    classification: 'reader_eligible' | 'editor_eligible' | 'high_entropy_disallowed' | 'ambiguous_scope' | 'profile_mismatch' | 'deployment_unavailable';
+    /**
+     * Human-readable explanation of the routing decision.
+     * Must be specific enough that a developer can understand why a task was accepted/rejected.
+     */
+    reason: string;
+    /**
+     * List of specific reasons that blocked routing (if decision === 'stay_main').
+     * Empty if decision === 'route_local'.
+     */
+    blockers: string[];
+    /**
+     * Whether a deployment check was performed and whether it passed.
+     * Useful for diagnostics when deployment_unavailable is the classification.
+     */
+    deploymentCheck: {
+        performed: boolean;
+        profileAvailable: boolean;
+        routingEnabled: boolean;
+        /** Whether the active checkpoint is currently marked as deployable in the training registry. */
+        checkpointDeployable: boolean;
+    };
+    /**
+     * The active checkpoint ID that would be used for routing (if decision === 'route_local').
+     * This is the checkpoint from the deployment registry.
+     * Null if decision === 'stay_main' or if no checkpoint is active.
+     *
+     * USE FOR SHADOW OBSERVATIONS:
+     * When routing in shadow mode (checkpoint is in shadow_ready state),
+     * the caller should record a shadow observation using this checkpoint ID.
+     */
+    activeCheckpointId: string | null;
+    /**
+     * The promotion state of the active checkpoint.
+     * Indicates whether this is a regular deployment or a shadow rollout.
+     * Useful for determining whether to record shadow observations.
+     */
+    activeCheckpointState?: 'promotable' | 'shadow_ready' | 'candidate_only';
+    /**
+     * Deprecated: runtime shadow observations are now recorded from real
+     * subagent lifecycle hooks instead of from classifyTask().
+     */
+    shadowObservationId?: string;
+}
+/**
+ * Classify a task and produce a routing decision.
+ *
+ * This is the main entry point for routing policy evaluation.
+ * It:
+ *   1. Classifies the task kind based on keywords and heuristics (core pure function)
+ *   2. Checks deployment availability for the target profile (plugin I/O)
+ *   3. Returns a fully explainable RoutingDecision
+ *
+ * @param input - The routing input describing the task
+ * @param stateDir - Workspace state directory (for deployment registry lookup)
+ * @returns RoutingDecision with classification, reason, blockers, and routing verdict
+ */
+export declare function classifyTask(input: CoreRoutingInput, stateDir: string): RoutingDecision;
+/**
+ * Convenience: check if a specific profile can handle a task.
+ * Equivalent to calling classifyTask with targetProfile set.
+ */
+export declare function canRouteToProfile(input: CoreRoutingInput, stateDir: string, profile: WorkerProfile): boolean;
+/**
+ * Check if any local worker routing is currently enabled for any profile.
+ */
+export declare function isAnyLocalRoutingEnabled(stateDir: string): boolean;
+/**
+ * List all profiles that currently have routing enabled.
+ */
+export declare function listEnabledProfiles(stateDir: string): WorkerProfile[];