@cleocode/core 2026.4.9 → 2026.4.12

package/dist/skills/orchestrator/validator.js

@@ -0,0 +1,301 @@
+/**
+ * Orchestrator protocol compliance validation.
+ * Ports lib/skills/orchestrator-validator.sh.
+ *
+ * Validates subagent output compliance, orchestrator behavior,
+ * manifest integrity, and pre-spawn compliance checks.
+ *
+ * @epic T4454
+ * @task T4519
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { MANIFEST_STATUSES } from '@cleocode/contracts';
+import { getAgentOutputsAbsolute, getManifestPath as getManifestPathFromPaths, } from '../../paths.js';
+import { getAccessor } from '../../store/data-accessor.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const KEY_FINDINGS_MIN = 3;
+const KEY_FINDINGS_MAX = 7;
+const MANIFEST_REQUIRED_FIELDS = [
+    'id',
+    'file',
+    'title',
+    'date',
+    'status',
+    'topics',
+    'key_findings',
+    'actionable',
+];
+const VALID_STATUSES_SET = new Set(MANIFEST_STATUSES);
+// ============================================================================
+// Manifest Helpers
+// ============================================================================
+/** Alias for centralized getManifestPath to avoid name conflicts with local usages. */
+function getManifestPath(cwd) {
+    return getManifestPathFromPaths(cwd);
+}
+/**
+ * Read all manifest entries from MANIFEST.jsonl.
+ */
+function readManifestEntries(cwd) {
+    const manifestPath = getManifestPath(cwd);
+    if (!existsSync(manifestPath))
+        return [];
+    const content = readFileSync(manifestPath, 'utf-8');
+    const entries = [];
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip invalid lines
+        }
+    }
+    return entries;
+}
+// ============================================================================
+// Subagent Output Validation
+// ============================================================================
+/**
+ * Validate a subagent's manifest entry for protocol compliance.
+ * @task T4519
+ */
+export function validateSubagentOutput(researchId, cwd) {
+    const issues = [];
+    const checkedRules = [
+        'MANIFEST_ENTRY_EXISTS',
+        'REQUIRED_FIELDS_PRESENT',
+        'STATUS_VALID_ENUM',
+        'KEY_FINDINGS_COUNT_3_7',
+        'DATE_ISO_8601',
+        'TOPICS_ARRAY_NON_EMPTY',
+        'NEEDS_FOLLOWUP_ARRAY',
+        'ACTIONABLE_BOOLEAN',
+        'OUTPUT_FILE_EXISTS',
+    ];
+    const entries = readManifestEntries(cwd);
+    const entry = entries.find((e) => e.id === researchId);
+    if (!entry) {
+        issues.push(`MANIFEST_ENTRY_MISSING: No manifest entry found for id=${researchId}`);
+        return { passed: false, issues, checkedRules };
+    }
+    // Check required fields
+    for (const field of MANIFEST_REQUIRED_FIELDS) {
+        if (!(field in entry)) {
+            issues.push(`MISSING_FIELD: ${field}`);
+        }
+    }
+    // Validate status
+    if (entry.status && !VALID_STATUSES_SET.has(entry.status)) {
+        issues.push(`INVALID_STATUS: ${entry.status} (must be completed|partial|blocked|archived)`);
+    }
+    // Validate key_findings count
+    if (!Array.isArray(entry.key_findings)) {
+        issues.push('KEY_FINDINGS_NOT_ARRAY');
+    }
+    else if (entry.key_findings.length < KEY_FINDINGS_MIN) {
+        issues.push(`KEY_FINDINGS_TOO_FEW: count=${entry.key_findings.length} (must be ${KEY_FINDINGS_MIN}-${KEY_FINDINGS_MAX})`);
+    }
+    else if (entry.key_findings.length > KEY_FINDINGS_MAX) {
+        issues.push(`KEY_FINDINGS_TOO_MANY: count=${entry.key_findings.length} (must be ${KEY_FINDINGS_MIN}-${KEY_FINDINGS_MAX})`);
+    }
+    // Validate date format
+    if (entry.date && !/^\d{4}-\d{2}-\d{2}$/.test(entry.date)) {
+        issues.push(`INVALID_DATE: ${entry.date} (must be YYYY-MM-DD)`);
+    }
+    // Validate topics
+    if (!Array.isArray(entry.topics) || entry.topics.length === 0) {
+        issues.push('TOPICS_EMPTY: topics must be a non-empty array');
+    }
+    // Validate actionable
+    if (typeof entry.actionable !== 'boolean') {
+        issues.push('ACTIONABLE_NOT_BOOLEAN');
+    }
+    // Check output file exists
+    if (entry.file) {
+        const absOutputDir = getAgentOutputsAbsolute(cwd);
+        const filePath = join(absOutputDir, entry.file);
+        if (!existsSync(filePath)) {
+            issues.push(`FILE_NOT_FOUND: Expected file at ${filePath}`);
+        }
+    }
+    return { passed: issues.length === 0, issues, checkedRules };
+}
+// ============================================================================
+// Manifest Integrity
+// ============================================================================
+/**
+ * Validate the entire manifest file integrity.
+ * @task T4519
+ */
+export function validateManifestIntegrity(cwd) {
+    const manifestPath = getManifestPath(cwd);
+    if (!existsSync(manifestPath)) {
+        return { exists: false, passed: true, issues: [] };
+    }
+    const content = readFileSync(manifestPath, 'utf-8');
+    const lines = content.split('\n').filter((l) => l.trim());
+    const issues = [];
+    let validEntries = 0;
+    let invalidEntries = 0;
+    const seenIds = new Set();
+    for (let i = 0; i < lines.length; i++) {
+        const lineNum = i + 1;
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        // Check valid JSON
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            issues.push(`LINE_${lineNum}_INVALID_JSON: Parse error`);
+            invalidEntries++;
+            continue;
+        }
+        // Check id field
+        if (!entry.id) {
+            issues.push(`LINE_${lineNum}_MISSING_ID: No id field`);
+            invalidEntries++;
+            continue;
+        }
+        // Check duplicate ID
+        if (seenIds.has(entry.id)) {
+            issues.push(`LINE_${lineNum}_DUPLICATE_ID: ${entry.id} already exists`);
+            invalidEntries++;
+            continue;
+        }
+        seenIds.add(entry.id);
+        // Check file exists
+        if (entry.file) {
+            const absOutputDir = getAgentOutputsAbsolute(cwd);
+            const filePath = join(absOutputDir, entry.file);
+            if (!existsSync(filePath)) {
+                issues.push(`LINE_${lineNum}_FILE_MISSING: ${entry.file} does not exist`);
+            }
+        }
+        validEntries++;
+    }
+    return {
+        exists: true,
+        passed: issues.length === 0,
+        stats: {
+            totalLines: lines.length,
+            validEntries,
+            invalidEntries,
+        },
+        issues,
+    };
+}
+// ============================================================================
+// Pre-Spawn Compliance Verification
+// ============================================================================
+/**
+ * Verify previous agent completed protocol compliance before spawning next.
+ * @task T4519
+ */
+export function verifyCompliance(previousTaskId, researchId, cwd) {
+    const violations = [];
+    const warnings = [];
+    const entries = readManifestEntries(cwd);
+    // Find manifest entry for previous task
+    let entry;
+    if (researchId) {
+        entry = entries.find((e) => e.id === researchId);
+    }
+    else {
+        // Search by linked_tasks
+        entry = entries.find((e) => e.linked_tasks?.includes(previousTaskId) || e.needs_followup?.includes(previousTaskId));
+        // Try ID pattern match
+        if (!entry) {
+            const taskNum = previousTaskId.replace(/^T/, '');
+            entry = entries.find((e) => e.id.includes(taskNum));
+        }
+    }
+    const manifestEntryExists = !!entry;
+    if (!manifestEntryExists) {
+        violations.push(`MANIFEST_ENTRY_MISSING: No manifest entry found for task ${previousTaskId}`);
+    }
+    // Check research linked to task
+    let researchLinkedToTask = false;
+    if (entry) {
+        researchLinkedToTask = entry.linked_tasks?.includes(previousTaskId) ?? false;
+        if (!researchLinkedToTask) {
+            warnings.push(`RESEARCH_NOT_LINKED: Research entry exists but not linked to task ${previousTaskId}`);
+        }
+    }
+    // Check return status
+    let returnStatusValid = null;
+    if (entry) {
+        returnStatusValid = VALID_STATUSES_SET.has(entry.status);
+        if (!returnStatusValid) {
+            violations.push(`INVALID_MANIFEST_STATUS: ${entry.status}`);
+        }
+    }
+    return {
+        previousTaskId,
+        researchId: entry?.id ?? null,
+        checks: {
+            manifestEntryExists,
+            researchLinkedToTask,
+            returnStatusValid,
+        },
+        canSpawnNext: violations.length === 0,
+        violations,
+        warnings,
+    };
+}
+/**
+ * Validate orchestrator compliance (post-hoc behavioral checks).
+ * @task T4519
+ */
+export async function validateOrchestratorCompliance(epicId, cwd) {
+    const violations = [];
+    const warnings = [];
+    const manifestPath = getManifestPath(cwd);
+    // Check manifest usage
+    if (!existsSync(manifestPath)) {
+        warnings.push(`ORC-005_NO_MANIFEST: Manifest file not found at ${manifestPath}`);
+    }
+    else {
+        const content = readFileSync(manifestPath, 'utf-8').trim();
+        if (!content) {
+            warnings.push('ORC-005_EMPTY_MANIFEST: Manifest exists but has no entries');
+        }
+    }
+    // Check dependency order (ORC-004) for completed tasks via DataAccessor
+    if (epicId) {
+        try {
+            const acc = await getAccessor(cwd);
+            const children = await acc.getChildren(epicId);
+            const tasks = children.filter((t) => t.status === 'done');
+            // Sort by updatedAt and check for dependency violations
+            const sorted = tasks.sort((a, b) => new Date(a.updatedAt ?? '').getTime() - new Date(b.updatedAt ?? '').getTime());
+            const completionOrder = sorted.map((t) => t.id);
+            for (let i = 0; i < sorted.length; i++) {
+                const deps = sorted[i].depends ?? [];
+                for (const dep of deps) {
+                    const depIdx = completionOrder.indexOf(dep);
+                    if (depIdx >= 0 && depIdx >= i) {
+                        violations.push(`ORC-004_DEPENDENCY_ORDER: Task ${sorted[i].id} completed before dependency ${dep}`);
+                    }
+                }
+            }
+        }
+        catch {
+            // Skip on DB error
+        }
+    }
+    return {
+        compliant: violations.length === 0,
+        violations,
+        warnings,
+    };
+}
+//# sourceMappingURL=validator.js.map

package/dist/skills/orchestrator/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../src/skills/orchestrator/validator.ts"],"names":[],"mappings":"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"}

package/dist/skills/precedence-integration.js

@@ -0,0 +1,73 @@
+import { buildSkillsMap, getEffectiveSkillsPaths, getProvidersBySkillsPrecedence, } from '@cleocode/caamp';
+/**
+ * Get effective skill paths for a provider considering precedence
+ * @param providerId - The ID of the provider
+ * @param scope - The scope ('global' or 'project')
+ * @param projectRoot - Optional project root path for project-scoped resolution
+ * @returns Array of resolved skill paths with precedence information
+ * @throws Error if provider not found
+ */
+export async function resolveSkillPathsForProvider(providerId, scope, projectRoot) {
+    const { getProvider } = await import('@cleocode/caamp');
+    const provider = getProvider(providerId);
+    if (!provider) {
+        throw new Error(`Provider ${providerId} not found`);
+    }
+    const paths = getEffectiveSkillsPaths(provider, scope, projectRoot);
+    const skillsCap = provider.skills;
+    return paths.map((p) => ({
+        path: p.path,
+        source: p.source,
+        scope: p.scope,
+        precedence: skillsCap?.precedence || 'vendor-only',
+        providerId: provider.id,
+    }));
+}
+/**
+ * Get all providers that use a specific precedence mode
+ * @param precedence - The precedence mode to filter by
+ * @returns Array of provider IDs using the specified precedence
+ */
+export function getProvidersWithPrecedence(precedence) {
+    return getProvidersBySkillsPrecedence(precedence).map((p) => p.id);
+}
+/**
+ * Build complete skills map with precedence information
+ * @returns Array of provider skill configurations with precedence data
+ */
+export function getSkillsMapWithPrecedence() {
+    return buildSkillsMap();
+}
+/**
+ * Determine target installation paths for a skill
+ * @param context - The installation context including target providers and project root
+ * @returns Array of installation targets with provider ID and path
+ */
+export async function determineInstallationTargets(context) {
+    const targets = [];
+    for (const providerId of context.targetProviders) {
+        const paths = await resolveSkillPathsForProvider(providerId, context.projectRoot ? 'project' : 'global', context.projectRoot);
+        // Take the first (highest precedence) path
+        if (paths.length > 0) {
+            targets.push({
+                providerId,
+                path: paths[0].path,
+            });
+        }
+    }
+    return targets;
+}
+/**
+ * Check if provider supports agents path
+ * @param providerId - The ID of the provider to check
+ * @returns True if provider has agents path configuration
+ */
+export async function supportsAgentsPath(providerId) {
+    const { getProviderCapabilities } = await import('@cleocode/caamp');
+    const caps = getProviderCapabilities(providerId);
+    if (!caps?.skills)
+        return false;
+    const skills = caps.skills;
+    return skills.agentsGlobalPath !== null || skills.agentsProjectPath !== null;
+}
+//# sourceMappingURL=precedence-integration.js.map

package/dist/skills/precedence-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"precedence-integration.js","sourceRoot":"","sources":["../../src/skills/precedence-integration.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,8BAA8B,GAG/B,MAAM,iBAAiB,CAAC;AAGzB;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,UAAkB,EAClB,KAA2B,EAC3B,WAAoB;IAEpB,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IAEzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,YAAY,UAAU,YAAY,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,KAAK,GAAG,uBAAuB,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;IACpE,MAAM,SAAS,GAAI,QAAkD,CAAC,MAAM,CAAC;IAE7E,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAA6C;QACvD,KAAK,EAAE,CAAC,CAAC,KAA6B;QACtC,UAAU,EAAE,SAAS,EAAE,UAAU,IAAI,aAAa;QAClD,UAAU,EAAE,QAAQ,CAAC,EAAE;KACxB,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,UAA4B;IACrE,OAAO,8BAA8B,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B;IAMxC,OAAO,cAAc,EAAE,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,OAAiC;IAEjC,MAAM,OAAO,GAAgD,EAAE,CAAC;IAEhE,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,MAAM,4BAA4B,CAC9C,UAAU,EACV,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,EAC1C,OAAO,CAAC,WAAW,CACpB,CAAC;QAEF,2CAA2C;QAC3C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CAAC;gBACX,UAAU;gBACV,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;aACpB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,UAAkB;IACzD,MAAM,EAAE,uBAAuB,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;IAEjD,IAAI,CAAC,IAAI,EAAE,MAAM;QAAE,OAAO,KAAK,CAAC;IAEhC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAkC,CAAC;IACvD,OAAO,MAAM,CAAC,gBAAgB,KAAK,IAAI,IAAI,MAAM,CAAC,iBAAiB,KAAK,IAAI,CAAC;AAC/E,CAAC"}

package/dist/skills/precedence-types.js

@@ -0,0 +1,16 @@
+/**
+ * Skills Precedence Types - Phase 3B of T5238
+ *
+ * Re-exports CAAMP precedence types and adds CLEO-specific wrapper types
+ * for skill path resolution and installation context.
+ *
+ * These types complement the skill types in `./types.ts`:
+ * - `./types.ts` defines the CLEO skill domain model (Skill, SkillFrontmatter, etc.)
+ * - This file defines CAAMP precedence integration types used when resolving
+ *   which skill version takes priority across providers and scopes.
+ *
+ * @task T5238
+ */
+// Import CAAMP functions that CLEO will use
+export { buildSkillsMap, getEffectiveSkillsPaths, getProvidersBySkillsPrecedence, } from '@cleocode/caamp';
+//# sourceMappingURL=precedence-types.js.map

package/dist/skills/precedence-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"precedence-types.js","sourceRoot":"","sources":["../../src/skills/precedence-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,4CAA4C;AAC5C,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,iBAAiB,CAAC"}

package/dist/skills/routing-table.js

@@ -0,0 +1,63 @@
+/**
+ * Dynamic Skill Routing Table
+ *
+ * Thin wrapper over the merged capability matrix. PreferredChannel data
+ * is now stored as part of OperationCapability in the capability matrix
+ * (packages/core/src/routing/capability-matrix.ts), which is the single
+ * SSoT for both execution mode and channel preference.
+ *
+ * @task T5240
+ * @epic T5149
+ * @see packages/core/src/routing/capability-matrix.ts
+ */
+import { getCapabilityMatrix } from '../routing/capability-matrix.js';
+/**
+ * Look up the preferred channel for a given domain + operation.
+ *
+ * Reads from the merged capability matrix (single SSoT).
+ *
+ * @param domain - Domain name
+ * @param operation - Operation name
+ * @returns Preferred channel ('cli' or 'either' as fallback)
+ */
+export function getPreferredChannel(domain, operation) {
+    const entry = getCapabilityMatrix().find((cap) => cap.domain === domain && cap.operation === operation);
+    return entry?.preferredChannel ?? 'either';
+}
+/**
+ * Get routing entries for a specific domain.
+ *
+ * Derives entries from the capability matrix.
+ *
+ * @param domain - Domain name
+ * @returns All routing entries for the domain
+ */
+export function getRoutingForDomain(domain) {
+    return getCapabilityMatrix()
+        .filter((cap) => cap.domain === domain)
+        .map((cap) => ({
+        domain: cap.domain,
+        operation: cap.operation,
+        preferredChannel: cap.preferredChannel,
+        reason: '',
+    }));
+}
+/**
+ * Get all operations that prefer a specific channel.
+ *
+ * Derives entries from the capability matrix.
+ *
+ * @param channel - Channel preference to filter by
+ * @returns Matching routing entries
+ */
+export function getOperationsByChannel(channel) {
+    return getCapabilityMatrix()
+        .filter((cap) => cap.preferredChannel === channel)
+        .map((cap) => ({
+        domain: cap.domain,
+        operation: cap.operation,
+        preferredChannel: cap.preferredChannel,
+        reason: '',
+    }));
+}
+//# sourceMappingURL=routing-table.js.map

package/dist/skills/routing-table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-table.js","sourceRoot":"","sources":["../../src/skills/routing-table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAsBtE;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,SAAiB;IACnE,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAC,IAAI,CACtC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,CAC9D,CAAC;IACF,OAAO,KAAK,EAAE,gBAAgB,IAAI,QAAQ,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,mBAAmB,EAAE;SACzB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC;SACtC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACb,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;QACtC,MAAM,EAAE,EAAE;KACX,CAAC,CAAC,CAAC;AACR,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAyB;IAC9D,OAAO,mBAAmB,EAAE;SACzB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,gBAAgB,KAAK,OAAO,CAAC;SACjD,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACb,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;QACtC,MAAM,EAAE,EAAE;KACX,CAAC,CAAC,CAAC;AACR,CAAC"}